Linux ip-172-26-5-244 6.1.0-28-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.119-1 (2024-11-22) x86_64
Apache
: 172.26.5.244 | : 216.73.216.21
Cant Read [ /etc/named.conf ]
8.3.14
daemon
Terminal
AUTO ROOT
Adminer
Backdoor Destroyer
Linux Exploit
Lock Shell
Lock File
Create User
CREATE RDP
PHP Mailer
BACKCONNECT
UNLOCK SHELL
HASH IDENTIFIER
README
+ Create Folder
+ Create File
/
opt /
saltstack /
salt /
share /
man /
man7 /
[ HOME SHELL ]
Name
Size
Permission
Action
salt.7
14.69
MB
-rw-r--r--
Delete
Unzip
Zip
${this.title}
Close
Code Editor : salt.7
.\" Man page generated from reStructuredText. . . .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 .. .TH "SALT" "7" "Generated on May 19, 2024 at 12:51:08 PM UTC." "3007.1" "Salt" .SH NAME salt \- Salt Documentation .SH SALT PROJECT \fI\%Salt Project License: Apache v2.0\fP\fI\%PyPi Package Downloads\fP\fI\%PyPi Package Downloads\fP\fI\%Salt Project Slack Community\fP\fI\%Salt Project Twitch Channel\fP\fI\%Salt Project subreddit\fP\fI\%Follow SaltStack on Twitter\fP.INDENT 0.0 .INDENT 2.5 [image: Salt Project Logo] [image] .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 \fI\%Latest Salt Documentation\fP .IP \(bu 2 \fI\%Open an issue\fP (bug report, feature request, etc.) .UNINDENT .sp \fISalt is the world\(aqs fastest, most intelligent and scalable automation\fP \fIengine.\fP .SS About Salt .sp Built on Python, Salt is an event\-driven automation tool and framework to deploy, configure, and manage complex IT systems. Use Salt to automate common infrastructure administration tasks and ensure that all the components of your infrastructure are operating in a consistent desired state. .sp Salt has many possible uses, including configuration management, which involves: .INDENT 0.0 .IP \(bu 2 Managing operating system deployment and configuration. .IP \(bu 2 Installing and configuring software applications and services. .IP \(bu 2 Managing servers, virtual machines, containers, databases, web servers, network devices, and more. .IP \(bu 2 Ensuring consistent configuration and preventing configuration drift. .UNINDENT .sp Salt is ideal for configuration management because it is pluggable, customizable, and plays well with many existing technologies. Salt enables you to deploy and manage applications that use any tech stack running on nearly any \fI\%operating system\fP, including different types of network devices such as switches and routers from a variety of vendors. .sp In addition to configuration management Salt can also: .INDENT 0.0 .IP \(bu 2 Automate and orchestrate routine IT processes, such as common required tasks for scheduled server downtimes or upgrading operating systems or applications. .IP \(bu 2 Create self\-aware, self\-healing systems that can automatically respond to outages, common administration problems, or other important events. .UNINDENT .SS About our sponsors .sp Salt powers VMware\(aqs \fI\%VMware Aria Automation Config\fP (previously vRealize Automation SaltStack Config / SaltStack Enterprise), and can be found under the hood of products from Juniper, Cisco, Cloudflare, Nutanix, SUSE, and Tieto, to name a few. .sp The original sponsor of our community, SaltStack, was \fI\%acquired by VMware in 2020\fP\&. The Salt Project remains an open source ecosystem that VMware supports and contributes to. VMware ensures the code integrity and quality of the Salt modules by acting as the official sponsor and manager of the Salt project. Many of the core Salt Project contributors are also VMware employees. This team carefully reviews and enhances the Salt modules to ensure speed, quality, and security. .SS Download and install Salt .sp Salt is tested and packaged to run on CentOS, Debian, RHEL, Ubuntu, MacOS, Windows, and more. Download Salt and get started now. See \fI\%supported operating systems\fP for more information. .sp To download and install Salt, see: * \fI\%The Salt install guide\fP * \fI\%Salt Project repository\fP .SS Technical support .sp Report bugs or problems using Salt by opening an issue: \fI\%https://github.com/saltstack/salt/issues\fP .sp To join our community forum where you can exchange ideas, best practices, discuss technical support questions, and talk to project maintainers, join our Slack workspace: \fI\%Salt Project Community Slack\fP .SS Salt Project documentation .sp Installation instructions, tutorials, in\-depth API and module documentation: .INDENT 0.0 .IP \(bu 2 \fI\%The Salt install guide\fP .IP \(bu 2 \fI\%The Salt user guide\fP .IP \(bu 2 \fI\%Latest Salt documentation\fP .IP \(bu 2 \fI\%Salt\(aqs contributing guide\fP .UNINDENT .SS Security advisories .sp Keep an eye on the Salt Project \fI\%Security Announcements\fP landing page. Salt Project recommends subscribing to the \fI\%Salt Project Security RSS feed\fP to receive notification when new information is available regarding security announcements. .sp Other channels to receive security announcements include the \fI\%Salt Community mailing list\fP and the \fI\%Salt Project Community Slack\fP\&. .SS Responsibly reporting security vulnerabilities .sp When reporting security vulnerabilities for Salt or other SaltStack projects, refer to the \fI\%SECURITY.md\fP file found in this repository. .SS Join our community .sp Salt is built by the Salt Project community, which includes more than 3,000 contributors working in roles just like yours. This well\-known and trusted community works together to improve the underlying technology and extend Salt by creating a variety of execution and state modules to accomplish the most common tasks or solve the most important problems that people in your role are likely to face. .sp If you want to help extend Salt or solve a problem with Salt, you can join our community and contribute today. .sp Please be sure to review our \fI\%Code of Conduct\fP\&. Also, check out some of our community resources including: .INDENT 0.0 .IP \(bu 2 \fI\%Salt Project Community Wiki\fP .IP \(bu 2 \fI\%Salt Project Community Slack\fP .IP \(bu 2 \fI\%Salt Project: IRC on LiberaChat\fP .IP \(bu 2 \fI\%Salt Project YouTube channel\fP .IP \(bu 2 \fI\%Salt Project Twitch channel\fP .UNINDENT .sp There are lots of ways to get involved in our community. Every month, there are around a dozen opportunities to meet with other contributors and the Salt Core team and collaborate in real time. The best way to keep track is by subscribing to the \fBSalt Project Community Events Calendar\fP on the main \fI\%https://saltproject.io\fP website. .sp If you have additional questions, email us at \fI\%saltproject@vmware.com\fP or reach out directly to the Community Manager, Jimmy Chunga via Slack. We\(aqd be glad to have you join our community! .SS License .sp Salt is licensed under the Apache 2.0 license. Please see the \fI\%LICENSE file\fP for the full text of the Apache license, followed by a full summary of the licensing used by external modules. .sp A complete list of attributions and dependencies can be found here: \fI\%salt/DEPENDENCIES.md\fP .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. .SH SALT SYSTEM ARCHITECTURE .SS Overview .sp This page provides a high\-level overview of the Salt system architecture and its different components. .SS What is Salt? .sp Salt is a Python\-based open\-source remote execution framework used for: .INDENT 0.0 .IP \(bu 2 Configuration management .IP \(bu 2 Automation .IP \(bu 2 Provisioning .IP \(bu 2 Orchestration .UNINDENT .SS The Salt system architecture .sp The following diagram shows the primary components of the basic Salt architecture: [image] .sp The following sections describe some of the core components of the Salt architecture. .SS Salt Masters and Salt Minions .sp Salt uses the master\-client model in which a master issues commands to a client and the client executes the command. In the Salt ecosystem, the Salt Master is a server that is running the \fBsalt\-master\fP service. It issues commands to one or more Salt Minions, which are servers that are running the \fBsalt\-minion\fP service and that are registered with that particular Salt Master. .sp Another way to describe Salt is as a publisher\-subscriber model. The master publishes jobs that need to be executed and Salt Minions subscribe to those jobs. When a specific job applies to that minion, it will execute the job. .sp When a minion finishes executing a job, it sends job return data back to the master. Salt has two ports used by default for the minions to communicate with their master(s). These ports work in concert to receive and deliver data to the Message Bus. Salt’s message bus is ZeroMQ, which creates an asynchronous network topology to provide the fastest communication possible. .SS Targets and grains .sp The master indicates which minions should execute the job by defining a \fItarget\fP\&. A target is the group of minions, across one or many masters, that a job\(aqs Salt command applies to. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 A master can also be managed like a minion and can be a target if it is running the \fBsalt\-minion\fP service. .UNINDENT .UNINDENT .sp The following is an example of one of the many kinds of commands that a master might issue to a minion. This command indicates that all minions should install the Vim application: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-v \(aq*\(aq pkg.install vim .ft P .fi .UNINDENT .UNINDENT .sp In this case the glob \fB\(aq*\(aq\fP is the target, which indicates that all minions should execute this command. Many other targeting options are available, including targeting a specific minion by its ID or targeting minions by their shared traits or characteristics (called \fIgrains\fP in Salt). .sp Salt comes with an interface to derive information about the underlying system. This is called the \fIgrains interface\fP, 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. You can also create your own custom grain data. .sp Grain data is relatively static. However, grain data is refreshed when system information changes (such as network settings) or when a new value is assigned to a custom grain. .SS Open event system (event bus) .sp The event system is used for inter\-process communication between the Salt Master and Salt Minions. In the event system: .INDENT 0.0 .IP \(bu 2 Events are seen by both the master and minions. .IP \(bu 2 Events can be monitored and evaluated by both. .UNINDENT .sp The event bus lays the groundwork for orchestration and real\-time monitoring. .sp All minions see jobs and results by subscribing to events published on the event system. Salt uses a pluggable event system with two layers: .INDENT 0.0 .IP \(bu 2 \fBZeroMQ (0MQ)\fP \- The current default socket\-level library providing a flexible transport layer. .IP \(bu 2 \fBTornado\fP \- Full TCP\-based transport layer event system. .UNINDENT .sp One of the greatest strengths of Salt is the speed of execution. The event system’s communication bus is more efficient than running a higher\-level web service (http). The remote execution system is the component that all components are built upon, allowing for decentralized remote execution to spread load across resources. .SS Salt states .sp In addition to remote execution, Salt provides another method for configuring minions by declaring which \fIstate\fP a minion should be in, otherwise referred to as \fISalt states\fP\&. Salt states make configuration management possible. You can use Salt states to deploy and manage infrastructure with simple YAML files. Using states, you can automate recursive and predictable tasks by queueing jobs for Salt to implement without needing user input. You can also add more complex conditional logic to state files with Jinja. .sp To illustrate the subtle differences between remote execution and configuration management, take the command referenced in the previous section about \fI\%Targets and grains\fP in which Salt installed the application Vim on all minions: .TS center; |l|l|l|. _ T{ Methodology T} T{ Implementation T} T{ Result T} _ T{ Remote execution T} T{ .INDENT 0.0 .IP \(bu 2 Run \fBsalt \-v \(aq*\(aq pkg.install vim\fP from the terminal .UNINDENT T} T{ .INDENT 0.0 .IP \(bu 2 Remotely installs Vim on the targeted minions .UNINDENT T} _ T{ Configuration management T} T{ .INDENT 0.0 .IP \(bu 2 Write a YAML state file that checks whether Vim is installed .IP \(bu 2 This state file is then applied to the targeted minions .UNINDENT T} T{ .INDENT 0.0 .IP \(bu 2 Ensures that Vim is always installed on the targeted minions .IP \(bu 2 Salt analyzes the state file and determines what actions need to be taken to ensure the minion complies with the state declarations .IP \(bu 2 If Vim is not installed, it automates the processes to install Vim on the targeted minions .UNINDENT T} _ .TE .sp The state file that verifies Vim is installed might look like the following example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # File:/srv/salt/vim_install.sls install_vim_now: pkg.installed: \- pkgs: \- vim .ft P .fi .UNINDENT .UNINDENT .sp To apply this state to a minion, you would use the \fBstate.apply\fP module, such as in the following example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply vim_install .ft P .fi .UNINDENT .UNINDENT .sp This command applies the \fBvim_install\fP state to all minions. .sp \fIFormulas\fP are collections of states that work in harmony to configure a minion or application. For example, one state might trigger another state. .SS The Top file .sp It is not practical to manually run each state individually targeting specific minions each time. Some environments have hundreds of state files targeting thousands of minions. .sp Salt offers two features to help with this scaling problem: .INDENT 0.0 .IP \(bu 2 \fBThe top.sls file\fP \- Maps Salt states to their applicable minions. .IP \(bu 2 \fBHighstate execution\fP \- Runs all Salt states outlined in \fBtop.sls\fP in a single execution. .UNINDENT .sp The top file maps which states should be applied to different minions in certain environments. The following is an example of a simple top file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # File: /srv/salt/top.sls base: \(aq*\(aq: \- all_server_setup \(aq01webserver\(aq: \- web_server_setup .ft P .fi .UNINDENT .UNINDENT .sp In this example, \fBbase\fP refers to the Salt environment, which is the default. You can specify more than one environment as needed, such as prod, dev, QA, etc. .sp Groups of minions are specified under the environment, and states are listed for each set of minions. This top file indicates that a state called \fBall_server_setup\fP should be applied to all minions \fB\(aq*\(aq\fP and the state called \fBweb_server_setup\fP should be applied to the \fB01webserver\fP minion. .sp To run the Salt command, you would use the state.highstate function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \e* state.highstate .ft P .fi .UNINDENT .UNINDENT .sp This command applies the top file to the targeted minions. .SS Salt pillar .sp Salt’s pillar feature takes data defined on the Salt Master and distributes it to minions as needed. Pillar is primarily used to store secrets or other highly sensitive data, such as account credentials, cryptographic keys, or passwords. Pillar is also useful for storing non\-secret data that you don\(aqt want to place directly in your state files, such as configuration data. .sp Salt pillar brings data into the cluster from the opposite direction as grains. While grains are data generated from the minion, the pillar is data generated from the master. .sp Pillars are organized similarly to states in a Pillar state tree, where \fBtop.sls\fP acts to coordinate pillar data to environments and minions privy to the data. Information transferred using pillar has a dictionary generated for the targeted minion and encrypted with that minion’s key for secure data transfer. Pillar data is encrypted on a per\-minion basis, which makes it useful for storing sensitive data specific to a particular minion. .SS Beacons and reactors .sp The beacon system is a monitoring tool that can listen for a variety of system processes on Salt Minions. Beacons can trigger reactors which can then help implement a change or troubleshoot an issue. For example, if a service’s response times out, the reactor system can restart the service. .sp Beacons are used for a variety of purposes, including: .INDENT 0.0 .IP \(bu 2 Automated reporting .IP \(bu 2 Error log delivery .IP \(bu 2 Microservice monitoring .IP \(bu 2 User shell activity .IP \(bu 2 Resource monitoring .UNINDENT .sp When coupled with reactors, beacons can create automated pre\-written responses to infrastructure and application issues. Reactors expand Salt with automated responses using pre\-written remediation states. .sp Reactors can be applied in a variety of scenarios: .INDENT 0.0 .IP \(bu 2 Infrastructure scaling .IP \(bu 2 Notifying administrators .IP \(bu 2 Restarting failed applications .IP \(bu 2 Automatic rollback .UNINDENT .sp When both beacons and reactors are used together , you can create unique states customized to your specific needs. .SS Salt runners and orchestration .sp Salt runners are convenience applications executed with the \fBsalt\-run\fP command. Salt runners work similarly to Salt execution modules. However, they execute on the Salt Master instead of the Salt Minions. A Salt runner can be a simple client call or a complex application. .sp Salt provides the ability to orchestrate system administrative tasks throughout the enterprise. Orchestration makes it possible to coordinate the activities of multiple machines from a central place. It has the added advantage of being able to control the sequence of when certain configuration events occur. Orchestration states execute on the master using the state runner module. .SH CONTRIBUTING .sp So you want to contribute to the Salt project? Excellent! You can help in a number of ways: .INDENT 0.0 .IP \(bu 2 Use Salt and open well\-written bug reports. .IP \(bu 2 Join a \fI\%working group\fP\&. .IP \(bu 2 Answer questions on \fI\%irc\fP, the \fI\%community Slack\fP, the \fI\%salt\-users mailing list\fP, \fI\%Server Fault\fP, or \fI\%r/saltstack on Reddit\fP\&. .IP \(bu 2 Fix bugs. .IP \(bu 2 \fI\%Improve the documentation\fP\&. .IP \(bu 2 Provide workarounds, patches, or other code without tests. .IP \(bu 2 Tell other people about problems you solved using Salt. .UNINDENT .sp If you\(aqd like to update docs or fix an issue, you\(aqre going to need the Salt repo. The best way to contribute is using \fI\%Git\fP\&. .SS Environment setup .sp To hack on Salt or the docs you\(aqre going to need to set up your development environment. If you already have a workflow that you\(aqre comfortable with, you can use that, but otherwise this is an opinionated guide for setting up your dev environment. Follow these steps and you\(aqll end out with a functioning dev environment and be able to submit your first PR. .sp This guide assumes at least a passing familiarity with \fI\%Git\fP, a common version control tool used across many open source projects, and is necessary for contributing to Salt. For an introduction to Git, watch \fI\%Salt Docs Clinic \- Git For the True Beginner\fP\&. Because of its widespread use, there are many resources for learning more about Git. One popular resource is the free online book \fI\%Learn Git in a Month of Lunches\fP\&. .SS pyenv, Virtual Environments, and you .sp We recommend \fI\%pyenv\fP, since it allows installing multiple different Python versions, which is important for testing Salt across all the versions of Python that we support. .SS On Linux .sp Install pyenv: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone https://github.com/pyenv/pyenv.git ~/.pyenv export PATH=\(dq$HOME/.pyenv/bin:$PATH\(dq git clone https://github.com/pyenv/pyenv\-virtualenv.git $(pyenv root)/plugins/pyenv\-virtualenv .ft P .fi .UNINDENT .UNINDENT .SS On Mac .sp Install pyenv using brew: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C brew update brew install pyenv brew install pyenv\-virtualenv .ft P .fi .UNINDENT .UNINDENT .sp .ce ---- .ce 0 .sp .sp Now add pyenv to your \fB\&.bashrc\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C echo \(aqexport PATH=\(dq$HOME/.pyenv/bin:$PATH\(dq\(aq >> ~/.bashrc pyenv init 2>> ~/.bashrc pyenv virtualenv\-init 2>> ~/.bashrc .ft P .fi .UNINDENT .UNINDENT .sp For other shells, see \fI\%the pyenv instructions\fP\&. .sp Go ahead and restart your shell. Now you should be able to install a new version of Python: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pyenv install 3.9.18 .ft P .fi .UNINDENT .UNINDENT .sp If that fails, don\(aqt panic! You\(aqre probably just missing some build dependencies. Check out \fI\%pyenv common build problems\fP\&. .sp Now that you\(aqve got your version of Python installed, you can create a new virtual environment with this command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pyenv virtualenv 3.9.18 salt .ft P .fi .UNINDENT .UNINDENT .sp Then activate it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pyenv activate salt .ft P .fi .UNINDENT .UNINDENT .sp Sweet! Now you\(aqre ready to clone Salt so you can start hacking away! If you get stuck at any point, check out the resources at the beginning of this guide. IRC and Slack are particularly helpful places to go. .SS Get the source! .sp Salt uses the fork and clone workflow for Git contributions. See \fI\%Using the Fork\-and\-Branch Git Workflow\fP for how to implement it. But if you just want to hurry and get started you can go ahead and follow these steps: .sp Clones are so shallow. Well, this one is anyway: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone \-\-depth=1 \-\-origin salt https://github.com/saltstack/salt.git .ft P .fi .UNINDENT .UNINDENT .sp This creates a shallow clone of Salt, which should be fast. Most of the time that\(aqs all you\(aqll need, and you can start building out other commits as you go. If you \fIreally\fP want all 108,300+ commits you can just run \fBgit fetch \-\-unshallow\fP\&. Then go make a sandwich because it\(aqs gonna be a while. .sp You\(aqre also going to want to head over to GitHub and create your own \fI\%fork of Salt\fP\&. Once you\(aqve got that set up you can add it as a remote: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git remote add yourname <YOUR SALT REMOTE> .ft P .fi .UNINDENT .UNINDENT .sp If you use your name to refer to your fork, and \fBsalt\fP to refer to the official Salt repo you\(aqll never get \fBupstream\fP or \fBorigin\fP confused. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Each time you start work on a new issue you should fetch the most recent changes from \fBsalt/upstream\fP\&. .UNINDENT .UNINDENT .SS Set up \fBpre\-commit\fP and \fBnox\fP .sp Here at Salt we use \fI\%pre\-commit\fP and \fI\%nox\fP to make it easier for contributors to get quick feedback, for quality control, and to increase the chance that your merge request will get reviewed and merged. Nox enables us to run multiple different test configurations, as well as other common tasks. You can think of it as Make with superpowers. Pre\-commit does what it sounds like: it configures some Git pre\-commit hooks to run \fBblack\fP for formatting, \fBisort\fP for keeping our imports sorted, and \fBpylint\fP to catch issues like unused imports, among others. You can easily install them in your virtualenv with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-m pip install pre\-commit nox pre\-commit install .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Currently there is an issue with the pip\-tools\-compile pre\-commit hook on Windows. The details around this issue are included here: \fI\%https://github.com/saltstack/salt/issues/56642\fP\&. Please ensure you export \fBSKIP=pip\-tools\-compile\fP to skip pip\-tools\-compile. .UNINDENT .UNINDENT .sp Now before each commit, it will ensure that your code at least \fIlooks\fP right before you open a pull request. And with that step, it\(aqs time to start hacking on Salt! .SS Set up imagemagick .sp One last prerequisite is to have \fBimagemagick\fP installed, as it is required by Sphinx for generating the HTML documentation. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # On Mac, via homebrew brew install imagemagick .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Example Linux installation: Debian\-based sudo apt install imagemagick .ft P .fi .UNINDENT .UNINDENT .SS Salt issues .SS Create your own .sp Perhaps you\(aqve come to this guide because you found a problem in Salt, and you\(aqve diagnosed the cause. Maybe you need some help figuring out the problem. In any case, creating quality bug reports is a great way to contribute to Salt even if you lack the skills, time, or inclination to fix it yourself. If that\(aqs the case, head on over to \fI\%Salt\(aqs issue tracker on GitHub\fP\&. .sp Creating a \fBgood\fP report can take a little bit of time \- but every minute you invest in making it easier for others to reproduce and understand your issue is time well spent. The faster someone can understand your issue, the faster it will be able to get fixed correctly. .sp The thing that every issue needs goes by many names, but one at least as good as any other is MCVE \- \fBM\fPinimum \fBC\fPomplete \fBV\fPerifiable \fBE\fPxample. .sp In a nutshell: .INDENT 0.0 .IP \(bu 2 \fBMinimum\fP: All of the \fBextra\fP information has been removed. Will 2 or 3 lines of master/minion config still exhibit the behavior? .IP \(bu 2 \fBComplete\fP: Minimum also means complete. If your example is missing information, then it\(aqs not complete. Salt, Python, and OS versions are all bits of information that make your example complete. Have you provided the commands that you ran? .IP \(bu 2 \fBVerifiable\fP: Can someone take your report and reproduce it? .UNINDENT .sp Slow is smooth, and smooth is fast \- it may feel like you\(aqre taking a long time to create your issue if you\(aqre creating a proper MCVE, but a MCVE eliminates back and forth required to reproduce/verify the issue so someone can actually create a fix. .SS Pick an issue .sp If you don\(aqt already have an issue in mind, you can search for \fI\%help wanted\fP issues. If you also search for \fI\%good first issue\fP then you should be able to find some issues that are good for getting started contributing to Salt. \fI\%Documentation issues\fP are also good starter issues. When you find an issue that catches your eye (or one of your own), it\(aqs a good idea to comment on the issue and mention that you\(aqre working on it. Good communication is key to collaboration \- so if you don\(aqt have time to complete work on the issue, just leaving some information about when you expect to pick things up again is a great idea! .SS Hacking away .SS Salt, tests, documentation, and you .sp Before approving code contributions, Salt requires: .INDENT 0.0 .IP \(bu 2 documentation .IP \(bu 2 meaningful passing tests .IP \(bu 2 correct code .UNINDENT .sp Documentation fixes just require correct documentation. .SS What if I don\(aqt write tests or docs? .sp If you aren\(aqt into writing documentation or tests, we still welcome your contributions! But your PR will be labeled \fBNeeds Testcase\fP and \fBHelp Wanted\fP until someone can get to write the tests/documentation. Of course, if you have a desire but just lack the skill we are more than happy to collaborate and help out! There\(aqs the \fI\%documentation working group\fP and the \fI\%testing working group\fP\&. We also regularly stream our test clinic \fI\%live on Twitch\fP every Tuesday afternoon and Thursday morning, Central Time. If you\(aqd like specific help with tests, bring them to the clinic. If no community members need help, you can also just watch tests written in real time. .SS Documentation .sp Salt uses both docstrings, as well as normal reStructuredText files in the \fBsalt/doc\fP folder for documentation. Sphinx is used to generate the documentation, and does require \fBimagemagick\fP\&. See \fI\%Set up imagemagick\fP for more information. .sp Before submitting a documentation PR, it helps to first build the Salt docs locally on your machine and preview them. Local previews helps you: .INDENT 0.0 .IP \(bu 2 Debug potential documentation output errors before submitting a PR. .IP \(bu 2 Saves you time by not needing to use the Salt CI/CD test suite to debug, which takes more than 30 minutes to run on a PR. .IP \(bu 2 Ensures the final output looks the way you intended it to look. .UNINDENT .sp To set up your local environment to preview the core Salt and module documentation: .INDENT 0.0 .IP 1. 3 Install the documentation dependencies. For example, on Ubuntu: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C sudo apt\-get update sudo apt\-get install \-y enchant\-2 git gcc imagemagick make zlib1g\-dev libc\-dev libffi\-dev g++ libxml2 libxml2\-dev libxslt\-dev libcurl4\-openssl\-dev libssl\-dev libgnutls28\-dev xz\-utils inkscape .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 Navigate to the folder where you store your Salt repository and remove any \fI\&.nox\fP directories that might be in that folder: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C rm \-rf .nox .ft P .fi .UNINDENT .UNINDENT .IP 3. 3 Install \fIpyenv\fP for the version of Python needed to run the docs. As of the time of writing, the Salt docs theme is not compatible with Python 3.10, so you\(aqll need to run 3.9 or earlier. For example: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C pyenv install 3.9.18 pyenv virtualenv 3.9.18 salt\-docs echo \(aqsalt\-docs\(aq > .python\-version .ft P .fi .UNINDENT .UNINDENT .IP 4. 3 Activate \fIpyenv\fP if it\(aqs not auto\-activated: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C pyenv exec pip install \-U pip setuptools wheel .ft P .fi .UNINDENT .UNINDENT .IP 5. 3 Install \fInox\fP into your pyenv environment, which is the utility that will build the Salt documentation: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C pyenv exec pip install nox .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Since we use \fBnox\fP, you can build your docs and view them in your browser with this one\-liner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-m nox \-e \(aqdocs\-html(compress=False, clean=False)\(aq; cd doc/_build/html; python \-m webbrowser http://localhost:8000/contents.html; python \-m http.server .ft P .fi .UNINDENT .UNINDENT .sp The first time you build the docs, it will take a while because there are a \fIlot\fP of modules. Maybe you should go grab some dessert if you already finished that sandwich. But once nox and Sphinx are done building the docs, python should launch your default browser with the URL \fI\%http://localhost:8000/contents.html\fP\&. Now you can navigate to your docs and ensure your changes exist. If you make changes, you can simply run this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd \-; python \-m nox \-e \(aqdocs\-html(compress=False, clean=False)\(aq; cd doc/_build/html; python \-m http.server .ft P .fi .UNINDENT .UNINDENT .sp And then refresh your browser to get your updated docs. This one should be quite a bit faster since Sphinx won\(aqt need to rebuild everything. .sp Alternatively, you could build the docs on your local machine and then preview the build output. To build the docs locally: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pyenv exec nox \-e \(aqdocs\-html(compress=False, clean=True)\(aq .ft P .fi .UNINDENT .UNINDENT .sp The output from this command will put the preview files in: \fBdoc > _build > html\fP\&. .sp If your change is a docs\-only change, you can go ahead and commit/push your code and open a PR. You can indicate that it\(aqs a docs\-only change by adding \fB[Documentation]\fP to the title of your PR. Otherwise, you\(aqll want to write some tests and code. .SS Running development Salt .sp Note: If you run into any issues in this section, check the Troubleshooting section. .sp If you\(aqre going to hack on the Salt codebase you\(aqre going to want to be able to run Salt locally. The first thing you need to do is install Salt as an editable pip install: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-m pip install \-e . .ft P .fi .UNINDENT .UNINDENT .sp This will let you make changes to Salt without having to re\-install it. .sp After all of the dependencies and Salt are installed, it\(aqs time to set up the config for development. Typically Salt runs as \fBroot\fP, but you can specify which user to run as. To configure that, just copy the master and minion configs. We have .gitignore setup to ignore the \fBlocal/\fP directory, so we can put all of our personal files there. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir \-p local/etc/salt/ .ft P .fi .UNINDENT .UNINDENT .sp Create a master config file as \fBlocal/etc/salt/master\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cat <<EOF >local/etc/salt/master user: $(whoami) root_dir: $PWD/local/ publish_port: 55505 ret_port: 55506 EOF .ft P .fi .UNINDENT .UNINDENT .sp And a minion config as \fBlocal/etc/salt/minion\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cat <<EOF >local/etc/salt/minion user: $(whoami) root_dir: $PWD/local/ master: localhost id: saltdev master_port: 55506 EOF .ft P .fi .UNINDENT .UNINDENT .sp Now you can start your Salt master and minion, specifying the config dir. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-master \-\-config\-dir=local/etc/salt/ \-\-log\-level=debug \-\-daemon salt\-minion \-\-config\-dir=local/etc/salt/ \-\-log\-level=debug \-\-daemon .ft P .fi .UNINDENT .UNINDENT .sp Now you should be able to accept the minion key: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-c local/etc/salt \-Ay .ft P .fi .UNINDENT .UNINDENT .sp And check that your master/minion are communicating: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-c local/etc/salt \e* test.version .ft P .fi .UNINDENT .UNINDENT .sp Rather than running \fBtest.version\fP from your master, you can run it from the minion instead: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-c local/etc/salt test.version .ft P .fi .UNINDENT .UNINDENT .sp Note that you\(aqre running \fBsalt\-call\fP instead of \fBsalt\fP, and you\(aqre not specifying the minion (\fB\e*\fP), but if you\(aqre running the dev version then you still will need to pass in the config dir. Now that you\(aqve got Salt running, you can hack away on the Salt codebase! .sp If you need to restart Salt for some reason, if you\(aqve made changes and they don\(aqt appear to be reflected, this is one option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C kill \-INT $(pgrep salt\-master) kill \-INT $(pgrep salt\-minion) .ft P .fi .UNINDENT .UNINDENT .sp If you\(aqd rather not use \fBkill\fP, you can have a couple of terminals open with your salt virtualenv activated and omit the \fB\-\-daemon\fP argument. Salt will run in the foreground, so you can just use ctrl+c to quit. .SS Test first? Test last? Test meaningfully! .sp You can write tests first or tests last, as long as your tests are meaningful and complete! \fITypically\fP the best tests for Salt are going to be unit tests. Testing is \fI\%a whole topic on its own\fP, But you may also want to write functional or integration tests. You\(aqll find those in the \fBtests/\fP directory. .sp When you\(aqre thinking about tests to write, the most important thing to keep in mind is, “What, exactly, am I testing?” When a test fails, you should know: .INDENT 0.0 .IP \(bu 2 What, specifically, failed? .IP \(bu 2 Why did it fail? .IP \(bu 2 As much as possible, what do I need to do to fix this failure? .UNINDENT .sp If you can\(aqt answer those questions then you might need to refactor your tests. .sp When you\(aqre running tests locally, you should make sure that if you remove your code changes your tests are failing. If your tests \fIaren\(aqt\fP failing when you haven\(aqt yet made changes, then it\(aqs possible that you\(aqre testing the wrong thing. .sp But whether you adhere to TDD/BDD, or you write your code first and your tests last, ensure that your tests are meaningful. .SS Running tests .sp As previously mentioned, we use \fBnox\fP, and that\(aqs how we run our tests. You should have it installed by this point but if not you can install it with this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-m pip install nox .ft P .fi .UNINDENT .UNINDENT .sp Now you can run your tests: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-m nox \-e \(dqtest\-3(coverage=False)\(dq \-\- tests/unit/cli/test_batch.py .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs a good idea to install \fI\%espeak\fP or use \fBsay\fP on Mac if you\(aqre running some long\-running tests. You can do something like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-m nox \-e \(dqtest\-3(coverage=False)\(dq \-\- tests/unit/cli/test_batch.py; espeak \(dqTests done, woohoo!\(dq .ft P .fi .UNINDENT .UNINDENT .sp That way you don\(aqt have to keep monitoring the actual test run. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-m nox \-e \(dqtest\-3(coverage=False)\(dq \-\- \-\-core\-tests .ft P .fi .UNINDENT .UNINDENT .sp You can enable or disable test groups locally by passing their respected flag: .INDENT 0.0 .IP \(bu 2 \-\-no\-fast\-tests \- Tests that are ~10s or faster. Fast tests make up ~75% of tests and can run in 10 to 20 minutes. .IP \(bu 2 \-\-slow\-tests \- Tests that are ~10s or slower. .IP \(bu 2 \-\-core\-tests \- Tests of any speed that test the root parts of salt. .IP \(bu 2 \-\-flaky\-jail \- Test that need to be temporarily skipped. .UNINDENT .sp In your PR, you can enable or disable test groups by setting a label. All fast, slow, and core tests specified in the change file will always run. .INDENT 0.0 .IP \(bu 2 test:no\-fast .IP \(bu 2 test:core .IP \(bu 2 test:slow .IP \(bu 2 test:flaky\-jail .UNINDENT .SS Changelog and commit! .sp When you write your commit message you should use imperative style. Do this: .INDENT 0.0 .INDENT 3.5 Add frobnosticate capability .UNINDENT .UNINDENT .sp Don\(aqt do this: .INDENT 0.0 .INDENT 3.5 Added frobnosticate capability .UNINDENT .UNINDENT .sp But that advice is backwards for the changelog. We follow the \fI\%keepachangelog\fP approach for our changelog, and use towncrier to generate it for each release. As a contributor, all that means is that you need to add a file to the \fBsalt/changelog\fP directory, using the \fB<issue #>.<type>\fP format. For instance, if you fixed issue 123, you would do: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C echo \(dqMade sys.doc inform when no minions return\(dq > changelog/123.fixed .ft P .fi .UNINDENT .UNINDENT .sp And that\(aqs all that would go into your file. When it comes to your commit message, it\(aqs usually a good idea to add other information, such as .INDENT 0.0 .IP \(bu 2 What does a reviewer need to know about the change that you made? .IP \(bu 2 If someone isn\(aqt an expert in this area, what will they need to know? .UNINDENT .sp This will also help you out, because when you go to create the PR it will automatically insert the body of your commit messages. .sp See the \fI\%changelog\fP docs for more information. .SS Pull request time! .sp Once you\(aqve done all your dev work and tested locally, you should check out our \fI\%PR guidelines\fP\&. After you read that page, it\(aqs time to \fI\%open a new PR\fP\&. Fill out the PR template \- you should have updated or created any necessary docs, and written tests if you\(aqre providing a code change. When you submit your PR, we have a suite of tests that will run across different platforms to help ensure that no known bugs were introduced. .SS Now what? .sp You\(aqve made your changes, added documentation, opened your PR, and have passing tests… now what? When can you expect your code to be merged? .sp When you open your PR, a reviewer will get automatically assigned. If your PR is submitted during the week you should be able to expect some kind of communication within that business day. If your tests are passing and we\(aqre not in a code freeze, ideally your code will be merged that week or month. If you haven\(aqt heard from your assigned reviewer, ping them on GitHub, \fI\%irc\fP, or Community Slack. .sp It\(aqs likely that your reviewer will leave some comments that need addressing \- it may be a style change, or you forgot a changelog entry, or need to update the docs. Maybe it\(aqs something more fundamental \- perhaps you encountered the rare case where your PR has a much larger scope than initially assumed. .sp Whatever the case, simply make the requested changes (or discuss why the requests are incorrect), and push up your new commits. If your PR is open for a significant period of time it may be worth rebasing your changes on the most recent changes to Salt. If you need help, the previously linked Git resources will be valuable. .sp But if, for whatever reason, you\(aqre not interested in driving your PR to completion then just note that in your PR. Something like, “I\(aqm not interested in writing docs/tests, I just wanted to provide this fix \- someone else will need to complete this PR.” If you do that then we\(aqll add a “Help Wanted” label and someone will be able to pick up the PR, make the required changes, and it can eventually get merged in. .sp In any case, now that you have a PR open, congrats! You\(aqre a Salt developer! You rock! .SS Troubleshooting .SS zmq.core.error.ZMQError .sp Once the minion starts, you may see an error like the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C :: .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 zmq.core.error.ZMQError: ipc path \(dq/path/to/your/virtualenv/var/run/salt/minion/minion_event_7824dcbcfd7a8f6755939af70b96249f_pub.ipc\(dq is longer than 107 characters (sizeof(sockaddr_un.sun_path)). .UNINDENT .UNINDENT .sp This means that the path to the socket the minion is using is too long. This is a system limitation, so the only workaround is to reduce the length of this path. This can be done in a couple different ways: .INDENT 0.0 .IP 1. 3 Create your virtualenv in a path that is short enough. .IP 2. 3 Edit the :conf_minion:\fBsock_dir\fP minion config variable and reduce its length. Remember that this path is relative to the value you set in :conf_minion:\fBroot_dir\fP\&. .UNINDENT .sp NOTE: The socket path is limited to 107 characters on Solaris and Linux, and 103 characters on BSD\-based systems. .SS No permissions to access ... .sp If you forget to pass your config path to any of the \fBsalt*\fP commands, you might see .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C No permissions to access \(dq/var/log/salt/master\(dq, are you running as the correct user? .ft P .fi .UNINDENT .UNINDENT .sp Just pass \fB\-c local/etc/salt\fP (or whatever you named it) .SS File descriptor limit .sp You might need to raise your file descriptor limit. You can check it with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ulimit \-n .ft P .fi .UNINDENT .UNINDENT .sp If the value is less than 3072, you should increase it with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ulimit \-n 3072 # For c\-shell: limit descriptors 3072 .ft P .fi .UNINDENT .UNINDENT .SS Pygit2 or other dependency install fails .sp You may see some failure messages when installing requirements. You can directly access your nox environment and possibly install pygit (or other dependency) that way. When you run nox, you\(aqll see a message like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nox > Re\-using existing virtual environment at .nox/pytest\-parametrized\-3\-crypto\-none\-transport\-zeromq\-coverage\-false. .ft P .fi .UNINDENT .UNINDENT .sp For this, you would be able to install with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&.nox/pytest\-parametrized\-3\-crypto\-none\-transport\-zeromq\-coverage\-false/bin/python \-m pip install pygit2 .ft P .fi .UNINDENT .UNINDENT .SH SALT PROJECT MAINTENANCE POLICIES .sp This document explains the current project maintenance policies. The goal of these policies are to reduce the maintenance burden on core maintainers of the Salt Project and to encourage more active engagement from the Salt community. .INDENT 0.0 .IP \(bu 2 \fI\%Issue management\fP .IP \(bu 2 \fI\%Pull request management\fP .IP \(bu 2 \fI\%Salt Enhancement Proposals (SEP) process\fP .UNINDENT .SS Issue management .sp Issues for the Salt Project are critical to Salt community communication and to find and resolve issues in the Salt Project. As such, the issue tracker needs to be kept clean and current to the currently supported releases of Salt. They also need to be free of feature requests, arguments, and trolling. .sp We have decided to update our issue policy to be similar to RedHat community project policies. .sp Community members who repeatedly violate these policies are subject to bans. .INDENT 0.0 .IP 1. 3 All issues that were not opened against a currently supported release of Salt will be closed. .INDENT 3.0 .IP \(bu 2 When an old release of Salt is marked out of support, all issues opened against the now defunct release will be closed. .IP \(bu 2 If the issue is still present in the current release of Salt, submit a new issue. Do not re\-open the old issue after it has been closed. .IP \(bu 2 When opening a new issue that was a bug in a previous release of Salt, you must validate it against a currently supported release of Salt for consideration. Issues that do not show the problem against a current release will be closed without consideration. .UNINDENT .IP 2. 3 Only defects can be submitted to the issue tracker. .INDENT 3.0 .IP \(bu 2 Feature requests without a PR will be immediately closed. .IP \(bu 2 Feature requests must be designated as a feature being developed and owned by the issue submitter and assigned to a release. Otherwise they will be immediately closed. .IP \(bu 2 Discussions about features can be held in the GitHub \fI\%Discussions\fP tab or in the community \fI\%Open Hour\fP\&. .IP \(bu 2 Questions will be immediately closed. .UNINDENT .IP 3. 3 Issues must submit sufficient information. .INDENT 3.0 .IP \(bu 2 Issues must follow the relevant template for information. .IP \(bu 2 Issues that do not give sufficient information about the nature of the issue \fBand how to reproduce the issue\fP will be immediately closed. .IP \(bu 2 Issues that do not comply will be immediately closed. .UNINDENT .UNINDENT .SS Pull request management .sp The Salt pull request (PR) queue has been a challenge to maintain for the entire life of the project. This is in large part due to the incredibly active and vibrant community around Salt. .sp Unfortunately, it has proven to be too much for the core team and the greater Salt community to manage. As such, we deem it necessary to make fundamental changes to how we manage the PR queue: .INDENT 0.0 .IP 1. 3 All PRs opened against releases of Salt that are no longer supported will be closed immediately. .IP 2. 3 Closed PRs can be resubmitted, NOT re\-opened. .IP 3. 3 PRs need to provide full tests for all of the code affected, regardless of whether the PR author wrote the code affected. .IP 4. 3 PR tests need to be written using the current test mechanism (pytest). .IP 5. 3 PRs need to pass tests. .IP 6. 3 PRs must NOT increase the overall test time by a noticeable length. .IP 7. 3 PRs must NOT add new plugins directly to Salt unless sanctioned by the Salt core team. New plugins should be made into Salt Extensions. .IP 8. 3 PRs that have not been updated due to inactivity will be closed. Inactivity is determined by a lack of submitter activity for the space of 1 month. .IP 9. 3 PR tests should always maintain or increase total code coverage. .UNINDENT .SS Salt Enhancement Proposals (SEP) process .sp \fBA message from Thomas Hatch, creator of Salt:\fP .sp In 2019, we decided to create a community process to discuss and review Salt Enhancement Proposals (SEPs). Unfortunately, I feel that this process has not proven to be an effective way to solve the core issues around Salt Enhancements. Overall, the Salt enhancement process has proven itself to be more of a burden than an accelerant to Salt stability, security, and progress. As such, I feel that the current optimal course of action is to shut the process down. .sp Instead of the Salt Enhancement Proposal process, we will add a time in the \fI\%Open Hour\fP for people to present ideas and concepts to better understand if they are worth their effort to develop. Extensive documentation around more intrusive or involved enhancements should be included in pull requests (PRs). Conversations about enhancements can also be held in the \fI\%Discussions\fP tab in GitHub. .sp By migrating the conversation into the PR process, we ensure that we are only reviewing viable proposals instead of being burdened with requests that the core team is expected to fulfill. .sp Effective immediately (January 2024), we are archiving and freezing the SEP repo. .SH INSTALLATION .sp See the \fI\%Salt Install Guide\fP for the current installation instructions. .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 Salt .sp Salt configuration is very simple. The default configuration for the \fI\%master\fP will work for most installations and the only requirement for setting up a \fI\%minion\fP 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 \(dqinterface\(dq 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 \fI\%master configuration reference\fP for more details about other configurable options. .SS Minion Configuration .sp Although there are many Salt Minion configuration options, configuring a Salt Minion is very simple. By default a Salt Minion will try to connect to the DNS name \(dqsalt\(dq; if the Minion is able to resolve that name correctly, no configuration is needed. .sp If the DNS name \(dqsalt\(dq does not resolve to point to the correct location of the Master, redefine the \(dqmaster\(dq 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 \fI\%minion configuration reference\fP 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 \(dqsalt\(dq. .sp In addition to the regular minion options, there are several proxy\-specific \- see the \fI\%proxy minion configuration reference\fP\&. .SS Running Salt .INDENT 0.0 .IP 1. 3 Start the master in the foreground (to daemonize the process, pass the \fI\%\-d flag\fP): .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt\-master .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 Start the minion in the foreground (to daemonize the process, pass the \fI\%\-d flag\fP): .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt\-minion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .IP "Having trouble?" .sp The simplest way to troubleshoot Salt is to run the master and minion in the foreground with \fI\%log 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 \fI\%logging document\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .IP "Run as an unprivileged (non\-root) user" .sp To run Salt as another user, set the \fI\%user\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 \fI\%here\fP\&. .UNINDENT .UNINDENT .sp There is also a full \fI\%troubleshooting guide\fP 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 \fI\%master_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 <MINION_ID>\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 \fI\%salt\-key manpage\fP .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 \fI\%targeting\fP is important. From there, depending on the way you wish to use Salt, you should also proceed to learn about \fI\%Remote Execution\fP and \fI\%Configuration Management\fP\&. .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 \fI\%Example master configuration file\fP\&. .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 Enabling this does not influence the limitations on cross\-minion communication. The Salt mine and \fBpublish.publish\fP do not work from regular minions to SSH minions, the other way around is partly possible since 3007.0 (during state rendering on the master). This means you can use the mentioned functions to call out to regular minions in \fBsls\fP templates and wrapper modules, but state modules (which are executed on the remote) relying on them still do not work. .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<LIB_STATE_DIR>/pki/master\fP .sp The directory to store the pki authentication keys. .sp \fB<LIB_STATE_DIR>\fP is the pre\-configured variable state directory set during installation via \fB\-\-salt\-lib\-state\-dir\fP\&. It defaults to \fB/etc/salt\fP\&. Systems following the Filesystem Hierarchy Standard (FHS) might set it to \fB/var/lib/salt\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pki_dir: /etc/salt/pki/master .ft P .fi .UNINDENT .UNINDENT .SS \fBcluster_id\fP .sp New in version 3007. .sp When defined, the master will operate in cluster mode. The master will send the cluster key and id to minions instead of its own key and id. The master will also forward its local event bus to other masters defined by \fBcluster_peers\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cluster_id: master .ft P .fi .UNINDENT .UNINDENT .SS \fBcluster_peers\fP .sp New in version 3007. .sp When \fBcluster_id\fP is defined, this setting is a list of other master (hostnames or ips) that will be in the cluster. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cluster_peers: \- master2 \- master3 .ft P .fi .UNINDENT .UNINDENT .SS \fBcluster_pki_dir\fP .sp New in version 3007. .sp When \fBcluster_id\fP is defined, this sets the location of where this cluster will store its cluster public and private key as well as any minion keys. This setting will default to the value of \fBpki_dir\fP, but should be changed to the filesystem location shared between peers in the cluster. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cluster_pki: /my/gluster/share/pki .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 where custom modules are synced to. 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\&. .sp Note, any directories or files not found in the \fImodule_dirs\fP location will be removed from the extension_modules path. .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. .sp Deprecated since version 3006: Replaced by \fI\%keep_jobs_seconds\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keep_jobs: 24 .ft P .fi .UNINDENT .UNINDENT .SS \fBkeep_jobs_seconds\fP .sp Default: \fB86400\fP .sp Set the number of seconds 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_seconds: 86400 .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 \fBmaintenance_interval\fP .sp New in version 3006.0. .sp Default: \fB3600\fP .sp Defines how often to restart the master\(aqs Maintenance process. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C maintenance_interval: 9600 .ft P .fi .UNINDENT .UNINDENT .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 \(dq\-\-out\-file\(dq 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\(dq\(dq\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 \(dqa minion function object for generic use on the master\(dq 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_seconds\fP option can be set to a lower value, such as \fB3600\fP, to limit the number of seconds jobs are stored in the job cache. (The default is 86400 seconds.) .sp Please see the \fI\%Managing the Job Cache\fP 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. \fI\%Presence events\fP 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 \fBdetect_remote_minions\fP .sp Default: False .sp When checking the minions connected to a master, also include the master\(aqs connections to minions on the port specified in the setting \fIremote_minions_port\fP\&. This is particularly useful when checking if the master is connected to any Heist\-Salt minions. If this setting is set to True, the master will check all connections on port 22 by default unless a user also configures a different port with the setting \fIremote_minions_port\fP\&. .sp Changing this setting will check the remote minions the master is connected to when using presence events, the manage runner, and any other parts of the code that call the \fIconnected_ids\fP method to check the status of connected minions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C detect_remote_minions: True .ft P .fi .UNINDENT .UNINDENT .SS \fBremote_minions_port\fP .sp Default: 22 .sp The port to use when checking for remote minions when \fIdetect_remote_minions\fP is set to True. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C remote_minions_port: 2222 .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 \fBipc_write_buffer\fP .sp Default: \fB0\fP .sp The maximum size of a message sent via the IPC transport module can be limited dynamically or by sharing an integer value lower than the total memory size. When the value \fBdynamic\fP is set, salt will use 2.5% of the total memory as \fBipc_write_buffer\fP value (rounded to an integer). A value of \fB0\fP disables this option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ipc_write_buffer: 10485760 .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. \fI\%Authentication events\fP 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 \fI\%2019.2.1 release notes\fP 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 \fI\%flat\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 \fI\%flat\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 \(dqmixed up\(dq 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 \fI\%Autoaccept Minions from Grains\fP 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 \(dqcmd\(dq 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. .sp Note: \fIkeep_acl_in_token\fP will be forced to True when using external authentication for REST API (\fIrest\fP is present under \fIexternal_auth\fP). This is because the REST API does not store the password, and can therefore not retroactively fetch the ACL, so the ACL must be stored in the token. .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: <filename_without_suffix> .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: <filename> .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: <path_to_keyfile> certfile: <path_to_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 Standards for busy environments: .INDENT 0.0 .IP \(bu 2 Use one worker thread per 200 minions. .IP \(bu 2 The value of worker_threads should not exceed 1½ times the available CPU cores. .UNINDENT .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 \(dqtop\(dq 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 \(dqstate_top\(dq 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 \fI\%highstate\fP\&. .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 \fI\%highstate\fP, 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 \fI\%highstate\fP, 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: <Shell command which returns yaml> .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_output_profile\fP .sp Default: \fBTrue\fP .sp The \fBstate_output_profile\fP setting changes whether profile information will be shown for each state run. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_output_profile: True .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_output_pct\fP .sp Default: \fBFalse\fP .sp The \fBstate_output_pct\fP setting changes whether success and failure information as a percent of total actions will be shown for each state run. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_output_pct: False .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_compress_ids\fP .sp Default: \fBFalse\fP .sp The \fBstate_compress_ids\fP setting aggregates information about states which have multiple \(dqnames\(dq under the same state ID in the highstate output. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_compress_ids: False .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_aggregate\fP .sp Default: \fBFalse\fP .sp Automatically aggregate all states that have support for \fBmod_aggregate\fP by setting to \fBTrue\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_aggregate: True .ft P .fi .UNINDENT .UNINDENT .sp 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 .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/<JID>/prog/<MID>/<RUN NUM>\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: \fBTrue\fP .sp If set to \fBFalse\fP, runner jobs will not be saved to job cache (defined by \fI\%master_job_cache\fP). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C runner_returns: False .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_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 \fI\%fileserver.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 \fI\%file.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 Changed in version 3005. .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 Taking dynamic environments one step further, \fB__env__\fP can also be used in the \fBfile_roots\fP filesystem path as of version 3005. It will be replaced with the actual \fBsaltenv\fP and searched for states and data to provide to the minion. Note this substitution ONLY occurs for the \fB__env__\fP environment. For instance, this configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: __env__: \- /srv/__env__/salt .ft P .fi .UNINDENT .UNINDENT .sp is equivalent to this static configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: dev: \- /srv/dev/salt test: \- /srv/test/salt prod: \- /srv/prod/salt .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 \fI\%GitFS Walkthrough\fP\&. .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 \fI\%GitFS Walkthrough\fP\&. .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 \fI\%here\fP 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 \fI\%here\fP 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 \fI\%here\fP 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 \fI\%here\fP for more info. .SS \fBgitfs_saltenv\fP .sp New in version 2016.11.0. .sp Default: \fB[]\fP .sp Global settings for \fI\%per\-saltenv configuration parameters\fP\&. 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 \fI\%per\-saltenv configuration parameters\fP\&. .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 \fI\%here\fP 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 \fI\%here\fP 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 \fI\%fileserver.envs\fP runner), but works within states and with \fI\%cp.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 \fI\%GitFS Walkthrough\fP\&. .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 \fI\%GitFS Walkthrough\fP\&. .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 \fI\%per\-remote config option\fP .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 \fI\%GitFS Walkthrough\fP\&. .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 \fI\%here\fP 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 \fI\%here\fP 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 \fI\%here\fP 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 \fI\%here\fP 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 \fI\%here\fP 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 \fI\%here\fP 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 \fI\%GitFS Walkthrough\fP\&. .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 \fI\%MinionFS\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since \fI\%MinionFS\fP 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 s3fs: S3 File Server Backend .sp New in version 0.16.0. .sp See the \fI\%s3fs 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 \fBfileserver_interval\fP .sp New in version 3006.0. .sp Default: \fB3600\fP .sp Defines how often to restart the master\(aqs FilesServerUpdate process. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_interval: 9600 .ft P .fi .UNINDENT .UNINDENT .SS Pillar Configuration .SS \fBpillar_roots\fP .sp Changed in version 3005. .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 .sp Taking dynamic environments one step further, \fB__env__\fP can also be used in the \fBpillar_roots\fP filesystem path as of version 3005. It will be replaced with the actual \fBpillarenv\fP and searched for Pillar data to provide to the minion. Note this substitution ONLY occurs for the \fB__env__\fP environment. For instance, this configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_roots: __env__: \- /srv/__env__/pillar .ft P .fi .UNINDENT .UNINDENT .sp is equivalent to this static configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_roots: dev: \- /srv/dev/pillar test: \- /srv/test/pillar prod: \- /srv/prod/pillar .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 \fI\%pillar.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 \fI\%pillar.ext\fP, and may be considered a security risk. However, pillar data generated in this way will not affect the \fI\%in\-memory pillar data\fP, so this risk is limited to instances in which states/modules/etc. (built\-in or custom) rely upon pillar data generated by \fI\%pillar.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 \fBgpg_decrypt_must_succeed\fP .sp New in version 3005. .sp Default: \fBFalse\fP .sp If this is \fBTrue\fP and the ciphertext could not be decrypted, then an error is raised. .sp Sending the ciphertext through basically is \fInever\fP desired, for example if a state is setting a database password from pillar and gpg rendering fails, then the state will update the password to the ciphertext, which by definition is not encrypted. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The value defaults to \fBFalse\fP for backwards compatibility. In the \fBChlorine\fP release, this option will default to \fBTrue\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gpg_decrypt_must_succeed: False .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\%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 \fI\%Pillars\fP .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 \(dqwins\(dq 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 \fI\%git_pillar remotes\fP, 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 \fI\%this explanation\fP 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 \fI\%GitFS Walkthrough\fP, 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 \fI\%GitFS counterpart\fP, 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 foo: 42 bar: !aggregate { element1: True } baz: !aggregate quux .ft P .fi .UNINDENT .UNINDENT .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C 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 .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This requires that the \fI\%render pipeline\fP defined in the \fI\%renderer\fP master configuration ends in \fByamlex\fP\&. .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 \(dqrenderer\(dq 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 \fI\%pillar includes\fP 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 \fI\%targeting minions with pillar\fP\&. .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. The cache TTL does not prevent pillar cache from being refreshed before its TTL expires. .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 \fI\%Reactor\fP 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 \fI\%salt\-api\fP 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 \fBnetapi_enable_clients\fP .sp New in version 3006.0. .sp Default: \fB[]\fP .sp Used by \fBsalt\-api\fP to enable access to the listed clients. Unless a client is addded to this list, requests will be rejected before authentication is attempted or processing of the low state occurs. .sp This can be used to only expose the required functionality via \fBsalt\-api\fP\&. .sp Configuration with all possible clients enabled: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C netapi_enable_clients: \- local \- local_async \- local_batch \- local_subset \- runner \- runner_async \- ssh \- wheel \- wheel_async .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Enabling all clients is not recommended \- only enable the clients that provide the functionality required. .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 \(dqPeer Publication\(dq 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\e.example\e.com: \- test\e..* \- pkg\e..* .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 It is also possible to limit target hosts with the \fI\%Compound Matcher\fP\&. You can achieve this by adding another layer in between the source and the allowed functions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer: \(aq.*\e.example\e.com\(aq: \- \(aqG@role:db\(aq: \- test\e..* \- pkg\e..* .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Notice that the source hosts are matched by a regular expression on their minion ID, while target hosts can be matched by any of the \fI\%available matchers\fP\&. .sp Note that globbing and regex matching on pillar values is not supported. You can only match exact values. .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 \fI\%log_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 \fI\%log_level\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_level: warning .ft P .fi .UNINDENT .UNINDENT .sp Any log level below the \fIinfo\fP level is INSECURE and may log sensitive data. This currently includes: #. profile #. debug #. trace #. garbage #. all .SS \fBlog_level_logfile\fP .sp Default: \fBwarning\fP .sp The level of messages to send to the log file. See also \fI\%log_level_logfile\fP\&. When it is not set explicitly it will inherit the level set by \fI\%log_level\fP option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_level_logfile: warning .ft P .fi .UNINDENT .UNINDENT .sp Any log level below the \fIinfo\fP level is INSECURE and may log sensitive data. This currently includes: #. profile #. debug #. trace #. garbage #. all .SS \fBlog_datefmt\fP .sp Default: \fB%H:%M:%S\fP .sp The date and time format used in console log messages. See also \fI\%log_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 \fI\%log_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 \fI\%log_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 \fI\%log_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 \fI\%log_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 \fI\%here\fP\&. .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 \fI\%ng\fP 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<commit_id> https://github.com/saltstack/salt\-winrepo.git\(aq .ft P .fi .UNINDENT .UNINDENT .sp Replace \fB<commit_id>\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 \fI\%ng\fP 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<commit_id> https://github.com/saltstack/salt\-winrepo\-ng.git\(aq .ft P .fi .UNINDENT .UNINDENT .sp Replace \fB<commit_id>\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 \fI\%GitFS Walkthrough\fP, 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 \fI\%GitFS counterpart\fP, 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 \fI\%example minion configuration file\fP .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 \fI\%multi\-master\fP 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 \fI\%Master Tops\fP system are normally executed \fIafter\fP any matches defined in the \fI\%Top File\fP\&. Set this option to \fBTrue\fP to have the minion execute the \fI\%Master Tops\fP 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: str .ft P .fi .UNINDENT .UNINDENT .sp If this option is \fBstr\fP (default), multiple hot masters are configured. Minions can connect to multiple masters simultaneously (all master are \(dqhot\(dq). .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/<minion_id>/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/<minion_id>/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. This setting can also be used to detect master DNS record changes when a minion has been disconnected. .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 \(dqsecondary masters\(dq 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<LIB_STATE_DIR>/pki/minion\fP .sp The directory used to store the minion\(aqs public and private keys. .sp \fB<LIB_STATE_DIR>\fP is the pre\-configured variable state directory set during installation via \fB\-\-salt\-lib\-state\-dir\fP\&. It defaults to \fB/etc/salt\fP\&. Systems following the Filesystem Hierarchy Standard (FHS) might set it to \fB/var/lib/salt\fP\&. .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 \fI\%Salt Walkthrough\fP .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\(dq\(dq\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 \fI\%state.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 \fI\%Using grains in a state\fP .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 {\(dqcustom1\(dq: {\(dqk1\(dq: \(dqv1\(dq}} def custom1_k2(): return {\(dqcustom1\(dq: {\(dqk2\(dq: \(dqv2\(dq}} .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 \fBgrains_refresh_pre_exec\fP .sp New in version 3005. .sp Default: \fBFalse\fP .sp The \fBgrains_refresh_pre_exec\fP setting allows for a minion to check its grains prior to the execution of any operation 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 before enabling this behavior. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grains_refresh_pre_exec: True .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 \fI\%here\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. \fI\%See this documentation on the Salt Mine\fP for more information. Note these can be defined in the pillar for a minion as well. .INDENT 0.0 .INDENT 3.5 \fI\%example minion configuration file\fP .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\&. On macOS, FQDN resolution can be very slow, therefore the default for macOS is \fBFalse\fP as well. All other OSes default to \fBTrue\fP\&. This option 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 \fI\%File State Backups documentation\fP 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 denies or rejects the minion\(aqs public key, retry instead of exiting. These 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: \fB5\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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For high latency networks try increasing this value .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth_timeout: 5 .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 \fBrequest_channel_timeout\fP .sp New in version 3006.2. .sp Default: \fB30\fP .sp The default timeout timeout for request channel requests. This setting can be used to tune minions to better handle long running pillar and file client requests. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C request_channel_timeout: 30 .ft P .fi .UNINDENT .UNINDENT .SS \fBrequest_channel_tries\fP .sp New in version 3006.2. .sp Default: \fB3\fP .sp The default number of times the minion will try request channel requests. This setting can be used to tune minions to better handle long running pillar and file client requests by retrying them after a timeout happens. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C request_channel_tries: 3 .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 \fBreturn_retry_tries\fP .sp Default: \fB3\fP .sp The maximum number of retries for a minion return attempt. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C return_retry_tries: 3 .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 \fBipc_write_buffer\fP .sp Default: \fB0\fP .sp The maximum size of a message sent via the IPC transport module can be limited dynamically or by sharing an integer value lower than the total memory size. When the value \fBdynamic\fP is set, salt will use 2.5% of the total memory as \fBipc_write_buffer\fP value (rounded to an integer). A value of \fB0\fP disables this option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ipc_write_buffer: 10485760 .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 \fI\%2019.2.1 release notes\fP 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 \fI\%mine\fP will be updated with the results of \fBdocker.ps verbose=True all=True host=True\fP\&. This mine data is used by \fI\%mine.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 \fI\%mine.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 \fI\%docker.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 \fI\%on an individual basis in an SLS file\fP, 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 .SS \fBstate_top\fP .sp Default: \fBtop.sls\fP .sp The state system uses a \(dqtop\(dq 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 \fI\%highstate\fP\&. .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 \fI\%highstate\fP, 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 \fI\%highstate\fP, 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 \fI\%highstate\fP (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_aggregate\fP .sp Default: \fBFalse\fP .sp Automatically aggregate all states that have support for \fBmod_aggregate\fP by setting to \fBTrue\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_aggregate: True .ft P .fi .UNINDENT .UNINDENT .sp 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 .SS \fBstate_queue\fP .sp Default: \fBFalse\fP .sp Instead of failing immediately when another state run is in progress, a value of \fBTrue\fP will queue the new state run to begin running once the other has finished. This option starts a new thread for each queued state run, so use this option sparingly. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_queue: True .ft P .fi .UNINDENT .UNINDENT .sp Additionally, it can be set to an integer representing the maximum queue size which can be attained before the state runs will fail to be queued. This can prevent runaway conditions where new threads are started until system performance is hampered. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_queue: 2 .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 \fBstate_output_profile\fP .sp Default: \fBTrue\fP .sp The \fBstate_output_profile\fP setting changes whether profile information will be shown for each state run. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_output_profile: True .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_output_pct\fP .sp Default: \fBFalse\fP .sp The \fBstate_output_pct\fP setting changes whether success and failure information as a percent of total actions will be shown for each state run. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_output_pct: False .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_compress_ids\fP .sp Default: \fBFalse\fP .sp The \fBstate_compress_ids\fP setting aggregates information about states which have multiple \(dqnames\(dq under the same state ID in the highstate output. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_compress_ids: 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 The default fileserver environment to use when copying files and applying states. .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 \fBglobal_state_conditions\fP .sp Default: \fBNone\fP .sp If set, this parameter expects a dictionary of state module names as keys and a list of conditions which must be satisfied in order to run any functions in that state module. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C global_state_conditions: \(dq*\(dq: [\(dqG@global_noop:false\(dq] service: [\(dqnot G@virtual_subtype:chroot\(dq] .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 \fI\%master 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 \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 \fI\%pillar.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 \fI\%pillar.ext\fP, and may be considered a security risk. However, pillar data generated in this way will not affect the \fI\%in\-memory pillar data\fP, so this risk is limited to instances in which states/modules/etc. (built\-in or custom) rely upon pillar data generated by \fI\%pillar.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 \fBgpg_decrypt_must_succeed\fP .sp New in version 3005. .sp Default: \fBFalse\fP .sp If this is \fBTrue\fP and the ciphertext could not be decrypted, then an error is raised. .sp Sending the ciphertext through basically is \fInever\fP desired, for example if a state is setting a database password from pillar and gpg rendering fails, then the state will update the password to the ciphertext, which by definition is not encrypted. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The value defaults to \fBFalse\fP for backwards compatibility. In the \fBChlorine\fP release, this option will default to \fBTrue\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gpg_decrypt_must_succeed: False .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 {\(dqopt1\(dq: \(dqvalue1\(dq, \(dqopt2\(dq: {\(dqsubopt1\(dq: \(dqvalue2\(dq}} .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: \(dqfoo bar\(dq .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 \(dqsalt\-key \-F master\(dq 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, \fI\%master_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: <filename_without_suffix> .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 \fI\%Autoaccept Minions from Grains\fP 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: <path_to_keyfile> certfile: <path_to_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 \fI\%Reactor\fP 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 \fI\%log_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 \fI\%log_level\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_level: warning .ft P .fi .UNINDENT .UNINDENT .sp Any log level below the \fIinfo\fP level is INSECURE and may log sensitive data. This currently includes: #. profile #. debug #. trace #. garbage #. all .SS \fBlog_level_logfile\fP .sp Default: \fBwarning\fP .sp The level of messages to send to the log file. See also \fI\%log_level_logfile\fP\&. When it is not set explicitly it will inherit the level set by \fI\%log_level\fP option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_level_logfile: warning .ft P .fi .UNINDENT .UNINDENT .sp Any log level below the \fIinfo\fP level is INSECURE and may log sensitive data. This currently includes: #. profile #. debug #. trace #. garbage #. all .SS \fBlog_datefmt\fP .sp Default: \fB%H:%M:%S\fP .sp The date and time format used in console log messages. See also \fI\%log_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 \fI\%log_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 \fI\%log_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 \fI\%log_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 \fI\%log_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 \fBtcp_reconnect_backoff\fP .sp Default: \fB1\fP .sp The time in seconds to wait before attempting another connection with salt master when the previous connection fails while on TCP transport. .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 \fI\%salt.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 \fI\%windows 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 \fI\%pkg.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 \fI\%windows 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 \fI\%ng\fP 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<commit_id> https://github.com/saltstack/salt\-winrepo.git\(aq .ft P .fi .UNINDENT .UNINDENT .sp Replace \fB<commit_id>\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 \fI\%ng\fP 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<commit_id> https://github.com/saltstack/salt\-winrepo\-ng.git\(aq .ft P .fi .UNINDENT .UNINDENT .sp Replace \fB<commit_id>\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 \fI\%example proxy minion configuration file\fP .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\&. .sp With the Salt 3004 release, the ability to configure proxy minions using the delta proxy was introduced. The delta proxy provides the ability for a single control proxy minion to manage multiple proxy minions. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Installing and Using Deltaproxy\fP .UNINDENT .UNINDENT .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: \fI\%mine_interval\fP, and \fBmine_functions\fP\&. .SS Delta proxy minions .sp Welcome to the delta proxy minion installation guide. This installation guide explains the process for installing and using delta proxy minion which is available beginning in version 3004. .sp This guide is intended for system and network administrators with the general knowledge and experience required in the field. This guide is also intended for users that have ideally already tested and used standard Salt proxy minions in their environment before deciding to move to a delta proxy minion environment. See \fI\%Salt proxy minions\fP for more information. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you have not used standard Salt proxy minions before, consider testing and deploying standard Salt proxy minions in your environment first. .UNINDENT .UNINDENT .SS Proxy minions vs. delta proxy minions .sp Salt can target network devices through \fI\%Salt proxy minions\fP, Proxy minions allow you to control network devices that, for whatever reason, cannot run the standard Salt minion. Examples include: .INDENT 0.0 .IP \(bu 2 Network gear that has an API but runs a proprietary operating system .IP \(bu 2 Devices with limited CPU or memory .IP \(bu 2 Devices that could run a minion but will not for security reasons .UNINDENT .sp A proxy minion acts as an intermediary between the Salt master and the device it represents. The proxy minion runs on the Salt master and then translates commands from the Salt master to the device as needed. .sp By acting as an intermediary for the actual minion, proxy minions eliminate the need to establish a constant connection from a Salt master to a minion. Proxy minions generally only open a connection to the actual minion when necessary. .sp Proxy minions also reduce the amount of CPU or memory the minion must spend checking for commands from the Salt master. Proxy minions use the Salt master\(aqs CPU or memory to check for commands. The actual minion only needs to use CPU or memory to run commands when needed. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For more information about Salt proxy minions, see: .INDENT 0.0 .IP \(bu 2 \fI\%Salt proxy minions\fP .IP \(bu 2 \fI\%Salt proxy modules\fP .UNINDENT .UNINDENT .UNINDENT .SS When delta proxy minions are needed .sp Normally, you would create a separate instance of proxy minion for each device that needs to be managed. However, this doesn\(aqt always scale well if you have thousands of devices. Running several thousand proxy minions can require a lot of memory and CPU. .sp A delta proxy minion can solve this problem: it makes it possible to run one minion that acts as the intermediary between the Salt master and the many network devices it can represent. In this scenario, one device (the delta proxy minion on the Salt master) runs several proxies. This configuration boosts performance and improves the overall scalability of the network. .SS Key terms .sp The following lists some important terminology that is used throughout this guide: .TS center; |l|l|. _ T{ Term T} T{ Definition T} _ T{ Salt master T} T{ The Salt master is a central node running the Salt master server. The Salt master issues commands to minions. T} _ T{ minion T} T{ Minions are nodes running the Salt minion service. Minions listen to commands from a Salt master and perform the requested tasks, then return data back to the Salt master as needed. T} _ T{ proxy minion T} T{ A Salt master that is running the proxy\-minion service. The proxy minion acts as an intermediary between the Salt master and the device it represents. The proxy minion runs on the Salt master and then translates commands from the Salt master to the device. A separate instance of proxy minion is needed for each device that is managed. T} _ T{ delta proxy minion T} T{ A Salt master that is running the delta proxy\-minion service. The delta proxy minion acts as the intermediary between the Salt master and the many network devices it can represent. Only one instance of the delta proxy service is needed to run several proxies. T} _ T{ control proxy T} T{ The control proxy runs on the Salt master. It manages a list of devices and issues commands to the network devices it represents. The Salt master needs at least one control proxy, but it is possible to have more than one control proxy, each managing a different set of devices. T} _ T{ managed device T} T{ A device (such as Netmiko) that is managed by proxy minions or by a control proxy minion. The proxy minion or control proxy only creates a connection to the actual minion it needs to issue a command. T} _ T{ pillar file T} T{ Pillars are structures of data (files) defined on the Salt master and passed through to one or more minions when the minion needs access to the pillar file. Pillars allow confidential, targeted data to be securely sent only to the relevant minion. Because all configurations for delta proxy minions are done on the Salt master (not on the minions), you use pillar files to configure the delta proxy\-minion service. T} _ T{ top file T} T{ The top file is a pillar file that maps which states should be applied to different minions in certain environments. T} _ .TE .SS Pre\-installation .SS Before you start .sp Before installing the delta proxy minion, ensure that: .INDENT 0.0 .IP \(bu 2 Your network device and firmware are supported. .IP \(bu 2 The Salt master that is acting as the control proxy minion has network access to the devices it is managing. .IP \(bu 2 You have installed, configured, and tested standard Salt proxy minions in your environment before introducing delta proxy minions into your environment. .UNINDENT .SS Install or upgrade Salt .sp Ensure your Salt masters are running at least Salt version 3004. For instructions on installing or upgrading Salt, see \fI\%repo.saltproject.io\fP\&. For RedHat systems, see \fI\%Install or Upgrade Salt\fP\&. .SS Installation .sp Before you begin the delta proxy minion installation process, ensure you have read and completed the \fI\%Pre\-installation\fP steps. .SS Overview of the installation process .sp Similar to proxy minions, all the delta proxy minion configurations are done on the Salt master rather than on the minions that will be managed. The installation process has the following phases: .INDENT 0.0 .IP 1. 3 \fI\%Configure the master to use delta proxy\fP \- Create a configuration file on the Salt master that defines its proxy settings. .IP 2. 3 \fI\%Create a pillar file for each managed device\fP \- Create a pillar file for each device that will be managed by the delta proxy minion and reference these minions in the top file. .IP 3. 3 \fI\%Create a control proxy configuration file\fP \- Create a control proxy file that lists the devices that it will manage. Then, reference this file in the top file. .IP 4. 3 \fI\%Start the delta proxy minion\fP \- Start the delta proxy\-minion service and validate that it has been set up correctly. .UNINDENT .SS Configure the master to use delta proxy .sp In this step, you\(aqll create a configuration file on the Salt master that defines its proxy settings. This is a general configuration file that tells the Salt master how to handle all proxy minions. .sp To create this configuration: .INDENT 0.0 .IP 1. 3 On the Salt master, navigate to the \fB/etc/salt\fP directory. In this directory, create a file named \fBproxy\fP if one doesn\(aqt already exist. .IP 2. 3 Open the file in your preferred editor and add the following configuration information: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C # Use delta proxy metaproxy metaproxy: deltaproxy # Disable the FQDNS grain enable_fqdns_grains: False # Enabled multprocessing multiprocessing: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 3.0 .INDENT 3.5 See the following section about \fI\%delta proxy configuration options\fP for a more detailed description of these configuration options. .UNINDENT .UNINDENT .IP 3. 3 Save the file. .UNINDENT .sp Your Salt master is now configured to use delta proxy. Next, you need to \fI\%Create a pillar file for each managed device\fP\&. .SS Delta proxy configuration options .sp The following table describes the configuration options used in the delta proxy configuration file: .TS center; |l|l|. _ T{ Field T} T{ Description T} _ T{ metaproxy T} T{ Set this configuration option to \fBdeltaproxy\fP\&. If this option is set to \fBproxy\fP or if this line is not included in the file, the Salt master will use the standard proxy service instead of the delta proxy service. T} _ T{ enable_fqdns_grains T} T{ If your router does not have the ability to use Reverse DNS lookup to obtain the Fully Qualified Domain Name (fqdn) for an IP address, you\(aqll need to change the \fBenable_fqdns_grains\fP setting in the pillar configuration file to \fBFalse\fP instead. T} _ T{ multiprocessing T} T{ Multi\-processing is the ability to run more than one task or process at the same time. A delta proxy minion has the ability to run with multi\-processing turned off. .sp If you plan to run with multi\-processing enabled, you should also enable the \fBskip_connect_on_init\fP setting to \fBTrue\fP\&. T} _ T{ skip_connect_on_init T} T{ This setting tells the control proxy whether or not it should make a connection to the managed device when it starts. When set to \fBTrue\fP, the delta proxy minion will only connect when it needs to issue commands to the managed devices. T} _ .TE .SS Create a pillar file for each managed device .sp Each device that needs to be managed by delta proxy needs a separate pillar file on the Salt master. To create this file: .INDENT 0.0 .IP 1. 3 Navigate to the \fB/srv/pillar\fP directory. .IP 2. 3 In this directory create a new pillar file for a minion. For example, \fBmy_managed_device_pillar_file_01.sls\fP\&. .IP 3. 3 Open the new file in your preferred editor and add the necessary configuration information for that minion and your environment. The following is an example pillar file for a Netmiko device: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: netmiko device_type: arista_eos host: 192.0.2.1 username: myusername password: mypassword always_alive: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 3.0 .INDENT 3.5 The available configuration options vary depending on the proxy type (in other words, the type of device it is). To read a detailed explanation of the configuration options, refer to the proxy module documentation for the type of device you need to manage. See: .INDENT 0.0 .IP \(bu 2 \fI\%Salt proxy modules\fP .IP \(bu 2 \fI\%Netmiko Salt proxy module\fP .UNINDENT .UNINDENT .UNINDENT .IP 4. 3 Save the file. .IP 5. 3 In an editor, open the top file: \fB/srv/pillar/top.sls\fP\&. .IP 6. 3 Add a section to the top file that indicates the minion ID of the device that will be managed. Then, list the name of the pillar file you created in the previous steps. For example: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C my_managed_device_minion_ID: \- my_managed_device_pillar_file_01 .ft P .fi .UNINDENT .UNINDENT .IP 7. 3 Repeat the previous steps for each minion that needs to be managed. .UNINDENT .sp You\(aqve now created the pillar file for the minions that will be managed by the delta proxy minion and you have referenced these files in the top file. Proceed to the next section. .SS Create a control proxy configuration file .sp On the Salt master, you\(aqll need to create or edit a control proxy file for each control proxy. The control proxy manages several devices and issues commands to the network devices it represents. The Salt master needs at least one control proxy, but it is possible to have more than one control proxy, each managing a different set of devices. .sp To configure a control proxy, you\(aqll create a file that lists the minion IDs of the minions that it will manage. Then you will reference this control proxy configuration file in the top file. .sp To create a control proxy configuration file: .INDENT 0.0 .IP 1. 3 On the Salt master, navigate to the \fB/srv/pillar\fP directory. In this directory, create a new proxy configuration file. Give this file a descriptive name, such as \fBcontrol_proxy_01_configuration.sls\fP\&. .IP 2. 3 Open the file in your preferred editor and add a list of the minion IDs for each device that needs to be managed. For example: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: deltaproxy ids: \- my_managed_device_01 \- my_managed_device_02 \- my_managed_device_03 .ft P .fi .UNINDENT .UNINDENT .IP 3. 3 Save the file. .IP 4. 3 In an editor, open the top file: \fB/srv/pillar/top.sls\fP\&. .IP 5. 3 Add a section to the top file that indicates references the delta proxy control proxy. For example: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C base: my_managed_device_minion_01: \- my_managed_device_pillar_file_01 my_managed_device_minion_02: \- my_managed_device_pillar_file_02 my_managed_device_minion_03: \- my_managed_device_pillar_file_03 delta_proxy_control: \- control_proxy_01_configuration .ft P .fi .UNINDENT .UNINDENT .IP 6. 3 Repeat the previous steps for each control proxy if needed. .IP 7. 3 In an editor, open the proxy config file: \fB/etc/salt/proxy\fP\&. Add a section for metaproxy and set it\(aqs value to deltaproxy. .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C metaproxy: deltaproxy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Now that you have created the necessary configurations, proceed to the next section. .SS Start the delta proxy minion .sp After you\(aqve successfully configured the delta proxy minion, you need to start the proxy minion service for each managed device and validate that it is working correctly. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This step explains the process for starting a single instance of a delta proxy minion. Because starting each minion individually can potentially be very time\-consuming, most organizations use a script to start their delta proxy minions since there are typically many devices being managed. Consider implementing a similar script for your environment to save time in deployment. .UNINDENT .UNINDENT .sp To start a single instance of a delta proxy minion and test that it is configured correctly: .INDENT 0.0 .IP 1. 3 In the terminal for the Salt master, run the following command, replacing the placeholder text with the actual minion ID: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C sudo salt\-proxy \-\-proxyid=<control_proxy_id> .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 To test the delta proxy minion, run the following \fBtest.version\fP command on the Salt master and target a specific minion. For example: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt my_managed_device_minion_ID test.version .ft P .fi .UNINDENT .UNINDENT .sp This command returns an output similar to the following: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C local: 3004 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp After you\(aqve successfully started the delta proxy minions and verified that they are working correctly, you can now use these minions the same as standard proxy minions. .SS Additional resources .sp This reference section includes additional resources for delta proxy minions. .sp For reference, see: .INDENT 0.0 .IP \(bu 2 \fI\%Salt proxy minions\fP .IP \(bu 2 \fI\%Salt proxy modules\fP .IP \(bu 2 \fI\%Netmiko Salt proxy module\fP .UNINDENT .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: \(dqinterface: \(aq::\(aq\(dq) #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 maintenance 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 where custom modules sync to. This directory can contain # subdirectories for each of Salt\(aqs module types such as \(dqrunners\(dq, # \(dqoutput\(dq, \(dqwheel\(dq, \(dqmodules\(dq, \(dqstates\(dq, \(dqreturners\(dq, \(dqengines\(dq, # \(dqutils\(dq, etc. # # Note, any directories or files not found in the \(gamodule_dirs\(ga # location will be removed from the extension_modules path. #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 \(dqrunners\(dq, \(dqoutput\(dq, \(dqwheel\(dq, \(dqmodules\(dq, # \(dqstates\(dq, \(dqreturners\(dq, \(dqengines\(dq, \(dqutils\(dq, etc. #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. # This option is deprecated by the keep_jobs_seconds option. #keep_jobs: 24 # Set the number of seconds to keep old job information in the job cache: #keep_jobs_seconds: 86400 # 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 \(dqnested\(dq. #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 \(dq\-\-out\-file\(dq # 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 <batch_safe_limit> minions, then run the command in # batches of <batch_safe_size>. 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.saltproject.io/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 \(dqopen mode\(dq, 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 \(dqcmd\(dq # 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. # # Note: \(gakeep_acl_in_token\(ga will be forced to True when using external authentication # for REST API (\(garest\(ga is present under \(gaexternal_auth\(ga). This is because the REST API # does not store the password, and can therefore not retroactively fetch the ACL, so # the ACL must be stored in the token. #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: <path_to_keyfile> # certfile: <path_to_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, \(dqroster_file=/foo/roster\(dq will be resolved as # \(dq/etc/salt/roster.d/foo/roster\(dq 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 \(dqtop\(dq 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 \(dqFile Server settings\(dq 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: <Shell command which returns yaml> # #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 # The state_output_profile setting changes whether profile information # will be shown for each state run. #state_output_profile: True # The state_output_pct setting changes whether success and failure information # as a percent of total actions will be shown for each state run. #state_output_pct: False # The state_compress_ids setting aggregates information about states which have # multiple \(dqnames\(dq under the same state ID in the highstate output. #state_compress_ids: 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/<JID>/prog/<MID>/<RUN NUM>\(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 # \(dqroots\(dq which uses the \(dqfile_roots\(dq 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 # # 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 # If this is \(gaTrue\(ga and the ciphertext could not be decrypted, then an error is # raised. #gpg_decrypt_must_succeed: False # 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 \(dqmaster\(dq. 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 \(dqrenderer\(dq 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.saltproject.io/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. # The cache TTL does not prevent pillar cache from being refreshed before its TTL expires. #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.saltproject.io/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 \(dqorder_masters\(dq setting to True. # # If this is a master that will be running a syndic daemon for passthrough, then # the \(dqsyndic_master\(dq 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 \(dqPeer Publication\(dq 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: <file|udp|tcp>://<host|socketpath>:<port\-if\-required>/<log\-facility> #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: # [\(aqprofile\(aq, \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, \(aqall\(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 \(dqpresent\(dq. # 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 # Set a list of clients to enable in in the API #netapi_enable_clients: [] .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 \(dqhot\(dq), or can be configured to failover if a master becomes # unavailable. Multiple hot masters are configured by setting this # value to \(dqstr\(dq. Failover masters can be requested by setting # to \(dqfailover\(dq. 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 \(dqfailover\(dq. 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 \(dqfailover\(dq, this setting can be set to \(dqTrue\(dq 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 \(dqmaster_type\(dq configuration is set to # \(dqfailover\(dq, and the \(dqmaster_failback\(dq 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 \(dqTrue\(dq. 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. # On macOS, FQDN resolution can be very slow, therefore the default for macOS is # \(gaFalse\(ga as well. 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 # \(dqnested\(dq. #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 \(dqminion\(dq. 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) # master_alive_interval: 10 # master_tries: \-1 # # 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 # The grains_refresh_pre_exec setting allows for a minion to check its grains # prior to the execution of any operation 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 before enabling this behavior. #grains_refresh_pre_exec: False # 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 \(dqTrue\(dq. Set to \(dqFalse\(dq 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 \(dqFalse\(dq. Set to \(dqTrue\(dq 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/<minion_id>/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/<minion_id>/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 \(dqsyndic_finger\(dq 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.saltproject.io/en/latest/ref/renderers/#composing\-renderers # # NOTE: The \(dqshebang\(dq prefix (e.g. \(dq#!jinja|yaml\(dq) 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 # Instead of failing immediately when another state run is in progress, a value # of True will queue the new state run to begin running once the other has # finished. This option starts a new thread for each queued state run, so use # this option sparingly. Additionally, it can be set to an integer representing # the maximum queue size which can be attained before the state runs will fail # to be queued. This can prevent runaway conditions where new threads are # started until system performance is hampered. # #state_queue: 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 # If set, this parameter expects a dictionary of state module names as keys # and list of conditions which must be satisfied in order to run any functions # in that state module. # #global_state_conditions: # \(dq*\(dq: [\(dqG@global_noop:false\(dq] # service: [\(dqnot G@virtual_subtype:chroot\(dq] ##### 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 \(dqlocal\(dq. 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 # # 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 # If this is \(gaTrue\(ga and the ciphertext could not be decrypted, then an error is # raised. #gpg_decrypt_must_succeed: 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 # # ###### Security settings ##### ########################################### # Enable \(dqopen mode\(dq, 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 # The state_output_pct setting changes whether success and failure information # as a percent of total actions will be shown for each state run. #state_output_pct: False # The state_compress_ids setting aggregates information about states which have # multiple \(dqnames\(dq under the same state ID in the highstate output. #state_compress_ids: False # 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 # \(dqsalt\-key \-f master.pub\(dq 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: <path_to_keyfile> # certfile: <path_to_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.saltproject.io/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: <file|udp|tcp>://<host|socketpath>:<port\-if\-required>/<log\-facility> #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: # [\(aqprofile\(aq, \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, \(aqall\(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 proxy minion will automatically include all config files # from proxy.d/*.conf (proxy.d is a directory in the same directory # as the main minion config file). #default_include: proxy.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 \(dqhot\(dq), or can be configured to failover if a master becomes # unavailable. Multiple hot masters are configured by setting this # value to \(dqstr\(dq. Failover masters can be requested by setting # to \(dqfailover\(dq. 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 \(dqfailover\(dq. # 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 # \(dqnested\(dq. #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 \(dqminion\(dq. 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.saltproject.io/en/latest/ref/renderers/#composing\-renderers # # NOTE: The \(dqshebang\(dq prefix (e.g. \(dq#!jinja|yaml\(dq) 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 \(dqlocal\(dq. 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 # 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 \(dqopen mode\(dq, 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 # The state_output_pct setting changes whether success and failure information # as a percent of total actions will be shown for each state run. #state_output_pct: False # The state_compress_ids setting aggregates information about states which have # multiple \(dqnames\(dq under the same state ID in the highstate output. #state_compress_ids: False # 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 # \(dqsalt\-key \-F master\(dq 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: <file|udp|tcp>://<host|socketpath>:<port\-if\-required>/<log\-facility> #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: # [\(aqprofile\(aq, \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, \(aqall\(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 \(dqon hold\(dq, 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 \fI\%this Access Control System\fP 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 \fI\%external_auth\fP configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C publisher_acl: # Allow thatch to execute anything. thatch: \- .* # Allow fred to use test and pkg, but only on \(dqweb*\(dq 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 \(dqweb*\(dq 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 \fI\%publisher_acl\fP and \fI\%publisher_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 \fI\%this Access Control System\fP 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 \fI\%access control system\fP: .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 \(dqFailed to authenticate!\(dq if the request timeout is reached. Use \-t flag to increase the timeout .UNINDENT .UNINDENT .sp To allow access to \fI\%wheel modules\fP or \fI\%runner modules\fP the following \fB@\fP syntax must be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: pam: thatch: \- \(aq@wheel\(aq # 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 \fI\%saltutil.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: <eauth backend>: <user or group%>: \- <regex to match function> .ft P .fi .UNINDENT .UNINDENT .sp By user, by minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: <eauth backend>: <user or group%>: <minion compound target>: \- <regex to match function> .ft P .fi .UNINDENT .UNINDENT .sp By user, by runner/wheel: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: <eauth backend>: <user or group%>: <@runner or @wheel>: \- <regex to match function> .ft P .fi .UNINDENT .UNINDENT .sp By user, by runner+wheel module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: <eauth backend>: <user or group%>: <@module_name>: \- <regex to match function without 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 \(dqeverything\(dq 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 (&(<value of auth.ldap.accountattributename>={{username}}) (objectClass=<value of auth.ldap.persontype>) ) .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=<distinguishedName from search above>) (objectClass=<value of auth.ldap.groupclass>) ) .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 allows minions with IDs ending in \fB\&.example.com\fP access to the test, ps, and pkg module functions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer: .*\e.example.com: \- test\e..* \- ps\e..* \- pkg\e..* .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: .*\e.example.com: \- test\e..* \- ps\e..* \- pkg\e..* .*\e.foo.org: \- test\e..* \- ps\e..* \- pkg\e..* .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Functions are matched using regular expressions as well. .UNINDENT .UNINDENT .sp It is also possible to limit target hosts with the \fI\%Compound Matcher\fP\&. You can achieve this by adding another layer in between the source and the allowed functions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer: \(aq.*\e.example\e.com\(aq: \- \(aqG@role:db\(aq: \- test\e..* \- pkg\e..* .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Notice that the source hosts are matched by a regular expression on their minion ID, while target hosts can be matched by any of the \fI\%available matchers\fP\&. .sp Note that globbing and regex matching on pillar values is not supported. You can only match exact values. .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 \fI\%saltutil\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 86400 seconds, but this can be configured via the \fBkeep_jobs_seconds\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 <job id number> .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 \fI\%schedule state\fP or \fI\%schedule 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 86400 seconds. If the default cache needs to store jobs for a different period the time can be easily adjusted by changing the \fBkeep_jobs_seconds\fP parameter in the Salt Master configuration file. The value passed in is measured in seconds: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keep_jobs_seconds: 86400 .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 \fI\%job_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 \fI\%job_cache\fP to \fBFalse\fP in addition to setting the \fI\%keep_jobs_seconds\fP option to a smaller value, such as \fB3600\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_seconds\fP option sets the number of seconds to keep old job information and defaults to \fB86400\fP seconds. 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 \fI\%Storing Job Results in an External System\fP\&. .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 \fI\%Default Job Cache\fP\&. .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 \fI\%Jobs 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 (\(dqreturners\(dq). 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 \fI\%all Salt returners\fP\&. 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 \fI\%MySQL 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: <returner> .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: <returner> .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 \fI\%logging development document\fP, 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 .sp Any log level below the \fIinfo\fP level is INSECURE and may log sensitive data. This currently includes: #. profile #. debug #. trace #. garbage #. all .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 <file|udp|tcp>://<host|socketpath>:<port\-if\-required>/<log\-facility> .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 \(dq%(colorlevel)s\(dq # log level name colorized by level \(dq%(colorname)s\(dq # colorized module name \(dq%(colorprocess)s\(dq # colorized process number \(dq%(colormsg)s\(dq # 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 \(dq%(bracketlevel)s\(dq # equivalent to [%(levelname)\-8s] \(dq%(bracketname)s\(dq # equivalent to [%(name)\-17s] \(dq%(bracketprocess)s\(dq # 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 .sp You can determine what log call name to use here by adding \fB%(module)s\fP to the log format. Typically, it is the path of the file which generates the log without the trailing \fB\&.py\fP and with path separators replaced with \fB\&.\fP .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 \fI\%external logging handlers\fP document. .SS External Logging Handlers .TS center; |l|l|. _ T{ \fI\%fluent_mod\fP T} T{ Fluent Logging Handler T} _ T{ \fI\%log4mongo_mod\fP T} T{ Log4Mongo Logging Handler T} _ T{ \fI\%logstash_mod\fP T} T{ Logstash Logging Handler T} _ T{ \fI\%sentry_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 <source> type forward bind localhost port 24224 </source> .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 \(dqmagic\(dq, 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 => \(dqudp\-type\(dq format => \(dqjson_event\(dq } } .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 => \(dqzeromq\-type\(dq mode => \(dqserver\(dq topology => \(dqpubsub\(dq address => \(dqtcp://0.0.0.0:2021\(dq charset => \(dqUTF\-8\(dq format => \(dqjson_event\(dq } } .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 => \(dqpubsub\(dq address => \(dqtcp://0.0.0.0:2021\(dq 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 \fI\%here\fP for a full list of Salt\(aqs fileserver backends. .SS Enabling a Fileserver Backend .sp Fileserver backends can be enabled with the \fI\%fileserver_backend\fP option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- git .ft P .fi .UNINDENT .UNINDENT .sp See the \fI\%documentation\fP for each backend to find the correct value to add to \fI\%fileserver_backend\fP in order to enable them. .SS Using Multiple Backends .sp If \fI\%fileserver_backend\fP is not defined in the Master config file, Salt will use the \fI\%roots\fP backend, but the \fI\%fileserver_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 \fI\%file_roots\fP parameter will be searched first, and if the file is not found then the git repositories defined in \fI\%gitfs_remotes\fP will be searched. .SS Defining Environments .sp Just as the order of the values in \fI\%fileserver_backend\fP matters, so too does the order in which different sources are defined within a fileserver environment. For example, given the below \fI\%file_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 \fI\%git\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 \fI\%roots\fP backend, while in the VCS backends (\fI\%git\fP, \fI\%hg\fP, \fI\%svn\fP) the environments are created from branches/tags/bookmarks/etc. For the \fI\%minion\fP backend, the files are all in a single environment, which is specified by the \fI\%minionfs_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 \fI\%roots\fP), environments are defined using the \fI\%roots\fP option. Other backends (such as \fI\%gitfs\fP) define environments in their own ways. For a list of available fileserver backends, see \fI\%here\fP\&. .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 \fI\%Reactor\fP 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 \fI\%environment\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 \fI\%state.highstate\fP .IP \(bu 2 \fI\%state.sls\fP .IP \(bu 2 \fI\%state.top\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When the \fBsaltenv\fP parameter is used to trigger a \fI\%highstate\fP using either \fBstate.apply\fP or \fI\%state.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 Periodic Restarts .sp The file server will restart periodically. The reason for this is to prevent any files erver backends which may not properly handle resources from endlessly consuming memory. A notable example of this is using a git backend with the pygit2 library. How often the file server restarts can be controlled with the \fBfileserver_interval\fP in your master\(aqs config file. .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 \(dqsalt://{{grains.os}}/vimrc\(dq /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=\(dqbase\(dq): \(dq\(dq\(dq Used to get a single file from the Salt master CLI Example: salt \(aq*\(aq cp.get_file salt://vimrc /etc/vimrc \(dq\(dq\(dq # 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=\(dqbase\(dq): \(dq\(dq\(dq Used to get a single file from the Salt master \(dq\(dq\(dq # Get the configuration data opts = salt.config.minion_config(\(dq/etc/salt/minion\(dq) # 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 \fI\%Salt Walkthrough\fP\&. .UNINDENT .UNINDENT .sp The gitfs backend allows Salt to serve files from git repositories. It can be enabled by adding \fBgit\fP to the \fI\%fileserver_backend\fP list, and configuring one or more repositories in \fI\%gitfs_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 \fI\%top files\fP, for this reason it may be useful to set \fI\%top_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 \fI\%gitfs_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 \(dqUnsupported URL Protocol\(dq 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 Debian Pygit2 Issues .sp The Debian repos currently have older versions of pygit2 (package \fBpython3\-pygit2\fP). These older versions may have issues using newer SSH keys (see [this issue](\fI\%https://github.com/saltstack/salt/issues/61790\fP)). Instead, \fBpygit2\fP can be installed from Pypi, but you will need a version that matches the \fBlibgit2\fP version from Debian. This is version 1.6.1. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # apt\-get install libgit2 # salt\-pip install pygit2==1.6.1 \-\-no\-deps .ft P .fi .UNINDENT .UNINDENT .sp Note that the above instructions assume a onedir installation. The need for \fI\-\-no\-deps\fP is to prevent the CFFI package from mismatching with Salt. .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 \fI\%pip.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 \fI\%fileserver_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 \fI\%gitfs_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 shell/init.sls second.git: edit/dev_vimrc haproxy/init.sls shell.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 Also a requested state file overrules a directory with an \fIinit.sls\fP\-file. For example: .INDENT 0.0 .IP \(bu 2 A request for \fBstate.apply shell\fP will be served from the \fBhttps://github.com/example/second.git\fP git 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 \fI\%gitfs_base\fP .IP \(bu 2 \fI\%gitfs_root\fP .IP \(bu 2 \fI\%gitfs_ssl_verify\fP .IP \(bu 2 \fI\%gitfs_mountpoint\fP (new in 2014.7.0) .IP \(bu 2 \fI\%gitfs_user\fP (\fBpygit2 only\fP, new in 2014.7.0) .IP \(bu 2 \fI\%gitfs_password\fP (\fBpygit2 only\fP, new in 2014.7.0) .IP \(bu 2 \fI\%gitfs_insecure_auth\fP (\fBpygit2 only\fP, new in 2014.7.0) .IP \(bu 2 \fI\%gitfs_pubkey\fP (\fBpygit2 only\fP, new in 2014.7.0) .IP \(bu 2 \fI\%gitfs_privkey\fP (\fBpygit2 only\fP, new in 2014.7.0) .IP \(bu 2 \fI\%gitfs_passphrase\fP (\fBpygit2 only\fP, new in 2014.7.0) .IP \(bu 2 \fI\%gitfs_refspecs\fP (new in 2017.7.0) .IP \(bu 2 \fI\%gitfs_disable_saltenv_mapping\fP (new in 2018.3.0) .IP \(bu 2 \fI\%gitfs_ref_types\fP (new in 2018.3.0) .IP \(bu 2 \fI\%gitfs_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 \fI\%gitfs_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. \fI\%file_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 \fI\%salt formulas\fP\&. 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 \(dqmaintenance\(dq process, in which various routine maintenance tasks were performed. This tied the update interval to the \fI\%loop_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 \fI\%gitfs_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 \fI\%gitfs_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 \fI\%gitfs_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 \fI\%gitfs_saltenv\fP (or \fI\%per\-saltenv configuration\fP) would be unaffected by this. .UNINDENT .UNINDENT .SS Serving from a Subdirectory .sp The \fI\%gitfs_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 \fI\%gitfs_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 \fI\%fileserver_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 \fI\%fileserver_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 To map a branch other than \fBmaster\fP as the \fBbase\fP environment, use the \fI\%gitfs_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 Use Case: Code Promotion (dev \-> qa \-> base) .sp When running a \fI\%highstate\fP, the \fBtop.sls\fP files from all of the different branches and tags will be merged into one. This does not work well with the use case where changes are tested in development branches before being merged upstream towards production, because if the same SLS file from multiple environments is part of the \fI\%highstate\fP, it can result in non\-unique state IDs, which will cause an error in the state compiler and not allow the \fI\%highstate\fP to proceed. .sp To accomplish this use case, you should do three things: .INDENT 0.0 .IP 1. 3 Use \fB{{ saltenv }}\fP in place of your environment in your \fBtop.sls\fP\&. This will let you use the same top file in all branches, because \fB{{ saltenv }}\fP gets replaced with the effective saltenv of the environment being processed. .IP 2. 3 Set \fI\%top_file_merging_strategy\fP to \fBsame\fP in the minion configuration. This will keep the \fBbase\fP environment from looking at the \fBtop.sls\fP from the \fBdev\fP or \fBqa\fP branches, etc. .IP 3. 3 Explicitly define your \fI\%saltenv\fP\&. (More on this below.) .UNINDENT .sp Consider the following example top file and SLS file: .sp \fBtop.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ saltenv }}: \(aq*\(aq: \- mystuff .ft P .fi .UNINDENT .UNINDENT .sp \fBmystuff.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C manage_mystuff: pkg.installed: \- name: mystuff file.managed: \- name: /etc/mystuff.conf \- source: salt://mystuff/files/mystuff.conf service.running: \- name: mystuffd \- enable: True \- watch: \- file: /etc/mystuff.conf .ft P .fi .UNINDENT .UNINDENT .sp Imagine for a moment that you need to change your \fBmystuff.conf\fP\&. So, you go to your \fBdev\fP branch, edit \fBmystuff/files/mystuff.conf\fP, and commit and push. .sp If you have only done the first two steps recommended above, and you run your \fI\%highstate\fP, you will end up with conflicting IDs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myminion: Data failed to compile: \-\-\-\-\-\-\-\-\-\- Detected conflicting IDs, SLS IDs need to be globally unique. The conflicting ID is \(aqmanage_mystuff\(aq and is found in SLS \(aqbase:mystuff\(aq and SLS \(aqdev:mystuff\(aq \-\-\-\-\-\-\-\-\-\- Detected conflicting IDs, SLS IDs need to be globally unique. The conflicting ID is \(aqmanage_mystuff\(aq and is found in SLS \(aqdev:mystuff\(aq and SLS \(aqqa:mystuff\(aq .ft P .fi .UNINDENT .UNINDENT .sp This is because, in the absence of an explicit \fI\%saltenv\fP, all environments\(aq top files are considered. Each environment looks at only its own \fBtop.sls\fP, but because the \fBmystuff.sls\fP exists in each branch, they all get pulled into the highstate, resulting in these conflicting IDs. This is why explicitly setting your \fI\%saltenv\fP is important for this use case. .sp There are two ways of explicitly defining the \fI\%saltenv\fP: .INDENT 0.0 .IP 1. 3 Set the \fI\%saltenv\fP in your minion configuration file. This allows you to isolate which states are run to a specific branch/tag on a given minion. This also works nicely if you have different salt deployments for dev, qa, and prod. Boxes in dev can have \fI\%saltenv\fP set to \fBdev\fP, boxes in \fBqa\fP can have the \fI\%saltenv\fP set to \fBqa\fP, and boxes in prod can have the \fI\%saltenv\fP set to \fBbase\fP\&. .IP 2. 3 At runtime, you can set the \fBsaltenv\fP like so: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt myminion state.apply saltenv=dev .ft P .fi .UNINDENT .UNINDENT .sp A couple notes about setting the saltenv at runtime: .INDENT 3.0 .IP \(bu 2 It will take precedence over the \fI\%saltenv\fP setting from the minion config file, and pairs nicely with cases where you do not have separate salt deployments for dev/qa/prod. You can have a box with \fI\%saltenv\fP set to \fBbase\fP, which you can test your dev changes on by running your \fBstate.apply\fP with \fBsaltenv=dev\fP\&. .IP \(bu 2 If you don\(aqt set \fI\%saltenv\fP in the minion config file, you _must_ specify it at runtime to avoid conflicting IDs. .UNINDENT .UNINDENT .sp If you branched \fBqa\fP off of \fBmaster\fP, and \fBdev\fP off of \fBqa\fP, you can merge changes from \fBdev\fP into \fBqa\fP, and then merge \fBqa\fP into master to promote your changes to from dev to qa to prod. .SS Environment Whitelist/Blacklist .sp New in version 2014.7.0. .sp The \fI\%gitfs_saltenv_whitelist\fP and \fI\%gitfs_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 \fI\%gitfs_saltenv_whitelist\fP is used, then \fBonly\fP branches/tags which match the whitelist will be available as environments .IP \(bu 2 If only \fI\%gitfs_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 \fI\%gitfs_pubkey\fP and \fI\%gitfs_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 \fI\%gitfs_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://<user>:<password>@<url>\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/var/lib/salt/.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 \fI\%ssh.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 \fI\%Reactor System\fP 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 \fI\%event.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 \fI\%here\fP\&. .SS Why aren\(aqt my custom modules/states/etc. syncing to my Minions? .sp In versions 0.16.3 and older, when using the \fI\%git 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 \fI\%cp.push\fP\&. To get up to speed, check out the \fI\%Salt Walkthrough\fP\&. .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 \fI\%cp.push\fP) .IP 2. 3 The \fI\%minionfs\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 \fI\%file_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 \fI\%cp.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 \fI\%cachedir\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 \fI\%file_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/<minion\-id>\fP for each minion that needs to be exposed can be cumbersome and prone to errors. .sp Enter \fI\%minionfs\fP\&. This fileserver backend will make files pushed using \fI\%cp.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 \fI\%minionfs\fP backend, add \fBminionfs\fP to the list of backends in the \fI\%fileserver_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 \fI\%minionfs\fP are by default located at \fBsalt://<minion\-id>/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 \fI\%minionfs\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 \fI\%minionfs_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 \fI\%minionfs\fP\&. These lists can be managed using the \fI\%minionfs_whitelist\fP and \fI\%minionfs_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 \fI\%minionfs\fP\&. All minions will have access to these files. .IP \(bu 2 Unless the \fI\%minionfs_whitelist\fP and/or \fI\%minionfs_blacklist\fP config options are used, all minions which push files to the master will have their files made available via \fI\%minionfs\fP\&. .UNINDENT .SS Salt Package Manager .sp The Salt Package Manager, or \fI\%SPM\fP, 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 \fI\%Building SPM Packages\fP .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 \fI\%Distributing SPM Packages\fP .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 \fI\%Installing SPM Packages\fP .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 \fI\%FORMULA\fP 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<formula name>.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 \fI\%FORMULA\fP file and place it in the root of the package folder. .IP 3. 3 Run \fBspm build <folder name>\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 \fI\%repository system\fP\&. .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<package_name>.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 \fI\%SPM Development Guide\fP 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 \fI\%directly on a Salt master\fP, 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: \- /srv/salt \- /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<package_name>.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<file_roots>/_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<file_roots>\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 \fI\%SPM Development Guide\fP 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<package_name>.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__[\(dqspm_db\(dq], 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, \(dqr\(dq) 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://<profile>/<args> .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 For SDB sub\-keys, ie users[\(aquser1\(aq][\(aqid\(aq] .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: user1: id: 12345 .ft P .fi .UNINDENT .UNINDENT .sp To get SDB sub\-keys from the CLI, use a colon to separate sub key values. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call sdb.get sdb://users:user1:id .ft P .fi .UNINDENT .UNINDENT .sp To get SDB sub\-keys in a state file, use this syntax: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: user1: id: sdb.get sdb://users:user1:id .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__[\(dqconfig.get\(dq](\(dqmykey\(dq) .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__ = { \(dqset_\(dq: \(dqset\(dq, } .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 \fI\%user\fP parameter in the master configuration file. and restarting the \fBsalt\-master\fP service. .sp The minion has its own \fI\%user\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 \fI\%root_dir\fP parameter specified will affect these paths, as will setting options like \fI\%pki_dir\fP, \fI\%cachedir\fP, \fI\%log_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 \fI\%highstate\fP 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 \(dqstate\(dq. .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 \fI\%highstate\fP 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 The guidance here should be taken in combination with \fI\%Salt Best Practices\fP\&. .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 Refer to the \fI\%Receiving security announcements\fP 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 \(dqlowest common denominator\(dq. 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 .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Grains can be set by users that have access to the minion configuration files on the local system, making them less secure than other identifiers in Salt. Avoid storing sensitive data, such as passwords or keys, on minions. Instead, make use of \fI\%Storing Static Data in the Pillar\fP and/or \fI\%Storing Data in Other Databases\fP\&. .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Jinja\fP supports a \fI\%secure, sandboxed template execution environment\fP that Salt takes advantage of. Other text \fI\%Renderers\fP do not support this functionality, so Salt highly recommends usage of \fBjinja\fP / \fBjinja|yaml\fP\&. .UNINDENT .UNINDENT .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 \fI\%ACL system\fP to avoid having to give out root access in order to run Salt commands. .IP \(bu 2 Use Salt\(aqs Client \fI\%ACL system\fP to restrict which users can run what commands. .IP \(bu 2 Use \fI\%external Pillar\fP 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 \(dqone\-off\(dq CLI commands because it helps mitigate typos and mistakes. .IP \(bu 2 Use salt\-api, SSL, and restrict authentication with the \fI\%external auth\fP system if you need to expose your Salt master to external services. .IP \(bu 2 Make use of Salt\(aqs event system and \fI\%reactor\fP 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 \fI\%disable_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 \fI\%master\fP and \fI\%minion\fP config files. There are many options for securing an installation. .IP \(bu 2 Run \fI\%masterless\-mode\fP minions on particularly sensitive minions. There is also \fI\%Salt SSH\fP 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 Rotating keys .sp There are several reasons to rotate keys. One example is exposure or a compromised key. An easy way to rotate a key is to remove the existing keys and let the \fBsalt\-master\fP or \fBsalt\-minion\fP process generate new keys on restart. .SS Rotate a minion key .sp Run the following on the Salt minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call saltutil.regen_keys systemctl stop salt\-minion .ft P .fi .UNINDENT .UNINDENT .sp Run the following on the Salt master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-d <minion\-id> .ft P .fi .UNINDENT .UNINDENT .sp Run the following on the Salt minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl start salt\-minion .ft P .fi .UNINDENT .UNINDENT .sp Run the following on the Salt master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-a <minion\-id> .ft P .fi .UNINDENT .UNINDENT .SS Rotate a master key .sp Run the following on the Salt master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl stop salt\-master rm <pki_dir>/master.{pem,pub} systemctl start salt\-master .ft P .fi .UNINDENT .UNINDENT .sp Run the following on the Salt minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl stop salt\-minion rm <pki_dir>/minion_master.pub systemctl start salt\-minion .ft P .fi .UNINDENT .UNINDENT .SS Hardening of syndic setups .sp Syndics must be run as the same user as their syndic master process. The master of master\(aqs will include publisher ACL information in jobs sent to downstream masters via syndics. This means that any minions connected directly to a master of masters will also receive ACL information in jobs being published. For the most secure setup, only connect syndics directly to master of masters. .SS Security disclosure policy .INDENT 0.0 .TP .B email \fI\%saltproject\-security.pdl@broadcom.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 mZRqiQJVBBMBAgA/AhsDBgsJCAcDAgYVCAIJCgsEFgIDAQIeAQIXgBYhBIq+Tvzw 9LJL/yqvkNVw8tNOoHk9BQJb0e5rBQkL3m8IAAoJENVw8tNOoHk9fzMP/ApQtkQD BmoYEBTF6BH1bywzDw5OHpnBSLbuoYtA3gkhnm/83MzFDcGn22pgo2Fv0MuHltWI G2oExzje7szmcM6Xg3ZTKapJ3/p2J+P33tkJA1LWpg+DdgdQlqrjlXKwEnikszuB 9IMhbjoPeBzwiUtsBQmcwbVgwMzbscwoV5DJ/gLDCkgF4rp2uKEYAcBi8s9NGX6p zQsb9Sb0/bKdCrszAcvUn4WYB6WbAPttvutYHtg/nZfXEeX/SgBueXo3lO9vzFlO r3Zgk7WeucsEqa9Qo0VLOq28HykixM5mEJKsAQrNIqM1DqXgfDch8RJAHzgMBHFH Qi9hJXk1/6OA2FPXQGcA9Td5Dt0i1Z7wMrAUMj3s9gNMVCD0hQqEKfUtpyV7KBAj AO5j8Wr8KafnRm6czBCkcV0SRzHQSHdYyncozWwPgWOaRC9AY9fEDz8lBaSoB/C+ dyO/xZMTWoaWqkHozVoHIrCc4CAtZTye/5mxFhq15Q1Iy/NjelrMTCD1kql1dNIP oOgfOYl1xLMQIBwrrCrgeRIvxEgKRf9KOLbSrS7+3vOKoxf+LD4AQfLci8dFyH+I t0Z43nk93yTOI82RTdz5GwUXIKcvGhsJ8bgNlGTxM1R/Sl8Sg8diE2PRAp/fk7+g CwOM8VkeyrDM2k1cy64d8USkbR7YtT3otyFQiQJVBBMBCAA/AhsDBgsJCAcDAgYV CAIJCgsEFgIDAQIeAQIXgBYhBIq+Tvzw9LJL/yqvkNVw8tNOoHk9BQJeapbNBQkN v4KKAAoJENVw8tNOoHk9BFQP/04a1yQb3aOYbNgx+ER9l54wZbUUlReU+ujmlW03 12ZW8fFZ0SN2q7xKtE/I9nNl1gjJ7NHTP3FhZ0eNyG+mJeGyrscVKxaAkTV+71e3 7n94/qC2bM753X+2160eR7Md+R/itoljStwmib1583rSTTUld1i4FnUTrEhF7MBt I/+5l7vUK4Hj1RPovHVeHXYfdbrS6wCBi6GsdOfYGfGacZIfM4XLXTkyjVt4Zg0j rwZ36P1amHky1QyvQ2stkXjCEtP04h3o3EfC1yupNXarO1VXj10/wWYhoGAz6AT2 Usk6DiaiJqHPy2RwPfKzv7ZrUlMxKrqjPUHcoBf++EjzFtR3LJ0pY2fLwp6Pk4s4 18Xwi7r16HnCH/BZgqZVyXAhDV6+U9rAHab/n4b0hcWWaT2SIhsyZKtEMiTMJeq5 aAMcRSWX+dHO+MzMIBzNu7BO3b+zODD0+XSMsPqeHp3cqfZ3EHobKQPPFucdfjug Hx2+dbPD3IwJVIilc9Otfz/+JYG4im5p4N6UCwXHbtiuuREC1SQpU9BqEjQAyIiL gXlE5MSVqXijkrIpYB+K8cR+44nQ4K2kc4ievNqXR6D7XQ3AE76QN84Lby2b5W86 bbboIy0Bgy+9jgCx0CS7fk1P8zx1dw2FNDVfxZ+s473ZvwP1wdSRZICjZUvM8hx4 4kPCiQJVBBMBCAA/AhsDBgsJCAcDAgYVCAIJCgsEFgIDAQIeAQIXgBYhBIq+Tvzw 9LJL/yqvkNVw8tNOoHk9BQJiOkMeBQkUJ/c7AAoJENVw8tNOoHk9Xx8P/26W8v/v Exmttzcqh7MlihddXfr2lughSuUBQ8aLsffGHSGIgyqSPlq0Fl5qOCoJ8hYZSBqV yEfo7iRY7E3K1LGXKDkpup9hC1wMjR0A25eoXwEnD2vEQ/upXXueH05vkcMc165B cK0kNxas+2amCc3nHJOlfWILXQk4OS+nB0lBWe8H96ppfAaX/G0JiYsa0hjNycZq 0ftEdCkAJRvSFuu6d3gXH69KLxoNcJOE+99f3wMOuOcX3Xf1k/cwqdJRdEiW8oz8 Gf5ZRzWcpsXXg6nB2mkahLoRDMM2U+1C6fHbUg4yTvU1AB+F/OYqe1d0hedho0o5 +WWoTuM/U79+m3NM14qvr0iJP7ytABiEE96nNAz+Q0NDZqA6JoUd7obo8KVjGHEt 9bRl/8K/zWkdNLoF84tWjEiBCzCKXGEay7lgiIx5f3OvP91CfGL+ILHrk/AZR1eE M+KI7wB8sJEFF95UoKVua3YzLIFScB4bUEOg6bz8xSSP4a0BWktSm5ws8iCWqOE6 S9haCppZ7a6k5czQNPJV2bp2eTS4ykFAQLv/mHMS5awIvb8b630Rufn1vZHKCrMf WdSbBZD7oojxYo1psPlfzN2KUrNXgl7vAUNagJEogMoiYAZ2ML7rTVAC1qnbxQb+ DeC+r0I98AIY6igIgRbcybH3ccfXYNtcxLUJuQINBFO15mMBEAC5UuLii9ZLz6qH 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 HqEsbIFUXBYXPgbwXTm7c4IHGgXXdwARAQABiQI8BBgBAgAmAhsMFiEEir5O/PD0 skv/Kq+Q1XDy006geT0FAlvR7oMFCQvebyAACgkQ1XDy006geT2Hxw//Zha8j8Uc 4B+DmHhZIvPmHp9aFI4DWhC7CBDrYKztBz42H6eX+UsBu4p+uBDKdW9xJH+Qt/zF nf/zB5Bhc/wFceVRCAkWxPdiIQeo5XQGjZeORjle7E9iunTko+5q1q9I7IgqWYrn jRmulDvRhO7AoUrqGACDrV6t0F1/XPB8seR2i6axFmFlt1qBHasRq11yksdgNYiD KXaovf7csDGPGOCWEKMX7BFGpdK/dWdNYfH0Arfom0U5TqNfvGtP4yRPx2bcs7/1 VXPj7IqhBgOtA9pwtMjFki8HGkqj7bB2ErFBOnSwqqNnNcbnhiO6D74SHVGAHhKZ whaMPDg76EvjAezoLHg7KWYOyUkWJSLa+YoM9r4+PJuEuW/XuaZCNbrAhek+p3pD ywhElvZe/2UFk619qKzwSbTzk7a90rxLQ2wwtd0vxAW/GyjWl4/kOMZhI5+LAk1l REucE0fSQxzCTeXu2ObvFR9ic02IYGH3Koz8CrGReEI1J05041Y5IhKxdsvGOD2W e7ymcblYW4Gz8eYFlLeNJkj/38R7qmNZ028XHzAZDCAWDiTFrnCoglyk+U0JRHfg HTsdvoc8mBdT/s24LhnfAbpLizlrZZquuOF6NLQSkbuLtmIwf+h9ynEEJxEkGGWg 7JqB1tMjNHLkRpveO/DTYB+iffpba1nCgumJAjwEGAEIACYCGwwWIQSKvk788PSy S/8qr5DVcPLTTqB5PQUCYjpDOQUJFCf3VgAKCRDVcPLTTqB5PYDiEADaj1aAdXDb +XrlhzlGCT3e16RDiE4BjSD1KHZX8ZDABI79JDG0iMN2PpWuViXq7AvWuwgNYdac WjHsZGgHW82UoPVGKnfEVjjf0lQQIIcgdS5dEV8LamkeIo4vKUX/MZY+Mivk6luP vCec9Euj/XU1nY6gGq6inpwDtZkNoJlCBune/IIGS82dU8RrSGAHNRZoaDJfdfQm j7YAOWCUqyzn747yMyuMUOc15iJIgOz1dKN5YwDmFkzjlw+616Aswcp8UA0OfOQ+ e4THli32BgKTSNeOGhGgx1xCDkt+0gP1L0L2Sqhlr6BnqNF65mQ4j2v6UGY1noCo jYxFchoa1zEdEiZRr/sRO91XlJtK7HyIAI0cUHKVU+Cayoh//OBQBJnbeZlfh9Qn 4ead1pTz9bcKIeZleAjlzNG249bGY+82WsFghb4/7U9MYJVePz0m1zJKPkdABZ+R lSDvhf4ImesfH5UuofZFv1UXmQL4yV7PDXXdy2xhma7YLznyZTUobDoJiZbuO72O g5HJCpYoNfvGx++Z9naomUWufqi9PWigEMxU8lUtiGaLQrDW3inTOZTTmTnsJiAI Lhku0Jr4SjCqxoEFydXOGvNV5XB4WXvf+A6JhcZI+/S72ai1CeSgMFiJLAEb2MZ+ fwPKmQ2cKnCBs5ASj1DkgUcz2c8DTUPVqg== =i1Tf \-\-\-\-\-END PGP PUBLIC KEY BLOCK\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .sp The SaltStack Security Team is available at \fI\%saltproject\-security.pdl@broadcom.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\%saltproject\-security.pdl@broadcom.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 pre\-announcement is sent out to the \fI\%salt\-announce\fP mailing list approximately a week before the CVE release. This announcement does not include details of the vulnerability. The pre\-announcement will include the date the release will occur and the vulnerability rating. .IP 6. 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 7. 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 Channels .sp One of the fundamental features of Salt is remote execution. Salt has two basic \(dqchannels\(dq 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. Channels use \fI\%Transports\fP for sending and receiving messages. .SS Pub Channel .sp The pub (or pubish) 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 published payloads. .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. The req channel is also used by the salt cli to publish jobs to the master. .SS Salt Transport .sp Transports in Salt are used by \fI\%Channels\fP to send messages between Masters, Minions, and the Salt CLI. Transports can be brokerless or brokered. There are two types of server / client implementations needed to implement a channel. .SS Publish Server .sp The publish server implements a publish / subscribe paradigm and is used by Minions to receive jobs from Masters. .SS Publish Client .sp The publish client subscribes to, and receives messages from a Publish Server. .SS Request Server .sp The request server implements a request / reply paradigm. Every request sent by the client must receive exactly one reply. .SS Request Client .sp The request client sends requests to a Request Server and receives a reply message. .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 Publish Server and Client .sp The publish server and client are 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 Request Server and Client .sp The request server and client are 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 transport 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 \fI\%transport\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 TLS Support .sp The TLS transport supports full encryption and verification using both server and client certificates. See \fI\%Transport TLS Support\fP for more details. .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 \(dqhead\(dq and \(dqbody\(dq. Head contains header information (such as \(dqmessage id\(dq). The Body contains the actual message that we are sending. With this flexible wire protocol we can implement any message semantics that we\(aqd like\-\- including multiplexed message passing on a single socket. .SS Crypto .sp The current implementation uses the same crypto as the \fBzeromq\fP transport. .SS Publish Server and Client .sp For the publish server and client we send messages without \(dqmessage ids\(dq which the remote end interprets as a one\-way send. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As of Salt \fI\%2016.3.0\fP, publishes using \fBlist\fP targeting are sent only to relevant minions and not broadcasted. .sp As of Salt \fI\%3005\fP, publishes using \fBpcre\fP and \fBglob\fP targeting are also sent only to relevant minions and not broadcasted. Other targeting types are always sent to all minions and rely on minion\-side filtering. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt CLI defaults to \fBglob\fP targeting type, so in order to target specific minions without broadcast, you need to use \fI\-L\fP option, such as \fBsalt \-L my.minion test.ping\fP, for masters before 3005. .UNINDENT .UNINDENT .SS Request Server and Client .sp For the request server and client we send messages with a \(dqmessage id\(dq. This \(dqmessage id\(dq allows us to multiplex messages across the socket. .SS Websocket Transport .sp The Websocket transport is an implementation of Salt\(aqs transport using the websocket protocol. The Websocket transport is enabled by changing the \fI\%transport\fP setting to \fBws\fP on each Salt minion and Salt master. .SS TLS Support .sp The Websocket transport supports full encryption and verification using both server and client certificates. See \fI\%Transport TLS Support\fP for more details. .SS Publish Server and Client .sp The publish server and client are implemented using aiohttp. .SS Request Server and Client .sp The request server and client are implemented using aiohttp. .SS Transport TLS Support .sp Whenever possible transports should provide TLS Support. Currently the \fI\%TCP Transport\fP and \fI\%Websocket Transport\fP transports support encryption and verification using TLS. .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 \fBssl\fP option is enabled. The \fBssl\fP option is passed as a dict and roughly corresponds to the options passed to the Python \fI\%ssl.wrap_socket\fP function for backwards compatability. .sp New in version 3007.0. .sp The \fBssl\fP option accepts \fBverify_locations\fP and \fBverify_flags\fP\&. The \fBverify_locations\fP option is a list of strings or dictionaries. Strings are passed as a single argument to the SSL context\(aqs \fBload_verify_locations\fP method. Dictionary keys are expected to be one of \fBcafile\fP, \fBcapath\fP, \fBcadata\fP\&. For each corresponding key, the key and value will be passed as a keyword argument to \fBload_verify_locations\fP\&. The \fBverify_flags\fP option is a list of string names of verification flags which will be set on the SSL context. All paths are assumed to be the full path to the file or directory. .sp A simple setup looks like this, on the Salt Master add the \fBssl\fP option to the master configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssl: keyfile: <path_to_keyfile> certfile: <path_to_certfile> .ft P .fi .UNINDENT .UNINDENT .sp A more complex setup looks like this, on the Salt Master add the \fBssl\fP option to the master\(aqs configuration file. In this example the Salt Master will require valid client side certificates from Minions by setting \fBcert_reqs\fP to \fBCERT_REQUIRED\fP\&. The Salt Master will also check a certificate revocation list if one is provided in \fBverify_locations\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssl: keyfile: <path_to_keyfile> certfile: <path_to_certfile> cert_reqs: CERT_REQUIRED verify_locations: \- <path_to_ca_cert> \- capath: <directory_of_certs> \- cafile: <path_to_crl> verify_flags: \- VERIFY_CRL_CHECK_CHAIN .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 A Minion can be configured to present a client certificate to the master like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssl: keyfile: <path_to_keyfile> certfile: <path_to_certfile> .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. .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 \fI\%highstate\fP 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 Changed in version 3007.0: Masterless minions now support master top modules as well. .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 \fI\%Cobbler\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 \fI\%Reclass\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 \fI\%saltutil.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__ = \(dqcustomtop\(dq log = logging.getLogger(__name__) def __virtual__(): return __virtualname__ def top(**kwargs): log.debug(\(dqCalling top in customtop\(dq) return {\(dqbase\(dq: [\(dqtest\(dq]} .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 \fI\%top file\fP 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 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 \fI\%renderer\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. Some exceptions to this would be the \fI\%pure python\fP and \fI\%gpg\fP renderers which could be used in either capacity. .SS Text Renderers .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Jinja\fP supports a \fI\%secure, sandboxed template execution environment\fP that Salt takes advantage of. Other text \fI\%Renderers\fP do not support this functionality, so Salt highly recommends usage of \fBjinja\fP / \fBjinja|yaml\fP\&. .UNINDENT .UNINDENT .sp A text renderer returns text. These include templating engines such as \fI\%jinja\fP, \fI\%mako\fP, and \fI\%genshi\fP, as well as the \fI\%gpg\fP renderer. The following are all text renderers: .INDENT 0.0 .IP \(bu 2 \fI\%aws_kms\fP .IP \(bu 2 \fI\%cheetah\fP .IP \(bu 2 \fI\%genshi\fP .IP \(bu 2 \fI\%gpg\fP .IP \(bu 2 \fI\%jinja\fP .IP \(bu 2 \fI\%mako\fP .IP \(bu 2 \fI\%nacl\fP .IP \(bu 2 \fI\%pass\fP .IP \(bu 2 \fI\%py\fP .IP \(bu 2 \fI\%wempy\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 \fI\%dson\fP .IP \(bu 2 \fI\%hjson\fP .IP \(bu 2 \fI\%json5\fP .IP \(bu 2 \fI\%json\fP .IP \(bu 2 \fI\%pydsl\fP .IP \(bu 2 \fI\%pyobjects\fP .IP \(bu 2 \fI\%py\fP .IP \(bu 2 \fI\%stateconf\fP .IP \(bu 2 \fI\%yamlex\fP .IP \(bu 2 \fI\%yaml\fP .IP \(bu 2 \fI\%gpg\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 \(dqshebang\(dq\-like syntax on the first line of the SLS file: .sp Here is an example of using the \fI\%pure python\fP renderer to install a package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!py def run(): \(dq\(dq\(dq Install version 1.5\-1.el7 of package \(dqpython\-foo\(dq \(dq\(dq\(dq return { \(dqinclude\(dq: [\(dqpython\(dq], \(dqpython\-foo\(dq: {\(dqpkg.installed\(dq: [{\(dqversion\(dq: \(dq1.5\-1.el7\(dq}]}, } .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 \(dqRender Pipeline\(dq) .sp A render pipeline can be composed from other renderers by connecting them in a series of \(dqpipes\(dq (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 \(dqUsing Salt ${grains[\(aqsaltversion\(aq]}\(dq \e \(dqfrom path {{grains[\(aqsaltpath\(aq]}}.\(dq \- cwd: / <%doc> ${...} is Mako\(aqs notation, and so is this comment. </%doc> {# 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 \fI\%yaml\fP renderer is a Python data structure, and the \fI\%jinja\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=\(dqbase\(dq, sls=\(dq\(dq, **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 \fI\%state.apply\fP .IP \(bu 2 \fI\%saltutil.sync_renderers\fP .IP \(bu 2 \fI\%saltutil.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 \fI\%saltutil.sync_renderers\fP or \fI\%saltutil.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\%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=\(dq\(dq, sls=\(dq\(dq, **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 .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Jinja\fP supports a \fI\%secure, sandboxed template execution environment\fP that Salt takes advantage of. Other text \fI\%Renderers\fP do not support this functionality, so Salt highly recommends usage of \fBjinja\fP / \fBjinja|yaml\fP\&. .UNINDENT .UNINDENT .TS center; |l|l|. _ T{ \fI\%aws_kms\fP T} T{ T} _ T{ \fI\%cheetah\fP T} T{ Cheetah Renderer for Salt T} _ T{ \fI\%dson\fP T} T{ DSON Renderer for Salt T} _ T{ \fI\%genshi\fP T} T{ Genshi Renderer for Salt T} _ T{ \fI\%gpg\fP T} T{ Renderer that will decrypt GPG ciphers T} _ T{ \fI\%hjson\fP T} T{ hjson renderer for Salt T} _ T{ \fI\%jinja\fP T} T{ Jinja loading utils to enable a more powerful backend for jinja templates T} _ T{ \fI\%json\fP T} T{ JSON Renderer for Salt T} _ T{ \fI\%json5\fP T} T{ JSON5 Renderer for Salt T} _ T{ \fI\%mako\fP T} T{ Mako Renderer for Salt T} _ T{ \fI\%msgpack\fP T} T{ T} _ T{ \fI\%nacl\fP T} T{ Renderer that will decrypt NACL ciphers T} _ T{ \fI\%pass\fP T} T{ Pass Renderer for Salt T} _ T{ \fI\%py\fP T} T{ Pure python state renderer T} _ T{ \fI\%pydsl\fP T} T{ A Python\-based DSL T} _ T{ \fI\%pyobjects\fP T} T{ Python renderer that includes a Pythonic Object based interface T} _ T{ \fI\%stateconf\fP T} T{ A flexible renderer that takes a templating engine and a data format T} _ T{ \fI\%tomlmod\fP T} T{ T} _ T{ \fI\%wempy\fP T} T{ T} _ T{ \fI\%yaml\fP T} T{ YAML Renderer for Salt T} _ T{ \fI\%yamlex\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 \(dqsalt\(dq, 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 \(dq%s\(dq\en\(aq \(dq$data_key\(dq >> 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 value 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 The default \fIGPG Homedir <gpg\-homedir>\fP is \fB~/.gnupg\fP and needs to be set using \fBgpg \-\-homedir\fP\&. Be very careful to not forget this option. It is also important to run \fBgpg\fP commands as the user that owns the keys directory. If the salt\-master runs as user \fBsalt\fP, then use \fBsu \- salt\fP before running any gpg commands. .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\&. .sp The \fB\-\-homedir\fP argument can be configured for the current user using \fBecho \(aqhomedir /etc/salt/gpgkeys\(aq >> ~/.gnupg\fP, but this should be used with caution to avoid potential confusion. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gpg_keydir: <path/to/homedir> .ft P .fi .UNINDENT .UNINDENT .SS GPG Keys .sp GPG key pairs include both a public and private key. The private key is akin to a password and should be kept secure by the owner. A public key is used to encrypt data being sent to the owner of the private key. .sp This means that the public key will be freely distributed so that others can encrypt pillar data without access to the secret key. .SS New Key Pair .sp To create a new GPG key pair for encrypting data, log in to the master as root and run the following: .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 \-\-gen\-key .ft P .fi .UNINDENT .UNINDENT .sp Do not supply a password for the keypair and use a name that makes sense for your application. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In some situations, gpg may be starved of entropy and will take an incredibly long time to finish. Two common tools to generate (less secure) pseudo\-random data are \fBrng\-tools\fP and \fBhaveged\fP\&. .UNINDENT .UNINDENT .sp The new keys can be seen and verified using \fB\-\-list\-secret\-keys\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # gpg \-\-homedir /etc/salt/gpgkeys \-\-list\-secret\-keys /etc/salt/gpgkeys/pubring.kbx \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- sec rsa4096 2002\-05\-12 [SC] [expires: 2012\-05\-10] 2DC47B416EE8C3484450B450A4D44406274AF44E uid [ultimate] salt\-master (gpg key for salt) <salt@cm.domain.tld> ssb rsa4096 2002\-05\-12 [E] [expires: 2012\-05\-10] .ft P .fi .UNINDENT .UNINDENT .sp In the example above, our KEY\-ID is \fB2DC47B416EE8C3484450B450A4D44406274AF44E\fP\&. .SS Export Public Key .sp To export a public key suitable for public distribution: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # gpg \-\-homedir /etc/salt/gpgkeys \-\-armor \-\-export <KEY\-ID> > exported_pubkey.asc .ft P .fi .UNINDENT .UNINDENT .SS Import Public Key .sp Users wishing to import the public key into their local keychain may run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ gpg \-\-import exported_pubkey.asc .ft P .fi .UNINDENT .UNINDENT .SS Export (Save) Private Key .sp This key protects all gpg\-encrypted pillar data and should be backed up to a safe and secure location. This command will generate a backup of secret keys in the \fB/etc/salt/gpgkeys\fP directory to the \fBgpgkeys.secret\fP file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # gpg \-\-homedir /etc/salt/gpgkeys \-\-export\-secret\-keys \-\-export\-options export\-backup \-o gpgkeys.secret .ft P .fi .UNINDENT .UNINDENT .sp Salt does not support password\-protected private keys, which means this file is essentially a clear\-text password (just add \fB\-\-armor\fP). Fortunately, it is trivial to pass this export back to gpg to be encrypted with symmetric key: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # gpg \-\-homedir /etc/salt/gpgkeys \-\-export\-secret\-keys \-\-export\-options export\-backup | gpg \-\-symmetric \-o gpgkeys.gpg .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In some cases, particularly when using su/sudo, gpg gets confused and needs to be told which TTY to use; this can be done with: \fBexport GPG_TTY=$(tty)\fP\&. .UNINDENT .UNINDENT .SS Import (Restore) Private Key .sp To import/restore a private key, create a directory with the correct permissions and import using gpg. .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 \-\-import gpgkeys.secret .ft P .fi .UNINDENT .UNINDENT .sp If the export was encrypted using a symmetric key, then decrypt first with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # gpg \-\-decrypt gpgkeys.gpg | gpg \-\-homedir /etc/salt/gpgkeys \-\-import .ft P .fi .UNINDENT .UNINDENT .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. .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 <KEY\-ID> .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 Encrypting Data .sp In order to encrypt data to a recipient (salt), the public key must be imported into the local keyring. Importing the public key is described above in the \fIImport Public Key <gpg\-importpubkey:>\fP section. .sp To generate a cipher from a secret: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ echo \-n \(aqsupersecret\(aq | gpg \-\-trust\-model always \-ear <KEY\-ID> .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 \fI\%state.highstate\fP and \fI\%state.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=\(dq{\(aqmypillar\(aq: \(aqfoo\(aq}\(dq .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 \(dqsupersecret\(dq | gpg \-\-armor \-\-batch \-\-trust\-model always \-\-encrypt \-r user@domain.com | awk \(aq{printf \(dq%s\e\en\(dq,$0} END {print \(dq\(dq}\(aq\(ga # Perl ciphertext=\(gaecho \-n \(dqsupersecret\(dq | 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=\(dq{secret_pillar: \(aq$ciphertext\(aq}\(dq .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 \(dq{\(aqsecret_a\(aq: \(aqCorrectHorseBatteryStaple\(aq, \(aqsecret_b\(aq: \(aqGPG is fun!\(aq}\(dq | gpg \-\-armor \-\-batch \-\-trust\-model always \-\-encrypt \-r user@domain.com | awk \(aq{printf \(dq%s\e\en\(dq,$0} END {print \(dq\(dq}\(aq\(ga # Perl ciphertext=\(gaecho \-n \(dq{\(aqsecret_a\(aq: \(aqCorrectHorseBatteryStaple\(aq, \(aqsecret_b\(aq: \(aqGPG is fun!\(aq}\(dq | 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=\(dq$ciphertext\(dq .ft P .fi .UNINDENT .UNINDENT .SS Configuration .sp The default behaviour of this renderer is to log a warning if a block could not be decrypted; in other words, it just returns the ciphertext rather than the encrypted secret. .sp This behaviour can be changed via the \fIgpg_decrypt_must_succeed\fP configuration option. If set to \fITrue\fP, any gpg block that cannot be decrypted raises a \fISaltRenderError\fP exception, which registers an error in \fB_errors\fP during rendering. .sp In the Chlorine release, the default behavior will be reversed and an error message will be added to \fB_errors\fP by default. .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 \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Jinja\fP supports a \fI\%secure, sandboxed template execution environment\fP that Salt takes advantage of. Other text \fI\%Renderers\fP do not support this functionality, so Salt highly recommends usage of \fBjinja\fP / \fBjinja|yaml\fP\&. .UNINDENT .UNINDENT .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 = {\(dqbaz\(dq: [1, 2, 3], \(dqfoo\(dq: true, \(dqbar\(dq: 42, \(dqqux\(dq: 2.0} python = {\(aqbar\(aq: 42, \(aqbaz\(aq: [1, 2, 3], \(aqfoo\(aq: True, \(aqqux\(aq: 2.0} xml = \(dq\(dq\(dq<<?xml version=\(dq1.0\(dq ?> <root_node bar=\(dq42\(dq foo=\(dqTrue\(dq qux=\(dq2.0\(dq> <baz>1</baz> <baz>2</baz> <baz>3</baz> </root_node>\(dq\(dq\(dq .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 = \(dq{foo: it works}\(dq|load_yaml %} {%\- set json_src = \(aq{\(dqbar\(dq: \(dqfor real\(dq}\(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 %} { \(dqbar\(dq: \(dqfor real\(dq } {% 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 \(dqmyfile.yml\(dq as myfile %} {% import_json \(dqdefaults.json\(dq as defaults %} {% import_text \(dqcompleteworksofshakespeare.txt\(dq 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 \(dqdoc1.sls\(dq 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 .sp ** Salt State Parameter Format Filters ** .sp New in version 3005. .sp Renders a formatted multi\-line YAML string from a Python dictionary. Each key/value pair in the dictionary will be added as a single\-key dictionary to a list that will then be sent to the YAML formatter. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set thing_params = { \(dqname\(dq: \(dqthing\(dq, \(dqchanges\(dq: True, \(dqwarnings\(dq: \(dqOMG! Stuff is happening!\(dq } %} thing: test.configurable_test_state: {{ thing_params | dict_to_sls_yaml_params | indent }} .ft P .fi .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \&.. code\-block:: yaml .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B thing: .INDENT 7.0 .TP .B test.configurable_test_state: .INDENT 7.0 .IP \(bu 2 name: thing .IP \(bu 2 changes: true .IP \(bu 2 warnings: OMG! Stuff is happening! .UNINDENT .UNINDENT .UNINDENT .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 .sp This renderer requires the Mako library. .sp To install Mako, do the following: .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 PyNacl >= 1.0 .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: \(dqNACL[MRN3cc+fmdxyQbz6WMF+jq1hKdU5X5BBI7OjK+atvHo1ll+w1gZ7XyWtZVfq9gK9rQaMfkDxmidJKwE0Mw==]\(dq .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 .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<user>\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 <location_of_private_gpg_key> \- unless: gpg \-\-list\-keys \(aq<gpg_name>\(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: <git_repo> \- target: /<user>/.password\-store \- identity: <location_of_ssh_private_key> \- 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 .sp Salt master configuration options .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # If the prefix is *not* set (default behavior), all template variables are # considered for fetching secrets from Pass. Those that cannot be resolved # to a secret are passed through. # # If the prefix is set, only the template variables with matching prefix are # considered for fetching the secrets, other variables are passed through. # # For ease of use it is recommended to set the following options as well: # renderer: \(aqjinja|yaml|pass\(aq # pass_strict_fetch: true # pass_variable_prefix: \(aqpass:\(aq # If set to \(aqtrue\(aq, error out when unable to fetch a secret for a template variable. pass_strict_fetch: true # Set GNUPGHOME env for Pass. # Defaults to: ~/.gnupg pass_gnupghome: <path> # Set PASSWORD_STORE_DIR env for Pass. # Defaults to: ~/.password\-store pass_dir: <path> .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 \- \fI\%Execution functions\fP (i.e. \fB__salt__[\(aqtest.echo\(aq](\(aqfoo\(aq)\fP) .IP \(bu 2 \fB__grains__\fP \- \fI\%Grains\fP (i.e. \fB__grains__[\(aqos\(aq]\fP) .IP \(bu 2 \fB__pillar__\fP \- \fI\%Pillar data\fP (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 \(dqsaltenv\(dq. \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 used in a scenario where additional user\-provided context data is supplied (such as with \fI\%file.managed\fP), the additional data will typically be injected into the script as one or more global variables: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/http/conf/http.conf: file.managed: \- source: salt://apache/generate_http_conf.py \- template: py \- context: # Will be injected as the global variable \(dqsite_name\(dq. site_name: {{ site_name }} .ft P .fi .UNINDENT .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 \fI\%Include declaration\fP\(aqs. .UNINDENT .UNINDENT .sp \fBextend\fP .INDENT 0.0 .INDENT 3.5 Salt PyDSL function for creating \fI\%Extend declaration\fP\(aqs. .UNINDENT .UNINDENT .sp \fBstate\fP .INDENT 0.0 .INDENT 3.5 Salt PyDSL function for creating \fI\%ID declaration\fP\(aqs. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp A state \fI\%ID declaration\fP is created with a \fBstate(id)\fP function call. Subsequent \fBstate(id)\fP call with the same id returns the same object. This singleton access pattern 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 \fI\%State declaration\fP 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 \fI\%Function declaration\fP object can be created from a \fI\%State declaration\fP 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 \fI\%State declaration\fP 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 \fI\%State declaration\fP, 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 \fI\%Function declaration\fP object, any \fI\%Function arg declaration\fP\(aqs can be passed as keyword arguments to the call. Subsequent calls of a \fI\%Function declaration\fP 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 \fI\%State declaration\fP 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 \fI\%Requisite declaration\fP object with its \fI\%Requisite reference\fP\(aqs can be created by invoking one of the requisite methods (see \fI\%State Requisites\fP) on either a \fI\%Function declaration\fP object or a \fI\%State declaration\fP object. The return value of a requisite call is also a \fI\%Function declaration\fP object, so you can chain several requisite calls together. .sp Arguments to a requisite call can be a list of \fI\%State declaration\fP objects and/or a set of keyword arguments whose names are state modules and values are IDs of \fI\%ID declaration\fP\(aqs or names of \fI\%Name declaration\fP\(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 \fI\%Include declaration\fP objects can be created with the \fBinclude\fP function, while \fI\%Extend declaration\fP objects can be created with the \fBextend\fP function, whose arguments are just \fI\%Function declaration\fP 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 \fI\%Include declaration\fP\(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, \(dqthree\(dq) .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 \fI\%Include declaration\fP in the rendered result, and such call always returns \fBNone\fP\&. .SS Special integration with the \fIcmd\fP state .sp Taking advantage of rendering a Python module, PyDSL allows you to declare a state that calls a pre\-defined Python function when the state is executed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C greeting = \(dqhello world\(dq 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, \(dqtest123\(dq, \(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 \fI\%salt.states.cmd.call()\fP for more information. .SS Implicit ordering of states .sp Salt states are explicitly ordered via \fI\%Requisite declaration\fP\(aqs. However, with \fIpydsl\fP it\(aqs possible to let the renderer track the order of creation for \fI\%Function declaration\fP objects, and implicitly add \fBrequire\fP requisites for your states to enforce the ordering. This feature is enabled by setting the \fBordered\fP option on \fB__pydsl__\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 this feature is only available if your minions are using Python >= 2.7. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include(\(aqsome.sls.file\(aq) A = state(\(aqA\(aq).cmd.run(cwd=\(aq/var/tmp\(aq) extend(A) __pydsl__.set(ordered=True) for i in range(10): i = str(i) state(i).cmd.run(\(aqecho \(aq+i, cwd=\(aq/\(aq) state(\(aq1\(aq).cmd.run(\(aqecho one\(aq) state(\(aq2\(aq).cmd.run(name=\(aqecho two\(aq) .ft P .fi .UNINDENT .UNINDENT .sp Notice that the \fBordered\fP option needs to be set after any \fBextend\fP calls. This is to prevent \fIpydsl\fP from tracking the creation of a state function that\(aqs passed to an \fBextend\fP call. .sp Above example should create states from \fB0\fP to \fB9\fP that will output \fB0\fP, \fBone\fP, \fBtwo\fP, \fB3\fP, ... \fB9\fP, in that order. .sp It\(aqs important to know that \fIpydsl\fP tracks the \fIcreations\fP of \fI\%Function declaration\fP objects, and automatically adds a \fBrequire\fP requisite to a \fI\%Function declaration\fP object that requires the last \fI\%Function declaration\fP object created before it in the sls file. .sp This means later calls (perhaps to update the function\(aqs \fI\%Function arg declaration\fP) to a previously created function declaration will not change the order. .SS Render time state execution .sp When Salt processes a salt formula file, 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 \fI\%ID declaration\fP 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 \fI\%ID declaration\fP 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 \fI\%ID declaration\fP object must be done before a new \fI\%Function declaration\fP is created. .UNINDENT .UNINDENT .SS Integration with the stateconf renderer .sp The \fI\%salt.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.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(\(dq/tmp\(dq, user=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq1777\(aq) .ft P .fi .UNINDENT .UNINDENT .sp Nice and Pythonic! .sp By using the \(dqshebang\(dq 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(\(dqnginx\(dq): Service.running(\(dqnginx\(dq, enable=True) with Service(\(dqnginx\(dq, \(dqwatch_in\(dq): File.managed(\(dq/etc/nginx/conf.d/mysite.conf\(dq, 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(\(dqnginx\(dq) Service.running(\(dqnginx\(dq, enable=True, require=Pkg(\(dqnginx\(dq)) File.managed(\(dq/etc/nginx/conf.d/mysite.conf\(dq, owner=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq0444\(aq, source=\(aqsalt://nginx/mysite.conf\(aq, watch_in=Service(\(dqnginx\(dq)) .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(\(dqnginx\(dq, require=Pkg(\(dqsome\-other\-package\(dq)) .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(\(dqmy\-service\(dq, \(dqwatch_in\(dq): ... .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(\(dqmy\-service\(dq)\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 Opts dictionary and SLS name .sp Pyobjects provides variable access to the minion options dictionary and the SLS name that the code resides in. These variables are the same as the \fIopts\fP and \fIsls\fP variables available in the Jinja renderer. .sp The following lines show how to access that information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects test_mode = __opts__[\(dqtest\(dq] sls_name = __sls__ .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(\(dqsamba\(dq, names=[Samba.server, Samba.client]): Service.running(\(dqsamba\(dq, 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, \(dqhttp://%(host)s:%(port)s/\(dq % 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.tomlmod.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 {\(dqmy_key\(dq: \(dqmy_value\(dq} .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 {\(dqfirst_level_dict_key\(dq: {\(dqsecond_level_dict_key\(dq: \(dqvalue_in_second_level_dict\(dq}} .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 \fI\%Understanding YAML\fP\&. .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 \fI\%grains\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/<minion ID>/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 \fI\%top file\fP 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 \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Grains can be set by users that have access to the minion configuration files on the local system, making them less secure than other identifiers in Salt. Avoid storing sensitive data, such as passwords or keys, on minions. Instead, make use of \fI\%Storing Static Data in the Pillar\fP and/or \fI\%Storing Data in Other Databases\fP\&. .UNINDENT .UNINDENT .sp The grains are derived by executing all of the \(dqpublic\(dq 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 \fI\%file_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 \fI\%state.highstate\fP is run, or by executing the \fI\%saltutil.sync_grains\fP or \fI\%saltutil.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[\(dqyourcustomgrain\(dq] = True grains[\(dqanothergrain\(dq] = \(dqsomevalue\(dq 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 \fI\%Pillar\fP 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 \fI\%top file\fP 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 \fI\%highstate\fP\&. To make custom grains available on a minion\(aqs first highstate, it is recommended to use \fI\%this example\fP 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 = {\(dqfoo\(dq: \(dqbar\(dq, \(dqhello\(dq: \(dqworld\(dq} return my_grain def main(): # initialize a grains dictionary grains = {} grains[\(dqmy_grains\(dq] = _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: \-\-\-\-\-\-\-\-\-\- <Snipped for brevity> 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: \-\-\-\-\-\-\-\-\-\- <Snipped for brevity> foo: bar <Snipped for brevity> hello: world <Snipped for brevity> 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\%salt/grains/core.py\fP .SS Syncing Grains .sp Syncing grains can be done a number of ways. They are automatically synced when \fI\%state.highstate\fP is called, or (as noted above) the grains can be manually synced and reloaded by calling the \fI\%saltutil.sync_grains\fP or \fI\%saltutil.sync_all\fP functions. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When the \fI\%grains_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 \fI\%pillar_roots\fP setup that matches the structure of the \fI\%file_roots\fP used in the Salt file server. Like \fI\%file_roots\fP, the \fI\%pillar_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 \fI\%top file\fP\&. .sp conf_master:\fIpillar_roots\fP is configured just like \fI\%file_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 \fI\%Is Targeting using Grain Data Secure?\fP 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 \fI\%running states\fP, 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 \fI\%pillar_roots\fP, all environments that are not explicitly specified in \fI\%pillar_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. .sp Taking it one step further, \fB__env__\fP can also be used in the \fBpillar_root\fP filesystem path. It will be replaced with the actual \fBpillarenv\fP and searched for Pillar data to provide to the minion. Note this substitution ONLY occurs for the \fB__env__\fP environment. For instance, this configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_roots: __env__: \- /srv/__env__/pillar .ft P .fi .UNINDENT .UNINDENT .sp is equivalent to this static configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_roots: dev: \- /srv/dev/pillar test: \- /srv/test/pillar prod: \- /srv/prod/pillar .ft P .fi .UNINDENT .UNINDENT .sp New in version 3005. .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 \fI\%pillar.item\fP, \fI\%pillar.get\fP, and \fI\%pillar.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 \fI\%saltutil.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 \fI\%pillar.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 \fI\%pillar.item\fP, \fI\%pillar.get\fP, and \fI\%pillar.raw\fP will not see this data unless refreshed using \fI\%saltutil.refresh_pillar\fP\&. .sp If you are using the Pillar Cache and have set \fI\%pillar_cache\fP to \fITrue\fP, the pillar cache can be updated either when you run \fI\%saltutil.refresh_pillar\fP, or using the pillar runner function \fI\%pillar.clear_pillar_cache\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run pillar.clear_pillar_cache \(aqminion\(aq .ft P .fi .UNINDENT .UNINDENT .sp The pillar will not be updated when running \fI\%pillar.items\fP or a state for example. If you are using a Salt version before 3003, you would need to manually delete the cache file, located in Salt\(aqs master cache. For example, on linux the file would be in this directory: /var/cache/salt/master/pillar_cache/ .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 \fI\%pillarenv\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 \fI\%pillarenv\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 \fI\%pillarenv\fP option to be set in the minion config file. When \fI\%pillarenv\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 \fI\%pillarenv_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, \fI\%pillarenv_from_saltenv\fP will be ignored, and passing a \fBpillarenv\fP on the CLI will temporarily override \fI\%pillarenv_from_saltenv\fP\&. .SS Viewing Pillar Data .sp To view pillar data, use the \fI\%pillar\fP execution module. This module includes several functions, each of them with their own use. These functions include: .INDENT 0.0 .IP \(bu 2 \fI\%pillar.item\fP \- Retrieves the value of one or more keys from the \fI\%in\-memory pillar data\fP\&. .IP \(bu 2 \fI\%pillar.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 \fI\%pillar.item\fP and returns their values from the \fI\%in\-memory pillar data\fP\&. .IP \(bu 2 \fI\%pillar.raw\fP \- Like \fI\%pillar.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 \fI\%pillar.get\fP \- Described in detail below. .UNINDENT .SS The \fI\%pillar.get\fP Function .sp New in version 0.14.0. .sp The \fI\%pillar.get\fP function works much in the same way as the \fBget\fP method in a python dict, but with an enhancement: nested dictionaries 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 \fI\%pillar.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{\(dqcheese\(dq: \(dqspam\(dq}\(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 \fI\%decrypt_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 \fI\%pillar.get\fP function. .sp If a different delimiter is needed, it can be specified using the \fI\%decrypt_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 \fI\%decrypt_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 \fI\%pillar.items\fP .IP \(bu 2 \fI\%state.apply\fP .IP \(bu 2 \fI\%state.highstate\fP .IP \(bu 2 \fI\%state.sls\fP .UNINDENT .sp Triggering 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: \(dq\-\-\-\-\-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\-\-\-\-\-\(dq}\(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 \fI\%decrypt_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 \fI\%gpg\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, \fI\%decrypt_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 \fI\%decrypt_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 \fI\%decrypt_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 \fI\%decrypt_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 \fI\%walkthrough\fP\&. .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 \fI\%top file\fP\&. .UNINDENT .UNINDENT .sp The top file will need to be updated to include this sls file: .sp \fB/srv/pillar/top.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- data \- users .ft P .fi .UNINDENT .UNINDENT .sp Now the data will be available to the minions. To use the pillar data in a state, 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 <salt.modules.state.apply_()\fP like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq salt \(aq*\(aq state.apply my_sls_file pillar=\(aq{\(dqhello\(dq: \(dqworld\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp Nested pillar values can also be set via the command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.sls my_sls_file pillar=\(aq{\(dqfoo\(dq: {\(dqbar\(dq: \(dqbaz\(dq}}\(aq .ft P .fi .UNINDENT .UNINDENT .sp Lists can be passed via command line pillar data as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.sls my_sls_file pillar=\(aq{\(dqsome_list\(dq: [\(dqfoo\(dq, \(dqbar\(dq, \(dqbaz\(dq]}\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If a key is passed on the command line that already exists on the minion, the key that is passed in will overwrite the entire value of that key, rather than merging only the specified value set via the command line. .UNINDENT .UNINDENT .sp The example below will swap the value for vim with telnet in the previously specified list, notice the nested pillar dict: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply edit.vim pillar=\(aq{\(dqpkgs\(dq: {\(dqvim\(dq: \(dqtelnet\(dq}}\(aq .ft P .fi .UNINDENT .UNINDENT .sp This will attempt to install telnet on your minions, feel free to uninstall the package or replace telnet value with anything else. .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 More On Pillar .sp Pillar data is generated on the Salt master and securely distributed to minions. Salt is not restricted to the pillar sls files when defining the pillar but can retrieve data from external sources. This can be useful when information about an infrastructure is stored in a separate location. .sp Reference information on pillar and the external pillar interface can be found in the Salt documentation: .sp \fI\%Pillar\fP .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql.pass: hardtoguesspassword .ft P .fi .UNINDENT .UNINDENT .sp This is very convenient when you need some dynamic configuration change that you want to be applied on the fly. For example, there is a chicken and the egg problem if you do this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql\-admin\-passwd: mysql_user.present: \- name: root \- password: somepasswd mydb: mysql_db.present .ft P .fi .UNINDENT .UNINDENT .sp The second state will fail, because you changed the root password and the minion didn\(aqt notice it. Setting mysql.pass in the pillar, will help to sort out the issue. But always change the root admin password in the first place. .sp This is very helpful for any module that needs credentials to apply state changes: mysql, keystone, etc. .SS Targeting Minions .sp Targeting minions is specifying which minions should run a command or execute a state by matching against hostnames, or system information, or defined groups, or even combinations thereof. .sp For example the command \fBsalt web1 apache.signal restart\fP to restart the Apache httpd server specifies the machine \fBweb1\fP as the target and the command will only be run on that one minion. .sp Similarly when using States, the following \fI\%top file\fP specifies that only the \fBweb1\fP minion should execute the contents of \fBwebserver.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqweb1\(aq: \- webserver .ft P .fi .UNINDENT .UNINDENT .sp The simple target specifications, glob, regex, and list will cover many use cases, and for some will cover all use cases, but more powerful options exist. .SS Targeting with Grains .sp The Grains interface was built into Salt to allow minions to be targeted by system properties. So minions running on a particular operating system can be called to execute a function, or a specific kernel. .sp Calling via a grain is done by passing the \-G option to salt, specifying a grain and a glob expression to match the value of the grain. The syntax for the target is the grain key followed by a glob expression: \(dqos:Arch*\(dq. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos:Fedora\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp Will return True from all of the minions running Fedora. .sp To discover what grains are available and what the values are, execute the grains.item salt function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.items .ft P .fi .UNINDENT .UNINDENT .sp More info on using targeting with grains can be found \fI\%here\fP\&. .SS Compound Targeting .sp New in version 0.9.5. .sp Multiple target interfaces can be used in conjunction to determine the command targets. These targets can then be combined using \fBand\fP or \fBor\fP statements. This is well defined with an example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-C \(aqG@os:Debian and webser* or E@db.*\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp In this example any minion who\(aqs id starts with \fBwebser\fP and is running Debian, or any minion who\(aqs id starts with db will be matched. .sp The type of matcher defaults to glob, but can be specified with the corresponding letter followed by the \fB@\fP symbol. In the above example a grain is used with \fBG@\fP as well as a regular expression with \fBE@\fP\&. The \fBwebser*\fP target does not need to be prefaced with a target type specifier because it is a glob. .sp More info on using compound targeting can be found \fI\%here\fP\&. .SS Node Group Targeting .sp New in version 0.9.5. .sp For certain cases, it can be convenient to have a predefined group of minions on which to execute commands. This can be accomplished using what are called \fI\%nodegroups\fP\&. Nodegroups allow for predefined compound targets to be declared in the master configuration file, as a sort of shorthand for having to type out complicated compound expressions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nodegroups: group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com\(aq group2: \(aqG@os:Debian and foo.domain.com\(aq group3: \(aqG@os:Debian and N@group1\(aq .ft P .fi .UNINDENT .UNINDENT .SS Advanced Targeting Methods .sp There are many ways to target individual minions or groups of minions in Salt: .SS Matching the \fBminion id\fP .sp Each minion needs a unique identifier. By default when a minion starts for the first time it chooses its FQDN as that identifier. The minion id can be overridden via the minion\(aqs \fI\%id\fP configuration setting. .sp \fBTIP:\fP .INDENT 0.0 .INDENT 3.5 minion id and minion keys .sp The \fI\%minion id\fP is used to generate the minion\(aqs public/private keys and if it ever changes the master must then accept the new key as though the minion was a new host. .UNINDENT .UNINDENT .SS Globbing .sp The default matching that Salt utilizes is \fBshell\-style globbing\fP around the \fI\%minion id\fP\&. This also works for states in the \fI\%top file\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You must wrap \fBsalt\fP calls that use globbing in single\-quotes to prevent the shell from expanding the globs before Salt is invoked. .UNINDENT .UNINDENT .sp Match all minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp Match all minions in the example.net domain or any of the example domains: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*.example.net\(aq test.version salt \(aq*.example.*\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp Match all the \fBwebN\fP minions in the example.net domain (\fBweb1.example.net\fP, \fBweb2.example.net\fP … \fBwebN.example.net\fP): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqweb?.example.net\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp Match the \fBweb1\fP through \fBweb5\fP minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqweb[1\-5]\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp Match the \fBweb1\fP and \fBweb3\fP minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqweb[1,3]\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp Match the \fBweb\-x\fP, \fBweb\-y\fP, and \fBweb\-z\fP minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqweb\-[x\-z]\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For additional targeting methods please review the \fI\%compound matchers\fP documentation. .UNINDENT .UNINDENT .SS Regular Expressions .sp Minions can be matched using Perl\-compatible \fBregular expressions\fP (which is globbing on steroids and a ton of caffeine). .sp Match both \fBweb1\-prod\fP and \fBweb1\-devel\fP minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-E \(aqweb1\-(prod|devel)\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp When using regular expressions in a State\(aqs \fI\%top file\fP, you must specify the matcher as the first option. The following example executes the contents of \fBwebserver.sls\fP on the above\-mentioned minions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqweb1\-(prod|devel)\(aq: \- match: pcre \- webserver .ft P .fi .UNINDENT .UNINDENT .SS Lists .sp At the most basic level, you can specify a flat list of minion IDs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-L \(aqweb1,web2,web3\(aq test.version .ft P .fi .UNINDENT .UNINDENT .SS Targeting using Grains .sp Grain data can be used when targeting minions. .sp For example, the following matches all CentOS minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos:CentOS\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp Match all minions with 64\-bit CPUs, and return number of CPU cores for each matching minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqcpuarch:x86_64\(aq grains.item num_cpus .ft P .fi .UNINDENT .UNINDENT .sp Additionally, globs can be used in grain matches, and grains that are nested in a dictionary can be matched by adding a colon for each level that is traversed. For example, the following will match hosts that have a grain called \fBec2_tags\fP, which itself is a dictionary with a key named \fBenvironment\fP, which has a value that contains the word \fBproduction\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqec2_tags:environment:*production*\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 See \fI\%Is Targeting using Grain Data Secure?\fP for important security information. .UNINDENT .UNINDENT .SS Targeting using Pillar .sp Pillar data can be used when targeting minions. This allows for ultimate control and flexibility when targeting minions. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To start using Pillar targeting it is required to make a Pillar data cache on Salt Master for each Minion via following commands: \fBsalt \(aq*\(aq saltutil.refresh_pillar\fP or \fBsalt \(aq*\(aq saltutil.sync_all\fP\&. Also Pillar data cache will be populated during the \fI\%highstate\fP run. Once Pillar data changes, you must refresh the cache by running above commands for this targeting method to work correctly. .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-I \(aqsomekey:specialvalue\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp Like with \fI\%Grains\fP, it is possible to use globbing as well as match nested values in Pillar, by adding colons for each level that is being traversed. The below example would match minions with a pillar named \fBfoo\fP, which is a dict containing a key \fBbar\fP, with a value beginning with \fBbaz\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-I \(aqfoo:bar:baz*\(aq test.version .ft P .fi .UNINDENT .UNINDENT .SS Subnet/IP Address Matching .sp Minions can easily be matched based on IP address, or by subnet (using \fI\%CIDR\fP notation). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-S 192.168.40.20 test.version salt \-S 2001:db8::/64 test.version .ft P .fi .UNINDENT .UNINDENT .sp Ipcidr matching can also be used in compound matches .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-C \(aqS@10.0.0.0/24 and G@os:Debian\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp It is also possible to use in both pillar and state\-matching .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aq172.16.0.0/12\(aq: \- match: ipcidr \- internal .ft P .fi .UNINDENT .UNINDENT .SS Compound matchers .sp Compound matchers allow very granular minion targeting using any of Salt\(aqs matchers. The default matcher is a \fBglob\fP match, just as with CLI and \fI\%top file\fP matching. To match using anything other than a glob, prefix the match string with the appropriate letter from the table below, followed by an \fB@\fP sign. .TS center; |l|l|l|l|. _ T{ Letter T} T{ Match Type T} T{ Example T} T{ \fI\%Alt Delimiter?\fP T} _ T{ G T} T{ Grains glob T} T{ \fBG@os:Ubuntu\fP T} T{ Yes T} _ T{ E T} T{ PCRE Minion ID T} T{ \fBE@web\ed+\e.(dev|qa|prod)\e.loc\fP T} T{ No T} _ T{ P T} T{ Grains PCRE T} T{ \fBP@os:(RedHat|Fedora|CentOS)\fP T} T{ Yes T} _ T{ L T} T{ List of minions T} T{ \fBL@minion1.example.com,minion3.domain.com or bl*.domain.com\fP T} T{ No T} _ T{ I T} T{ Pillar glob T} T{ \fBI@pdata:foobar\fP T} T{ Yes T} _ T{ J T} T{ Pillar PCRE T} T{ \fBJ@pdata:^(foo|bar)$\fP T} T{ Yes T} _ T{ S T} T{ Subnet/IP address T} T{ \fBS@192.168.1.0/24\fP or \fBS@192.168.1.100\fP T} T{ No T} _ T{ R T} T{ Range cluster T} T{ \fBR@%foo.bar\fP T} T{ No T} _ T{ N T} T{ Nodegroups T} T{ \fBN@group1\fP T} T{ No T} _ .TE .sp Matchers can be joined using boolean \fBand\fP, \fBor\fP, and \fBnot\fP operators. .sp For example, the following string matches all Debian minions with a hostname that begins with \fBwebserv\fP, as well as any minions that have a hostname which matches the \fBregular expression\fP \fBweb\-dc1\-srv.*\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-C \(aqwebserv* and G@os:Debian or E@web\-dc1\-srv.*\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp That same example expressed in a \fI\%top file\fP looks like the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqwebserv* and G@os:Debian or E@web\-dc1\-srv.*\(aq: \- match: compound \- webserver .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .sp Excluding a minion based on its ID is also possible: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-C \(aqnot web\-dc1\-srv\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp Versions prior to 2015.8.0 a leading \fBnot\fP was not supported in compound matches. Instead, something like the following was required: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-C \(aq* and not G@kernel:Darwin\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp Excluding a minion based on its ID was also possible: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-C \(aq* and not web\-dc1\-srv\(aq test.version .ft P .fi .UNINDENT .UNINDENT .SS Precedence Matching .sp Matchers can be grouped together with parentheses to explicitly declare precedence amongst groups. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-C \(aq( ms\-1 or G@id:ms\-3 ) and G@id:ms\-3\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Be certain to note that spaces are required between the parentheses and targets. Failing to obey this rule may result in incorrect targeting! .UNINDENT .UNINDENT .SS Alternate Delimiters .sp New in version 2015.8.0. .sp Matchers that target based on a key value pair use a colon (\fB:\fP) as a delimiter. Matchers with a \fBYes\fP in the \fBAlt Delimiters\fP column in the previous table support specifying an alternate delimiter character. .sp This is done by specifying an alternate delimiter character between the leading matcher character and the \fB@\fP pattern separator character. This avoids incorrect interpretation of the pattern in the case that \fB:\fP is part of the grain or pillar data structure traversal. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-C \(aqJ|@foo|bar|^foo:bar$ or J!@gitrepo!https://github.com:example/project.git\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .SS Node groups .sp Nodegroups are declared using a compound target specification. The compound target documentation can be found \fI\%here\fP\&. .sp The \fI\%nodegroups\fP master config file parameter is used to define nodegroups. Here\(aqs an example nodegroup configuration within \fB/etc/salt/master\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nodegroups: group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com or bl*.domain.com\(aq group2: \(aqG@os:Debian and foo.domain.com\(aq 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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBL\fP within group1 is matching a list of minions, while the \fBG\fP in group2 is matching specific grains. See the \fI\%compound matchers\fP documentation for more details. .sp As of the 2017.7.0 release of Salt, group names can also be prepended with a dash. This brings the usage in line with many other areas of Salt. For example: .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 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp New in version 2015.8.0. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Nodegroups can reference other nodegroups as seen in \fBgroup3\fP\&. Ensure that you do not have circular references. Circular references will be detected and cause partial expansion with a logged error message. .UNINDENT .UNINDENT .sp New in version 2015.8.0. .sp Compound nodegroups can be either string values or lists of string values. When the nodegroup is A string value will be tokenized by splitting on whitespace. This may be a problem if whitespace is necessary as part of a pattern. When a nodegroup is a list of strings then tokenization will happen for each list element as a whole. .sp To match a nodegroup on the CLI, use the \fB\-N\fP command\-line option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-N group1 test.version .ft P .fi .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBN@\fP classifier historically could not be used in compound matches within the CLI or \fI\%top file\fP, it was only recognized in the \fI\%nodegroups\fP master config file parameter. As of the 2019.2.0 release, this limitation no longer exists. .UNINDENT .UNINDENT .sp To match a nodegroup in your \fI\%top file\fP, make sure to put \fB\- match: nodegroup\fP on the line directly following the nodegroup name. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: group1: \- match: nodegroup \- webserver .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When adding or modifying nodegroups to a master configuration file, the master must be restarted for those changes to be fully recognized. .sp A limited amount of functionality, such as targeting with \-N from the command\-line may be available without a restart. .UNINDENT .UNINDENT .SS Defining Nodegroups as Lists of Minion IDs .sp A simple list of minion IDs would traditionally be defined like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nodegroups: group1: L@host1,host2,host3 .ft P .fi .UNINDENT .UNINDENT .sp They can now also be defined as a YAML list, like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nodegroups: group1: \- host1 \- host2 \- host3 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .SS Batch Size .sp The \fB\-b\fP (or \fB\-\-batch\-size\fP) option allows commands to be executed on only a specified number of minions at a time. Both percentages and finite numbers are supported. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq \-b 10 test.version salt \-G \(aqos:RedHat\(aq \-\-batch\-size 25% apache.signal restart .ft P .fi .UNINDENT .UNINDENT .sp This will only run test.version on 10 of the targeted minions at a time and then restart apache on 25% of the minions matching \fBos:RedHat\fP at a time and work through them all until the task is complete. This makes jobs like rolling web server restarts behind a load balancer or doing maintenance on BSD firewalls using carp much easier with salt. .sp The batch system maintains a window of running minions, so, if there are a total of 150 minions targeted and the batch size is 10, then the command is sent to 10 minions, when one minion returns then the command is sent to one additional minion, so that the job is constantly running on 10 minions. .sp New in version 2016.3. .sp The \fB\-\-batch\-wait\fP argument can be used to specify a number of seconds to wait after a minion returns, before sending the command to a new minion. .SS SECO Range .sp SECO range is a cluster\-based metadata store developed and maintained by Yahoo! .sp The Range project is hosted here: .sp \fI\%https://github.com/ytoolshed/range\fP .sp Learn more about range here: .sp \fI\%https://github.com/ytoolshed/range/wiki/\fP .SS Prerequisites .sp To utilize range support in Salt, a range server is required. Setting up a range server is outside the scope of this document. Apache modules are included in the range distribution. .sp With a working range server, cluster files must be defined. These files are written in YAML and define hosts contained inside a cluster. Full documentation on writing YAML range files is here: .sp \fI\%https://github.com/ytoolshed/range/wiki/%22yamlfile%22\-module\-file\-spec\fP .sp Additionally, the Python seco range libraries must be installed on the salt master. One can verify that they have been installed correctly via the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-c \(aqimport seco.range\(aq .ft P .fi .UNINDENT .UNINDENT .sp If no errors are returned, range is installed successfully on the salt master. .SS Preparing Salt .sp Range support must be enabled on the salt master by setting the hostname and port of the range server inside the master configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C range_server: my.range.server.com:80 .ft P .fi .UNINDENT .UNINDENT .sp Following this, the master must be restarted for the change to have an effect. .SS Targeting with Range .sp Once a cluster has been defined, it can be targeted with a salt command by using the \fB\-R\fP or \fB\-\-range\fP flags. .sp For example, given the following range YAML file being served from a range server: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ cat /etc/range/test.yaml CLUSTER: host1..100.test.com APPS: \- frontend \- backend \- mysql .ft P .fi .UNINDENT .UNINDENT .sp One might target host1 through host100 in the test.com domain with Salt as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-\-range %test:CLUSTER test.version .ft P .fi .UNINDENT .UNINDENT .sp The following salt command would target three hosts: \fBfrontend\fP, \fBbackend\fP, and \fBmysql\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-\-range %test:APPS test.version .ft P .fi .UNINDENT .UNINDENT .SS Loadable Matchers .sp New in version 2019.2.0. .sp Internally targeting is implemented with chunks of code called Matchers. As of the 2019.2.0 release, matchers can be loaded dynamically. Currently new matchers cannot be created, but existing matchers can have their functionality altered or extended. For more information on Matchers see .SS Matchers .sp New in version 3000. .sp Matchers are modules that provide Salt\(aqs targeting abilities. As of the 3000 release, matchers can be dynamically loaded. Currently new matchers cannot be created because the required plumbing for the CLI does not exist yet. Existing matchers may have their functionality altered or extended. .sp For details of targeting methods, see the \fI\%Targeting\fP topic. .sp A matcher module must have a function called \fBmatch()\fP\&. This function ends up becoming a method on the Matcher class. All matcher functions require at least two arguments, \fBself\fP (because the function will be turned into a method), and \fBtgt\fP, which is the actual target string. The grains and pillar matchers also take a \fBdelimiter\fP argument and should default to \fBDEFAULT_TARGET_DELIM\fP\&. .sp Like other Salt loadable modules, modules that override built\-in functionality can be placed in \fBfile_roots\fP in a special directory and then copied to the minion through the normal sync process. \fI\%saltutil.sync_all\fP will transfer all loadable modules, and the 3000 release introduces \fI\%saltutil.sync_matchers\fP\&. For matchers, the directory is \fB/srv/salt/_matchers\fP (assuming your \fBfile_roots\fP is set to the default \fB/srv/salt\fP). .sp As an example, let\(aqs modify the \fBlist\fP matcher to have the separator be a \(aq\fB/\fP\(aq instead of the default \(aq\fB,\fP\(aq. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from __future__ import absolute_import, print_function, unicode_literals from salt.ext import six # pylint: disable=3rd\-party\-module\-not\-gated def match(self, tgt): \(dq\(dq\(dq Determines if this host is on the list \(dq\(dq\(dq if isinstance(tgt, six.string_types): # The stock matcher splits on \(ga,\(ga. Change to \(ga/\(ga below. tgt = tgt.split(\(dq/\(dq) return bool(self.opts[\(dqid\(dq] in tgt) .ft P .fi .UNINDENT .UNINDENT .sp Place this code in a file called \fBlist_match.py\fP in a \fB_matchers\fP directory in your \fBfile_roots\fP\&. Sync this down to your minions with \fI\%saltutil.sync_matchers\fP\&. Then attempt to match with the following, replacing \fBminionX\fP with three of your minions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-L \(aqminion1/minion2/minion3\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Three of your minions should respond. .sp The current supported matchers and associated filenames are .TS center; |l|l|l|. _ T{ Salt CLI Switch T} T{ Match Type T} T{ Filename T} _ T{ <none> 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 \fI\%salt.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 \fI\%salt.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 \fI\%Targeting Minions\fP 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 \(dqhello!\(dq\(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 \fI\%Minions targeting\fP to fetch Mine data from particular hosts, such as glob or regular expression matching on Minion id (name), grains, pillars and \fI\%compound matches\fP\&. See the \fI\%salt.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 \fI\%relevant section\fP\&. .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 \(dqweb\(dq 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 \fI\%salt.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 \fI\%The full list of runners\fP .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(\(dqHello world\(dq) ... .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({\(dqmessage\(dq: \(dqA progress message\(dq}, \(dqprogress\(dq) .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: \(dqA progress message\(dq} .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 \fI\%runner_dirs\fP in the master configuration file. .SS Examples .sp Examples of runners can be found in the Salt distribution: .sp \fI\%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(): \(dq\(dq\(dq Print a list of all of the minions that are up \(dq\(dq\(dq client = salt.client.LocalClient(__opts__[\(dqconf_file\(dq]) minions = client.cmd(\(dq*\(dq, \(dqtest.version\(dq, 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 \fI\%external processes\fP 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\%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 {\(dqmy_key\(dq: \(dqmy_value\(dq} .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 {\(dqmy_key\(dq: \(dqmy_value\(dq} .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 {\(dqfirst_level_dict_key\(dq: {\(dqsecond_level_dict_key\(dq: \(dqvalue_in_second_level_dict\(dq}} .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 {\(dqmy_dictionary\(dq: [\(dqlist_value_one\(dq, \(dqlist_value_two\(dq, \(dqlist_value_three\(dq]} .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 \fI\%Understanding Jinja\fP\&. .SS Understanding Jinja .sp \fI\%Jinja\fP is the default templating language in SLS files. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Jinja\fP supports a \fI\%secure, sandboxed template execution environment\fP that Salt takes advantage of. Other text \fI\%Renderers\fP do not support this functionality, so Salt highly recommends usage of \fBjinja\fP / \fBjinja|yaml\fP\&. .UNINDENT .UNINDENT .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 \fI\%pillars\fP, 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 {{ \(dq2002/12/25\(dq|strftime(\(dq%y\(dq) }} {{ \(dq1040814000\(dq|strftime(\(dq%Y\-%m\-%d\(dq) }} {{ datetime|strftime(\(dq%u\(dq) }} {{ \(dqtomorrow\(dq|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 \(dqsalty\(dq\(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\(dqThe quick brown fox . . .\(dq\(aq %} {%\- set baz = \(aqThe word of the day is \(dqsalty\(dq.\(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 \fBdict_to_sls_yaml_params\fP .sp New in version 3005. .sp Renders a formatted multi\-line YAML string from a Python dictionary. Each key/value pair in the dictionary will be added as a single\-key dictionary to a list that will then be sent to the YAML formatter. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set thing_params = { \(dqname\(dq: \(dqthing\(dq, \(dqchanges\(dq: True, \(dqwarnings\(dq: \(dqOMG! Stuff is happening!\(dq } %} thing: test.configurable_test_state: {{ thing_params | dict_to_sls_yaml_params | indent }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C thing: test.configurable_test_state: \- name: thing \- changes: true \- warnings: OMG! Stuff is happening! .ft P .fi .UNINDENT .UNINDENT .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 \(dqtruthy\(dq (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 \(dqtruthy\(dq (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 (\(dqdefabcdef\(dq,) .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 \fBflatten\fP .sp New in version 3005. .sp Flatten a list. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [3, [4, 2] ] | flatten }} # => [3, 4, 2] .ft P .fi .UNINDENT .UNINDENT .sp Flatten only the first level of a list: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [3, [4, [2]] ] | flatten(levels=1) }} # => [3, 4, [2]] .ft P .fi .UNINDENT .UNINDENT .sp Preserve nulls in a list, by default \fBflatten\fP removes them. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [3, None, [4, [2]] ] | flatten(levels=1, preserve_nulls=True) }} # => [3, None, 4, [2]] .ft P .fi .UNINDENT .UNINDENT .SS \fBcombinations\fP .sp New in version 3005. .sp Invokes the \fBcombinations\fP function from the \fBitertools\fP library. .sp See the \fI\%itertools documentation\fP for more information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for one, two in \(dqABCD\(dq | combinations(2) %}{{ one~two }} {% endfor %} # => AB AC AD BC BD CD .ft P .fi .UNINDENT .UNINDENT .SS \fBcombinations_with_replacement\fP .sp New in version 3005. .sp Invokes the \fBcombinations_with_replacement\fP function from the \fBitertools\fP library. .sp See the \fI\%itertools documentation\fP for more information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for one, two in \(dqABC\(dq | combinations_with_replacement(2) %}{{ one~two }} {% endfor %} # => AA AB AC BB BC CC .ft P .fi .UNINDENT .UNINDENT .SS \fBcompress\fP .sp New in version 3005. .sp Invokes the \fBcompress\fP function from the \fBitertools\fP library. .sp See the \fI\%itertools documentation\fP for more information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for val in \(dqABCDEF\(dq | compress([1,0,1,0,1,1]) %}{{ val }} {% endfor %} # => A C E F .ft P .fi .UNINDENT .UNINDENT .SS \fBpermutations\fP .sp New in version 3005. .sp Invokes the \fBpermutations\fP function from the \fBitertools\fP library. .sp See the \fI\%itertools documentation\fP for more information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for one, two in \(dqABCD\(dq | permutations(2) %}{{ one~two }} {% endfor %} # => AB AC AD BA BC BD CA CB CD DA DB DC .ft P .fi .UNINDENT .UNINDENT .SS \fBproduct\fP .sp New in version 3005. .sp Invokes the \fBproduct\fP function from the \fBitertools\fP library. .sp See the \fI\%itertools documentation\fP for more information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for one, two in \(dqABCD\(dq | product(\(dqxy\(dq) %}{{ one~two }} {% endfor %} # => Ax Ay Bx By Cx Cy Dx Dy .ft P .fi .UNINDENT .UNINDENT .SS \fBzip\fP .sp New in version 3005. .sp Invokes the native Python \fBzip\fP function. .sp The \fBzip\fP function returns a zip object, which is an iterator of tuples where the first item in each passed iterator is paired together, and then the second item in each passed iterator are paired together etc. .sp If the passed iterators have different lengths, the iterator with the least items decides the length of the new iterator. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for one, two in \(dqABCD\(dq | zip(\(dqxy\(dq) %}{{ one~two }} {% endfor %} # => Ax By .ft P .fi .UNINDENT .UNINDENT .SS \fBzip_longest\fP .sp New in version 3005. .sp Invokes the \fBzip_longest\fP function from the \fBitertools\fP library. .sp See the \fI\%itertools documentation\fP for more information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for one, two in \(dqABCD\(dq | zip_longest(\(dqxy\(dq, fillvalue=\(dq\-\(dq) %}{{ one~two }} {% endfor %} # => Ax By C\- D\- .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 {\(dqnew\(dq: [4], \(dqold\(dq: [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 {\(dqa\(dq: {\(dqnew\(dq: \(dqc\(dq, \(dqold\(dq: \(dqb\(dq}} .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 \fI\%YAML ASCII support\fP in the \fI\%YAML Idiosyncrasies\fP 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 3003 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 3003 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 {\(dqa\(dq: \(dq\exd0\ex94\(dq} .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 \fI\%hash_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 \fBrandom_sample\fP .sp New in version 3005. .sp Returns a given sample size from a list. The \fBseed\fP parameter can be used to return a predictable outcome. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set my_list = [\(dqone\(dq, \(dqtwo\(dq, \(dqthree\(dq, \(dqfour\(dq] %} {{ my_list | random_sample(2) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [\(dqfour\(dq, \(dqone\(dq] .ft P .fi .UNINDENT .UNINDENT .SS \fBrandom_shuffle\fP .sp New in version 3005. .sp Returns a shuffled copy of an input list. The \fBseed\fP parameter can be used to return a predictable outcome. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set my_list = [\(dqone\(dq, \(dqtwo\(dq, \(dqthree\(dq, \(dqfour\(dq] %} {{ my_list | random_shuffle }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [\(dqfour\(dq, \(dqthree\(dq, \(dqone\(dq, \(dqtwo\(dq] .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{ \(dquserId\(dq: 1, \(dqid\(dq: 1, \(dqtitle\(dq: \(dqsunt aut facere repellat provident occaecati excepturi option reprehenderit\(dq, \(dqbody\(dq: \(dqquia 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\(dq }\(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 {\(dqc1\(dq: \(dqfoo\(dq} .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 \(dqdefault\(dq .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: {{ {\(dqmachines\(dq: [ {\(dqname\(dq: \(dqa\(dq, \(dqstate\(dq: \(dqrunning\(dq}, {\(dqname\(dq: \(dqb\(dq, \(dqstate\(dq: \(dqstopped\(dq}, {\(dqname\(dq: \(dqc\(dq, \(dqstate\(dq: \(dqrunning\(dq} ]} | json_query(\(dqmachines[?state==\(aqrunning\(aq].name\(dq) }} Example 3: {{ {\(dqservices\(dq: [ {\(dqname\(dq: \(dqhttp\(dq, \(dqhost\(dq: \(dq1.2.3.4\(dq, \(dqport\(dq: 80}, {\(dqname\(dq: \(dqsmtp\(dq, \(dqhost\(dq: \(dq1.2.3.5\(dq, \(dqport\(dq: 25}, {\(dqname\(dq: \(dqssh\(dq, \(dqhost\(dq: \(dq1.2.3.6\(dq, \(dqport\(dq: 22}, ]} | json_query(\(dqservices[].port\(dq) }} .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_entries\fP .sp New in version 3007.0. .sp A port of the \fBto_entries\fP function from \fBjq\fP\&. This function converts between an object and an array of key\-value pairs. If \fBto_entries\fP is passed an object, then for each \fBk: v\fP entry in the input, the output array includes \fB{\(dqkey\(dq: k, \(dqvalue\(dq: v}\fP\&. The \fBfrom_entries\fP function performs the opposite conversion. \fBfrom_entries\fP accepts \(dqkey\(dq, \(dqKey\(dq, \(dqname\(dq, \(dqName\(dq, \(dqvalue\(dq, and \(dqValue\(dq as keys. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ {\(dqa\(dq: 1, \(dqb\(dq: 2} | to_entries }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [{\(dqkey\(dq:\(dqa\(dq, \(dqvalue\(dq:1}, {\(dqkey\(dq:\(dqb\(dq, \(dqvalue\(dq:2}] .ft P .fi .UNINDENT .UNINDENT .SS \fBfrom_entries\fP .sp New in version 3007.0. .sp A port of the \fBfrom_entries\fP function from \fBjq\fP\&. This function converts between an array of key\-value pairs and an object. If \fBfrom_entries\fP is passed an object, then the input is expected to be an array of dictionaries in the format of \fB{\(dqkey\(dq: k, \(dqvalue\(dq: v}\fP\&. The output will be be key\-value pairs \fBk: v\fP\&. \fBfrom_entries\fP accepts \(dqkey\(dq, \(dqKey\(dq, \(dqname\(dq, \(dqName\(dq, \(dqvalue\(dq, and \(dqValue\(dq as keys. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [{\(dqkey\(dq:\(dqa\(dq, \(dqvalue\(dq:1}, {\(dqkey\(dq:\(dqb\(dq, \(dqvalue\(dq:2}] | from_entries }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {\(dqa\(dq: 1, \(dqb\(dq: 2} .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 \fBhuman_to_bytes\fP .sp New in version 3005. .sp Given a human\-readable byte string (e.g. 2G, 30MB, 64KiB), return the number of bytes. Will return 0 if the argument has unexpected form. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Example 1: {{ \(dq32GB\(dq | human_to_bytes }} Example 2: {{ \(dq32GB\(dq | human_to_bytes(handle_metric=True) }} Example 3: {{ \(dq32\(dq | human_to_bytes(default_unit=\(dqGiB\(dq) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Example 1: 34359738368 Example 2: 32000000000 Example 3: 34359738368 .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 [\(dq192.168.0.1\(dq, \(dqfe80::\(dq] .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 [\(dq192.168.0.1\(dq] .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 [\(dqfe80::\(dq] .ft P .fi .UNINDENT .UNINDENT .SS \fBipwrap\fP .sp New in version 3006.0. .sp From a string, list, or tuple, returns any IPv6 addresses wrapped in square brackets([]) .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [\(aq192.0.2.1\(aq, \(aqfoo\(aq, \(aqbar\(aq, \(aqfe80::\(aq, \(aq2001:db8::1/64\(aq] | ipwrap }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [\(dq192.0.2.1\(dq, \(dqfoo\(dq, \(dqbar\(dq, \(dq[fe80::]\(dq, \(dq[2001:db8::1]/64\(dq] .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 [\(dq192.168.0.1\(dq, \(dq192.168.0.2\(dq] .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 \fI\%YAML ASCII support\fP in the \fI\%YAML Idiosyncrasies\fP 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 [{\(dqvalue\(dq: 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 [{\(dqvalue\(dq: \(dqb\(dq}, {\(dqvalue\(dq: \(dqc\(dq}] .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 Global Functions .sp Salt Project extends \fI\%builtin global functions\fP with these custom global functions: .SS \fBifelse\fP .sp Evaluate each pair of arguments up to the last one as a (matcher, value) tuple, returning \fBvalue\fP if matched. If none match, returns the last argument. .sp The \fBifelse\fP function is like a multi\-level if\-else statement. It was inspired by CFEngine\(aqs \fBifelse\fP function which in turn was inspired by Oracle\(aqs \fBDECODE\fP function. It must have an odd number of arguments (from 1 to N). The last argument is the default value, like the \fBelse\fP clause in standard programming languages. Every pair of arguments before the last one are evaluated as a pair. If the first one evaluates true then the second one is returned, as if you had used the first one in a compound match expression. Boolean values can also be used as the first item in a pair, as it will be translated to a match that will always match (\(dq*\(dq) or never match (\(dqSALT_IFELSE_MATCH_NOTHING\(dq) a target system. .sp This is essentially another way to express the \fBmatch.filter_by\fP functionality in way that\(aqs familiar to CFEngine or Oracle users. Consider using \fBmatch.filter_by\fP unless this function fits your workflow. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ ifelse(\(aqfoo*\(aq, \(aqfooval\(aq, \(aqbar*\(aq, \(aqbarval\(aq, \(aqdefaultval\(aq, minion_id=\(aqbar03\(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 start 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 \(dqexample\-job\(dq { <snipped> task \(dqexample\(dq { driver = \(dqdocker\(dq config { image = \(dqdocker\-registry.service.consul:5000/example\-job:{{key \(dqnomad/jobs/example\-job/version\(dq}}\(dq <snipped> {% 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 \fI\%execution function\fP\&. .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<name>\(aq %}<jinja code>{% endprofile %}\fP, where \fB<name>\fP can be any string. The \fB<name>\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 \fI\%How to Convert Jinja Logic to an Execution Module\fP .IP \(bu 2 \fI\%Writing Execution Modules\fP .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 \fI\%dnsutil\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 \fI\%NAPALM 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 If already running, the master must be restarted for these config changes to take effect. .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=\(dq\-\-listen\(dq\(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 \fI\%Salt Virt Networking\fP .UNINDENT .UNINDENT .SS Libvirt State .sp One of the challenges of deploying a libvirt based cloud is the distribution of libvirt certificates. These certificates allow for virtual machine migration. Salt comes with a system used to auto deploy these certificates. Salt manages the signing authority key and generates keys for libvirt clients on the master, signs them with the certificate authority, and uses pillar to distribute them. This is managed via the \fBlibvirt\fP state. Simply execute this formula on the minion to ensure that the certificate is in place and up to date: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The above formula includes the calls needed to set up libvirt keys. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C libvirt_keys: 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\%url 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 \fI\%Salt File Server\fP 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 \fI\%Opening the Firewall up for Salt\fP .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 <new hypervisor> .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 \fI\%Salt install guide\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.saltproject.io/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. \fI\%salt.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 \fI\%Salt Walkthrough\fP\&. .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 \fI\%Salt Proxy Minion\fP documentation and the \fI\%Salt Proxy Minion End\-to\-End Example\fP 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 \(dqproxies\(dq communication from the Salt Master to the ESXi host. The master does not know or care that the ESXi target is not a \(dqreal\(dq Salt Minion. .sp More in\-depth conceptual reading on Proxy Minions can be found in the \fI\%Proxy Minion\fP 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 <host\-location> \-u <username> \-p <password> 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: <salt\-master\-location> .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: <ip or dns name of esxi host> username: <ESXi 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 \fI\%vsphere.update_host_password\fP execution module function or via the \fI\%esxi.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: <salt\-master\-location> .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 \fI\%Salt.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 \fI\%salt.modules.esxi\fP execution module acts as a \(dqshim\(dq between the vSphere execution module functions and the proxy process. .sp The \(dqshim\(dq 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 \fI\%salt.modules.vsphere\fP instead of \fI\%salt.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 <vsphere\-function\-name>\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 \(dqshim\(dq 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 \fI\%salt.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 \fI\%ESXi Proxy Minion\fP .IP \(bu 2 \fI\%ESXi Execution Module\fP .IP \(bu 2 \fI\%ESXi State Module\fP .IP \(bu 2 \fI\%Salt Proxy Minion Docs\fP .IP \(bu 2 \fI\%Salt Proxy Minion End\-to\-End Example\fP .IP \(bu 2 \fI\%vSphere Execution Module\fP .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=<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=\(dqSalt\(dq 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 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(\(dqhttp://example.com\(dq) .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(\(dqhttp://example.com/delete/url\(dq, \(dqDELETE\(dq) .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( \(dqhttp://example.com/post/url\(dq, method=\(dqPOST\(dq, 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( \(dqhttp://example.com/post/url\(dq, method=\(dqPOST\(dq, data_file=\(dq/srv/salt/somefile.xml\(dq ) .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( \(dqhttp://example.com/post/url\(dq, method=\(dqPOST\(dq, data_file=\(dq/srv/salt/somefile.jinja\(dq, data_render=True, template_dict={\(dqkey1\(dq: \(dqvalue1\(dq, \(dqkey2\(dq: \(dqvalue2\(dq}, ) .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( \(dqhttp://example.com/post/url\(dq, method=\(dqPOST\(dq, data_file=\(dq/srv/salt/somefile.mako\(dq, data_render=True, data_renderer=\(dqmako\(dq, template_dict={\(dqkey1\(dq: \(dqvalue1\(dq, \(dqkey2\(dq: \(dqvalue2\(dq}, ) .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( \(dqhttp://example.com/post/url\(dq, method=\(dqPOST\(dq, data_file=\(dq/srv/salt/somefile.jinja\(dq, data_render=True, template_dict={\(dqkey1\(dq: \(dqvalue1\(dq, \(dqkey2\(dq: \(dqvalue2\(dq}, opts=__opts__, ) salt.utils.http.query( \(dqhttp://example.com/post/url\(dq, method=\(dqPOST\(dq, data_file=\(dq/srv/salt/somefile.jinja\(dq, data_render=True, template_dict={\(dqkey1\(dq: \(dqvalue1\(dq, \(dqkey2\(dq: \(dqvalue2\(dq}, node=\(dqmaster\(dq, ) .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( \(dqhttp://example.com/delete/url\(dq, method=\(dqPOST\(dq, header_file=\(dq/srv/salt/headers.jinja\(dq, header_render=True, header_renderer=\(dqjinja\(dq, template_dict={\(dqkey1\(dq: \(dqvalue1\(dq, \(dqkey2\(dq: \(dqvalue2\(dq}, ) .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(\(dqhttp://example.com\(dq, username=\(dqlarry\(dq, password=\(dq5700g3543v4r\(dq) .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(\(dqhttp://example.com\(dq, 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( \(dqhttp://example.com\(dq, cookies=True, cookie_jar=\(dq/path/to/cookie_jar.txt\(dq ) .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( \(dqhttp://example.com\(dq, cookies=True, cookie_jar=\(dq/path/to/cookie_jar.txt\(dq, cookie_format=\(dqmozilla\(dq, ) .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( \(dqhttp://example.com\(dq, persist_session=True, session_cookie_jar=\(dq/path/to/jar.p\(dq ) .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(\(dqhttp://example.com\(dq, opts=__opts__, backend=\(dqtornado\(dq) .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(\(dqhttp://example.com\(dq, decode_type=\(dqxml\(dq) .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(\(dqhttp://example.com\(dq, 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(\(dqhttp://example.com\(dq, 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( \(dqhttp://example.com\(dq, text=False, headers=False, text_out=\(dq/path/to/url_download.txt\(dq, headers_out=\(dq/path/to/headers_download.txt\(dq, ) .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(\(dqhttps://example.com\(dq, 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(\(dqhttps://example.com\(dq, ca_bundle=\(dq/path/to/ca_bundle.pem\(dq) .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=\(dq/path/to/ca\-bundle.crt\(dq, source=\(dqhttps://example.com/path/to/ca\-bundle.crt\(dq, 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=[ \(dq/etc/ssl/private_cert_1.pem\(dq, \(dq/etc/ssl/private_cert_2.pem\(dq, \(dq/etc/ssl/private_cert_3.pem\(dq, ], ) .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, see the \fI\%Salt install guide\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 \(dqthundering herd\(dq 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 \(dqthundering herd\(dq. 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 \(dqthundering herd\(dq. 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 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 \fI\%gpg\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_seconds: 86400 .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 maintenance 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 \(dqif your maps.jinja is too complicated, write an execution module!\(dq. 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 \(dqJinja is not a Programming Language\(dq. There\(aqs an even older saying known as Maslow\(aqs hammer. It goes something like \(dqif all you have is a hammer, everything looks like a nail\(dq. 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 \(dq\(dq\(dq Functions related to storage servers. \(dq\(dq\(dq import re def ips(): \(dq\(dq\(dq Provide a list of all local storage server IPs. CLI Example:: salt \e* storage.ips \(dq\(dq\(dq if __grains__.get(\(dqvirtual\(dq, None) in [\(dqVirtualBox\(dq, \(dqoracle\(dq]: return [ \(dq192.168.33.51\(dq, ] colo = __pillar__.get(\(dqinventory\(dq, {}).get(\(dqcolo\(dq, \(dqUnknown\(dq) return __pillar__.get(\(dqstorage_servers\(dq, {}).get(colo, [\(dqunknown\(dq]) def ip(): \(dq\(dq\(dq 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 <ahammond@anchorfree.com> :maturity: new :depends: None :platform: all CLI Example:: salt \e* storage.ip \(dq\(dq\(dq numerical_suffix = re.compile(r\(dq^.*(\ed+)$\(dq) servers_list = ips() m = numerical_suffix.match(__grains__[\(dqid\(dq]) 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 \fI\%Salt Walkthrough\fP\&. .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 \fI\%libcloud_compute\fP \- Compute \- services such as OpenStack Nova, Amazon EC2, Microsoft Azure VMs .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fI\%libcloud_dns\fP \- DNS as a Service \- services such as Amazon Route 53 and Zerigo .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fI\%libcloud_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 \fI\%libcloud_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 \(dqprofiles\(dq to be configured with authentication details for each driver. .sp Each driver will have a string identifier, these can be found in the libcloud.<api>.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 \(dq\fIshopper_id\fP\(dq, 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 \(dqroute53_prod\(dq and \(dqroute54_test\(dq 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 \fI\%libcloud_compute\fP \- Compute \- services such as OpenStack Nova, Amazon EC2, Microsoft Azure VMs .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fI\%libcloud_dns\fP \- DNS as a Service \- services such as Amazon Route 53 and Zerigo .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fI\%libcloud_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 \fI\%libcloud_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 \fI\%libcloud_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 \fI\%libcloud_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 \fI\%libcloud_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 \fI\%Salt Walkthrough\fP\&. .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, \fI\%grains\fP, \fI\%pillar\fP, or the master config file. The profile is retrieved by Salt using the \fI\%config.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 \fI\%config.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 \fI\%lxc.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 \fI\%config.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 \fI\%lxc.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\-<interface_name>\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 \fI\%lxc.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 \fI\%lxc.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 \fI\%lxc.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 \fI\%lxc.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 \fI\%lxc.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 \fI\%lxc.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 \fI\%LXC runner\fP contains a runner function of the same name (\fI\%lxc.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 <salt.modules.cmdmod.run\fP). The means of doing this have been changed significantly in version 2015.5.0 (though the deprecated behavior will still be supported for a few releases). Both the old and new usage are documented below. .SS 2015.5.0 and Newer .sp New functions have been added to mimic the behavior of the functions in the \fI\%cmd\fP module. Below is a table with the \fI\%cmd\fP functions and their \fI\%lxc\fP module equivalents: .TS center; |l|l|l|. _ T{ Description T} T{ \fI\%cmd\fP module T} T{ \fI\%lxc\fP module T} _ T{ Run a command and get all output T} T{ \fI\%cmd.run\fP T} T{ \fI\%lxc.run\fP T} _ T{ Run a command and get just stdout T} T{ \fI\%cmd.run_stdout\fP T} T{ \fI\%lxc.run_stdout\fP T} _ T{ Run a command and get just stderr T} T{ \fI\%cmd.run_stderr\fP T} T{ \fI\%lxc.run_stderr\fP T} _ T{ Run a command and get just the retcode T} T{ \fI\%cmd.retcode\fP T} T{ \fI\%lxc.retcode\fP T} _ T{ Run a command and get all information T} T{ \fI\%cmd.run_all\fP T} T{ \fI\%lxc.run_all\fP T} _ .TE .SS 2014.7.x and Earlier .sp Earlier Salt releases use a single function (\fBlxc.run_cmd\fP) to run commands within containers. Whether stdout, stderr, etc. are returned depends on how the function is invoked. .sp To run a command and return the stdout: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.run_cmd web1 \(aqtail /var/log/messages\(aq .ft P .fi .UNINDENT .UNINDENT .sp To run a command and return the stderr: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.run_cmd web1 \(aqtail /var/log/messages\(aq stdout=False stderr=True .ft P .fi .UNINDENT .UNINDENT .sp To run a command and return the retcode: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.run_cmd web1 \(aqtail /var/log/messages\(aq stdout=False stderr=False .ft P .fi .UNINDENT .UNINDENT .sp To run a command and return all information: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.run_cmd web1 \(aqtail /var/log/messages\(aq stdout=True stderr=True .ft P .fi .UNINDENT .UNINDENT .SS Container Management Using salt\-cloud .sp Salt cloud uses under the hood the salt runner and module to manage containers, Please look at \fI\%this chapter\fP .SS Container Management Using States .sp Several states are being renamed or otherwise modified in version 2015.5.0. The information in this tutorial refers to the new states. For 2014.7.x and earlier, please refer to the \fI\%documentation for the LXC states\fP\&. .SS Ensuring a Container Is Present .sp To ensure the existence of a named container, use the \fI\%lxc.present\fP state. Here are some examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Using a template web1: lxc.present: \- template: download \- options: dist: centos release: 6 arch: amd64 # Cloning web2: lxc.present: \- clone_from: web\-base # Using a rootfs image web3: lxc.present: \- image: salt://path/to/cent6.tar.gz # Using profiles web4: lxc.present: \- profile: centos_web \- network_profile: centos .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The \fI\%lxc.present\fP state will not modify an existing container (in other words, it will not re\-create the container). If an \fI\%lxc.present\fP state is run on an existing container, there will be no change and the state will return a \fBTrue\fP result. .UNINDENT .UNINDENT .sp The \fI\%lxc.present\fP state also includes an optional \fBrunning\fP parameter which can be used to ensure that a container is running/stopped. Note that there are standalone \fI\%lxc.running\fP and \fI\%lxc.stopped\fP states which can be used for this purpose. .SS Ensuring a Container Does Not Exist .sp To ensure that a named container is not present, use the \fI\%lxc.absent\fP state. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C web1: lxc.absent .ft P .fi .UNINDENT .UNINDENT .SS Ensuring a Container is Running/Stopped/Frozen .sp Containers can be in one of three states: .INDENT 0.0 .IP \(bu 2 \fBrunning\fP \- Container is running and active .IP \(bu 2 \fBfrozen\fP \- Container is running, but all process are blocked and the container is essentially non\-active until the container is \(dqunfrozen\(dq .IP \(bu 2 \fBstopped\fP \- Container is not running .UNINDENT .sp Salt has three states (\fI\%lxc.running\fP, \fI\%lxc.frozen\fP, and \fI\%lxc.stopped\fP) which can be used to ensure a container is in one of these states: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C web1: lxc.running # Restart the container if it was already running web2: lxc.running: \- restart: True web3: lxc.stopped # Explicitly kill all tasks in container instead of gracefully stopping web4: lxc.stopped: \- kill: True web5: lxc.frozen # If container is stopped, do not start it (in which case the state will fail) web6: lxc.frozen: \- start: False .ft P .fi .UNINDENT .UNINDENT .SS Master Cluster .sp A clustered Salt Master has several advantages over Salt\(aqs traditional High Availability options. First, a master cluster is meant to be served behind a load balancer. Minions only need to know about the load balancer\(aqs IP address. Therefore, masters can be added and removed from a cluster without the need to re\-configure minions. Another major benefit of master clusters over Salt\(aqs older HA implimentations is that Masters in a cluster share the load of all jobs. This allows Salt administrators to more easily scale their environments to handle larger numbers of minions and larger jobs. .SS Minimum Requirements .sp Running a cluster master requires all nodes in the cluster to have a shared filesystem. The \fIcluster_pki_dir\fP, \fIcache_dir\fP, \fIfile_roots\fP and \fIpillar_roots\fP must all be on a shared filesystem. Most implementations will also serve the masters publish and request server ports via a tcp load balancer. All of the masters in a cluster are assumed to be running on a reliable local area network. .sp Each master in a cluster maintains its own public and private key, and an in memory aes key. Each cluster peer also has access to the \fIcluster_pki_dir\fP where a cluster wide public and private key are stored. In addition, the cluster wide aes key is generated and stored in the \fIcluster_pki_dir\fP\&. Further, when operating as a cluster, minion keys are stored in the \fIcluster_pki_dir\fP instead of the master\(aqs \fIpki_dir\fP\&. .SS Reference Implimentation .sp Gluster: \fI\%https://docs.gluster.org/en/main/Quick\-Start\-Guide/Quickstart/\fP .sp HAProxy: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C frontend salt\-master\-pub mode tcp bind 10.27.5.116:4505 option tcplog timeout client 1m default_backend salt\-master\-pub\-backend backend salt\-master\-pub\-backend mode tcp option tcplog #option log\-health\-checks log global #balance source balance roundrobin timeout connect 10s timeout server 1m server rserve1 10.27.12.13:4505 check server rserve2 10.27.7.126:4505 check server rserve3 10.27.3.73:4505 check frontend salt\-master\-req mode tcp bind 10.27.5.116:4506 option tcplog timeout client 1m default_backend salt\-master\-req\-backend backend salt\-master\-req\-backend mode tcp option tcplog #option log\-health\-checks log global balance roundrobin #balance source timeout connect 10s timeout server 1m server rserve1 10.27.12.13:4506 check server rserve2 10.27.7.126:4506 check server rserve3 10.27.3.73:4506 check .ft P .fi .UNINDENT .UNINDENT .sp Master Config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C id: 10.27.12.13 cluster_id: master_cluster cluster_peers: \- 10.27.7.126 \- 10.27.3.73 cluster_pki_dir: /my/gluster/share/pki cachedir: /my/gluster/share/cache file_roots: \- /my/gluster/share/srv/salt pillar_roots: \- /my/gluster/share/srv/pillar .ft P .fi .UNINDENT .UNINDENT .SS Remote execution tutorial .sp \fBBefore continuing\fP make sure you have a working Salt installation by following the instructions in the \fI\%Salt install guide\fP\&. .INDENT 0.0 .INDENT 3.5 .IP "Stuck?" .sp The Salt Project community can help offer advice and help troubleshoot technical issues as you\(aqre learning about Salt. One of the best places to talk to the community is on the \fI\%Salt Project Slack workspace\fP\&. .UNINDENT .UNINDENT .SS Order your minions around .sp Now that you have a \fI\%master\fP and at least one \fI\%minion\fP communicating with each other you can perform commands on the minion via the \fBsalt\fP command. Salt calls are comprised of three main components: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq<target>\(aq <function> [arguments] .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%salt manpage\fP .UNINDENT .UNINDENT .SS target .sp The target component allows you to filter which minions should run the following function. The default filter is a glob on the minion id. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.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 \fI\%Grains system\fP .UNINDENT .UNINDENT .sp Targets can be filtered by regular expression: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-E \(aqvirtmach[0\-9]\(aq test.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 \fI\%the full list of modules\fP .UNINDENT .UNINDENT .SS arguments .sp Space\-delimited arguments to the function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.exec_code python \(aqimport sys; print sys.version\(aq .ft P .fi .UNINDENT .UNINDENT .sp Optional, keyword arguments are also supported: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.install salt timeout=5 upgrade=True .ft P .fi .UNINDENT .UNINDENT .sp They are always in the form of \fBkwarg=argument\fP\&. .SS 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 \fI\%file_roots\fP are kept consistent. .sp Beginning with Salt 2016.11.0, the \fI\%Pluggable Minion Data Cache\fP 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 \fI\%Minion Data Cache\fP 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 \fI\%file_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 \fI\%gitfs_global_lock\fP/\fI\%git_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 \fI\%file_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: <name_without_suffix> .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, \fI\%highstate\fP, 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 random_master: 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: <seconds> .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: <filename> .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=\(dq ... \(dq, packages=find_packages(), entry_points=\(dq\(dq\(dq [salt.loader] engines_dirs = <package>.<loader\-module>:engines_dirs fileserver_dirs = <package>.<loader\-module>:fileserver_dirs pillar_dirs = <package>.<loader\-module>:pillar_dirs returner_dirs = <package>.<loader\-module>:returner_dirs roster_dirs = <package>.<loader\-module>:roster_dirs \(dq\(dq\(dq, ) .ft P .fi .UNINDENT .UNINDENT .sp The above setup script example mentions a loader module. here\(aqs an example of how \fI<package>/<loader\-module>.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(): \(dq\(dq\(dq yield one path per parent directory of where engines can be found \(dq\(dq\(dq yield os.path.join(PKG_DIR, \(dqengines_1\(dq) yield os.path.join(PKG_DIR, \(dqengines_2\(dq) def fileserver_dirs(): \(dq\(dq\(dq yield one path per parent directory of where fileserver modules can be found \(dq\(dq\(dq yield os.path.join(PKG_DIR, \(dqfileserver\(dq) def pillar_dirs(): \(dq\(dq\(dq yield one path per parent directory of where external pillar modules can be found \(dq\(dq\(dq yield os.path.join(PKG_DIR, \(dqpillar\(dq) def returner_dirs(): \(dq\(dq\(dq yield one path per parent directory of where returner modules can be found \(dq\(dq\(dq yield os.path.join(PKG_DIR, \(dqreturners\(dq) def roster_dirs(): \(dq\(dq\(dq yield one path per parent directory of where roster modules can be found \(dq\(dq\(dq yield os.path.join(PKG_DIR, \(dqroster\(dq) .ft P .fi .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 \fI\%generate 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 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 Before run the script, it is a good practice to verify the checksum of the downloaded file. You can verify the checksum with SHA256 by running this command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C test $(sha256sum bootstrap_salt.sh | awk \(aq{print $1}\(aq) \e = $(curl \-sL https://bootstrap.saltproject.io/sha256 | cat \-) \e && echo \(dqOK\(dq \e || echo \(dqFile does not match checksum\(dq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The previous example is the preferred method because by downloading the script you can investigate the contents of the bootstrap script or using it again later. Alternatively, if you want to download the bash script and run it immediately, use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-L https://bootstrap.saltproject.io | sudo sh \-s \-\- .ft P .fi .UNINDENT .UNINDENT .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 \fI\%file_client\fP configuration option needs to be set in the minion configuration file. By default the \fI\%file_client\fP is set to \fBremote\fP so that the minion gathers file server and pillar data from the salt master. When setting the \fI\%file_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 \fI\%master configuration\fP (e.g. \fB/etc/salt/master\fP) should be moved to the \fI\%minion configuration\fP 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 \fI\%more complex states\fP\&. .SS running salt as normal user tutorial .sp \fBBefore continuing\fP make sure you have a working Salt installation by following the instructions in the \fI\%Salt install guide\fP\&. .INDENT 0.0 .INDENT 3.5 .IP "Stuck?" .sp The Salt Project community can help offer advice and help troubleshoot technical issues as you\(aqre learning about Salt. One of the best places to talk to the community is on the \fI\%Salt Project Slack workspace\fP\&. .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_ + \(dq/salt/root\(dq # you need to edit this _location_of_source_code_ = ... INSTALL_DIR = _location_of_source_code_ CONFIG_DIR = ROOT_DIR + \(dq/etc/salt\(dq CACHE_DIR = ROOT_DIR + \(dq/var/cache/salt\(dq SOCK_DIR = ROOT_DIR + \(dq/var/run/salt\(dq SRV_ROOT_DIR = ROOT_DIR + \(dq/srv\(dq BASE_FILE_ROOTS_DIR = ROOT_DIR + \(dq/srv/salt\(dq BASE_PILLAR_ROOTS_DIR = ROOT_DIR + \(dq/srv/pillar\(dq BASE_MASTER_ROOTS_DIR = ROOT_DIR + \(dq/srv/salt\-master\(dq LOGS_DIR = ROOT_DIR + \(dq/var/log/salt\(dq PIDFILE_DIR = ROOT_DIR + \(dq/var/run\(dq CLOUD_DIR = INSTALL_DIR + \(dq/cloud\(dq BOOTSTRAP = CLOUD_DIR + \(dq/deploy/bootstrap\-salt.sh\(dq .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 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 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 \fI\%master_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 \fI\%Configuring the Salt Minion\fP 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 \fI\%file_client\fP configuration option needs to be set. By default the \fI\%file_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 \fI\%file_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 \fI\%file_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 \(dqscript\(dq 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 \fI\%External pillars\fP are supported when running in masterless mode. .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\fPtructured \fBL\fPayered \fBS\fPtate. 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 \fI\%Pillar\fP next. .UNINDENT .UNINDENT .SS It is All Just Data .sp Before delving into the particulars, it will help to understand that the SLS file is just a data structure under the hood. While understanding that the SLS is just a data structure isn\(aqt critical for understanding and making use of Salt States, it should help bolster knowledge of where the real power is. .sp SLS files are therefore, in reality, just 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 \fI\%here\fP\&. .SS Default Data \- YAML .sp By default Salt represents the SLS data in what is one of the simplest serialization formats available \- \fI\%YAML\fP\&. .sp A typical SLS file will often look like this in YAML: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 These demos use some generic service and package names, different distributions often use different names for packages and services. For instance \fIapache\fP should be replaced with \fIhttpd\fP on a Red Hat system. Salt uses the name of the init script, systemd name, upstart name etc. based on what the underlying service management for the platform. To get a list of the available service names on a platform execute the service.get_all salt function. .sp Information on how to make states work with multiple distributions is later in the tutorial. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg.installed: [] service.running: \- require: \- pkg: apache .ft P .fi .UNINDENT .UNINDENT .sp This SLS data will ensure that the package named apache is installed, and that the apache service is running. The components can be explained in a simple way. .sp The first line is the ID for a set of data, and it is called the ID Declaration. This ID sets the name of the thing that needs to be manipulated. .sp The second and third lines contain the state module function to be run, in the format \fB<state_module>.<function>\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 \fI\%top.sls\fP and \fI\%Include declaration\fP 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 \fI\%States Tutorial\fP\&. .SS Extending Included SLS Data .sp Sometimes SLS data needs to be extended. Perhaps the apache service needs to watch additional resources, or under certain circumstances a different file needs to be placed. .sp In these examples, the first will add a custom banner to ssh and the second will add more watchers to apache to include mod_python. .sp \fBssh/custom\-server.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- ssh.server extend: /etc/ssh/banner: file: \- source: salt://ssh/custom\-banner .ft P .fi .UNINDENT .UNINDENT .sp \fBpython/mod_python.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- apache extend: apache: service: \- watch: \- pkg: mod_python mod_python: pkg.installed .ft P .fi .UNINDENT .UNINDENT .sp The \fBcustom\-server.sls\fP file uses the extend statement to overwrite where the banner is being downloaded from, and therefore changing what file is being used to configure the banner. .sp In the new mod_python SLS the mod_python package is added, but more importantly the apache service was extended to also watch the mod_python package. .INDENT 0.0 .INDENT 3.5 .IP "Using extend with require or watch" .sp The \fBextend\fP statement works differently for \fBrequire\fP or \fBwatch\fP\&. It appends to, rather than replacing the requisite component. .UNINDENT .UNINDENT .SS Understanding the Render System .sp Since SLS data is simply that (data), it does not need to be represented with YAML. Salt defaults to YAML because it is very straightforward and easy to learn and use. But the SLS files can be rendered from almost any imaginable medium, so long as a renderer module is provided. .sp The default rendering system is the \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 \fI\%pydsl\fP renderer provides a flexible, domain\-specific language for authoring SLS data in Python; and the \fI\%pyobjects\fP renderer gives you a \fI\%\(dqPythonic\(dq\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 \fI\%file.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 \fI\%file 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(): \(dq\(dq\(dq Install the django package \(dq\(dq\(dq return {\(dqinclude\(dq: [\(dqpython\(dq], \(dqdjango\(dq: {\(dqpkg\(dq: [\(dqinstalled\(dq]}} .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 \fI\%HighState data structure\fP\&. .sp Alternatively, using the \fI\%pydsl\fP renderer, the above example can be written more succinctly as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pydsl include(\(dqpython\(dq, delayed=True) state(\(dqdjango\(dq).pkg.installed() .ft P .fi .UNINDENT .UNINDENT .sp The \fI\%pyobjects\fP renderer provides an \fI\%\(dqPythonic\(dq\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(\(dqpython\(dq) Pkg.installed(\(dqdjango\(dq) .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 \fI\%Pillar Walkthrough\fP .UNINDENT .UNINDENT .SS States tutorial, part 1 \- Basic Usage .sp The purpose of this tutorial is to demonstrate how quickly you can configure a system to be managed by Salt States. For detailed information about the state system please refer to the full \fI\%states reference\fP\&. .sp This tutorial will walk you through using Salt to configure a minion to run the Apache HTTP server and to ensure the server is running. .sp \fBBefore continuing\fP make sure you have a working Salt installation by following the instructions in the \fI\%Salt install guide\fP\&. .INDENT 0.0 .INDENT 3.5 .IP "Stuck?" .sp The Salt Project community can help offer advice and help troubleshoot technical issues as you\(aqre learning about Salt. One of the best places to talk to the community is on the \fI\%Salt Project Slack workspace\fP\&. .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 (\fI\%file_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 \fI\%top.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 \fI\%top file\fP is separated into environments (discussed later). The default environment is \fBbase\fP\&. Under the \fBbase\fP environment a collection of minion matches is defined; for now simply specify all hosts (\fB*\fP). .INDENT 0.0 .INDENT 3.5 .IP "Targeting minions" .sp The expressions can use any of the targeting mechanisms used by Salt — minions can be matched by glob, PCRE regular expression, or by \fI\%grains\fP\&. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqos:Fedora\(aq: \- match: grain \- webserver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Create an \fBsls\fP file .sp In the same directory as the \fI\%top file\fP, create a file named \fBwebserver.sls\fP, containing the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: # ID declaration pkg: # state declaration \- installed # function declaration .ft P .fi .UNINDENT .UNINDENT .sp The first line, called the \fI\%ID declaration\fP, is an arbitrary identifier. In this case it defines the name of the package to be installed. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The package name for the Apache httpd web server may differ depending on OS or distro — for example, on Fedora it is \fBhttpd\fP but on Debian/Ubuntu it is \fBapache2\fP\&. .UNINDENT .UNINDENT .sp The second line, called the \fI\%State declaration\fP, defines which of the Salt States we are using. In this example, we are using the \fI\%pkg state\fP to ensure that a given package is installed. .sp The third line, called the \fI\%Function declaration\fP, defines which function in the \fI\%pkg 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 \fI\%Renderers\fP and they are dead\-simple to write. .sp In this tutorial we will be using YAML in Jinja2 templates, which is the default format. The default can be changed by editing \fI\%renderer\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 \fI\%top file\fP 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 \(dqhighstate\(dq, and can be run using the \fI\%state.highstate\fP function. However, to make the usage easier to understand (\(dqhighstate\(dq is not necessarily an intuitive name), a \fI\%state.apply\fP function was added in version 2015.5.0, which when invoked without any SLS names will trigger a highstate. \fI\%state.highstate\fP still exists and can be used, but the documentation (as can be seen above) has been updated to reference \fI\%state.apply\fP, so keep the following in mind as you read the documentation: .INDENT 0.0 .IP \(bu 2 \fI\%state.apply\fP invoked without any SLS names will run \fI\%state.highstate\fP .IP \(bu 2 \fI\%state.apply\fP invoked with SLS names will run \fI\%state.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 \fI\%custom grain modules\fP, 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 \fI\%this example\fP 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 \fI\%top.sls\fP or an \fI\%Include declaration\fP 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 under the configured file_roots (default: \fB/srv/salt/\fP) 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 (\fI\%\-d\fP) one can view any output from the minion as it works: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-minion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Increase the default timeout value when running \fBsalt\fP\&. For example, to change the default timeout to 60 seconds: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-t 60 .ft P .fi .UNINDENT .UNINDENT .sp For best results, combine all three: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-minion \-l debug # On the minion salt \(aq*\(aq state.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. \fI\%Part 2\fP 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 \fI\%part 1\fP\&. It is recommended that you begin there. .UNINDENT .UNINDENT .sp In the \fI\%last part\fP of the Salt States tutorial we covered the basics of installing a package. We will now modify our \fBwebserver.sls\fP file to have requirements, and use even more Salt States. .SS Call multiple States .sp You can specify multiple \fI\%State declaration\fP under an \fI\%ID declaration\fP\&. For example, a quick modification to our \fBwebserver.sls\fP to also start Apache if it is not running: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg.installed: [] service.running: \- require: \- pkg: apache .ft P .fi .UNINDENT .UNINDENT .sp Try stopping Apache before running \fI\%state.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, \fI\%service state\fP\&. With the example above, just add \(dq\- name: httpd\(dq 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 \fI\%ID declaration\fP\&. In this example it is the location we want to install our custom HTML file. (\fBNote:\fP the default location that Apache serves may differ from the above on your OS or distro. \fB/srv/www\fP could also be a likely place to look.) .sp \fBLine 8\fP the \fI\%State declaration\fP\&. This example uses the Salt \fI\%file state\fP\&. .sp \fBLine 9\fP is the \fI\%Function declaration\fP\&. The \fI\%managed function\fP will download a file from the master and install it in the location specified. .sp \fBLine 10\fP is a \fI\%Function arg declaration\fP which, in this example, passes the \fBsource\fP argument to the \fI\%managed function\fP\&. .sp \fBLine 11\fP is a \fI\%Requisite declaration\fP\&. .sp \fBLine 12\fP is a \fI\%Requisite reference\fP which refers to a state and an ID. In this example, it is referring to the \fBID declaration\fP from our example in \fI\%part 1\fP\&. This declaration tells Salt not to install the HTML file until Apache is installed. .sp Next, create the \fBindex.html\fP file and save it in the \fBwebserver\fP directory: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C <!DOCTYPE html> <html> <head><title>Salt rocks</title></head> <body> <h1>This file brought to you by Salt</h1> </body> </html> .ft P .fi .UNINDENT .UNINDENT .sp Last, call \fI\%state.apply\fP again and the minion will fetch and execute the \fI\%highstate\fP 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 \fI\%Requisite declaration\fP, “require”, and “watch”. Not every state supports “watch”. The \fI\%service 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 \fI\%Name declaration\fP which explained in \fI\%Part 3\fP\&. .UNINDENT .UNINDENT .SS Next steps .sp In \fI\%part 3\fP we will discuss how to use includes, extends, and templating to make a more complete State Tree configuration. .SS States tutorial, part 3 \- Templating, Includes, Extends .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This tutorial builds on topics covered in \fI\%part 1\fP and \fI\%part 2\fP\&. It is recommended that you begin there. .UNINDENT .UNINDENT .sp This part of the tutorial will cover more advanced templating and configuration techniques for \fBsls\fP files. .SS Templating SLS modules .sp SLS modules may require programming logic or inline execution. This is accomplished with module templating. The default module templating system used is \fI\%Jinja2\fP and may be configured by changing the \fI\%renderer\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. \fI\%Salt grains\fP objects are made available in the template context. The \fIgrains\fP can be used from within sls modules: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg.installed: {% if grains[\(aqos\(aq] == \(aqRedHat\(aq %} \- name: httpd {% elif grains[\(aqos\(aq] == \(aqUbuntu\(aq %} \- name: apache2 {% endif %} .ft P .fi .UNINDENT .UNINDENT .SS 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=\(dqworld\(dq 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(\(dqsome_group_that_exists\(dq) .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[\(dqnetwork.hw_addr\(dq](\(dqeth0\(dq) .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, \fI\%Requisites and Other Global State Arguments\fP span multiple files by using an \fI\%Include declaration\fP\&. For example: .sp \fBpython/python\-libs.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-dateutil: pkg.installed .ft P .fi .UNINDENT .UNINDENT .sp \fBpython/django.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- python.python\-libs django: pkg.installed: \- require: \- pkg: python\-dateutil .ft P .fi .UNINDENT .UNINDENT .SS Extend declaration .sp You can modify previous declarations by using an \fI\%Extend declaration\fP\&. For example the following modifies the Apache tree to also restart Apache when the vhosts file is changed: .sp \fBapache/apache.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg.installed .ft P .fi .UNINDENT .UNINDENT .sp \fBapache/mywebsite.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- apache.apache extend: apache: service: \- running \- watch: \- file: /etc/httpd/extra/httpd\-vhosts.conf /etc/httpd/extra/httpd\-vhosts.conf: file.managed: \- source: salt://apache/httpd\-vhosts.conf .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .IP "Using extend with require or watch" .sp The \fBextend\fP statement works differently for \fBrequire\fP or \fBwatch\fP\&. It appends to, rather than replacing the requisite component. .UNINDENT .UNINDENT .SS Name declaration .sp You can override the \fI\%ID declaration\fP by using a \fI\%Name declaration\fP\&. For example, the previous example is a bit more maintainable if rewritten as follows: .sp \fBapache/mywebsite.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- apache.apache extend: apache: service: \- running \- watch: \- file: mywebsite mywebsite: file.managed: \- name: /etc/httpd/extra/httpd\-vhosts.conf \- source: salt://apache/httpd\-vhosts.conf .ft P .fi .UNINDENT .UNINDENT .SS Names declaration .sp Even more powerful is using a \fI\%Names declaration\fP to override the \fI\%ID declaration\fP for multiple states at once. This often can remove the need for looping in a template. For example, the first example in this tutorial can be rewritten without the loop: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C stooges: user.present: \- names: \- moe \- larry \- curly .ft P .fi .UNINDENT .UNINDENT .SS Next steps .sp In \fI\%part 4\fP we will discuss how to use salt\(aqs \fI\%file_roots\fP to set up a workflow in which states can be \(dqpromoted\(dq 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 \fI\%part 1\fP, \fI\%part 2\fP, and \fI\%part 3\fP\&. It is recommended that you begin there. .UNINDENT .UNINDENT .sp This part of the tutorial will show how to use salt\(aqs \fI\%file_roots\fP to set up a workflow in which states can be \(dqpromoted\(dq 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 \(dqwins\(dq. 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 \fI\%fileserver_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 \fI\%fileserver_backend\fP list, then the file in \fBroots\fP will \(dqwin\(dq, and the file in gitfs will be ignored. .sp A more thorough explanation of how Salt\(aqs modular fileserver works can be found \fI\%here\fP\&. 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 \fI\%here\fP 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 \fI\%state.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 \fI\%state.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 \fI\%reference documentation\fP 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. One of the best places to talk to the community is on the \fI\%Salt Project Slack workspace\fP\&. .sp In addition, by continuing to the \fI\%Orchestrate Runner\fP 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 \fI\%Orchestrate Runner\fP\&. .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 \fI\%syslog_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: \(dq127.0.0.1\(dq \- 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: \(dq127.0.0.1\(dq \- 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\(dqstring\(dq\fP in the generated configuration, it should be like \fB\(aq\(dqstring\(dq\(aq\fP in the YAML document .IP \(bu 2 similarly, users should write \fB\(dq\(aqstring\(aq\(dq\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: \(dq/home/tibi/install/syslog\-ng/etc/syslog\-ng.conf\(dq # 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: \(dq/home/tibi/install/syslog\-ng/sbin\(dq # Writes the first lines into the config file, also erases its previous # content write_version: module.run: \- name: syslog_ng.write_version \- m_name: \(dq3.6\(dq # There is a shorter form to set the above variables set_variables: module.run: \- name: syslog_ng.set_parameters \- version: \(dq3.6\(dq \- binary_path: \(dq/home/tibi/install/syslog\-ng/sbin\(dq \- config_file: \(dq/home/tibi/install/syslog\-ng/etc/syslog\-ng.conf\(dq # Some global options options.global_options: syslog_ng.config: \- config: \- time_reap: 30 \- mark_freq: 10 \- keep_hostname: \(dqyes\(dq source.s_localhost: syslog_ng.config: \- config: \- tcp: \- ip: \(dq127.0.0.1\(dq \- port: 1233 destination.d_log_server: syslog_ng.config: \- config: \- tcp: \- \(dq127.0.0.1\(dq \- 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 \fI\%syslog_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 \fI\%syslog_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 \fI\%syslog_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( \(dq/var/log/apache/access.log\(dq, 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\(dq/var/log/apache/access.log\(dq\(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\(dq/var/log/apache/access.log\(dq\(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\(dq/var/log/apache/access.log\(dq\(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(\(dq0.0.0.0\(dq), 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( \(dq@json:\(dq ); }; .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\(dq@json:\(dq\(aq\(aq .ft P .fi .UNINDENT .UNINDENT .SS Template .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C template t_demo_filetemplate { template( \(dq$ISODATE $HOST $MSG \(dq ); 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\(dq$ISODATE $HOST $MSG\en\(dq\(aq \- template_escape: \- \(dqno\(dq .ft P .fi .UNINDENT .UNINDENT .SS Rewrite .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rewrite r_set_message_to_MESSAGE { set( \(dq${.json.message}\(dq, value(\(dq$MESSAGE\(dq) ); }; .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\(dq${.json.message}\(dq\(aq \- value : \(aq\(dq$MESSAGE\(dq\(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: \(dqyes\(dq .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( \(dq/tmp/json\-input.log\(dq, template(t_gsoc2014) ); }; flags(final); }; channel { filter(f_not_json); parser { syslog\-parser( ); }; rewrite(r_set_syslog_tag); flags(final); }; }; destination { file( \(dq/tmp/all.log\(dq, 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\(dq/tmp/json\-input.log\(dq\(aq \- template: t_gsoc2014 \- flags: final \- channel: \- filter: f_not_json \- parser: \- syslog\-parser: [] \- rewrite: r_set_syslog_tag \- flags: final \- destination: \- file: \- \(dq/tmp/all.log\(dq \- template: t_gsoc2014 .ft P .fi .UNINDENT .UNINDENT .SS Salt in 10 Minutes .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Welcome to Salt Project! 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 Project creator and Chief Developer of Salt Project .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 \fI\%Salt install guide\fP provides 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 \fI\%here\fP\&. .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 \fI\%Masterless Minion Quickstart\fP .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 \fI\%id\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 \fI\%master_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 \fI\%test.version\fP function. .sp In the case of \fBtest.version\fP, \fBtest\fP refers to a \fI\%execution module\fP\&. \fBversion\fP refers to the \fI\%version\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 \fI\%test.version\fP in parallel and return the result. Using \fI\%test.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 \fI\%id\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 \fI\%on the web\fP\&. .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 \fI\%Execution Modules\fP\&. .UNINDENT .UNINDENT .SS Helpful Functions to Know .sp The \fI\%cmd\fP module contains functions to shell out on minions, such as \fI\%cmd.run\fP and \fI\%cmd.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 \fI\%here\fP\&. .UNINDENT .UNINDENT .sp The \fI\%network.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 \fI\%here\fP\&. .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 \fI\%here\fP\&. .SS Grains .sp Salt uses a system called \fI\%Grains\fP to build up static data about minions. This data includes information about the operating system that is running, CPU architecture and much more. The grains system is used throughout Salt to deliver platform data to many components and to users. .sp Grains can also be statically set, this makes it easy to assign values to minions for grouping and managing. .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 \fI\%grains.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: \fI\%Targeting with Grains\fP .TP .B Pillar Target based on pillar data: \fI\%Targeting with Pillar\fP .TP .B IP Target based on IP address/subnet/range .TP .B Compound Create logic to target based on multiple targets: \fI\%Targeting with Compound\fP .TP .B Nodegroup Target with nodegroups: \fI\%Targeting with Nodegroup\fP .UNINDENT .sp The concepts of targets are used on the command line with Salt, but also function in many other areas as well, including the state system and the systems used for ACLs and user permissions. .SS Passing in Arguments .sp Many of the functions available accept arguments 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 \(dq{\(aqfoo\(aq: \(aqbar\(aq}\(dq .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: \fI\%Requisites\fP .sp Also evaluation ordering is available in Salt as well: \fI\%Ordering States\fP .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 \fI\%state.apply\fP is just another remote execution function, just like \fI\%test.version\fP or \fI\%disk.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 \fI\%Starting States\fP .IP 2. 3 \fI\%Pillar Walkthrough\fP .UNINDENT .sp An understanding of Pillar is extremely helpful in using States. .SS Getting Deeper Into States .sp Two more in\-depth States tutorials exist, which delve much more deeply into States functionality. .INDENT 0.0 .IP 1. 3 \fI\%How Do I Use Salt States?\fP, covers much more to get off the ground with States. .IP 2. 3 The \fI\%States Tutorial\fP also provides a fantastic introduction. .UNINDENT .sp These tutorials include much more in\-depth information including templating SLS formulas etc. .SS So Much More! .sp This concludes the initial Salt 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 \fI\%Pillar\fP .IP \(bu 2 \fI\%Job Management\fP .UNINDENT .sp A few more tutorials are also available: .INDENT 0.0 .IP \(bu 2 \fI\%Remote Execution Tutorial\fP .IP \(bu 2 \fI\%Standalone Minion\fP .UNINDENT .sp This still is only scratching the surface, many components such as the reactor and event systems, extending Salt, modular components and more are not covered here. For an overview of all Salt features and documentation, look at the \fI\%Table of Contents\fP\&. .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 \(dqmaster\(dq server sending commands to one or multiple \(dqminion\(dq servers. The master server is the \(dqcommand center\(dq. It is going to be the place where you store your configuration files, aka: \(dqwhich server is the db, which is the web server, and what libraries and software they should have installed\(dq. 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 \(dqsalt communication channels\(dq or \(dqmeta\(dq or \(dqconfig\(dq 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 \(dqbusiness\(dq or \(dqservice\(dq configuration files (once again, not an official name): these are configuration files, ending with \(dq.sls\(dq 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 \(dqmasterless\(dq configuration where a minion is autonomous (in which case salt can be seen as a local configuration tool), or in \(dqmultiple master\(dq 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 \(dqSalt master\(dq 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 \(dqSalt minion\(dq 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 See the \fI\%Salt install guide\fP for macOS installation instructions. .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 \(dqopen\(dq 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 \(dq$(curl \-fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)\(dq .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\%https://docs.saltproject.io/en/latest/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 \(dqprovisioners\(dq. 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 \(dqprovisioner\(dq 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 ubuntu/focal64 .ft P .fi .UNINDENT .UNINDENT .sp This command creates a default Vagrantfile configuration file and import focal64 virtualbox image file to configuration, so it could be used. This configuration file will be used to pass configuration parameters to the Salt provisioner in Step 3. .SS Modify the Vagrantfile .sp Modify Vagrantfile to use th private_ip in local network. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C config.vm.network :private_network, ip: \(dq192.168.33.10\(dq .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@focal64:~$\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 = \(dq/etc/salt/minion\(dq salt.minion_key = \(dq./minion1.pem\(dq salt.minion_pub = \(dq./minion1.pub\(dq 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 \(dqBootstrapping Salt... (this may take a while) Salt successfully configured and installed!\(dq .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 \fI\%state.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 \fI\%state.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\%https://docs.saltproject.io/en/latest/index.html#configuration\-management\fP .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 \fI\%Salt Walkthrough\fP\&. .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 \fI\%Installing Salt for Development\fP and the \fI\%Contributing\fP 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 \(aqtest\-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 \(aqtest\-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. Pass any pytest options after \fI\-\-\fP .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): \(dq\(dq\(dq test.ping \(dq\(dq\(dq self.assertTrue(self.run_function(\(dqtest.ping\(dq)) .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 \(aqtest\-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 \(aqtest\-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 \(aqtest\-3(coverage=False)\(aq \-\- tests/pytests/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 \(aqtest\-3(coverage=False)\(aq \-\- tests/pytests/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 \(aqtest\-3(coverage=False)\(aq \-\- tests/pytests/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 \(aqtest\-3(coverage=False)\(aq \-\- tests/pytests/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 \(dqnew\(dq 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): \(dq\(dq\(dq test.ping \(dq\(dq\(dq self.assertTrue(self.run_function(\(dqtest.ping\(dq)) .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): \(dq\(dq\(dq test.echo \(dq\(dq\(dq self.assertEqual(self.run_function(\(dqtest.echo\(dq, [\(dqtext\(dq]), \(dqtext\(dq) .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): \(dq\(dq\(dq aliases.set_target and aliases.get_target \(dq\(dq\(dq set_ret = self.run_function(\(dqaliases.set_target\(dq, alias=\(dqfred\(dq, target=\(dqbob\(dq) self.assertTrue(set_ret) tgt_ret = self.run_function(\(dqaliases.get_target\(dq, alias=\(dqfred\(dq) self.assertEqual(tgt_ret, \(dqbob\(dq) .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 \fI\%Integration Test Class Examples\fP 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, decorate the test function with the \fBdestructive_test\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C @pytest.mark.destructive_test def test_pkg_install(salt_cli): ret = salt_cli.run(\(dqpkg.install\(dq, \(dqfinch\(dq) assert 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 \(dqblock all of the exits\(dq. More information about how to properly mock external resources can be found in Salt\(aqs \fI\%Unit Test\fP 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 \(dqblocking all the exits\(dq. .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/pytests/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): \(dq\(dq\(dq Test if get_file can\(aqt find the file. \(dq\(dq\(dq with patch(\(dqsalt.modules.cp.hash_file\(dq, MagicMock(return_value=False)): path = \(dqsalt://saltines\(dq dest = \(dq/srv/salt/cheese\(dq ret = \(dq\(dq 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 \(dqblocking the exits\(dq 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 \fI\%Simple Unit Test Example\fP .IP \(bu 2 \fI\%Complete Unit Test Example\fP .IP \(bu 2 \fI\%Complex Unit Test Example\fP .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/ci\fP directory. You will need to add your module to the appropriate file under \fBrequirements/static/ci\fP\&. When \fBpre\-commit\fP is run it will create all of the needed requirement files under \fBrequirements/static/ci/py3{6,7,8,9}\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\-ci\-images\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 def test_issue_58763_a(tmp_path, modules, state_tree, caplog): venv_dir = tmp_path / \(dqissue\-2028\-pip\-installed\(dq sls_contents = \(dq\(dq\(dq test.random_hash: module.run: \- size: 10 \- hash_type: md5 \(dq\(dq\(dq with pytest.helpers.temp_file(\(dqissue\-58763.sls\(dq, sls_contents, state_tree): with caplog.at_level(logging.DEBUG): ret = modules.state.sls( mods=\(dqissue\-58763\(dq, ) assert len(ret.raw) == 1 for k in ret.raw: assert ret.raw[k][\(dqresult\(dq] is True assert ( \(dqDetected legacy module.run syntax: test.random_hash\(dq in caplog.messages ) .ft P .fi .UNINDENT .UNINDENT .SS Test Groups .sp Salt has four groups .INDENT 0.0 .IP \(bu 2 fast \- Tests that are ~10s or faster. Fast tests make up ~75% of tests and can run in 10 to 20 minutes. .IP \(bu 2 slow \- Tests that are ~10s or slower. .IP \(bu 2 core \- Tests of any speed that test the root parts of salt. .IP \(bu 2 flaky\-jail \- Test that need to be temporarily skipped. .UNINDENT .sp Pytest Decorators .INDENT 0.0 .IP \(bu 2 @pytest.mark.slow_test .IP \(bu 2 @pytest.mark.core_test .IP \(bu 2 @pytest.mark.flaky_jail .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C @pytest.mark.core_test def test_ping(self): \(dq\(dq\(dq test.ping \(dq\(dq\(dq self.assertTrue(self.run_function(\(dqtest.ping\(dq)) .ft P .fi .UNINDENT .UNINDENT .sp You can also mark all the tests in file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pytestmark = [ pytest.mark.core_test, ] def test_ping(self): \(dq\(dq\(dq test.ping \(dq\(dq\(dq self.assertTrue(self.run_function(\(dqtest.ping\(dq)) def test_ping2(self): \(dq\(dq\(dq test.ping \(dq\(dq\(dq for _ in range(10): self.assertTrue(self.run_function(\(dqtest.ping\(dq)) .ft P .fi .UNINDENT .UNINDENT .sp You can enable or disable test groups locally by passing there respected flag: .INDENT 0.0 .IP \(bu 2 \-\-no\-fast\-tests .IP \(bu 2 \-\-slow\-tests .IP \(bu 2 \-\-core\-tests .IP \(bu 2 \-\-flaky\-jail .UNINDENT .sp In your PR you can enable or disable test groups by setting a label. All thought the fast, slow and core tests specified in the change file will always run. .INDENT 0.0 .IP \(bu 2 test:no\-fast .IP \(bu 2 test:slow .IP \(bu 2 test:core .IP \(bu 2 test:flaky\-jail .UNINDENT .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 \fI\%Salt\(aqs Test Suite Documentation\fP .IP \(bu 2 \fI\%Integration Tests\fP .IP \(bu 2 \fI\%Unit Tests\fP .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 \fI\%firewall configuration\fP page for help opening the firewall on various platforms. .sp If you\(aqve opened the correct TCP ports and still aren\(aqt seeing connections, check that no additional access control system such as \fI\%SELinux\fP or \fI\%AppArmor\fP is blocking Salt. .SS Too many open files .sp The salt\-master needs at least 2 sockets per host that connects to it, one for the Publisher and one for response port. Thus, large installations may, upon scaling up the number of minions accessing a given master, encounter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 12:45:29,289 [salt.master ][INFO ] Starting Salt worker process 38 Too many open files sock != \-1 (tcp_listener.cpp:335) .ft P .fi .UNINDENT .UNINDENT .sp The solution to this would be to check the number of files allowed to be opened by the user running salt\-master (root by default): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@salt\-master ~]# ulimit \-n 1024 .ft P .fi .UNINDENT .UNINDENT .sp If this value is not equal to at least twice the number of minions, then it will need to be raised. For example, in an environment with 1800 minions, the \fBnofile\fP limit should be set to no less than 3600. This can be done by creating the file \fB/etc/security/limits.d/99\-salt.conf\fP, with the following contents: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root hard nofile 4096 root soft nofile 4096 .ft P .fi .UNINDENT .UNINDENT .sp Replace \fBroot\fP with the user under which the master runs, if different. .sp If your master does not have an \fB/etc/security/limits.d\fP directory, the lines can simply be appended to \fB/etc/security/limits.conf\fP\&. .sp As with any change to resource limits, it is best to stay logged into your current shell and open another shell to run \fBulimit \-n\fP again and verify that the changes were applied correctly. Additionally, if your master is running upstart, it may be necessary to specify the \fBnofile\fP limit in \fB/etc/default/salt\-master\fP if upstart isn\(aqt respecting your resource limits: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C limit nofile 4096 4096 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The above is simply an example of how to set these values, and you may wish to increase them even further if your Salt master is doing more than just running Salt. .UNINDENT .UNINDENT .SS Salt Master Stops Responding .sp There are known bugs with ZeroMQ versions less than 2.1.11 which can cause the Salt master to not respond properly. If you\(aqre running a ZeroMQ version greater than or equal to 2.1.9, you can work around the bug by setting the sysctls \fBnet.core.rmem_max\fP and \fBnet.core.wmem_max\fP to 16777216. Next, set the third field in \fBnet.ipv4.tcp_rmem\fP and \fBnet.ipv4.tcp_wmem\fP to at least 16777216. .sp You can do it manually with something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # echo 16777216 > /proc/sys/net/core/rmem_max # echo 16777216 > /proc/sys/net/core/wmem_max # echo \(dq4096 87380 16777216\(dq > /proc/sys/net/ipv4/tcp_rmem # echo \(dq4096 87380 16777216\(dq > /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 \(dq%%f\(dq gprof2dot.exe \-f callgrind \-\-show\-samples \(dq%%f\(dq \-o \(dq%%f.dot\(dq dot.exe \(dq%%f.dot\(dq \-Tpdf \-O del \(dq%%f.dot\(dq ) .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 \fI\%state.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 \fI\%\-\-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 \fI\%firewall configuration\fP page for help opening the firewall on various platforms. .sp If you have netcat installed, you can check port connectivity from the minion with the \fBnc\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ nc \-v \-z salt.master.ip.addr 4505 Connection to salt.master.ip.addr 4505 port [tcp/unknown] succeeded! $ nc \-v \-z salt.master.ip.addr 4506 Connection to salt.master.ip.addr 4506 port [tcp/unknown] succeeded! .ft P .fi .UNINDENT .UNINDENT .sp The \fI\%Nmap\fP utility can also be used to check if these ports are open: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # nmap \-sS \-q \-p 4505\-4506 salt.master.ip.addr Starting Nmap 6.40 ( http://nmap.org ) at 2013\-12\-29 19:44 CST Nmap scan report for salt.master.ip.addr (10.0.0.10) Host is up (0.0026s latency). PORT STATE SERVICE 4505/tcp open unknown 4506/tcp open unknown MAC Address: 00:11:22:AA:BB:CC (Intel) Nmap done: 1 IP address (1 host up) scanned in 1.64 seconds .ft P .fi .UNINDENT .UNINDENT .sp If you\(aqve opened the correct TCP ports and still aren\(aqt seeing connections, check that no additional access control system such as \fI\%SELinux\fP or \fI\%AppArmor\fP is blocking Salt. 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 \fI\%state.apply\fP\&. .sp When initially creating your state tree, it is generally recommended to invoke highstates by running \fI\%state.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 \fI\%targeting system\fP\&. .SS Live Python Debug Output .sp If the minion seems to be unresponsive, a SIGUSR1 can be passed to the process to display what piece of code is executing. This debug information can be invaluable in tracking down bugs. .sp To pass a SIGUSR1 to the minion, first make sure the minion is running in the foreground. Stop the service if it is running as a daemon, and start it in the foreground like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-minion \-l debug .ft P .fi .UNINDENT .UNINDENT .sp Then pass the signal to the minion when it seems to be unresponsive: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # killall \-SIGUSR1 salt\-minion .ft P .fi .UNINDENT .UNINDENT .sp When filing an issue or sending questions to the mailing list for a problem with an unresponsive daemon, be sure to include this information if possible. .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 \fI\%\-\-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 \fI\%firewall configuration\fP document that might help as well. .sp If you\(aqve enabled the right TCP ports on your operating system or Linux distribution\(aqs firewall and still aren\(aqt seeing connections, check that no additional access control system such as \fI\%SELinux\fP or \fI\%AppArmor\fP is blocking Salt. .SS Using salt\-call .sp The \fBsalt\-call\fP command was originally developed for aiding in the development of new Salt modules. Since then, many applications have been developed for running any Salt module locally on a minion. These range from the original intent of salt\-call, development assistance, to gathering more verbose output from calls like \fI\%state.apply\fP\&. .sp When initially creating your state tree, it is generally recommended to invoke \fI\%state.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 \fI\%targeting system\fP\&. .SS Too many open files .sp The salt\-master needs at least 2 sockets per host that connects to it, one for the Publisher and one for response port. Thus, large installations may, upon scaling up the number of minions accessing a given master, encounter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 12:45:29,289 [salt.master ][INFO ] Starting Salt worker process 38 Too many open files sock != \-1 (tcp_listener.cpp:335) .ft P .fi .UNINDENT .UNINDENT .sp The solution to this would be to check the number of files allowed to be opened by the user running salt\-master (root by default): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@salt\-master ~]# ulimit \-n 1024 .ft P .fi .UNINDENT .UNINDENT .sp And modify that value to be at least equal to the number of minions x 2. This setting can be changed in limits.conf as the nofile value(s), and activated upon new a login of the specified user. .sp So, an environment with 1800 minions, would need 1800 x 2 = 3600 as a minimum. .SS Salt Master Stops Responding .sp There are known bugs with ZeroMQ versions less than 2.1.11 which can cause the Salt master to not respond properly. If you\(aqre running a ZeroMQ version greater than or equal to 2.1.9, you can work around the bug by setting the sysctls \fBnet.core.rmem_max\fP and \fBnet.core.wmem_max\fP to 16777216. Next, set the third field in \fBnet.ipv4.tcp_rmem\fP and \fBnet.ipv4.tcp_wmem\fP to at least 16777216. .sp You can do it manually with something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # echo 16777216 > /proc/sys/net/core/rmem_max # echo 16777216 > /proc/sys/net/core/wmem_max # echo \(dq4096 87380 16777216\(dq > /proc/sys/net/ipv4/tcp_rmem # echo \(dq4096 87380 16777216\(dq > /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 \fI\%file.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: \(dqoverride\(dq \- defaults: custom_var: \(dqdefault value\(dq 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: \(dqoverride\(dq } \- defaults: { custom_var: \(dqdefault value\(dq, 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( \&... \(dq\(dq\(dqmystate: \&... file.managed: \&... \- context: \&... some: var\(dq\(dq\(dq \&... ) {\(aqmystate\(aq: {\(aqfile.managed\(aq: [{\(aqcontext\(aq: {\(aqsome\(aq: \(aqvar\(aq}}]}} >>> yaml.safe_load( \&... \(dq\(dq\(dqmystate: \&... file.managed: \&... \- context: \&... some: var\(dq\(dq\(dq \&... ) {\(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 \fI\%file.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\(dq \(dq\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\(dqfalse\(dq\(aq \- \(dq\(aqTrue\(aq\(dq \- \(dq\(aqYES\(aq\(dq \- \(aq\(dqNo\(dq\(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\(dq\(dq \(dq\(dq\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\(dq23:00\(dq\(aq day: 6 \- Every Friday SAT_10: time: \(aq\(dq06:00\(dq\(aq day: 7 \- Every Saturday SAT_20: time: \(aq\(dq14:00\(dq\(aq day: 7 \- Every Saturday SAT_30: time: \(aq\(dq22:00\(dq\(aq day: 7 \- Every Saturday SUN_10: time: \(aq\(dq06:00\(dq\(aq day: 1 \- Every Sunday {% endload %} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS YAML does not like \(dqDouble Short Decs\(dq .sp If I can find a way to make YAML accept \(dqDouble Short Decs\(dq then I will, since I think that double short decs would be awesome. So what is a \(dqDouble Short Dec\(dq? 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 \(dqold way\(dq, or with multiple \(dqfull decs\(dq: .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: \(dq\eu00b5\(dq \- copyright: \(dq\eu00A9\(dq \- A: \(dq\ex41\(dq \- alpha: \(dq\eu0251\(dq \- Alef: \(dq\eu05d0\(dq .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(\(dqText with wrong characters i need to figure out\(dq) .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(\(dq2013_05_10\(dq) 20130510 >>> yaml.safe_load(\(aq\(dq2013_05_10\(dq\(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(\(dq2014\-01\-20 14:23:23\(dq) datetime.datetime(2014, 1, 20, 14, 23, 23) >>> yaml.safe_load(\(aq\(dq2014\-01\-20 14:23:23\(dq\(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(\(dq4017\-16\-20\(dq) Traceback (most recent call last): File \(dq<stdin>\(dq, line 1, in <module> File \(dq/usr/local/lib/python2.7/site\-packages/yaml/__init__.py\(dq, line 93, in safe_load return load(stream, SafeLoader) File \(dq/usr/local/lib/python2.7/site\-packages/yaml/__init__.py\(dq, line 71, in load return loader.get_single_data() File \(dq/usr/local/lib/python2.7/site\-packages/yaml/constructor.py\(dq, line 39, in get_single_data return self.construct_document(node) File \(dq/usr/local/lib/python2.7/site\-packages/yaml/constructor.py\(dq, line 43, in construct_document data = self.construct_object(node) File \(dq/usr/local/lib/python2.7/site\-packages/yaml/constructor.py\(dq, line 88, in construct_object data = constructor(self, node) File \(dq/usr/local/lib/python2.7/site\-packages/yaml/constructor.py\(dq, line 312, in construct_yaml_timestamp return datetime.date(year, month, day) ValueError: month must be in 1..12 >>> yaml.safe_load(\(aq\(dq4017\-16\-20\(dq\(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 \fI\%master\fP and \fI\%minion\fP 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 \(dqopen core\(dq. 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 VMware, 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 \fI\%reporting a bug\fP\&. .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 \fI\%here\fP\&. .SS I\(aqm seeing weird behavior (including but not limited to packages not installing their users properly) .sp This is often caused by SELinux. Try disabling SELinux or putting it in permissive mode and see if the weird behavior goes away. .SS My script runs every time I run a \fIstate.apply\fP\&. Why? .sp You are probably using \fI\%cmd.run\fP rather than \fI\%cmd.wait\fP\&. A \fI\%cmd.wait\fP state will only run when there has been a change in a state that it is watching. .sp A \fI\%cmd.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 \fI\%cmd\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 \(dqMinion did not return\(dq 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 \fI\%manage.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 \fI\%jobs.list_jobs\fP runner can be used to show the job IDs of the jobs that have been run, and the \fI\%jobs.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 \fI\%worker_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 \fI\%id\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 \fI\%here\fP\&. .SS I\(aqm trying to manage packages/services but I get an error saying that the state is not available. Why? .sp Salt detects the Minion\(aqs operating system and assigns the correct package or service management module based on what is detected. However, for certain custom spins and OS derivatives this detection fails. In cases like this, an issue should be opened on our \fI\%tracker\fP, with the following information: .INDENT 0.0 .IP 1. 3 The output of the following command: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt <minion_id> 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 \fI\%saltutil.sync_modules\fP, or \fI\%saltutil.sync_all\fP is run. .sp Similarly, custom states are synced to Minions when \fI\%saltutil.sync_states\fP, or \fI\%saltutil.sync_all\fP is run. .sp They are both also synced when a \fI\%highstate\fP 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 \fI\%state.apply\fP/\fI\%state.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 \fI\%saltutil\fP module for more information. .sp \fI\%This reactor example\fP 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 \fI\%file.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 \fI\%backup_mode\fP, backup_mode can be configured on a per state basis, or in the minion config (note that if set in the minion config this would simply be the default method to use, you still need to specify that the file should be backed up!). .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 \fI\%file_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 \fI\%nodegroups\fP\&. See the \fI\%documentation\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 \fI\%file.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 \fI\%pillar.get\fP, with a colon representing a nested dictionary. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Deploying binary contents using the \fI\%file.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 \fI\%masterless mode\fP 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 \(dqRestart\-Service \-Name salt\-minion\(dq\(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 \(dqsalted\(dq 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 \(dqsalted\(dq 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 \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Grains can be set by users that have access to the minion configuration files on the local system, making them less secure than other identifiers in Salt. Avoid storing sensitive data, such as passwords or keys, on minions. Instead, make use of \fI\%Storing Static Data in the Pillar\fP and/or \fI\%Storing Data in Other Databases\fP\&. .UNINDENT .UNINDENT .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 \(dq{\(aqgrain\(aq: \(aqOldValue\(aq}\(dq .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. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 The guidance here should be taken in combination with \fI\%Hardening Salt\fP\&. .UNINDENT .UNINDENT .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. .sp \fBWARNING:\fP .INDENT 3.0 .INDENT 3.5 Grains can be set by users that have access to the minion configuration files on the local system, making them less secure than other identifiers in Salt. Avoid storing sensitive data, such as passwords or keys, on minions. Instead, make use of \fI\%Storing Static Data in the Pillar\fP and/or \fI\%Storing Data in Other Databases\fP\&. .UNINDENT .UNINDENT .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\%url 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 \fI\%Formulas\fP 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 \fI\%Pillars\fP 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 \(dqapache/map.jinja\(dq 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 \fI\%Formula documentation\fP), 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 \(dqapache/map.jinja\(dq 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 \(dqapache/map.jinja\(dq 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 \(dqapache/map.jinja\(dq 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: \(dqtest3rdb\(dq \- 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 \fI\%Full list of execution modules\fP Contains: a list of core modules that ship with Salt. .TP .B \fI\%Writing execution modules\fP 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 \fI\%Configuration\fP .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 \fI\%Targeting\fP\&. .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 \(dqHello: $FIRST_NAME\(dq\(aq env=\(aq{FIRST_NAME: \(dqJoe\(dq}\(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 \(dqHello\(aq: \(aq$FIRST_NAME\(dq\(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 \(dqHello: $FIRST_NAME\(dq\(aq env=\(aq{FIRST_NAME: \(dqJoe\(dq}\(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 \(dqfoo\(dq 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 \(dq1,2,3\(dq\(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. \fI\%roots\fP), unless environments are otherwise defined in the \fI\%file_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 \fI\%state.highstate\fP (or \fI\%state.apply\fP with no state argument) .IP \(bu 2 \fI\%saltutil.sync_modules\fP .IP \(bu 2 \fI\%saltutil.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 \fI\%saltutil.sync_modules\fP .IP \(bu 2 \fI\%saltutil.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<modulename>.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 \fI\%enable_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.<function>\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<module_name>.py\fP goes in \fB<module_name>/__init__.py\fP\&. The dependency packages are subdirectories of \fB<module_name>/\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): \(dq\(dq\(dqChecks whether a person is really a lumberjack\(dq\(dq\(dq 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 \fI\%file_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__[\(dqcmd.run\(dq](bar) .ft P .fi .UNINDENT .UNINDENT .sp This code will call the \fIrun\fP function in the \fI\%cmd\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 \fI\%salt runner\fP\&. .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.<value>\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. \fI\%salt.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 \(dq\(dq\(dq Cheese module initialization example \(dq\(dq\(dq def __init__(opts): \(dq\(dq\(dq Allow foreign imports if configured to do so \(dq\(dq\(dq if opts.get(\(dqcheese.allow_foreign\(dq, 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 \fI\%outputters\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __outputter__ = {\(dqrun\(dq: \(dqtxt\(dq} .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, \fI\%yumpkg\fP on RHEL/CentOS systems , and \fI\%aptpkg\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 \fI\%\(dqdunder\(dq dictionaries\fP 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 \(dq\(dq\(dq Cheese execution (or returner/beacon/etc.) module \(dq\(dq\(dq try: import enzymes HAS_ENZYMES = True except ImportError: HAS_ENZYMES = False def __virtual__(): \(dq\(dq\(dq only load cheese if enzymes are available \(dq\(dq\(dq if HAS_ENZYMES: return \(dqcheese\(dq else: return ( False, \(dqThe cheese execution module cannot be loaded: enzymes unavailable.\(dq, ) def slice(): pass .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(dq\(dq\(dq Cheese state module. Note that this works in state modules because it is guaranteed that execution modules are loaded first \(dq\(dq\(dq def __virtual__(): \(dq\(dq\(dq only load cheese if enzymes are available \(dq\(dq\(dq # predicate loading of the cheese state on the corresponding execution module if \(dqcheese.slice\(dq in __salt__: return \(dqcheese\(dq else: return False, \(dqThe cheese state module cannot be loaded: enzymes unavailable.\(dq .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 \fI\%here\fP\&. .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 \fI\%pkg\fP .IP \(bu 2 \fI\%service\fP .IP \(bu 2 \fI\%user\fP .IP \(bu 2 \fI\%shadow\fP .IP \(bu 2 \fI\%group\fP .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 \fI\%grains.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 \fI\%providers\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 \fI\%aptpkg\fP module to provide package management. .sp For per\-state provider overrides, see documentation on \fI\%state providers\fP\&. .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__ = \(dqpkg\(dq def __virtual__(): \(dq\(dq\(dq Confine this module to Mac OS with Homebrew. \(dq\(dq\(dq if salt.utils.path.which(\(dqbrew\(dq) and __grains__[\(dqos\(dq] == \(dqMacOS\(dq: 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__(): \(dq\(dq\(dq Only load if git exists on the system \(dq\(dq\(dq if salt.utils.path.which(\(dqgit\(dq) is None: return (False, \(dqThe git execution module cannot be loaded: git unavailable.\(dq) 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): \(dq\(dq\(dq A function to make some spam with eggs! CLI Example:: salt \(aq*\(aq test.spam eggs \(dq\(dq\(dq 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 <thatch@saltstack.com, Seth House <shouse@saltstack.com> :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(\(dqHere is Some Information\(dq) log.warning(\(dqYou Should Not Do That\(dq) log.error(\(dqIt Is Busted\(dq) .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__ = { \(dqset_\(dq: \(dqset\(dq, \(dqlist_\(dq: \(dqlist\(dq, } .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(\(dqFailed to import dependency_that_sometimes_exists: {0}\(dq.format(e)) @depends(\(dqdependency_that_sometimes_exists\(dq) def foo(): \(dq\(dq\(dq Function with a dependency on the \(dqdependency_that_sometimes_exists\(dq module, if the \(dqdependency_that_sometimes_exists\(dq is missing this function will not exist \(dq\(dq\(dq return True def _fallback(): \(dq\(dq\(dq Fallback function for the depends decorator to replace a function with \(dq\(dq\(dq return \(aq\(dqdependency_that_sometimes_exists\(dq needs to be installed for this function to exist\(aq @depends(\(dqdependency_that_sometimes_exists\(dq, fallback_function=_fallback) def foo(): \(dq\(dq\(dq Function with a dependency on the \(dqdependency_that_sometimes_exists\(dq module. If the \(dqdependency_that_sometimes_exists\(dq is missing this function will be replaced with \(dq_fallback\(dq \(dq\(dq\(dq 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 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 \fI\%Full list of builtin returners\fP .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 \fI\%master_job_cache\fP, \fI\%Storing Job Results in an External System\fP, 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): \(dq\(dq\(dq Return information to a redis server \(dq\(dq\(dq # Get a redis connection serv = redis.Redis(host=\(dqredis\-serv.example.com\(dq, port=6379, db=\(dq0\(dq) serv.sadd(\(dq%(id)s:jobs\(dq % ret, ret[\(dqjid\(dq]) serv.set(\(dq%(jid)s:%(id)s\(dq % ret, salt.utils.json.dumps(ret[\(dqreturn\(dq])) serv.sadd(\(dqjobs\(dq, ret[\(dqjid\(dq]) serv.sadd(ret[\(dqjid\(dq], ret[\(dqid\(dq]) .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 \fI\%file_roots\fP specified by the master config file. .sp Like all custom modules, these must be synced to the relevant master or minion before they can be used. See \fI\%Modular Systems\fP for details. .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 \fI\%__virtual__ function\fP\&. 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__ = \(dqredis\(dq def __virtual__(): if not HAS_REDIS: return False return __virtualname__ .ft P .fi .UNINDENT .UNINDENT .SS Master Job Cache Support .sp \fI\%master_job_cache\fP, \fI\%Storing Job Results in an External System\fP, and \fI\%Event Returners\fP\&. Salt\(aqs \fI\%master_job_cache\fP allows returners to be used as a pluggable replacement for the \fI\%Default Job Cache\fP\&. 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 \(dq\(dq\(dq Do any work necessary to prepare a JID, including sending a custom id \(dq\(dq\(dq 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): \(dq\(dq\(dq Save the load to the specified jid id \(dq\(dq\(dq query = \(dq\(dq\(dqINSERT INTO salt.jids ( jid, load ) VALUES ( \(aq{0}\(aq, \(aq{1}\(aq );\(dq\(dq\(dq.format( jid, salt.utils.json.dumps(load) ) # cassandra_cql.cql_query may raise a CommandExecutionError try: __salt__[\(dqcassandra_cql.cql_query\(dq](query) except CommandExecutionError: log.critical(\(dqCould not save load in jids table.\(dq) raise except Exception as e: log.critical(\(dqUnexpected error while inserting into jids: {0}\(dq.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): \(dq\(dq\(dq Return the load data that marks a specified jid \(dq\(dq\(dq query = \(dq\(dq\(dqSELECT load FROM salt.jids WHERE jid = \(aq{0}\(aq;\(dq\(dq\(dq.format(jid) ret = {} # cassandra_cql.cql_query may raise a CommandExecutionError try: data = __salt__[\(dqcassandra_cql.cql_query\(dq](query) if data: load = data[0].get(\(dqload\(dq) if load: ret = json.loads(load) except CommandExecutionError: log.critical(\(dqCould not get load from jids table.\(dq) raise except Exception as e: log.critical( \(dq\(dq\(dqUnexpected error while getting load from jids: {0}\(dq\(dq\(dq.format( str(e) ) ) raise return ret .ft P .fi .UNINDENT .UNINDENT .SS External Job Cache Support .sp Salt\(aqs \fI\%Storing Job Results in an External System\fP extends the \fI\%master_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 { \(dqlocal\(dq: { \(dqmaster_minion\(dq: { \(dqfun_args\(dq: [], \(dqjid\(dq: \(dq20150330121011408195\(dq, \(dqreturn\(dq: \(dq2018.3.4\(dq, \(dqretcode\(dq: 0, \(dqsuccess\(dq: true, \(dqcmd\(dq: \(dq_return\(dq, \(dq_stamp\(dq: \(dq2015\-03\-30T12:10:12.708663\(dq, \(dqfun\(dq: \(dqtest.version\(dq, \(dqid\(dq: \(dqmaster_minion\(dq } } } .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 { \(dqlocal\(dq: { \(dqminion1\(dq: \(dqtest.version\(dq, \(dqminion3\(dq: \(dqtest.version\(dq, \(dqminion2\(dq: \(dqtest.version\(dq } } .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 { \(dqlocal\(dq: [ \(dq20150330121011408195\(dq, \(dq20150330195922139916\(dq ] } .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 { \(dqlocal\(dq: [ \(dqminion3\(dq, \(dqminion2\(dq, \(dqminion1\(dq, \(dqmaster_minion\(dq ] } .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): \(dq\(dq\(dq Return event to mysql server Requires that configuration be enabled via \(aqevent_return\(aq option in master config. \(dq\(dq\(dq with _get_serv(events, commit=True) as cur: for event in events: tag = event.get(\(dqtag\(dq, \(dq\(dq) data = event.get(\(dqdata\(dq, \(dq\(dq) sql = \(dq\(dq\(dqINSERT INTO \(gasalt_events\(ga (\(gatag\(ga, \(gadata\(ga, \(gamaster_id\(ga ) VALUES (%s, %s, %s)\(dq\(dq\(dq cur.execute(sql, (tag, salt.utils.json.dumps(data), __opts__[\(dqid\(dq])) .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 \fI\%master_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{ \fI\%appoptics_return\fP T} T{ Salt returner to return highstate stats to AppOptics Metrics T} _ T{ \fI\%carbon_return\fP T} T{ Take data from salt and \(dqreturn\(dq it into a carbon receiver T} _ T{ \fI\%cassandra_cql_return\fP T} T{ Return data to a cassandra server T} _ T{ \fI\%couchbase_return\fP T} T{ Simple returner for Couchbase. T} _ T{ \fI\%couchdb_return\fP T} T{ Simple returner for CouchDB. T} _ T{ \fI\%elasticsearch_return\fP T} T{ Return data to an elasticsearch server for indexing. T} _ T{ \fI\%etcd_return\fP T} T{ Return data to an etcd server or cluster T} _ T{ \fI\%highstate_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{ \fI\%influxdb_return\fP T} T{ Return data to an influxdb server. T} _ T{ \fI\%kafka_return\fP T} T{ Return data to a Kafka topic T} _ T{ \fI\%librato_return\fP T} T{ Salt returner to return highstate stats to Librato T} _ T{ \fI\%local\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{ \fI\%local_cache\fP T} T{ Return data to local job cache T} _ T{ \fI\%mattermost_returner\fP T} T{ Return salt data via mattermost T} _ T{ \fI\%memcache_return\fP T} T{ Return data to a memcache server T} _ T{ \fI\%mongo_future_return\fP T} T{ Return data to a mongodb server T} _ T{ \fI\%mongo_return\fP T} T{ Return data to a mongodb server T} _ T{ \fI\%multi_returner\fP T} T{ Read/Write multiple returners T} _ T{ \fI\%mysql\fP T} T{ Return data to a mysql server T} _ T{ \fI\%nagios_nrdp_return\fP T} T{ Return salt data to Nagios T} _ T{ \fI\%odbc\fP T} T{ Return data to an ODBC compliant server. T} _ T{ \fI\%pgjsonb\fP T} T{ Return data to a PostgreSQL server with json data stored in Pg\(aqs jsonb data type T} _ T{ \fI\%postgres\fP T} T{ Return data to a postgresql server T} _ T{ \fI\%postgres_local_cache\fP T} T{ Use a postgresql server for the master job cache. T} _ T{ \fI\%pushover_returner\fP T} T{ T} _ T{ \fI\%rawfile_json\fP T} T{ Take data from salt and \(dqreturn\(dq it into a raw file containing the json, with one line per event. T} _ T{ \fI\%redis_return\fP T} T{ Return data to a redis server T} _ T{ \fI\%sentry_return\fP T} T{ Salt returner that reports execution results back to sentry. T} _ T{ \fI\%slack_returner\fP T} T{ Return salt data via slack T} _ T{ \fI\%slack_webhook_return\fP T} T{ Return salt data via Slack using Incoming Webhooks T} _ T{ \fI\%sms_return\fP T} T{ Return data by SMS. T} _ T{ \fI\%smtp_return\fP T} T{ Return salt data via email T} _ T{ \fI\%splunk\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{ \fI\%sqlite3_return\fP T} T{ Insert minion return data into a sqlite3 database T} _ T{ \fI\%syslog_return\fP T} T{ Return data to the host operating system\(aqs syslog facility T} _ T{ \fI\%telegram_return\fP T} T{ Return salt data via Telegram. T} _ T{ \fI\%xmpp_return\fP T} T{ Return salt data via xmpp T} _ T{ \fI\%zabbix_return\fP T} T{ T} _ .TE .SS salt.returners.appoptics_return .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: <token string here> .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: <the minion ID \- matches @host> tier: <the tier/etc. of this node> cluster: <the cluster name, etc.> .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 \(dqreturn\(dq 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: <server ip address> 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: <server IP or hostname> port: <carbon port> skip_on_error: True mode: (pickle|text) metric_base_pattern: <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: <server IP or hostname> port: <carbon 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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqskip_on_error\(dq: 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.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: 86400 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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqbucket\(dq: \(dqanother\-salt\(dq}\(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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqdb\(dq: \(dqanother\-salt\(dq}\(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.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 \fI\%elasticsearch 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. <index>\-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<index>\-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/\-<date>) indexes if enabled .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C elasticsearch: hosts: \- \(dq10.10.10.10:9200\(dq \- \(dq10.10.10.11:9200\(dq \- \(dq10.10.10.12:9200\(dq 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 or etcd3\-py .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 In order to choose whether to use etcd API v2 or v3, you can put the following configuration option in the same place as your etcd configuration. This option defaults to true, meaning you will use v2 unless you specify otherwise. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.require_v2: True .ft P .fi .UNINDENT .UNINDENT .sp When using API v3, there are some specific options available to be configured within your etcd profile. They are defaulted to the following... .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.encode_keys: False etcd.encode_values: True etcd.raw_keys: False etcd.raw_values: False etcd.unicode_errors: \(dqsurrogateescape\(dq .ft P .fi .UNINDENT .UNINDENT .sp \fBetcd.encode_keys\fP indicates whether you want to pre\-encode keys using msgpack before adding them to etcd. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you set \fBetcd.encode_keys\fP to \fBTrue\fP, all recursive functionality will no longer work. This includes \fBtree\fP and \fBls\fP and all other methods if you set \fBrecurse\fP/\fBrecursive\fP to \fBTrue\fP\&. This is due to the fact that when encoding with msgpack, keys like \fB/salt\fP and \fB/salt/stack\fP will have differing byte prefixes, and etcd v3 searches recursively using prefixes. .UNINDENT .UNINDENT .sp \fBetcd.encode_values\fP indicates whether you want to pre\-encode values using msgpack before adding them to etcd. This defaults to \fBTrue\fP to avoid data loss on non\-string values wherever possible. .sp \fBetcd.raw_keys\fP determines whether you want the raw key or a string returned. .sp \fBetcd.raw_values\fP determines whether you want the raw value or a string returned. .sp \fBetcd.unicode_errors\fP determines what you policy to follow when there are encoding/decoding errors. .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 .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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqdb\(dq: \(dqanother\-salt\(dq}\(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 \(dqserver1:9092\(dq .IP \(bu 2 \(dqserver2:9092\(dq .IP \(bu 2 \(dqserver3:9092\(dq .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 .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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqhost\(dq: \(dqhostname.domain.com\(dq}\(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: <database name> mongo.host: <server ip address> mongo.user: <MongoDB username> mongo.password: <MongoDB user 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: <database name> alternative.mongo.host: <server ip address> alternative.mongo.user: <MongoDB username> alternative.mongo.password: <MongoDB user 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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqdb\(dq: \(dqanother\-salt\(dq}\(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: <database name> mongo.host: <server ip address> mongo.user: <MongoDB username> mongo.password: <MongoDB user 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: <database name> alternative.mongo.host: <server ip address> alternative.mongo.user: <MongoDB username> alternative.mongo.password: <MongoDB user 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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqdb\(dq: \(dqanother\-salt\(dq}\(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 \(dqlocking\(dq 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_seconds\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_seconds\fP is set to \fI86400\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_seconds\fP seconds 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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqdb\(dq: \(dqanother\-salt\(dq}\(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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqservice\(dq: \(dqservice\-name\(dq}\(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 = \(dqSalt Returner\(dq Driver=TDS Server = <your server ip or fqdn> 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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqdsn\(dq: \(dqdsn\-name\(dq}\(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 \fI\%master job cache\fP\&. 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 \fI\%returners.postgres\fP and \fI\%returners.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_seconds\fP to the number of seconds 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_seconds\fP seconds 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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqdb\(dq: \(dqanother\-salt\(dq}\(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 \fI\%master job cache\fP\&. 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 \fI\%returners.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 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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqdb\(dq: \(dqanother\-salt\(dq}\(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 \fI\%master job cache\fP\&. 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 \fI\%returners.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 \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%pushover Salt Extension\fP\&. .UNINDENT .UNINDENT .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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqtitle\(dq: \(dqSalt is awesome!\(dq}\(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 \(dqreturn\(dq 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: <path_to_output_file> .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 \fI\%event_return_whitelist\fP or \fI\%event_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 redis.password: \(aq\(aq .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 alternative.redis.password: \(aq\(aq .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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqdb\(dq: \(dqanother\-salt\(dq}\(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 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:<jid>\(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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqchannel\(dq: \(dq#random\(dq}\(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 <github@cdalvaro.io>\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.event_return(events) Send event data to returner function :param events: The Salt event return :return: The result of the post .UNINDENT .INDENT 0.0 .TP .B salt.returners.slack_webhook_return.returner(ret, **kwargs) 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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqto\(dq: \(dquser@domain.com\(dq}\(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 .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: <splunk_http_forwarder_token> indexer: <hostname/IP of Splunk indexer> sourcetype: <Destination sourcetype for data> index: <Destination index for data> 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 salt.returners.splunk.event_return(events) Return events to Splunk via the HTTP Event Collector. Requires the Splunk HTTP Event Collector running on port 8088. This is available on Splunk Enterprise version 6.3 or higher. .UNINDENT .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 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. Requires the Splunk HTTP Event Collector running on port 8088. This is available on Splunk Enterprise version 6.3 or higher. .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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqdb\(dq: \(dq/var/lib/salt/another\-salt.db\(dq}\(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 \(dqsalt\-minion\(dq 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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqlevel\(dq: \(dqLOG_DEBUG\(dq}\(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{\(dqkey:\(dq: \(dqvalue\(dq}\(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{\(dqrecipient\(dq: \(dqsomeone\-else@xmpp.example.com\(dq}\(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 .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%zabbix Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Return salt data to Zabbix .sp The following Type: \(dqZabbix trapper\(dq with \(dqType of information\(dq 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 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[{ \(dqclient\(dq: \(dqlocal\(dq, \(dqtgt\(dq: \(dq*\(dq, \(dqfun\(dq: \(dqtest.version\(dq, \(dqmodule_executors\(dq: [\(dqsplay\(dq, \(dqdirect_call\(dq], \(dqexecutor_opts\(dq: {\(dqsplaytime\(dq: 10} }]\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%The full list of executors\fP .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 \fI\%Full list of states\fP Contains: list of install packages, create users, transfer files, start services, and so on. .TP .B \fI\%Pillar System\fP Contains: description of Salt\(aqs Pillar system. .TP .B \fI\%Highstate data structure\fP Contains: a dry vocabulary and technical representation of the configuration format that states represent. .TP .B \fI\%Writing states\fP 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 \fI\%module\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 \fI\%Full list of renderers\fP 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 \fI\%Renderers\fP 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 \(dqstate\(dq 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): \(dq\(dq\(dq 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 \(dq\(dq\(dq pkgs = [] # What functions should we aggregate? agg_enabled = [ \(dqinstalled\(dq, \(dqlatest\(dq, \(dqremoved\(dq, \(dqpurged\(dq, ] # The \(galow\(ga data is just a dict with the state, function (fun) and # arguments passed in from the sls if low.get(\(dqfun\(dq) not in agg_enabled: return low # Now look into what other things are set to execute for chunk in chunks: # The state runtime uses \(dqtags\(dq to track completed jobs, it may # look familiar with the _|\- tag = __utils__[\(dqstate.gen_tag\(dq](chunk) if tag in running: # Already ran the pkg state, skip aggregation continue if chunk.get(\(dqstate\(dq) == \(dqpkg\(dq: if \(dq__agg__\(dq in chunk: continue # Check for the same function if chunk.get(\(dqfun\(dq) != low.get(\(dqfun\(dq): continue # Pull out the pkg names! if \(dqpkgs\(dq in chunk: pkgs.extend(chunk[\(dqpkgs\(dq]) chunk[\(dq__agg__\(dq] = True elif \(dqname\(dq in chunk: pkgs.append(chunk[\(dqname\(dq]) chunk[\(dq__agg__\(dq] = True if pkgs: if \(dqpkgs\(dq in low: low[\(dqpkgs\(dq].extend(pkgs) else: low[\(dqpkgs\(dq] = 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 \fI\%here\fP\&. .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 .sp The backup_mode can be set to any of the following options: .INDENT 0.0 .IP \(bu 2 \fBminion\fP: backup to the minion. .IP \(bu 2 \fBmaster\fP: backup to the master, a planned mode that has not yet been implemented, so does nothing. .IP \(bu 2 \fBboth\fP: backup to both. a combination of both master and minion. .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 \fI\%file.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 \fI\%file.restore_backup\fP, just pass the path and the numeric id found with \fI\%file.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 \fI\%file.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 \fI\%file.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 \(dqHigh Data\(dq structure is then compiled down to \(dqLow Data\(dq. 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 { \(dqapache\(dq: { \(dqpkg\(dq: [ { \(dqname\(dq: \(dqhttpd\(dq }, \(dqinstalled\(dq, { \(dqorder\(dq: 10000 } ], \(dqservice\(dq: [ { \(dqname\(dq: \(dqhttpd\(dq }, { \(dqwatch\(dq: [ { \(dqfile\(dq: \(dqapache_conf\(dq }, { \(dqpkg\(dq: \(dqapache\(dq } ] }, \(dqrunning\(dq, { \(dqorder\(dq: 10001 } ], \(dq__sls__\(dq: \(dqblah\(dq, \(dq__env__\(dq: \(dqbase\(dq }, \(dqapache_conf\(dq: { \(dqfile\(dq: [ { \(dqname\(dq: \(dq/etc/httpd/conf.d/httpd.conf\(dq }, { \(dqsource\(dq: \(dqsalt://apache/httpd.conf\(dq }, \(dqmanaged\(dq, { \(dqorder\(dq: 10002 } ], \(dq__sls__\(dq: \(dqblah\(dq, \(dq__env__\(dq: \(dqbase\(dq } } .ft P .fi .UNINDENT .UNINDENT .sp The subsequent Low Data will look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ { \(dqname\(dq: \(dqhttpd\(dq, \(dqstate\(dq: \(dqpkg\(dq, \(dq__id__\(dq: \(dqapache\(dq, \(dqfun\(dq: \(dqinstalled\(dq, \(dq__env__\(dq: \(dqbase\(dq, \(dq__sls__\(dq: \(dqblah\(dq, \(dqorder\(dq: 10000 }, { \(dqname\(dq: \(dqhttpd\(dq, \(dqwatch\(dq: [ { \(dqfile\(dq: \(dqapache_conf\(dq }, { \(dqpkg\(dq: \(dqapache\(dq } ], \(dqstate\(dq: \(dqservice\(dq, \(dq__id__\(dq: \(dqapache\(dq, \(dqfun\(dq: \(dqrunning\(dq, \(dq__env__\(dq: \(dqbase\(dq, \(dq__sls__\(dq: \(dqblah\(dq, \(dqorder\(dq: 10001 }, { \(dqname\(dq: \(dq/etc/httpd/conf.d/httpd.conf\(dq, \(dqsource\(dq: \(dqsalt://apache/httpd.conf\(dq, \(dqstate\(dq: \(dqfile\(dq, \(dq__id__\(dq: \(dqapache_conf\(dq, \(dqfun\(dq: \(dqmanaged\(dq, \(dq__env__\(dq: \(dqbase\(dq, \(dq__sls__\(dq: \(dqblah\(dq, \(dqorder\(dq: 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 \(dqLow Data\(dq and \(dqHigh Data\(dq 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 \(dqLow Data\(dq 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 \(dqLow Data\(dq 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 \(dqin\(dq 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 \fI\%failhard\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 \fI\%here\fP\&. .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 \fI\%file_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 \fI\%state_top\fP\&. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%A detailed description of the top file\fP .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 \fI\%highstate\fP 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 \fI\%watch_in\fP or \fI\%require_in\fP syntax instead of extending another \fBSLS\fP file. .sp \fI\%State Requisites\fP .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 \fI\%installed\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 \(dqstandard\(dq 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 \fI\%managed\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: \(dqOf all smells, bread; of all tastes, salt.\(dq .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 <Include Declaration>: \- <Module Reference> \- <Module Reference> <Extend Declaration>: <ID Declaration>: [<overrides>] # standard declaration <ID Declaration>: <State Module>: \- <Function> \- <Function Arg> \- <Function Arg> \- <Function Arg> \- <Name>: <name> \- <Requisite Declaration>: \- <Requisite Reference> \- <Requisite Reference> # inline function and names <ID Declaration>: <State Module>.<Function>: \- <Function Arg> \- <Function Arg> \- <Function Arg> \- <Names>: \- <name> \- <name> \- <name> \- <Requisite Declaration>: \- <Requisite Reference> \- <Requisite Reference> # multiple states for single id <ID Declaration>: <State Module>: \- <Function> \- <Function Arg> \- <Name>: <name> \- <Requisite Declaration>: \- <Requisite Reference> <State Module>: \- <Function> \- <Function Arg> \- <Names>: \- <name> \- <name> \- <Requisite Declaration>: \- <Requisite Reference> .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 \(dqdev\(dq 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 \fI\%top.sls\fP and \fI\%Include declaration\fP 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 \fI\%highstate\fP 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 \(dqevaluated\(dq in order. To see what the low state looks like for a \fI\%highstate\fP, 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 \(dqHigh Data\(dq, 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 \(dqSLS files\(dq. This is because a single SLS was only constituted in a single file. Now the term \(dqSLS Formula\(dq 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 \fI\%state.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 \fI\%highstate\fP use \fI\%state.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 \fI\%here\fP\&. .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 deterministic 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 deterministic 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 deterministic 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 \fI\%Understanding State Compiler Ordering\fP\&. .SS Requisite Statements .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The behavior of requisites changed in version 0.9.7 of Salt. This documentation applies to requisites in version 0.9.7 and later. .UNINDENT .UNINDENT .sp Often when setting up states any single action will require or depend on another action. Salt allows for the building of relationships between states with requisite statements. A requisite statement ensures that the named state is evaluated before the state requiring it. There are three types of requisite statements in Salt, \fBrequire\fP, \fBwatch\fP, and \fBprereq\fP\&. .sp These requisite statements are applied to a specific state declaration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: [] file.managed: \- name: /etc/httpd/conf/httpd.conf \- source: salt://httpd/httpd.conf \- require: \- pkg: httpd .ft P .fi .UNINDENT .UNINDENT .sp In this example, the \fBrequire\fP requisite is used to declare that the file /etc/httpd/conf/httpd.conf should only be set up if the pkg state executes successfully. .sp The requisite system works by finding the states that are required and executing them before the state that requires them. Then the required states can be evaluated to see if they have executed correctly. .sp Require statements can refer to any state defined in Salt. The basic examples are \fIpkg\fP, \fIservice\fP, and \fIfile\fP, but any used state can be referenced. .sp In addition to state declarations such as pkg, file, etc., \fBsls\fP type requisites are also recognized, and essentially allow \(aqchaining\(aq of states. This provides a mechanism to ensure the proper sequence for complex state formulas, especially when the discrete states are split or groups into separate sls files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- network httpd: pkg.installed: [] service.running: \- require: \- pkg: httpd \- sls: network .ft P .fi .UNINDENT .UNINDENT .sp In this example, the httpd service running state will not be applied (i.e., the httpd service will not be started) unless both the httpd package is installed AND the network state is satisfied. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Requisite matching .sp Requisites match on both the ID Declaration and the \fBname\fP parameter. Therefore, if using the \fBpkgs\fP or \fBsources\fP argument to install a list of packages in a pkg state, it\(aqs important to note that it is impossible to match an individual package in the list, since all packages are installed as a single state. .UNINDENT .UNINDENT .SS Multiple Requisites .sp The requisite statement is passed as a list, allowing for the easy addition of more requisites. Both requisite types can also be separately declared: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: [] service.running: \- enable: True \- watch: \- file: /etc/httpd/conf/httpd.conf \- require: \- pkg: httpd \- user: httpd \- group: httpd file.managed: \- name: /etc/httpd/conf/httpd.conf \- source: salt://httpd/httpd.conf \- require: \- pkg: httpd user.present: [] group.present: [] .ft P .fi .UNINDENT .UNINDENT .sp In this example, the httpd service is only going to be started if the package, user, group, and file are executed successfully. .SS Requisite Documentation .sp For detailed information on each of the individual requisites, \fI\%please look here.\fP .SS The Order Option .sp Before using the \fIorder\fP option, remember that the majority of state ordering should be done with a \fI\%Requisite declaration\fP, 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 \fI\%service\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 \fI\%here\fP\&. .sp Also, keep in mind that this only works for states with an identically\-named virtual module (\fI\%pkg\fP, \fI\%service\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<state name>: <ID or name>\fP\&. The specific form is defined as a \fI\%Requisite Reference\fP\&. .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\%<requisite>_in\fP form that can be used to establish a \(dqreverse\(dq 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 Identifier matching .sp Requisites match on both the ID Declaration and the \fBname\fP parameter. This means that, in the \(dqDeploy server package\(dq 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 \(dqExtract server package\(dq 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 Wildcard matching in requisites .sp New in version 0.9.8. .sp Wildcard matching is supported for state identifiers. .INDENT 0.0 .IP \(bu 2 \fB*\fP matches zero or more characters .IP \(bu 2 \fB?\fP matches a single character .IP \(bu 2 \fB[]\fP matches a single character from the enclosed set .UNINDENT .sp Note that this does not follow glob rules \- dots and slashes are not special, and it is matching against state identifiers, not file paths. .sp In the example below, a change in any state managing an apache config file 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 .sp A leading or bare \fB*\fP must be quoted to avoid confusion with YAML references: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/letsencrypt/renewal\-hooks/deploy/install.sh: cmd.run: \- onchanges: \- acme: \(aq*\(aq .ft P .fi .UNINDENT .UNINDENT .SS Omitting state module .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 identifier 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_watch\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 There is no combined form of \fI\%_any\fP and \fI\%_in\fP requisites, such as \fBrequire_any_in\fP! .sp Lastly, onfail has one special \fBonfail_all\fP form to account for when \fBAND\fP logic is desired instead of the default \fBOR\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 \(dqresult\(dq 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\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 An \fBonchanges\fP requisite has no effect on SLS requisites (monitoring for changes in an included SLS). Only the individual state IDs from an included SLS can be monitored. .UNINDENT .UNINDENT .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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 A \fBwatch\fP requisite has no effect on SLS requisites (watching for changes in an included SLS). Only the individual state IDs from an included SLS can be watched. .UNINDENT .UNINDENT .sp A good example of using \fBwatch\fP is with a \fI\%service.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 \(dqchanges\(dq. Here are two examples of state return dictionaries, shown in json for clarity: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { \(dqlocal\(dq: { \(dqfile_|\-/tmp/foo_|\-/tmp/foo_|\-directory\(dq: { \(dqcomment\(dq: \(dqDirectory /tmp/foo updated\(dq, \(dq__run_num__\(dq: 0, \(dqchanges\(dq: { \(dquser\(dq: \(dqbar\(dq }, \(dqname\(dq: \(dq/tmp/foo\(dq, \(dqresult\(dq: true } } } .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { \(dqlocal\(dq: { \(dqpkgrepo_|\-salt\-minion_|\-salt\-minion_|\-managed\(dq: { \(dqcomment\(dq: \(dqPackage repo \(aqsalt\-minion\(aq already configured\(dq, \(dq__run_num__\(dq: 0, \(dqchanges\(dq: {}, \(dqname\(dq: \(dqsalt\-minion\(dq, \(dqresult\(dq: true } } } .ft P .fi .UNINDENT .UNINDENT .sp If the \(dqresult\(dq 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 \(dqresult\(dq of the watched state is \fBTrue\fP \fIand\fP the \(dqchanges\(dq 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 \(dqchanges\(dq key contains an empty dictionary, the \fBwatch\fP requisite acts exactly like the \fBrequire\fP requisite (the watching state will execute if \(dqresult\(dq is \fBTrue\fP, and fail if \(dqresult\(dq 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_watch\fP function of a state module. Rather than modifying execution order, the \fBmod_watch\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 \(dqchanges\(dq. (See the \fBwatch\fP section above for examples of \(dqchanges\(dq dictionaries.) .sp If the \(dqchanges\(dq 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 \(dqchanges\(dq 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: \(dqBuilding website fail on {{ salt.grains.get(\(aqid\(aq) }}\(dq .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: \(dqBoth primary and backup sites are down!\(dq \- 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 (\fI\%globally\fP or in \fI\%the failing state\fP) 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 \(dqafter the fact\(dq. .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_watch\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 \fBA\fP will run because at least one of the requirements specified, \fBB\fP or \fBC\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 \(dqresult\(dq 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 \fI\%Reloading Modules\fP\&. .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 .sp Changed in version 3006.0: Since the \fBunless\fP requisite utilizes \fBcmd.retcode\fP, certain parameters included in the state are passed along to \fBcmd.retcode\fP\&. On occasion this can cause issues, particularly if the \fBshell\fP option in a \fBuser.present\fP is set to /sbin/nologin and this shell is passed along to \fBcmd.retcode\fP\&. This would cause \fBcmd.retcode\fP to run the command using that shell which would fail regardless of the result of the command. .sp By including \fBshell\fP in \fBcmd_opts_exclude\fP, that parameter would not be passed along to the call to \fBcmd.retcode\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C jim_nologin: user.present: \- name: jim \- shell: /sbin/nologin \- unless: \- echo hello world \- cmd_opts_exclude: \- shell .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 .sp Changed in version 3006.0: Since the \fBonlyif\fP requisite utilizes \fBcmd.retcode\fP, certain parameters included in the state are passed along to \fBcmd.retcode\fP\&. On occasion this can cause issues, particularly if the \fBshell\fP option in a \fBuser.present\fP is set to /sbin/nologin and this shell is passed along to \fBcmd.retcode\fP\&. This would cause \fBcmd.retcode\fP to run the command using that shell which would fail regardless of the result of the command. .sp By including \fBshell\fP in \fBcmd_opts_exclude\fP, that parameter would not be passed along to the call to \fBcmd.retcode\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C jim_nologin: user.present: \- name: jim \- shell: /sbin/nologin \- onlyif: \- echo hello world \- cmd_opts_exclude: \- shell .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 \fI\%cmd\fP and \fI\%docker_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 command 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: \- \(dq! grep \(aqenabled=0\(aq /etc/yum.repos.d/fedora.repo\(dq .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 \(dqFalse\(dq, with the following comment: \(dqSpecified path /path/to/file does not exist\(dq Attempt 2: Returned a result of \(dqFalse\(dq, with the following comment: \(dqSpecified path /path/to/file does not exist\(dq Attempt 3: Returned a result of \(dqFalse\(dq, with the following comment: \(dqSpecified path /path/to/file does not exist\(dq Attempt 4: Returned a result of \(dqFalse\(dq, with the following comment: \(dqSpecified path /path/to/file does not exist\(dq Attempt 5: Returned a result of \(dqFalse\(dq, with the following comment: \(dqSpecified path /path/to/file does not exist\(dq Attempt 6: Returned a result of \(dqFalse\(dq, with the following comment: \(dqSpecified path /path/to/file does not exist\(dq Attempt 7: Returned a result of \(dqFalse\(dq, with the following comment: \(dqSpecified path /path/to/file does not exist\(dq Attempt 8: Returned a result of \(dqFalse\(dq, with the following comment: \(dqSpecified path /path/to/file does not exist\(dq Attempt 9: Returned a result of \(dqFalse\(dq, with the following comment: \(dqSpecified path /path/to/file does not exist\(dq Specified path /path/to/file does not exist Started: 09:08:12.903000 Duration: 47000.0 ms Changes: .ft P .fi .UNINDENT .UNINDENT .SS Run State With a Different Umask .sp New in version 3002: NOTE: not available on Windows .sp The \fBumask\fP state argument can be used to run a state with a different umask. Prior to version 3002 this was available to \fI\%cmd\fP states, but it is now a global state argument that can be applied to any state. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cleanup_script: cmd.script: \- name: salt://myapp/files/my_script.sh \- umask: \(dq077\(dq \- onchanges: \- file: /some/file .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 \fI\%highstate\fP Execute \fI\%state.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 \fI\%state.apply\fP to run the \fI\%highstate\fP 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 \(dqtop\(dq 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, \fI\%file_roots\fP . .sp In the most common single\-environment setup, only the \fBbase\fP environment is defined in \fI\%file_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 \fI\%file_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 \fI\%file_roots\fP\&. .sp The states that will be applied to a minion in a given environment can be viewed using the \fI\%state.show_top\fP function. .sp Minions may be pinned to a particular environment by setting the \fI\%environment\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 \fI\%compound matcher\fP, 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 \fI\%grain\fP, optionally using globbing (e.g. \fBkernel:Linux\fP or \fBkernel:*BSD\fP) T} _ T{ grain_pcre T} T{ Match a \fI\%grain\fP 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{ \fI\%Pillar\fP match, optionally using globbing (e.g. \fBrole:webserver\fP or \fBrole:web*\fP) T} _ T{ pillar_pcre T} T{ \fI\%Pillar\fP match using PCRE (e.g. \fBrole:web(server|proxy)\fP T} _ T{ pillar_exact T} T{ \fI\%Pillar\fP 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 \fI\%data\fP execution module) T} _ T{ range T} T{ \fI\%Range\fP cluster T} _ T{ compound T} T{ Complex expression combining multiple match types (see \fI\%here\fP) T} _ T{ nodegroup T} T{ Pre\-defined compound expressions in the master config file (see \fI\%here\fP) 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 \fI\%highstate\fP is executed and an environment is specified (either using the \fI\%environment\fP config option or by passing the saltenv when executing the \fI\%highstate\fP), 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 \fI\%highstate\fP 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 \fI\%GitFS\fP 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 \fI\%top_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 \fI\%state_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 \fI\%GitFS\fP, 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. \fI\%gitfs_saltenv_whitelist\fP and \fI\%gitfs_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 \fI\%GitFS\fP 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 \fI\%highstate\fP\&. .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 \fI\%state_top_saltenv\fP .IP \(bu 2 \fI\%top_file_merging_strategy\fP .IP \(bu 2 \fI\%env_order\fP .IP \(bu 2 \fI\%default_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 \fI\%highstate\fP 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 \fI\%highstate\fP, 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 \fI\%highstate\fP, and it would be applied to all minions. .sp If the \fBqa\fP environment were specified, the \fI\%highstate\fP would exit with an error. .SS Scenario 2 \- No Environment Specified, \fI\%top_file_merging_strategy\fP is \(dqmerge\(dq .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, \fI\%top_file_merging_strategy\fP is \(dqsame\(dq .sp Changed in version 2016.11.0: In prior versions, \(dqsame\(dq 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 \fI\%default_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 \fI\%default_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, \fI\%top_file_merging_strategy\fP is \(dqmerge_all\(dq .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 3005 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. .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 \(dq\(dq .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 \(dq.\(dq. This is usually identical to \fIslspath\fP except in case of root\-level sls, where this will return a \(dq\fI\&.\fP\(dq. .sp A Common use case for this variable is to generate relative salt urls like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-file: file.managed: source: salt://{{ tpldir }}/files/my\-template .ft P .fi .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 \(dq\(dq .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 \(dqname\(dq, unless a \(dqname\(dq argument is specified below file.managed: # maps to <filename>.<function> \- e.g. \(dqmanaged\(dq 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 \fI\%pkgrepo.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 = {\(dqname\(dq: name, \(dqresult\(dq: False, \(dqchanges\(dq: {}, \(dqcomment\(dq: \(dq\(dq} if foo and bar: ret[\(dqcomment\(dq] = \(dqOnly one of foo and bar is permitted\(dq 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 \fI\%execution module\fP\&. 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__[\(dqmodname.check\(dq](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[\(dqresult\(dq] = True ret[\(dqcomment\(dq] = \(dq{0} is already installed\(dq.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__[\(dqtest\(dq]: ret[\(dqresult\(dq] = None ret[\(dqcomment\(dq] = \(dq{0} would be installed\(dq.format(name) ret[\(dqchanges\(dq] = 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__[\(dqmodname.install\(dq](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[\(dqchanges\(dq] = __salt__[\(dqmodname.check\(dq](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[\(dqchanges\(dq]: ret[\(dqcomment\(dq] = \(dq{0} failed to install\(dq.format(name) else: ret[\(dqresult\(dq] = True ret[\(dqcomment\(dq] = \(dq{0} was installed\(dq.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 \fI\%saltutil.sync_states\fP or \fI\%saltutil.sync_all\fP\&. Alternatively, when running a \fI\%highstate\fP 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 \fI\%__virtual__ function\fP\&. .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 \fI\%cross calling execution modules\fP\&. .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__[\(dqfile.managed\(dq](name=\(dq/tmp/myfile\(dq, source=\(dqsalt://myfile\(dq) .ft P .fi .UNINDENT .UNINDENT .sp This code will call the \fImanaged\fP function in the \fI\%file\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 \(dqname\(dq. .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 \(dqold\(dq and \(dqnew\(dq containing the old/new values. For example, the pkg state\(aqs \fBchanges\fP dict has one key for each package changed, with the \(dqold\(dq and \(dqnew\(dq 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[\(dqchanges\(dq].update({\(dqmy_pkg_name\(dq: {\(dqold\(dq: \(dq\(dq, \(dqnew\(dq: \(dqmy_pkg_name\-1.0\(dq}}) .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 \(dqsub_state_run\(dq 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 \(dqsub_state_run\(dq 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 = { \(dqname\(dq: None, # The parent state name \(dqresult\(dq: None, # The overall status of the external state engine run \(dqcomment\(dq: None, # Comments on the overall external state engine run \(dqchanges\(dq: {}, # An empty dictionary, each sub state run has it\(aqs own changes to report \(dqsub_state_run\(dq: [ { \(dqchanges\(dq: {}, # A dictionary describing the changes made in the external state run \(dqresult\(dq: None, # The external state run name \(dqcomment\(dq: None, # Comment on the external state run \(dqduration\(dq: None, # Optional, the duration in seconds of the external state run \(dqstart_time\(dq: None, # Optional, the timestamp of the external state run\(aqs start time \(dqlow\(dq: { \(dqname\(dq: None, # The name of the state from the external state run \(dqstate\(dq: None, # Name of the external state run \(dq__id__\(dq: None, # ID of the external state run \(dqfun\(dq: 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__[\(dqtest\(dq]: ret[\(dqresult\(dq] = None ret[\(dqcomment\(dq] = \(dqState Foo will execute with param {0}\(dq.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): \(dq\(dq\(dq Refresh the package database here so that it only needs to happen once \(dq\(dq\(dq if low[\(dqfun\(dq] == \(dqinstalled\(dq or low[\(dqfun\(dq] == \(dqlatest\(dq: rtag = __gen_rtag() if not os.path.exists(rtag): open(rtag, \(dqw+\(dq).write(\(dq\(dq) 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(\(dqHere is Some Information\(dq) log.warning(\(dqYou Should Not Do That\(dq) log.error(\(dqIt Is Busted\(dq) .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 \(dqbefore\(dq and \(dqafter\(dq 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): \(dq\(dq\(dq 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 \(dq\(dq\(dq ret = { \(dqname\(dq: name, \(dqchanges\(dq: {}, \(dqresult\(dq: False, \(dqcomment\(dq: \(dq\(dq, } # Start with basic error\-checking. Do all the passed parameters make sense # and agree with each\-other? if bar == True and foo.startswith(\(dqFoo\(dq): raise salt.exceptions.SaltInvocationError( \(aqArgument \(dqfoo\(dq cannot start with \(dqFoo\(dq if argument \(dqbar\(dq is True.\(aq ) # Check the current state of the system. Does anything need to change? current_state = __salt__[\(dqmy_custom_module.current_state\(dq](name) if current_state == foo: ret[\(dqresult\(dq] = True ret[\(dqcomment\(dq] = \(dqSystem already in the correct state\(dq 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__[\(dqtest\(dq] == True: ret[\(dqcomment\(dq] = \(aqThe state of \(dq{0}\(dq will be changed.\(aq.format(name) ret[\(dqchanges\(dq] = { \(dqold\(dq: current_state, \(dqnew\(dq: \(dqDescription, diff, whatever of the new state\(dq, } # Return \(ga\(gaNone\(ga\(ga when running with \(ga\(gatest=true\(ga\(ga. ret[\(dqresult\(dq] = None return ret # Finally, make the actual change and return the result. new_state = __salt__[\(dqmy_custom_module.change_state\(dq](name, foo) ret[\(dqcomment\(dq] = \(aqThe state of \(dq{0}\(dq was changed!\(aq.format(name) ret[\(dqchanges\(dq] = { \(dqold\(dq: current_state, \(dqnew\(dq: new_state, } ret[\(dqresult\(dq] = 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 \fI\%remote execution\fP 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 \fI\%runners\fP\&. .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 \(dqmagic translation\(dq 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 \fI\%target expressions\fP 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 \fI\%compound\fP 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 \fI\%here\fP\&. .SS Reloading Modules .sp Some Salt states require that specific packages be installed in order for the module to load. As an example the \fI\%pip\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 \fI\%pip\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 \fI\%cmd\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 \fI\%States\fP, 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 \fI\%__context__\fP 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__[\(dqretcode\(dq] = 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 \fI\%__context__\fP 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 \fI\%__context__\fP 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 (\fI\%state modules\fP), \fI\%execution modules\fP, 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 \(dqutility modules\(dq. 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 \-*\- \(dq\(dq\(dq My utils module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- This module contains common functions for use in my other custom types. \(dq\(dq\(dq def bar(): return \(dqbaz\(dq .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 \-*\- \(dq\(dq\(dq My awesome execution module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \(dq\(dq\(dq def observe_the_awesomeness(): \(dq\(dq\(dq Prints information from my utility module CLI Example: .. code\-block:: bash salt \(aq*\(aq mymodule.observe_the_awesomeness \(dq\(dq\(dq return __utils__[\(dqfoo.bar\(dq]() .ft P .fi .UNINDENT .UNINDENT .sp Utility modules, like any other kind of Salt extension, support using a \fI\%__virtual__ function\fP 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 \-*\- \(dq\(dq\(dq My utils module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- This module contains common functions for use in my other custom types. \(dq\(dq\(dq def __virtual__(): \(dq\(dq\(dq Load as a different name \(dq\(dq\(dq return \(dqfoo\(dq def bar(): return \(dqbaz\(dq .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 \-*\- \(dq\(dq\(dq My OOP\-style utils module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- This module contains common functions for use in my other custom types. \(dq\(dq\(dq class Foo(object): def __init__(self): pass def bar(self): return \(dqbaz\(dq .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 \-*\- \(dq\(dq\(dq My awesome execution module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \(dq\(dq\(dq import mymodule def observe_the_awesomeness(): \(dq\(dq\(dq Prints information from my utility module CLI Example: .. code\-block:: bash salt \(aq*\(aq mymodule.observe_the_awesomeness \(dq\(dq\(dq 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 \fI\%outputter\fP/returner, as well as an execution module. .sp Utility modules placed in \fBsalt://_utils/\fP will be synced to the minions when a \fI\%highstate\fP is run, as well as when any of the following Salt functions are called: .INDENT 0.0 .IP \(bu 2 \fI\%saltutil.sync_utils\fP .IP \(bu 2 \fI\%saltutil.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 \fI\%state.apply\fP/\fI\%state.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 \fI\%saltutil.sync_utils\fP .IP \(bu 2 \fI\%saltutil.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/<MID>/start\fP or firing a custom event tag instead. .UNINDENT .UNINDENT .UNINDENT .SS Start events .INDENT 0.0 .TP .B salt/minion/<MID>/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 \fI\%Salt\-Cloud\fP) will not cause firing of these events. .UNINDENT .UNINDENT .SS Job events .INDENT 0.0 .TP .B salt/job/<JID>/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/<JID>/ret/<MID> 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/<JID>/prog/<MID>/<RUN NUM> Fired each time a each function in a state run completes execution. Can also be fired on individual state if the \fI\%fire_event\fP option is set on that state. .sp Can be enabled for all state runs in the Salt master config with the \fI\%state_events\fP option. To enable for an individual state run, pass \fBstate_events=True\fP to the \fI\%state\fP function being used. .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/<JID>/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/<JID>/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/<JID>/args New in version 2016.11.0. .sp Fired by the \fI\%state.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 \fI\%presence_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/<VM NAME>/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/<VM NAME>/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/<VM NAME>/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/<VM NAME>/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/<VM NAME>/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/<VM NAME>/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/<VM NAME>/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/<VM NAME>/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/<VM NAME>/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/<VM NAME>/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 \fI\%state.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 \fI\%salt.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 \(dq/var/run/salt/master\(dq 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(\(dq/etc/salt/master\(dq) event = salt.utils.event.get_event(\(dqmaster\(dq, sock_dir=opts[\(dqsock_dir\(dq], opts=opts) data = event.get_event() .ft P .fi .UNINDENT .UNINDENT .sp Events will also use a \(dqtag\(dq. 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 \(dqsalt/auth\(dq. .sp The \fBget_event\fP method has a default poll time assigned of 5 seconds. To change this time set the \(dqwait\(dq 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=\(dqsalt/auth\(dq) .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=\(dqsalt/job\(dq, full=True) tag, data = evdata[\(dqtag\(dq], evdata[\(dqdata\(dq] .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=\(dqsalt/auth\(dq): 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(\(dq/etc/salt/master\(dq) sevent = salt.utils.event.get_event(\(dqmaster\(dq, sock_dir=opts[\(dqsock_dir\(dq], opts=opts) while True: ret = sevent.get_event(full=True) if ret is None: continue if fnmatch.fnmatch(ret[\(dqtag\(dq], \(dqsalt/job/*/ret/*\(dq): do_something_with_job_return(ret[\(dqdata\(dq]) .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 \fI\%event.fire\fP execution function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call event.fire \(aq{\(dqdata\(dq: \(dqmessage to be sent in the event\(dq}\(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 \fI\%event.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: \(dqIt works!\(dq}\(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(\(dq/etc/salt/minion\(dq) event = salt.utils.event.MinionEvent(opts) for evdata in event.iter_events(match_type=\(dqregex\(dq, tag=\(dqcustom/.*\(dq): # 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=\(dqregex\(dq, tag=\(dqcustom/.*\(dq): # do your processing here... ... .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt minionname event.fire \(aq{\(dqdata\(dq: \(dqmessage for the minion\(dq}\(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(): \(dq\(dq\(dq Do something and fire an event to the master when finished CLI Example:: salt \(aq*\(aq my_custom_module:do_something \(dq\(dq\(dq # do something! __salt__[\(dqevent.send\(dq]( \(dqmyco/my_custom_module/finished\(dq, {\(dqfinished\(dq: True, \(dqmessage\(dq: \(dqThe something is finished!\(dq}, ) .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( \(dqevent.send\(dq, \(dqmyco/event/success\(dq, {\(dqsuccess\(dq: True, \(dqmessage\(dq: \(dqIt works!\(dq} ) 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 \fI\%reactor\fP\&. .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 \fI\%beacon modules\fP for a current list. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt beacons are an event generation mechanism. Beacons leverage the Salt \fI\%reactor\fP 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: mask: \- modify /opt: mask: \- modify .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_important_file: \- files: /etc/important_file: mask: \- modify \- beacon_module: inotify watch_another_file: \- files: /etc/another_file: mask: \- modify \- 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: mask: \- modify /opt: mask: \- modify \- 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: {} mask: \- modify \- 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 \fI\%inotify\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 { \(dq_stamp\(dq: \(dq2015\-09\-09T15:59:37.972753\(dq, \(dqdata\(dq: { \(dqchange\(dq: \(dqIN_IGNORED\(dq, \(dqid\(dq: \(dqlarry\(dq, \(dqpath\(dq: \(dq/etc/important_file\(dq }, \(dqtag\(dq: \(dqsalt/beacon/larry/inotify//etc/important_file\(dq } .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[\(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 \fI\%idempotent\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 \fI\%here\fP 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 \fI\%inotify\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 [{\(dqchanges\(dq: [\(dq/foo/bar\(dq], \(dqtag\(dq: \(dqfoo\(dq}, {\(dqchanges\(dq: [\(dq/foo/baz\(dq], \(dqtag\(dq: \(dqbar\(dq}] .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 \fI\%Modular Systems\fP\&. .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 \(dqreactor\(dq \- \(aqsalt/minion/*/start\(aq: # Match tag \(dqsalt/minion/*/start\(dq \- /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 \fI\%querystring syntax\fP (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 \fI\%state.apply\fP, which performs a \fI\%highstate\fP\&. 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 initiate 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 \fI\%remote\-execution function\fP on targeted minions T} _ T{ \fI\%runner\fP T} T{ Executes a \fI\%runner function\fP T} _ T{ \fI\%wheel\fP T} T{ Executes a \fI\%wheel function\fP on the master T} _ T{ \fI\%caller\fP T} T{ Runs a \fI\%remote\-execution function\fP 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 \fI\%fileserver_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 \fI\%remote\-execution function\fP 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 \fI\%LocalClient().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 \fI\%target type\fP 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 \fI\%runner functions\fP 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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 State ids of reactors for runners and wheels should all be unique. They can overwrite each other when added to the async queue causing lost reactions. .UNINDENT .UNINDENT .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{\(dqevent_tag\(dq: \(dqfoo\(dq, \(dqevent_data\(dq: {\(dqbar\(dq: \(dqbaz\(dq}}\(aq .ft P .fi .UNINDENT .UNINDENT .SS Wheel Reactions .sp Wheel reactions run \fI\%wheel functions\fP 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 \fI\%wheel function\fP (or in \fBarg\fP or \fBkwarg\fP parameters). .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 State ids of reactors for runners and wheels should all be unique. They can overwrite each other when added to the async queue causing lost reactions. .UNINDENT .UNINDENT .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 \fI\%remote\-execution functions\fP on a minion daemon\(aqs Reactor system. To run a Reactor on the minion, it is necessary to configure the \fI\%Reactor 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 \fI\%reactor\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 \fI\%requisites\fP\&. .sp Complex Jinja templating that calls out to slow \fI\%remote\-execution\fP or \fI\%runner\fP 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 \fI\%orchestration\fP jobs. .sp Therefore, when complex tasks are in order, \fI\%orchestration\fP 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 \fI\%remote\-execution\fP or \fI\%runner\fP 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 \fI\%requisites\fP, 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: {\(dqfoo\(dq: \(dqFoo!\(dq, \(dqbar: \(dqbar*\(dq, \(dqbaz\(dq: \(dqBaz!\(dq} 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 \fI\%beacon documentation\fP for examples. .SS Manually Firing an Event .SS From the Master .sp Use the \fI\%event.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 \fI\%event.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 \fI\%event.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 \fI\%state.event runner\fP\&. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Common Salt Events\fP .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 { \(dq_stamp\(dq: \(dq2015\-02\-13T00:19:05.724583\(dq, \(dqarg\(dq: [], \(dqfun\(dq: \(dqtest.ping\(dq, \(dqjid\(dq: \(dq20150213001905721678\(dq, \(dqminions\(dq: [ \(dqjerry\(dq ], \(dqtgt\(dq: \(dq*\(dq, \(dqtgt_type\(dq: \(dqglob\(dq, \(dquser\(dq: \(dqroot\(dq } salt/job/20150213001910749506/ret/jerry { \(dq_stamp\(dq: \(dq2015\-02\-13T00:19:11.136730\(dq, \(dqcmd\(dq: \(dq_return\(dq, \(dqfun\(dq: \(dqsaltutil.find_job\(dq, \(dqfun_args\(dq: [ \(dq20150213001905721678\(dq ], \(dqid\(dq: \(dqjerry\(dq, \(dqjid\(dq: \(dq20150213001910749506\(dq, \(dqretcode\(dq: 0, \(dqreturn\(dq: {}, \(dqsuccess\(dq: 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 \fI\%state.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 :\fI\%state.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 \fI\%Salt Mine\fP\&. If this state is invoked from the Reactor then the custom Pillar value from above will be available and the new minion will be added to the pool but with the \fBdisabled\fP flag so that HAProxy won\(aqt yet direct traffic to it. .sp \fB/srv/salt/haproxy/refresh_pool.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set new_minion = salt[\(aqpillar.get\(aq](\(aqnew_minion\(aq) %} listen web *:80 balance source {% for server,ip in salt[\(aqmine.get\(aq](\(aqweb*\(aq, \(aqnetwork.interfaces\(aq, [\(aqeth0\(aq]).items() %} {% if server == new_minion %} server {{ server }} {{ ip }}:80 disabled {% else %} server {{ server }} {{ ip }}:80 check {% endif %} {% endfor %} .ft P .fi .UNINDENT .UNINDENT .SS A Complete Example .sp In this example, we\(aqre going to assume that we have a group of servers that will come online at random and need to have keys automatically accepted. We\(aqll also add that we don\(aqt want all servers being automatically accepted. For this example, we\(aqll assume that all hosts that have an id that starts with \(aqink\(aq will be automatically accepted and have \fI\%state.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 attempt 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 \(dq{{ data[\(aqid\(aq] }}\(dq \(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 \fI\%highstate\fP 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 \fI\%salt.returners.smtp_return\fP documentation for that. .SS Syncing Custom Types on Minion Start .sp Salt will sync all custom types (by running a \fI\%saltutil.sync_all\fP) on every \fI\%highstate\fP\&. However, there is a chicken\-and\-egg issue where, on the initial \fI\%highstate\fP, 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 \fI\%highstate\fP 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 \fI\%Requisites and Other Global State Arguments\fP 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 \fI\%state.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 \fI\%salt.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 \(dqname\(dq 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 \(dqname\(dq 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 \(dqfail function\(dq allows for a more flexible means of assessing success or failure. .sp A fail function can be written as part of a \fI\%custom execution module\fP\&. 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 \fI\%salt.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 \fI\%salt.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{\(dqservers\(dq: \(dqnewsystem1\(dq, \(dqmaster\(dq: \(dqmymaster\(dq}\(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 \fI\%state return dictionary\fP\&. 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__[\(dqretcode\(dq] = 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 \fI\%Requisites and Other Global State Arguments\fP, can be used to easily configure complex orchestration tasks. Additionally, the states/functions will be executed in the order in which they are defined, unless prevented from doing so by any \fI\%Requisites and Other Global State Arguments\fP, 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 \(dqweb\(dq, 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 { \(dqoutputter\(dq: \(dqhighstate\(dq, \(dqdata\(dq: { \(dqfa5944a73aa8_master\(dq: { \(dqsalt_|\-good_state_|\-good_state_|\-state\(dq: { \(dqcomment\(dq: \(dqStates ran successfully. Updating myminion.\(dq, \(dqname\(dq: \(dqgood_state\(dq, \(dqstart_time\(dq: \(dq21:35:16.868345\(dq, \(dqresult\(dq: true, \(dqduration\(dq: 267.299, \(dq__run_num__\(dq: 0, \(dq__jid__\(dq: \(dq20171130213516897392\(dq, \(dq__sls__\(dq: \(dqtest\(dq, \(dqchanges\(dq: { \(dqret\(dq: { \(dqmyminion\(dq: { \(dqtest_|\-test succeed with changes_|\-test succeed with changes_|\-succeed_with_changes\(dq: { \(dqcomment\(dq: \(dqSuccess!\(dq, \(dqname\(dq: \(dqtest succeed with changes\(dq, \(dqstart_time\(dq: \(dq21:35:17.022592\(dq, \(dqresult\(dq: true, \(dqduration\(dq: 0.362, \(dq__run_num__\(dq: 0, \(dq__sls__\(dq: \(dqsucceed_with_changes\(dq, \(dqchanges\(dq: { \(dqtesting\(dq: { \(dqnew\(dq: \(dqSomething pretended to change\(dq, \(dqold\(dq: \(dqUnchanged\(dq } }, \(dq__id__\(dq: \(dqtest succeed with changes\(dq } } }, \(dqout\(dq: \(dqhighstate\(dq }, \(dq__id__\(dq: \(dqgood_state\(dq }, \(dqsalt_|\-bad_state_|\-bad_state_|\-state\(dq: { \(dqcomment\(dq: \(dqRun failed on minions: test\(dq, \(dqname\(dq: \(dqbad_state\(dq, \(dqstart_time\(dq: \(dq21:35:17.136511\(dq, \(dqresult\(dq: false, \(dqduration\(dq: 197.635, \(dq__run_num__\(dq: 1, \(dq__jid__\(dq: \(dq20171130213517202203\(dq, \(dq__sls__\(dq: \(dqtest\(dq, \(dqchanges\(dq: { \(dqret\(dq: { \(dqmyminion\(dq: { \(dqtest_|\-test fail with changes_|\-test fail with changes_|\-fail_with_changes\(dq: { \(dqcomment\(dq: \(dqFailure!\(dq, \(dqname\(dq: \(dqtest fail with changes\(dq, \(dqstart_time\(dq: \(dq21:35:17.326268\(dq, \(dqresult\(dq: false, \(dqduration\(dq: 0.509, \(dq__run_num__\(dq: 0, \(dq__sls__\(dq: \(dqfail_with_changes\(dq, \(dqchanges\(dq: { \(dqtesting\(dq: { \(dqnew\(dq: \(dqSomething pretended to change\(dq, \(dqold\(dq: \(dqUnchanged\(dq } }, \(dq__id__\(dq: \(dqtest fail with changes\(dq } } }, \(dqout\(dq: \(dqhighstate\(dq }, \(dq__id__\(dq: \(dqbad_state\(dq }, \(dqsalt_|\-mymod.myfunc_|\-mymod.myfunc_|\-function\(dq: { \(dqcomment\(dq: \(dqFunction ran successfully. Function mymod.myfunc ran on myminion.\(dq, \(dqname\(dq: \(dqmymod.myfunc\(dq, \(dqstart_time\(dq: \(dq21:35:17.334373\(dq, \(dqresult\(dq: true, \(dqduration\(dq: 151.716, \(dq__run_num__\(dq: 2, \(dq__jid__\(dq: \(dq20171130213517361706\(dq, \(dq__sls__\(dq: \(dqtest\(dq, \(dqchanges\(dq: { \(dqret\(dq: { \(dqmyminion\(dq: true }, \(dqout\(dq: \(dqhighstate\(dq }, \(dq__id__\(dq: \(dqmymod.myfunc\(dq }, \(dqsalt_|\-mymod.myfunc_false_result\-mymod.myfunc_false_result\-function\(dq: { \(dqcomment\(dq: \(dqRunning function mymod.myfunc_false_result failed on minions: myminion. Function mymod.myfunc_false_result ran on myminion.\(dq, \(dqname\(dq: \(dqmymod.myfunc_false_result\(dq, \(dqstart_time\(dq: \(dq21:35:17.486625\(dq, \(dqresult\(dq: false, \(dqduration\(dq: 174.241, \(dq__run_num__\(dq: 3, \(dq__jid__\(dq: \(dq20171130213517536270\(dq, \(dq__sls__\(dq: \(dqtest\(dq, \(dqchanges\(dq: { \(dqret\(dq: { \(dqmyminion\(dq: false }, \(dqout\(dq: \(dqhighstate\(dq }, \(dq__id__\(dq: \(dqmymod.myfunc_false_result\(dq } } }, \(dqretcode\(dq: 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 \fI\%state.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 dependent 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 \fI\%roster\fP 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 \fI\%SSH roster docs\fP for more details. .UNINDENT .UNINDENT .sp Simply create the roster file, the default location is \fI/etc/salt/roster\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C web1: 192.168.42.1 .ft P .fi .UNINDENT .UNINDENT .sp This is a very basic roster file where a Salt ID is being assigned to an IP address. A more elaborate roster can be created: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C web1: host: 192.168.42.1 # The IP addr or DNS hostname user: fred # Remote executions will be executed as user fred passwd: foobarbaz # The password to use for login, if omitted, keys are used sudo: True # Whether to sudo to root, not enabled by default web2: host: 192.168.42.2 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 sudo works only if NOPASSWD is set for user in /etc/sudoers: \fBfred ALL=(ALL) NOPASSWD: ALL\fP .UNINDENT .UNINDENT .SS 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\%Salt SSH reference\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 \(dqthin_dir\(dq setting in \fI\%Roster documentation\fP 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 \(dqPermission denied\(dq 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.saltproject.io/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 \fI\%roster modules\fP .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 <Salt ID>: # 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\-<hash>. 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. ssh_pre_flight_args: # The list of arguments to pass to the script # running on the minion with ssh_pre_flight. # Can be specified as single string. 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 ssh_pre_flight_args .sp Additional arguments to the script running on the minion with \fIssh_pre_flight\fP can be passed with specifying a list of arguments or a single string. In case of using single string distinct arguments will be passed to the script by splitting this string with the spaces. .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\-<hash>. 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 dependencies 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 dependencies 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 \fBdependencies\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 \fI\%ssh_pre_flight\fP .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 \fI\%SSH ext alternatives\fP .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 <srv>: <target>: \- <formula 1> \- <formula 2> \- <etc...> .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/<anything>/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 \fI\%Salt Cloud Configuration\fP\&. .IP \(bu 2 \fB/etc/salt/cloud.providers.d/*.conf\fP: Contains settings that configure a specific cloud host, such as credentials, region settings, and so on. Since configuration varies significantly between each cloud host, a separate file should be created for each cloud host. In Salt Cloud, a provider is synonymous with a cloud host (Amazon EC2, Google Compute Engine, Rackspace, and so on). See \fI\%Provider Specifics\fP\&. .IP \(bu 2 \fB/etc/salt/cloud.profiles.d/*.conf\fP: Contains settings that define a specific VM type. A profile defines the systems specs and image, and any other settings that are specific to this VM type. Each specific VM type is called a profile, and multiple profiles can be defined in a profile file. Each profile references a parent provider that defines the cloud host in which the VM is created (the provider settings are in the provider configuration explained above). Based on your needs, you might define different profiles for web servers, database servers, and so on. See \fI\%VM Profiles\fP\&. .UNINDENT .SS Configuration Inheritance .sp Configuration settings are inherited in order from the cloud config => providers => profile. [image] .sp For example, if you wanted to use the same image for all virtual machines for a specific provider, the image name could be placed in the provider file. This value is inherited by all profiles that use that provider, but is overridden if a image name is defined in the profile. .sp Most configuration settings can be defined in any file, the main difference being how that setting is inherited. .SS QuickStart .sp The \fI\%Salt Cloud Quickstart\fP 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 <FUNC\-NAME> <PROVIDER>, \-\-function=<FUNC\-NAME> <PROVIDER> 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 \(dqlinode\(dq, or pass \(dqall\(dq 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 \(dqlinode\(dq, or pass \(dqall\(dq 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 \(dqAWS\(dq, or pass \(dqall\(dq to list sizes for all configured cloud providers .UNINDENT .SS Cloud Credentials .INDENT 0.0 .TP .B \-\-set\-password=<USERNAME> <PROVIDER> Configure password for a cloud provider and save it to the keyring. PROVIDER can be specified with or without a driver, for example: \(dq\-\-set\-password bob rackspace\(dq or more specific \(dq\-\-set\-password bob rackspace:openstack\(dq 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 \fI\%many others\fP\&. .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 \fI\%Provider\fP and \fI\%Profile\fP 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 <profile> 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: <the local master ip address> 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: <the local master ip address> 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{\(dqcentos7\(dq: [{\(dqsaltmaster\(dq: {\(dqminion\(dq: \e {\(dqtransport\(dq: \(dqtcp\(dq}, \(dqmake_master\(dq: true, \(dqmaster\(dq: {\(dqtransport\(dq: \e \(dqtcp\(dq}}}, {\(dqminion001\(dq: {\(dqminion\(dq: {\(dqtransport\(dq: \(dqtcp\(dq}}}]}\(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 \(dqreboot\(dq 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 \fI\%Salt Cloud Feature Matrix\fP\&. .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 \fI\%Salt Cloud Feature Matrix\fP\&. .SS Core Configuration .SS Install Salt Cloud .sp Salt Cloud is now part of Salt proper. It was merged in as of \fI\%Salt version 2014.1.0\fP\&. .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: \fI\%Installing Salt for development\fP\&. .SS Core Configuration .sp A number of core configuration options and some options that are global to the VM profiles can be set in the cloud configuration file. By default this file is located at \fB/etc/salt/cloud\fP\&. .SS 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 \fI\%Configuring the Salt Minion\fP 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 \fI\%here\fP\&. .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<provider\-alias>: <provider\-name>\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 \(dqMy Credentials\(dq link. .sp If you do not have \fBAPI token\fP you can create one by clicking the \(dqCreate New Token\(dq 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: asldkgfaklsdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf password: F00barbazlonglongp@ssword 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 \(dqMy Account\(dq 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 <https://docs.openstack.org/shade/latest/>\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 <https://docs.openstack.org/os\-client\-config/latest/>\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 <https://docs.openstack.org/os\-client\-config/latest/user/vendor\-support.html>\fP options. .sp For more information, look at \fI\%Openstack 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 \(dqMy Settings\(dq 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 \fI\%Getting Started with Saltify\fP 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 \fI\%Getting Started With Vagrant\fP\&. .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 [ { \(dqdeploy\(dq: False, \(dqimage\(dq: \(dqami\-08d97e61\(dq, \(dqprofile\(dq: \(dqFedora\-17\(dq, \(dqprovider\(dq: \(dqmy\-ec2\-config\(dq, \(dqsecuritygroup\(dq: [\(dqdefault\(dq], \(dqsize\(dq: \(dqt1.micro\(dq, \(dqssh_username\(dq: \(dqec2_user\(dq, }, { \(dqdeploy\(dq: False, \(dqimage\(dq: \(dqami\-09b61d60\(dq, \(dqprofile\(dq: \(dqCentOS\-5\(dq, \(dqprovider\(dq: \(dqmy\-aws\-config\(dq, \(dqsecuritygroup\(dq: [\(dqdefault\(dq], \(dqsize\(dq: \(dqt1.micro\(dq, \(dqssh_username\(dq: \(dqec2_user\(dq, }, { \(dqdeploy\(dq: False, \(dqimage\(dq: \(dqami\-54cf5c3d\(dq, \(dqprofile\(dq: \(dqAmazon\-Linux\-AMI\-2012.09\-64bit\(dq, \(dqprovider\(dq: \(dqmy\-ec2\-config\(dq, \(dqsecuritygroup\(dq: [\(dqdefault\(dq], \(dqsize\(dq: \(dqt1.micro\(dq, \(dqssh_username\(dq: \(dqec2_user\(dq, }, { \(dqdeploy\(dq: False, \(dqprofile\(dq: \(dqdevelopment\-instances\(dq, \(dqprovider\(dq: \(dqmy\-ec2\-config\(dq, \(dqsecuritygroup\(dq: [\(dqdefault\(dq], \(dqsize\(dq: \(dqt1.micro\(dq, \(dqssh_username\(dq: \(dqec2_user\(dq, }, ] .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 { \(dqproviders\(dq: { \(dqmy\-develop\-envs\(dq: [ { \(dqavailability_zone\(dq: \(dqap\-southeast\-1b\(dq, \(dqid\(dq: \(dqHJGRYCILJLKJYG\(dq, \(dqkey\(dq: \(dqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(dq, \(dqkeyname\(dq: \(dqtest\(dq, \(dqlocation\(dq: \(dqap\-southeast\-1\(dq, \(dqprivate_key\(dq: \(dq/root/test.pem\(dq, \(dqdriver\(dq: \(dqaws\(dq, \(dqsecuritygroup\(dq: \(dqquick\-start\(dq, }, { \(dqlocation\(dq: \(dqRaleigh\(dq, \(dqpassword\(dq: \(dqmypass\(dq, \(dqdriver\(dq: \(dqibmsce\(dq, \(dqssh_key_file\(dq: \(dq/etc/salt/ibm/mykey.pem\(dq, \(dqssh_key_name\(dq: \(dqmykey\(dq, \(dquser\(dq: \(dqmyuser@mycorp.com\(dq, }, ], \(dqmy\-productions\-envs\(dq: [ { \(dqavailability_zone\(dq: \(dqus\-east\-1\(dq, \(dqlocation\(dq: \(dqus\-east\-1\(dq, \(dqpassword\(dq: \(dqmypass\(dq, \(dqdriver\(dq: \(dqibmsce\(dq, \(dqssh_key_file\(dq: \(dq/etc/salt/ibm/mykey.pem\(dq, \(dqssh_key_name\(dq: \(dqmykey\(dq, \(dquser\(dq: \(dqmy\-production\-user@mycorp.com\(dq, } ], } } .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 Dependencies .sp Salt Cloud needs the following packages: .INDENT 0.0 .IP \(bu 2 \fI\%pypsexec\fP\&. .IP \(bu 2 \fI\%smbprotocol\fP\&. .UNINDENT .sp For versions of Salt prior to 3006, Salt Cloud has a dependency on the \fBimpacket\fP library to set up the Windows Salt Minion installer: .INDENT 0.0 .IP \(bu 2 \fI\%impacket\fP\&. .UNINDENT .SS Requirements .sp A copy of the Salt Minion Windows installer must be present on the system on which Salt Cloud is running. See \fI\%Windows \- Salt install guide\fP for information about downloading and using the Salt Minion Windows installer. .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 <powershell> New\-NetFirewallRule \-Name \(dqSMB445\(dq \-DisplayName \(dqSMB445\(dq \-Protocol TCP \-LocalPort 445 Set\-Item (dir wsman:\elocalhost\eListener\e*\ePort \-Recurse).pspath 445 \-Force Restart\-Service winrm </powershell> .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 \fI\%renderer\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 \fI\%userdata_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 \fI\%userdata_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 <powershell> New\-NetFirewallRule \-Name \(dqSMB445\(dq \-DisplayName \(dqSMB445\(dq \-Protocol TCP \-LocalPort 445 New\-NetFirewallRule \-Name \(dqWINRM5986\(dq \-DisplayName \(dqWINRM5986\(dq \-Protocol TCP \-LocalPort 5986 winrm quickconfig \-q winrm set winrm/config/winrs \(aq@{MaxMemoryPerShellMB=\(dq300\(dq}\(aq winrm set winrm/config \(aq@{MaxTimeoutms=\(dq1800000\(dq}\(aq winrm set winrm/config/service/auth \(aq@{Basic=\(dqtrue\(dq}\(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\(dq($cert.Thumbprint)\(ga\(dq\(ga} Restart\-Service winrm </powershell> .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 \(dqUser Center\(dq section, under \(dqMy Service\(dq 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 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 \(dqApps & API\(dq section. The SSH key name can be found under the \(dqSSH Keys\(dq 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 vpc_name: Optional 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 \fI\%userdata_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 \fI\%userdata_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 <provider> 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 \(dqstatic\(dq and \(dqpermanent\(dq 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: {\(dqEnvironment\(dq: \(dqproduction\(dq} } # 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/my_bootstrap.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 \fI\%renderer\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 \fI\%userdata_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 \fI\%userdata_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<AWS account ID>\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.<region>.<service_url> .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 \(dqMy Account\(dq 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: \(dqyour\-project\-id\(dq service_account_email_address: \(dq123\-a5gt@developer.gserviceaccount.com\(dq service_account_private_key: \(dq/path/to/your/NEW.pem\(dq # 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 \(dqProject ID\(dq 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 labels: \(aq{\(dqname\(dq: \(dqmyinstance\(dq}\(aq tags: \(aq[\(dqone\(dq, \(dqtwo\(dq, \(dqthree\(dq]\(aq metadata: \(aq{\(dqone\(dq: \(dq1\(dq, \(dq2\(dq: \(dqtwo\(dq}\(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 labels: \(aq{\(dqname\(dq: \(dqmyinstance\(dq}\(aq tags: \(aq[\(dqone\(dq, \(dqtwo\(dq, \(dqthree\(dq]\(aq metadata: \(aq{\(dqone\(dq: \(dq1\(dq, \(dq2\(dq: \(dqtwo\(dq}\(aq use_persistent_disk: True delete_boot_pd: False ssh_interface: public_ips external_ip: \(dqephemeral\(dq .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 labels .sp This setting allows you to set labels on your GCE instances. It should be a dictionary and must be parse\-able by the python ast.literal_eval() function to convert it to a python dictionary. .sp New in version 3006. .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 labels: \(aq{\(dqname\(dq: \(dqmyinstance\(dq}\(aq tags: \(aq[\(dqone\(dq, \(dqtwo\(dq, \(dqthree\(dq]\(aq metadata: \(aq{\(dqone\(dq: \(dq1\(dq, \(dq2\(dq: \(dqtwo\(dq, \(dqsshKeys\(dq: \(dq\(dq}\(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{\(dqone\(dq: \(dq1\(dq, \(dq2\(dq: \(dqtwo\(dq, \(dqsshKeys\(dq: \(dqgceuser:ssh\-rsa <Your SSH Public Key> gceuser@host\(dq}\(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 \(dqdown\(dq 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 \(dqProject/Region/Scope\(dq. 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@<floating ip> .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: \(dq\-\-redacted\-\-\(dq .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: \(dq\-\-redacted\-\-\(dq # 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 \fI\%salt.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 \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 apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr... password: F00barbazverylongp@ssword .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/ubuntu22.04\fP); official images start with \fBlinode/\fP\&. .TP .B \fBlocation\fP \fB(Required)\fP The location of the VM. This should be a Linode region (e.g. \fBus\-east\fP). See \fI\%the list of locations\fP and \fI\%the guide to choose a location\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). See \fI\%the list of sizes\fP and \fI\%the guide to choose a size\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 \fB(optional)\fP Whether or not to assign a private IP to the VM. Defaults to \fBFalse\fP\&. .TP .B \fBbackups_enabled\fP \fB(optional)\fP Whether or not to enable the backup for this VM. Backup can be configured in your Linode account Defaults to \fBFalse\fP\&. .TP .B \fBcloneform\fP \fB(optional)\fP The name of the Linode to clone from. .TP .B \fBssh_interface\fP New in version 2016.3.0. .sp \fB(optional)\fP 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 \fB(optional)\fP The public key to authorize for SSH with the VM. .TP .B \fBswap\fP \fB(optional)\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 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\-linode\-profile: provider: my\-linode\-provider size: g6\-standard\-1 image: linode/ubuntu22.04 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\-1 image: linode/ubuntu22.04 location: us\-central password: iamaverylongp@ssword assign_private_ip: true ssh_interface: private_ips ssh_pubkey: ssh\-rsa AAAAB3NzaC1yc2EAAAADAQAB... swap_size: 512 .ft P .fi .UNINDENT .UNINDENT .SS Migrating to APIv4 .sp Linode APIv3 has been removed, and APIv4 is the only available version. .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 removed.\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 are no longer supported. * \fBdatacenter_id\fP has been removed and replaced by \fBlocation\fP\&. * \fBplan_id\fP has been removed and replaced by \fBsize\fP\&. .sp \fBThe \(ga\(gaget_plan_id\(ga\(ga function has been removed and is not supported by APIv4.\fP IDs are now the only way of referring to a \(dqplan\(dq (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/ubuntu22.04: \-\-\-\-\-\-\-\-\-\- created: 2019\-06\-20T17:17:11 created_by: linode deprecated: False description: None eol: 2021\-05\-01T04:00:00 expiry: None id: linode/ubuntu22.04 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 \fI\%lxc runner\fP .IP \(bu 2 \fI\%lxc module\fP .IP \(bu 2 \fI\%seed\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 \fI\%lxc.init\fP via the \fI\%lxc.cloud_init_interface\fP and seeds the minion via \fI\%seed.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 \fI\%LXC Management with Salt\fP before anything else. And specially \fI\%Profiles\fP\&. .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 \fI\%Container Profiles\fP\&. .TP .B network_profile Name of the profile or inline options for the LXC vm network settings, please see \fI\%Network Profiles\fP\&. .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 \fI\%Minion Configuration in Salt Cloud\fP) .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=\(dq\-c {0}\(dq .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: <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 \fI\%here\fP\&. .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 \(dqoneadmin\(dq 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 \(dqhosts\(dq, 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 \fI\%OpenNebula 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 \fI\%salt.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: <instance_name> # 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: <value from PARALLELS.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 \(dqData Center Designer\(dq (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=\(dqmy description\(dq .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 \(dqData Center Designer\(dq. .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 \(dqroot\(dq or \(dqAdministrator\(dq 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: <protocol> (TCP, UDP, ICMP) source_mac: <source\-mac> source_ip: <source\-ip> target_ip: <target\-ip> port_range_start: <port\-range\-start> port_range_end: <port\-range\-end> icmp_type: <icmp\-type> icmp_code: <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: <protocol> (TCP, UDP, ICMP) source_mac: <source\-mac> source_ip: <source\-ip> target_ip: <target\-ip> port_range_start: <port\-range\-start> port_range_end: <port\-range\-end> icmp_type: <icmp\-type> icmp_code: <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 \fI\%here\fP\&. .SS Getting Started With Proxmox .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This cloud provider will be removed from Salt in version 3009.0 in favor of the \fI\%saltext.proxmox Salt Extension\fP .UNINDENT .UNINDENT .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: <instance_name> # 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: <value from PROXMOX.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: <location>:<size>, format=<qcow2/vmdk/raw>, size=<size>GB #Example: local:120,format=qcow2,size=120GB #CD/DVD Drive ide2: <content_location>,media=cdrom #Example: local:iso/name.iso,media=cdrom # Network Device net0:<model>,bridge=<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 # Enable the use of a Qemu agent on VM to retrieve the IP\-address from. agent_get_ip: True .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 \(dqMy Credentials\(dq link. .sp If you do not have API token you can create one by clicking the \(dqCreate New Token\(dq 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 \fI\%Saltify Module documentation\fP and the \fI\%Miscellaneous Salt Cloud Options\fP 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 \(dqSalted\(dq 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 \(dq/etc/salt\(dq 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 \(dqforce_minion_config\(dq option to replace them. \- shutdown_on_destroy: false # default: false # last of all, send a \(dqshutdown\(dq 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 \(dqmagic packet\(dq 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 \(dqSalted\(dq 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 \(dqSalted\(dq 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 \(dqvagrant up\(dq command # vagrant_provider: \(aq\(aq # option for \(dqvagrant up\(dq like: \(dq\-\-provider vmware_fusion\(dq # ssh_host: None # \(dqNone\(dq means try to find the routable IP address from \(dqifconfig\(dq # 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 \(dqtrue\(dq 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 \(dqbevymaster\(dq .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 \(dqmy_laptop\(dq .IP \(bu 2 VirtualBox has been installed on \(dqmy_laptop\(dq (apt install is okay) .IP \(bu 2 Vagrant was installed from vagrantup.com. (not the 16.04 Ubuntu apt) .IP \(bu 2 \(dqmy_laptop\(dq has done \(dqvagrant plugin install vagrant\-vbguest\(dq .IP \(bu 2 the VM you want to start is on \(dqmy_laptop\(dq at \(dq/home/my_username/Vagrantfile\(dq .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # file /etc/salt/minion.d/vagrant_sdb.conf on host computer \(dqmy_laptop\(dq # \-\- 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 \(dqmy_laptop\(dq BEVY = \(dqbevy1\(dq DOMAIN = BEVY + \(dq.test\(dq # .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?(\(dq127.\(dq) return info.name end end return \(dqeth0\(dq # 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 \(dqpublic_network\(dq, bridge: interface_guesses if ARGV[0] == \(dqup\(dq puts \(dqTrying bridge network using interfaces: #{interface_guesses}\(dq end config.vm.provision \(dqshell\(dq, inline: \(dqip address\(dq, run: \(dqalways\(dq # make user feel good # . . . . . . . . . . . . Define machine QUAIL1 . . . . . . . . . . . . . . config.vm.define \(dqquail1\(dq, primary: true do |quail_config| quail_config.vm.box = \(dqboxesio/xenial64\-standard\(dq # a public VMware & Virtualbox box quail_config.vm.hostname = \(dqquail1.\(dq + DOMAIN # supply a name in our bevy quail_config.vm.provider \(dqvirtualbox\(dq 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 [\(dqmodifyvm\(dq, :id, \(dq\-\-natnet1\(dq, \(dq192.168.128.0/24\(dq] # 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 \(dqmy_laptop\(dq cwd: \(aq/home/my_username\(aq # the path (on \(dqmy_laptop\(dq) 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 \(dqv1\(dq (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 \(dqCloudConsole\(dq and then click on \(dqAPI Credentials\(dq. .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@g.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 vcenter03\-do\-not\-verify: driver: vmware user: \(aqDOMAIN\euser\(aq password: \(aqverybadpass\(aq url: \(aqvcenter01.domain.com\(aq protocol: \(aqhttps\(aq port: 443 verify_ssl: False 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: \(dq[nap004\-1] vmimages/tools\-isoimages/linux.iso\(dq 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 verify_ssl: False .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: \(dq[datastoreName] vmimages/tools\-isoimages/linux.iso\(dq\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 \fBcpu_hot_add\fP Boolean value that enables hot\-add support for adding CPU resources while the guest is powered on. .TP .B \fBcpu_hot_remove\fP Boolean value that enables hot\-remove support for removing CPU resources while the guest is powered on. .TP .B \fBmem_hot_add\fP Boolean value that enables hot\-add support for adding memory resources while the guest is powered on. .TP .B \fBnested_hv\fP Boolean value that enables support for nested hardware\-assisted virtualization. .TP .B \fBvpmc\fP Boolean value that enables virtual CPU performance counters. .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 \(dqadministrator\(dq 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 \(dqWindows User\(dq 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 .TP .B \fBverify_ssl\fP Verify the vmware ssl certificate. The default is True. .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 Instant Cloning a VM .sp Instant Cloning a powered\-ON VM is the easiest and the preferred way to work with VMs from controlled point in time using the VMware driver. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Instant Cloning operations are unsupported on standalone ESXi hosts, a vCenter server will be required. .UNINDENT .UNINDENT .sp Example of a minimal profile when skipping optional parameters: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-minimal\-clone: provider: vcenter01 clonefrom: \(aqtest\-vm\(aq instant_clone: true .ft P .fi .UNINDENT .UNINDENT .sp When Instant cloning a VM, all the profile configuration parameters are optional and the configuration gets inherited from the clone. .sp Example to specify optional parameters : .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-minimal\-clone: provider: vcenter01 clonefrom: \(aqtest\-vm\(aq instant_clone: true datastore: \(aqlocal\-0 (1)\(aq datacenter: \(aqvAPISdkDatacenter\(aq resourcepool: \(aqRP1\(aq .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 plugins such as execution, grains, and state modules which can be synchronised to minions to extend Salt with further functionality. .sp This option will inform Salt Cloud to synchronise your custom modules 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 all beacons clouds engines executors grains log matchers modules output pillar proxymodules renderers returners sdb serializers states thorium utils .ft P .fi .UNINDENT .UNINDENT .sp A present and non\-falsy value that doesn\(aqt match one of these list items will assume \fIall\fP, so \fIsync_after_install: True\fP and \fIsync_after_install: all\fP are equivalent (though the former will produce a warning). .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, \fI\%syndics\fP 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 \fI\%Salt Syndic\fP 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<SALT_CACHEDIR>/cloud/active/<DRIVER>/<PROVIDER>/<NODE_NAME>.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 \fI\%here\fP\&. .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\&. .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/<vm name>/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/<vm name>/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/<vm name>/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/<vm name>/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, \(dqtemplates\(dq). 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. .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/<vm name>/destroying\fP\&. Once the virtual machine has been destroyed, another event is fired. The tag for that event is \fBsalt/cloud/<vm name>/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): \(dq\(dq\(dq Return a list of the VMs that are on the provider, with select fields \(dq\(dq\(dq return salt.utils.cloud.list_nodes_select( list_nodes_full(\(dqfunction\(dq), __opts__[\(dqquery.selection\(dq], 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): \(dq\(dq\(dq Return a list of the VMs that are on the provider, with select fields \(dq\(dq\(dq if not conn: conn = get_conn() # pylint: disable=E0602 return salt.utils.cloud.list_nodes_select( list_nodes_full(conn, \(dqfunction\(dq), __opts__[\(dqquery.selection\(dq], 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): \(dq\(dq\(dq Show the details from EC2 concerning an AMI \(dq\(dq\(dq if call != \(dqaction\(dq: raise SaltCloudSystemExit( \(dqThe show_instance action must be called with \-a or \-\-action.\(dq ) 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): \(dq\(dq\(dq Show the details from EC2 concerning an AMI \(dq\(dq\(dq if call != \(dqfunction\(dq: raise SaltCloudSystemExit( \(dqThe show_image action must be called with \-f or \-\-function.\(dq ) params = {\(dqImageId.1\(dq: kwargs[\(dqimage\(dq], \(dqAction\(dq: \(dqDescribeImages\(dq} 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 \(dqbootstrap\-salt\(dq 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 \(dqvm\(dq. .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 \(dqminion\(dq 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 \fI\%state.apply\fP, which would finish provisioning the VM. Another common option (for testing) is to use \fI\%test.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 \fI\%Startup States\fP instead. .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.saltproject.io/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.saltproject.io/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.saltproject.io/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(\(dq/etc/salt/cloud\(dq) 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 \(dqLegacy\(dq. 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 \(dqthe old cloud\(dq 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<provider>.conf\fP, replacing \fB<provider>\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 \fI\%Provider specifics\fP 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 <provider_name> # my\-ec2 in the previous example salt\-cloud \-\-list\-images <provider_name> salt\-cloud \-\-list\-sizes <provider_name> .ft P .fi .UNINDENT .UNINDENT .sp Replace \fB<provider_name>\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<profile>.conf\fP, replacing \fB<profile>\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 <profile> <name1> <name2> ... .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 \fI\%Cloud Map File\fP\&. .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/<minion_id>/<task> .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 {\(dqname\(dq: \(dqweb1\(dq, \(dqprofile\(dq: \(dqec2\-centos\(dq, \(dqprovider\(dq: \(dqec2\-config:ec2\(dq} .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/<minion_id>/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/<minion_id>/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/<minion_id>/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/<minion_id>/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/<minion_id>/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/<minion_id>/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/<minion_id>/creating\fP .IP \(bu 2 \fBsalt/cloud/<minion_id>/requesting\fP .IP \(bu 2 \fBsalt/cloud/<minion_id>/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/<minion_id>/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: \(dqNew instance: {{ data[\(aqname\(aq] }}\(dq details: \(dqNew cloud instance created on {{ data[\(aqprovider\(aq] }}\(dq 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 \fI\%highstate\fP, 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 \fI\%highstate\fP 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 \fI\%highstate\fP 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 \fI\%highstate\fP 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 \fI\%highstate\fP 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 \fI\%proxy modules\fP 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 \fI\%Proxy Minion Walkthrough\fP for an end\-to\-end demonstration of a working REST\-based proxy minion. .sp See the \fI\%Proxy Minion SSH Walkthrough\fP for an end\-to\-end demonstration of a working SSH proxy minion. .sp See \fI\%Proxyminion States\fP 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 \fI\%Proxyminion Beacon\fP to help with easy configuration and management of \fBsalt\-proxy\fP processes. .SS New in 2017.7.0 .sp The \fI\%proxy_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 \fI\%proxy_keep_alive\fP is set to \fBTrue\fP\&. The polling interval is set using the \fI\%proxy_keep_alive_interval\fP option which defaults to 1 minute. .sp The developers are also able to use the \fI\%proxy_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__(): \(dq\(dq\(dq Only work on proxy \(dq\(dq\(dq try: if ( salt.utils.platform.is_proxy() and __opts__[\(dqproxy\(dq][\(dqproxytype\(dq] == \(dqssh_sample\(dq ): 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): \(dq\(dq\(dq Ask the remote device what IP it has \(dq\(dq\(dq return {\(dqip\(dq: proxy[\(dqproxymodulename.get_ip\(dq]()} .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 \fI\%Salt modules\fP specific to the controlled device. .IP 4. 3 \fI\%Salt states\fP 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 \(dqservice\(dq enumeration, starting, stopping, restarting, and status; \(dqpackage\(dq installation, and a ping. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # \-*\- coding: utf\-8 \-*\- \(dq\(dq\(dq 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 \(dq\(dq\(dq 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__ = [\(dqrest_sample\(dq] # 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__(): \(dq\(dq\(dq Only return if all the modules are available \(dq\(dq\(dq log.debug(\(dqrest_sample proxy __virtual__() called...\(dq) 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(\(dqrest_sample proxy init() called...\(dq) DETAILS[\(dqinitialized\(dq] = True # Save the REST URL DETAILS[\(dqurl\(dq] = opts[\(dqproxy\(dq][\(dqurl\(dq] # Make sure the REST URL ends with a \(aq/\(aq if not DETAILS[\(dqurl\(dq].endswith(\(dq/\(dq): DETAILS[\(dqurl\(dq] += \(dq/\(dq def alive(opts): \(dq\(dq\(dq 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. \(dq\(dq\(dq log.debug(\(dqrest_sample proxy alive() called...\(dq) return _complicated_function_that_determines_if_alive() def initialized(): \(dq\(dq\(dq 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 \(dq\(dq\(dq return DETAILS.get(\(dqinitialized\(dq, False) def grains(): \(dq\(dq\(dq Get the grains from the proxied device \(dq\(dq\(dq if not DETAILS.get(\(dqgrains_cache\(dq, {}): r = salt.utils.http.query( DETAILS[\(dqurl\(dq] + \(dqinfo\(dq, decode_type=\(dqjson\(dq, decode=True ) DETAILS[\(dqgrains_cache\(dq] = r[\(dqdict\(dq] return DETAILS[\(dqgrains_cache\(dq] def grains_refresh(): \(dq\(dq\(dq Refresh the grains from the proxied device \(dq\(dq\(dq DETAILS[\(dqgrains_cache\(dq] = None return grains() def fns(): return { \(dqdetails\(dq: \(dqThis key is here because a function in \(dq \(dqgrains/rest_sample.py called fns() here in the proxymodule.\(dq } def service_start(name): \(dq\(dq\(dq Start a \(dqservice\(dq on the REST server \(dq\(dq\(dq r = salt.utils.http.query( DETAILS[\(dqurl\(dq] + \(dqservice/start/\(dq + name, decode_type=\(dqjson\(dq, decode=True ) return r[\(dqdict\(dq] def service_stop(name): \(dq\(dq\(dq Stop a \(dqservice\(dq on the REST server \(dq\(dq\(dq r = salt.utils.http.query( DETAILS[\(dqurl\(dq] + \(dqservice/stop/\(dq + name, decode_type=\(dqjson\(dq, decode=True ) return r[\(dqdict\(dq] def service_restart(name): \(dq\(dq\(dq Restart a \(dqservice\(dq on the REST server \(dq\(dq\(dq r = salt.utils.http.query( DETAILS[\(dqurl\(dq] + \(dqservice/restart/\(dq + name, decode_type=\(dqjson\(dq, decode=True ) return r[\(dqdict\(dq] def service_list(): \(dq\(dq\(dq List \(dqservices\(dq on the REST server \(dq\(dq\(dq r = salt.utils.http.query( DETAILS[\(dqurl\(dq] + \(dqservice/list\(dq, decode_type=\(dqjson\(dq, decode=True ) return r[\(dqdict\(dq] def service_status(name): \(dq\(dq\(dq Check if a service is running on the REST server \(dq\(dq\(dq r = salt.utils.http.query( DETAILS[\(dqurl\(dq] + \(dqservice/status/\(dq + name, decode_type=\(dqjson\(dq, decode=True ) return r[\(dqdict\(dq] def package_list(): \(dq\(dq\(dq List \(dqpackages\(dq installed on the REST server \(dq\(dq\(dq r = salt.utils.http.query( DETAILS[\(dqurl\(dq] + \(dqpackage/list\(dq, decode_type=\(dqjson\(dq, decode=True ) return r[\(dqdict\(dq] def package_install(name, **kwargs): \(dq\(dq\(dq Install a \(dqpackage\(dq on the REST server \(dq\(dq\(dq cmd = DETAILS[\(dqurl\(dq] + \(dqpackage/install/\(dq + name if kwargs.get(\(dqversion\(dq, False): cmd += \(dq/\(dq + kwargs[\(dqversion\(dq] else: cmd += \(dq/1.0\(dq r = salt.utils.http.query(cmd, decode_type=\(dqjson\(dq, decode=True) return r[\(dqdict\(dq] def fix_outage(): r = salt.utils.http.query(DETAILS[\(dqurl\(dq] + \(dqfix_outage\(dq) return r def uptodate(name): \(dq\(dq\(dq Call the REST endpoint to see if the packages on the \(dqserver\(dq are up to date. \(dq\(dq\(dq r = salt.utils.http.query( DETAILS[\(dqurl\(dq] + \(dqpackage/remove/\(dq + name, decode_type=\(dqjson\(dq, decode=True ) return r[\(dqdict\(dq] def package_remove(name): \(dq\(dq\(dq Remove a \(dqpackage\(dq on the REST server \(dq\(dq\(dq r = salt.utils.http.query( DETAILS[\(dqurl\(dq] + \(dqpackage/remove/\(dq + name, decode_type=\(dqjson\(dq, decode=True ) return r[\(dqdict\(dq] def package_status(name): \(dq\(dq\(dq Check the installation status of a package on the REST server \(dq\(dq\(dq r = salt.utils.http.query( DETAILS[\(dqurl\(dq] + \(dqpackage/status/\(dq + name, decode_type=\(dqjson\(dq, decode=True ) return r[\(dqdict\(dq] def ping(): \(dq\(dq\(dq Is the REST server up? \(dq\(dq\(dq r = salt.utils.http.query(DETAILS[\(dqurl\(dq] + \(dqping\(dq, decode_type=\(dqjson\(dq, decode=True) try: return r[\(dqdict\(dq].get(\(dqret\(dq, False) except Exception: return False def shutdown(opts): \(dq\(dq\(dq For this proxy shutdown is a no\-op \(dq\(dq\(dq log.debug(\(dqrest_sample proxy shutdown() called...\(dq) .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 \-*\- \(dq\(dq\(dq Generate baseline proxy minion grains \(dq\(dq\(dq from __future__ import absolute_import import salt.utils.platform __proxyenabled__ = [\(dqrest_sample\(dq] __virtualname__ = \(dqrest_sample\(dq def __virtual__(): try: if ( salt.utils.platform.is_proxy() and __opts__[\(dqproxy\(dq][\(dqproxytype\(dq] == \(dqrest_sample\(dq ): 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 \(dqSalt Proxy Minion\(dq with two sections, one for \(dqservices\(dq and one for \(dqpackages\(dq 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://<IP your REST listens on>: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 \(dqinstall\(dq a package, use a standard \fBpkg.install\fP\&. If you pass \(aq==\(aq and a version 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 \(dqpackage\(dq installation. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # \-*\- coding: utf\-8 \-*\- \(dq\(dq\(dq 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. \(dq\(dq\(dq 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__ = [\(dqssh_sample\(dq] 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__(): \(dq\(dq\(dq Only return if all the modules are available \(dq\(dq\(dq log.info(\(dqssh_sample proxy __virtual__() called...\(dq) return True def init(opts): \(dq\(dq\(dq Required. Can be used to initialize the server connection. \(dq\(dq\(dq try: DETAILS[\(dqserver\(dq] = SSHConnection( host=__opts__[\(dqproxy\(dq][\(dqhost\(dq], username=__opts__[\(dqproxy\(dq][\(dqusername\(dq], password=__opts__[\(dqproxy\(dq][\(dqpassword\(dq], ) # connected to the SSH server out, err = DETAILS[\(dqserver\(dq].sendline(\(dqhelp\(dq) except TerminalException as e: log.error(e) return False def shutdown(opts): \(dq\(dq\(dq Disconnect \(dq\(dq\(dq DETAILS[\(dqserver\(dq].close_connection() def parse(out): \(dq\(dq\(dq Extract json from out. Parameter out: Type string. The data returned by the ssh command. \(dq\(dq\(dq jsonret = [] in_json = False for ln_ in out.split(\(dq\en\(dq): if \(dq{\(dq in ln_: in_json = True if in_json: jsonret.append(ln_) if \(dq}\(dq in ln_: in_json = False return salt.utils.json.loads(\(dq\en\(dq.join(jsonret)) def package_list(): \(dq\(dq\(dq List \(dqpackages\(dq 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 \(dq\(dq\(dq # Send the command to execute out, err = DETAILS[\(dqserver\(dq].sendline(\(dqpkg_list\(dq) # \(dqscrape\(dq the output and return the right fields as a dict return parse(out) def package_install(name, **kwargs): \(dq\(dq\(dq Install a \(dqpackage\(dq on the REST server \(dq\(dq\(dq cmd = \(dqpkg_install \(dq + name if \(dqversion\(dq in kwargs: cmd += \(dq/\(dq + kwargs[\(dqversion\(dq] else: cmd += \(dq/1.0\(dq # Send the command to execute out, err = DETAILS[\(dqserver\(dq].sendline(cmd) # \(dqscrape\(dq the output and return the right fields as a dict return parse(out) def package_remove(name): \(dq\(dq\(dq Remove a \(dqpackage\(dq on the REST server \(dq\(dq\(dq cmd = \(dqpkg_remove \(dq + name # Send the command to execute out, err = DETAILS[\(dqserver\(dq].sendline(cmd) # \(dqscrape\(dq 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 \(dqinstall\(dq a package, use a standard \fBpkg.install\fP\&. If you pass \(aq==\(aq and a version 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 \fI\%proxy minions\fP or using the \fI\%Salt SSH\fP\&. 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 \fI\%2016.11.0\fP\&. Network automation support is based on proxy minions. .INDENT 0.0 .IP \(bu 2 \fI\%NAPALM proxy\fP .IP \(bu 2 \fI\%Junos proxy\fP .IP \(bu 2 \fI\%Cisco NXOS\fP .IP \(bu 2 \fI\%Cisco NSO\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 \fI\%NAPALM grains\fP .IP \(bu 2 \fI\%NET execution module\fP \- Networking basic features .IP \(bu 2 \fI\%NTP execution module\fP .IP \(bu 2 \fI\%BGP execution module\fP .IP \(bu 2 \fI\%Routes execution module\fP .IP \(bu 2 \fI\%SNMP execution module\fP .IP \(bu 2 \fI\%Users execution module\fP .IP \(bu 2 \fI\%Probes execution module\fP .IP \(bu 2 \fI\%NTP peers management state\fP .IP \(bu 2 \fI\%SNMP configuration management state\fP .IP \(bu 2 \fI\%Users management state\fP .IP \(bu 2 \fI\%Netconfig 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 \fI\%Network ACL state\fP \- Manage the firewall configuration. It only requires writing the pillar structure correctly! .IP \(bu 2 \fI\%NAPALM 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 \fI\%NET 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 \fI\%BGP finder\fP \- Runner to search BGP neighbors details. .IP \(bu 2 \fI\%NAPALM 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 \fI\%pillar_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 \fI\%pillar_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 \fI\%BGP 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 \fI\%NET finder\fP, determine the devices containing the pattern \(dqPX\-1234\-LHR\(dq 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 \fI\%file_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 \fI\%Netconfig 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 \fI\%Junos proxy\fP .IP \(bu 2 \fI\%Junos execution module\fP .IP \(bu 2 \fI\%Junos state module\fP .IP \(bu 2 \fI\%Junos 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: <master_ip> .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: <hostip> 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: \fI\%Junos 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: \fI\%Junos 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 \fI\%Junos 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 <ip\-of\-the\-salt\-device> 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 \fI\%Cloud Controller Tutorial\fP .SS The Salt Virt Runner .sp The point of interaction with the cloud controller is the \fBvirt\fP runner. The \fBvirt\fP runner comes with routines to execute specific virtual machine routines. .sp Reference documentation for the virt runner is available with the runner module documentation: .sp \fI\%Virt 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 ONEDIR PACKAGING .SS Relenv onedir packaging .sp Starting in 3006, only onedir packaging will be available. The 3006 onedir packages are built with the \fI\%relenv\fP tool. .SS Docker Containers .sp The Salt Project uses docker containers to build our deb and rpm packages. If you are building your own packages you can use the same containers we build with in the Github piplines. These containers are documented \fI\%here\fP\&. .SS Package Grain .sp In the 3007.0 release a new package grain was added. This detects how Salt was installed using the \fI_pkg.txt\fP in the root of the Salt repo. By default this is set to \fBpip\fP, but it is set to \fBonedir\fP when \fBtools pkg build salt\-onedir\fP is run in our pipelines when building our onedir packages. If you are building your own custom packages, please ensure you set \fB_pkg.txt\fP contents to be the type of package you are creating. The options are \fBpip\fP, \fBonedir\fP or \fBsystem\fP\&. .SS How to build onedir only .INDENT 0.0 .IP 1. 3 Install relenv: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install relenv .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 2. 3 Fetch toolchain (Only required for linux OSs) .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C relenv toolchain fetch .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 3. 3 Fetch Native Python Build: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C relenv fetch \-\-python=<python\-version> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 4. 3 Create relenv environment: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C relenv create \-\-python=<python\-version> <relenv\-package\-path> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 5. 3 Add Salt into onedir. .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C <relenv\-package\-path>/bin/pip install /path/to/salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS How to build rpm packages .INDENT 0.0 .IP 1. 3 Ensure you are in the current Salt cloned git repo: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd <path\-to\-salt\-repo> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 2. 3 Install the dependencies: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yum \-y install python3 python3\-pip openssl git rpmdevtools rpmlint systemd\-units libxcrypt\-compat git gnupg2 jq createrepo rpm\-sign rustc cargo epel\-release yum \-y install patchelf pip install awscli .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install \-r requirements/static/ci/py{python_version}/tools.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 3. 3 (Optional) To build a specific Salt version, you will need to install tools and changelog dependencies: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install \-r requirements/static/ci/py{python_version}/changelog.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 4. 3 (Optional) To build a specific Salt version, run tools and set Salt version: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tools changelog update\-rpm <salt\-version> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 5. 3 Build the RPM: .INDENT 3.0 .INDENT 3.5 Only the arch argument is required, the rest are optional. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tools pkg build rpm \-\-relenv\-version <relenv\-version> \-\-python\-version <python\-version> \-\-arch <arch> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS How to build deb packages .INDENT 0.0 .IP 1. 3 Ensure you are in the current Salt cloned git repo.: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd <path\-to\-salt\-repo> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 2. 3 Install the dependencies: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apt install \-y apt\-utils gnupg jq awscli python3 python3\-venv python3\-pip build\-essential devscripts debhelper bash\-completion git patchelf rustc .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install \-r requirements/static/ci/py{python_version}/tools.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 3. 3 (Optional) To build a specific Salt version, you will need to install changelog dependencies: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install \-r requirements/static/ci/py{python_version}/changelog.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 4. 3 (Optional) To build a specific Salt version, run tools and set Salt version: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tools changelog update\-deb <salt\-version> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 5. 3 Build the deb package: .INDENT 3.0 .INDENT 3.5 Only the arch argument is required, the rest are optional. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tools pkg build deb \-\-relenv\-version <relenv\-version> \-\-python\-version <python\-version> \-\-arch <arch> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS How to build MacOS packages .INDENT 0.0 .IP 1. 3 Ensure you are in the current Salt cloned git repo.: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd <path\-to\-salt\-repo> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 2. 3 Install the dependencies: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install \-r requirements/static/ci/py{python_version}/tools.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 3. 3 Build the MacOS package: .INDENT 3.0 .INDENT 3.5 Only the salt\-version argument is required, the rest are optional. Do note that you will not be able to sign the packages when building them. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tools pkg build macos \-\-salt\-version <salt\-version> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS How to build Windows packages .INDENT 0.0 .IP 1. 3 Ensure you are in the current Salt cloned git repo.: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd <path\-to\-salt\-repo> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 2. 3 Install the dependencies: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install \-r requirements/static/ci/py{python_version}/tools.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 3. 3 Build the MacOS package: .INDENT 3.0 .INDENT 3.5 Only the arch and salt\-version arguments are required, the rest are optional. Do note that you will not be able to sign the packages when building them. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tools pkg build windows \-\-salt\-version <salt\-version> \-\-arch <arch> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS How to access python binary .sp The python library is available in the install directory of the onedir package. For example on linux the default location would be \fB/opt/saltstack/salt/bin/python3\fP\&. .SS Testing the packages .sp If you want to test your built packages, or any other collection of salt packages post 3006.0, follow \fI\%this guide\fP .SS Testing packages .SS The package test suite .sp The salt repo provides a test suite for testing basic functionality of our packages at \fB<repo\-root>/pkg/tests/\fP\&. You can run the install, upgrade, and downgrade tests. These tests run automatically on most PRs that are submitted against Salt. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 These tests make destructive changes to your system because they install the built packages onto the system. They may also install older versions in the case of upgrades or downgrades. To prevent destructive changes, run the tests in an isolated system, preferably a virtual machine. .UNINDENT .UNINDENT .SS Setup .sp In order to run the package tests, the \fI\%relenv\fP onedir and built packages need to be placed in the correct locations. .INDENT 0.0 .IP \(bu 2 Place all salt packages for the applicable testing version in \fB<repo\-root>/artifacts/pkg/\fP\&. .IP \(bu 2 The onedir must be located under \fB<repo\-root>/artifacts/\fP\&. .IP \(bu 2 Additionally, to ensure complete parity with Salt\(aqs CI/CD suite, place the \fBnox\fP virtual environment in \fB<repo\-root>/.nox/test\-pkgs\-onedir\fP\&. .UNINDENT .sp The following are a few ways this can be accomplished easily. .sp You can ensure parity by installing the package test suite through a few possible methods: .INDENT 0.0 .IP \(bu 2 Using \fBtools\fP .IP \(bu 2 Downloading individually .UNINDENT .SS Using \fBtools\fP .sp Salt has preliminary support for setting up the package test suite in the \fBtools\fP command suite that is located under \fB<repo\-root>/tools/testsuite/\fP\&. This method requires the Github CLI tool \fBgh\fP (\fI\%https://cli.github.com/\fP) to be properly configured for interaction with the salt repo. .INDENT 0.0 .IP 1. 3 Install the dependencies using this command: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install \-r requirements/static/ci/py{python_version}/tools.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 2. 3 Download and extract the artifacts with this \fBtools\fP command: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tools ts setup \-\-platform {linux|darwin|windows} \-\-slug <operating\-system\-slug> \-\-pr <pr\-number> \-\-pkg .ft P .fi .UNINDENT .UNINDENT .sp The most common use case is to test the packages built on a CI/CD run for a given PR. To see the possible options for each argument, and other ways to utilize this command, use the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tools ts setup \-h .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 You can only download artifacts from finished workflow runs. This is something imposed by the GitHub API. To download artifacts from a running workflow run, you either have to wait for the finish or cancel it. .UNINDENT .UNINDENT .SS Downloading individually .sp If the \fBtools ts setup\fP command doesn\(aqt work, you can download, unzip, and place the artifacts in the correct locations manually. Typically, you want to test packages built on a CI/CD run for a given PR. This guide explains how to set up for running the package tests using those artifacts. An analogous process can be performed for artifacts from nightly builds. .INDENT 0.0 .IP 1. 3 Find and download the artifacts: .INDENT 3.0 .INDENT 3.5 Under the summary page for the most recent actions run for that PR, there is a list of available artifacts from that run that can be downloaded. Download the package artifacts by finding \fBsalt\-<major>.<minor>+<number>.<sha>\-<arch>\-<pkg\-type>\fP\&. For example, the amd64 deb packages might look like: \fBsalt\-3006.2+123.01234567890\-x86_64\-deb\fP\&. .sp The onedir artifact will look like \fBsalt\-<major>.<minor>+<number>.<sha>\-onedir\-<platform>\-<arch>.tar.xz\fP\&. For instance, the macos x86_64 onedir may have the name \fBsalt\-3006.2+123.01234567890\-onedir\-darwin\-x86_64.tar.xz\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Windows onedir artifacts have \fB\&.zip\fP extensions instead of \fBtar.xz\fP .UNINDENT .UNINDENT .sp While it is optional, it is recommended to download the \fBnox\fP session artifact as well. This will have the form of \fBnox\-<os\-name>\-test\-pkgs\-onedir\-<arch>\fP\&. The amd64 Ubuntu 20.04 nox artifact may look like \fBnox\-ubuntu\-20.04\-test\-pkgs\-onedir\-x86_64\fP\&. .UNINDENT .UNINDENT .IP 2. 3 Place the artifacts in the correct location: .INDENT 3.0 .INDENT 3.5 Unzip the packages and place them in \fB<repo\-root>/artifacts/pkg/\fP\&. .sp You must unzip and untar the onedir packages and place them in \fB<repo\-root>/artifacts/\fP\&. Windows onedir requires an additional unzip action. If you set it up correctly, the \fB<repo\-root>/artifacts/salt\fP directory then contains the uncompressed onedir files. .sp Additionally, decompress the \fBnox\fP artifact and place it under \fB<repo\-root>/.nox/\fP\&. .UNINDENT .UNINDENT .UNINDENT .SS Running the tests .sp You can run the test suite run if all the artifacts are in the correct location. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You need root access to run the test artifacts. Run all nox commands at the root of the salt repo and as the root user. .UNINDENT .UNINDENT .INDENT 0.0 .IP 1. 3 Install \fBnox\fP: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install nox .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 2. 3 Run the install tests: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nox \-e test\-pkgs\-onedir \-\- install .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 3. 3 Run the upgrade or downgrade tests: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nox \-e test\-pkgs\-onedir \-\- upgrade \-\-prev\-version <previous\-version> .ft P .fi .UNINDENT .UNINDENT .sp You can run the downgrade tests in the same way, replacing \fBupgrade\fP with \fBdowngrade\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you are testing upgrades or downgrades and classic packages are available for your system, replace \fBupgrade\fP or \fBdowngrade\fP with \fBupgrade\-classic\fP or \fBdowngrade\-classic\fP respectively to test against those versions. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .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 \fI\%Standalone Minion\fP, and was originally created for \fI\%troubleshooting\fP\&. .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 \-\-no\-return\-event Do not send the return event back to master. .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 \fI\%many others\fP\&. .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 \-\-batch\-wait=BATCH_WAIT Wait the specified time in seconds after each job is done before freeing the slot in the batch of the next one. .UNINDENT .INDENT 0.0 .TP .B \-\-batch\-safe\-limit=BATCH_SAFE_LIMIT Execute the salt job in batch mode if the job would have executed on at least this many minions. .UNINDENT .INDENT 0.0 .TP .B \-\-batch\-safe\-size=BATCH_SAFE_SIZE Batch size to use for batch jobs created by \-\-batch\-safe\-limit. .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/3/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<grain value>:<glob expression>\(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<grain value>:< 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: \(dqrole:production*\(dq .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 \fI\%many others\fP\&. .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 \fI\%cp.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/3/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<grain value>:<glob expression>\(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<grain value>:< 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: \fI\%Salt Extend\fP\&. .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 \fI\%many others\fP\&. .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\-<id>.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/3/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 \fI\%many others\fP\&. .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 spm .SS \fBspm\fP .sp \fI\%Salt Package Manager\fP .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C spm <command> [<argument>] .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 \fI\%pillar modules\fP\&. .sp The below links contain documentation for the configuration options .INDENT 0.0 .IP \(bu 2 \fI\%master\-side configuration\fP .IP \(bu 2 \fI\%minion\-side configuration\fP .UNINDENT .sp Note that some of same the configuration options from the master are present in the minion configuration file, these are used in \fI\%masterless\fP mode. .sp The source for the built\-in Salt pillars can be found here: \fI\%salt/pillar\fP .SH MASTER TOPS .sp Salt includes a number of built\-in subsystems to generate top file data, they are listed at \fI\%master tops modules\fP\&. .sp The source for the built\-in Salt master tops can be found here: \fI\%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{ \fI\%auto\fP T} T{ An \(dqAlways Approved\(dq eauth interface to test against, not intended for production use T} _ T{ \fI\%django\fP T} T{ Provide authentication using Django Web Framework T} _ T{ \fI\%file\fP T} T{ Provide authentication using local files T} _ T{ \fI\%keystone\fP T} T{ Provide authentication using OpenStack Keystone T} _ T{ \fI\%ldap\fP T} T{ Provide authentication using simple LDAP binds T} _ T{ \fI\%mysql\fP T} T{ Provide authentication using MySQL. T} _ T{ \fI\%pam\fP T} T{ Authenticate against PAM T} _ T{ \fI\%pki\fP T} T{ Authenticate via a PKI certificate. T} _ T{ \fI\%rest\fP T} T{ Provide authentication using a REST call T} _ T{ \fI\%sharedsecret\fP T} T{ Provide authentication using configured shared secret T} _ T{ \fI\%yubico\fP T} T{ Provide authentication using YubiKey. T} _ .TE .SS salt.auth.auto .sp An \(dqAlways Approved\(dq 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 \fI\%external_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: <fully\-qualified reference to model class> .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 \fI\%hashutil.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 \fI\%hashutil.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 \fI\%External Authentication\fP 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 = \(dq{0}\(dq AND password = SHA2(\(dq{1}\(dq, 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 This module executes itself in a subprocess in order to user the system python and pam libraries. We do this to avoid openssl version conflicts when running under a salt onedir build. .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 \(dqpassword\(dq? 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 array that maps to a regular eauth YAML structure of a user as above. .INDENT 0.0 .TP .B salt.auth.rest.acl(username, **kwargs) REST authorization .UNINDENT .INDENT 0.0 .TP .B salt.auth.rest.auth(username, password) REST authentication .UNINDENT .INDENT 0.0 .TP .B salt.auth.rest.fetch(username, password) Call the rest authentication endpoint .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 2015.8.0. .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{ \fI\%adb\fP T} T{ Beacon to emit adb device state changes for Android devices T} _ T{ \fI\%aix_account\fP T} T{ Beacon to fire event when we notice a AIX user is locked due to many failed login attempts. T} _ T{ \fI\%avahi_announce\fP T} T{ Beacon to announce via avahi (zeroconf) T} _ T{ \fI\%bonjour_announce\fP T} T{ Beacon to announce via Bonjour (zeroconf) T} _ T{ \fI\%btmp\fP T} T{ Beacon to fire events at failed login of users T} _ T{ \fI\%cert_info\fP T} T{ Beacon to monitor certificate expiration dates from files on the filesystem. T} _ T{ \fI\%diskusage\fP T} T{ Beacon to monitor disk usage. T} _ T{ \fI\%glxinfo\fP T} T{ Beacon to emit when a display is available to a linux machine T} _ T{ \fI\%haproxy\fP T} T{ Watch current connections of haproxy server backends. T} _ T{ \fI\%inotify\fP T} T{ Watch files and translate the changes into salt events T} _ T{ \fI\%journald\fP T} T{ A simple beacon to watch journald for specific entries T} _ T{ \fI\%junos_rre_keys\fP T} T{ Junos redundant routing engine beacon. T} _ T{ \fI\%load\fP T} T{ Beacon to emit system load averages T} _ T{ \fI\%log_beacon\fP T} T{ Beacon to fire events at specific log messages. T} _ T{ \fI\%memusage\fP T} T{ Beacon to monitor memory usage. T} _ T{ \fI\%napalm_beacon\fP T} T{ Watch NAPALM functions and fire events on specific triggers T} _ T{ \fI\%network_info\fP T} T{ Beacon to monitor statistics from ethernet adapters T} _ T{ \fI\%network_settings\fP T} T{ Beacon to monitor network adapter setting changes on Linux T} _ T{ \fI\%pkg\fP T} T{ Watch for pkgs that have upgrades, then fire an event. T} _ T{ \fI\%proxy_example\fP T} T{ Example beacon to use with salt\-proxy T} _ T{ \fI\%ps\fP T} T{ Send events covering process status T} _ T{ \fI\%salt_monitor\fP T} T{ A beacon to execute salt execution module functions. T} _ T{ \fI\%salt_proxy\fP T} T{ Beacon to manage and report the status of one or more salt proxy processes T} _ T{ \fI\%sensehat\fP T} T{ Monitor temperature, humidity and pressure using the SenseHat of a Raspberry Pi T} _ T{ \fI\%service\fP T} T{ Send events covering service status T} _ T{ \fI\%sh\fP T} T{ Watch the shell commands being executed actively. T} _ T{ \fI\%smartos_imgadm\fP T} T{ Beacon that fires events on image import/delete. T} _ T{ \fI\%smartos_vmadm\fP T} T{ Beacon that fires events on vm state changes T} _ T{ \fI\%status\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{ \fI\%swapusage\fP T} T{ Beacon to monitor swap usage. T} _ T{ \fI\%telegram_bot_msg\fP T} T{ Beacon to emit Telegram messages T} _ T{ \fI\%twilio_txt_msg\fP T} T{ Beacon to emit Twilio text messages T} _ T{ \fI\%watchdog\fP T} T{ Watch files and translate the changes into salt events. T} _ T{ \fI\%wtmp\fP T} T{ Beacon to fire events at login of users as registered in the wtmp file T} _ .TE .SS salt.beacons.adb .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 .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 .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.<grain_name>\fP .IP \(bu 2 \fBgrains.<grain_name>[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 .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.<grain_name>\fP .IP \(bu 2 \fBgrains.<grain_name>[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: \(dqFailed login from \(ga{{ data.get(\(aquser\(aq, \(aq\(aq) or \(aqunknown user\(aq }}\(ga on \(ga{{ data[\(aqid\(aq] }}\(ga\(dq .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 \fI\%slack 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 \fI\%slack 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 \fI\%slack 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 \(dq/\(dq, 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 .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 .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.junos_rre_keys .sp Junos redundant routing engine beacon. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This beacon only works on the Juniper native minion. .UNINDENT .UNINDENT .sp Copies salt\-minion keys to the backup RE when present .sp Configure with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacon: beacons: junos_rre_keys: \- interval: 43200 .ft P .fi .UNINDENT .UNINDENT .sp \fIinterval\fP above is in seconds, 43200 is recommended (every 12 hours) .INDENT 0.0 .TP .B salt.beacons.junos_rre_keys.beacon(config) .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_beacon .sp Beacon to fire events at specific log messages. .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.beacons.log_beacon.beacon(config) Read the log file and return match whole string .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: log: \- file: <path> \- tags: <tag>: regex: <pattern> .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 regex matching is based on the \fI\%re\fP module .UNINDENT .UNINDENT .sp The defined tag is added to the beacon event tag. This is not the tag in the log. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: log: \- file: /var/log/messages #path to log. \- tags: goodbye/world: # tag added to beacon event tag. regex: .*good\-bye.* # match good\-bye string anywhere in the log entry. .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.log_beacon.validate(config) Validate the beacon configuration .UNINDENT .SS salt.beacons.memusage .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 \fI\%NAPALM 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 \fI\%ntp.stats\fP execution function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { \(dqcomment\(dq: \(dq\(dq, \(dqresult\(dq: true, \(dqout\(dq: [ { \(dqreferenceid\(dq: \(dq.GPSs.\(dq, \(dqremote\(dq: \(dq172.17.17.1\(dq, \(dqsynchronized\(dq: true, \(dqreachability\(dq: 377, \(dqoffset\(dq: 0.461, \(dqwhen\(dq: \(dq860\(dq, \(dqdelay\(dq: 143.606, \(dqhostpoll\(dq: 1024, \(dqstratum\(dq: 1, \(dqjitter\(dq: 0.027, \(dqtype\(dq: \(dq\-\(dq }, { \(dqreferenceid\(dq: \(dq.INIT.\(dq, \(dqremote\(dq: \(dq172.17.17.2\(dq, \(dqsynchronized\(dq: false, \(dqreachability\(dq: 0, \(dqoffset\(dq: 0.0, \(dqwhen\(dq: \(dq\-\(dq, \(dqdelay\(dq: 0.0, \(dqhostpoll\(dq: 1024, \(dqstratum\(dq: 16, \(dqjitter\(dq: 4000.0, \(dqtype\(dq: \(dq\-\(dq } ] } .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 \fI\%bgp.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 { \(dq_stamp\(dq: \(dq2017\-09\-05T09:51:09.377202\(dq, \(dqargs\(dq: [], \(dqdata\(dq: { \(dqcomment\(dq: \(dq\(dq, \(dqout\(dq: [ { \(dqdelay\(dq: 0.0, \(dqhostpoll\(dq: 1024, \(dqjitter\(dq: 4000.0, \(dqoffset\(dq: 0.0, \(dqreachability\(dq: 0, \(dqreferenceid\(dq: \(dq.INIT.\(dq, \(dqremote\(dq: \(dq172.17.17.1\(dq, \(dqstratum\(dq: 16, \(dqsynchronized\(dq: false, \(dqtype\(dq: \(dq\-\(dq, \(dqwhen\(dq: \(dq\-\(dq } ], \(dqresult\(dq: true }, \(dqfun\(dq: \(dqntp.stats\(dq, \(dqid\(dq: \(dqedge01.bjm01\(dq, \(dqkwargs\(dq: {}, \(dqmatch\(dq: { \(dqstratum\(dq: \(dq> 5\(dq } } .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 .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.saltproject.io/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 .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_monitor .sp A beacon to execute salt execution module functions. This beacon will fire only if the return data is \(dqtruthy\(dq. The function return, function name and args and/or kwargs, will be passed as data in the event. .sp The configuration can accept a list of salt functions to execute every interval. Make sure to allot enough time via \(aqinterval\(aq key to allow all salt functions to execute. The salt functions will be executed sequentially. .sp The elements in list of functions can be either a simple string (with no arguments) or a dictionary with a single key being the salt execution module and sub keys indicating args and / or kwargs. .sp See example config below. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: salt_monitor: \- salt_fun: \- slsutil.renderer: args: \- salt://states/apache.sls kwargs: \- default_renderer: jinja \- test.ping \- interval: 3600 # seconds .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.salt_monitor.beacon(config) .UNINDENT .INDENT 0.0 .TP .B salt.beacons.salt_monitor.validate(config) .UNINDENT .SS salt.beacons.salt_proxy .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 .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 .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 .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.swapusage .sp Beacon to monitor swap usage. .sp New in version 3003. .INDENT 0.0 .TP .B depends python\-psutil .UNINDENT .INDENT 0.0 .TP .B salt.beacons.swapusage.beacon(config) Monitor the swap 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: swapusage: \- percent: 13% .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.swapusage.validate(config) Validate the beacon configuration .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 \(dqmsgs\(dq 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: \(dq<bot access token>\(dq \- accept_from: \- \(dq<valid username>\(dq \- 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 \(dqtexts\(dq whose value is a list of texts. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: twilio_txt_msg: \- account_sid: \(dq<account sid>\(dq \- auth_token: \(dq<auth token>\(dq \- twilio_number: \(dq+15555555555\(dq \- 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 .sp Watch files and translate the changes into salt events. .sp New in version 2019.2.0. .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): .INDENT 7.0 .IP \(bu 2 create \- File or directory is created in watched directory .IP \(bu 2 modify \- The watched directory is modified .IP \(bu 2 delete \- File or directory is deleted from watched directory .IP \(bu 2 move \- File or directory is moved or renamed in the watched directory .UNINDENT .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: \(dq{{ 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\(dq .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 \fI\%slack 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 \fI\%slack 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 \fI\%slack 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 .sp For understanding and usage of the cache modules see the \fI\%Minion Data Cache\fP topic. .TS center; |l|l|. _ T{ \fI\%consul\fP T} T{ Minion data cache plugin for Consul key/value data store. T} _ T{ \fI\%etcd_cache\fP T} T{ Minion data cache plugin for Etcd key/value data store. T} _ T{ \fI\%localfs\fP T} T{ Cache data in filesystem. T} _ T{ \fI\%mysql_cache\fP T} T{ Minion data cache plugin for MySQL database. T} _ T{ \fI\%redis_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. .sp Changed in version 3005: Timestamp/cache updated support added. .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 consul.timestamp_suffix: .tstamp # Added in 3005.0 .ft P .fi .UNINDENT .UNINDENT .sp In order to bring the cache APIs into conformity, in 3005.0 timestamp information gets stored as a separate \fB{key}.tstamp\fP key/value. If your existing functionality depends on being able to store normal keys with the \fB\&.tstamp\fP suffix, override the \fBconsul.timestamp_suffix\fP default config. .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 .INDENT 0.0 .TP .B salt.cache.consul.updated(bank, key) Return the Unix Epoch timestamp of when the key was last updated. Return None if key is not found. .UNINDENT .SS salt.cache.etcd_cache .sp Minion data cache plugin for Etcd key/value data store. .sp New in version 2018.3.0. .sp Changed in version 3005. .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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 While etcd API v3 has been implemented in other places within salt, etcd_cache does not support it at this time due to fundamental differences in how the versions are designed and v3 not being compatible with the cache API. .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 .sp In Phosphorus, ls/list was changed to always return the final name in the path. This should only make a difference if you were directly using \fBls\fP on paths that were more or less nested than, for example: \fB1/2/3/4\fP\&. .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 .INDENT 0.0 .TP .B salt.cache.etcd_cache.updated(bank, key) Return Unix Epoch based timestamp of when the bank/key was updated. .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 2018.3.0. .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 \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The mysql.database and mysql.table_name will be directly added into certain queries. Salt treats these as trusted input. .UNINDENT .UNINDENT .sp The module requires the database (default \fBsalt_cache\fP) to exist but creates its own table if needed. The keys are indexed using the \fBbank\fP and \fBetcd_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 pymysql .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 # This may be enabled to create a fresh connection on every call mysql.fresh_connection: false .ft P .fi .UNINDENT .UNINDENT .sp Related docs can 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.force_reconnect() Force a reconnection to the MySQL database, by removing the client from Salt\(aqs __context__. .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, args=None, retries=3) Get a cursor and run a query. Reconnect up to \fBretries\fP times if needed. Returns: cursor, affected rows counter Raises: SaltCacheError, AttributeError, OperationalError, InterfaceError .UNINDENT .INDENT 0.0 .TP .B salt.cache.mysql_cache.store(bank, key, data) Store a key value. .UNINDENT .INDENT 0.0 .TP .B salt.cache.mysql_cache.updated(bank, key) Return the integer Unix epoch update timestamp of the specified bank and key. .UNINDENT .SS salt.cache.redis_cache .SS Redis .sp Redis plugin for the Salt caching subsystem. .sp New in version 2017.7.0. .sp Changed in version 3005. .sp To enable this cache plugin, the master will need the python client for redis installed. This can be easily installed with pip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \e* pip.install redis .ft P .fi .UNINDENT .UNINDENT .sp As Redis provides a simple mechanism for very fast key\-value store, in order to provide 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 <pattern>\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) \(dqsub\-bank\(dq 127.0.0.1:6379> SMEMBERS $BANK_root\-bank/sub\-bank 1) \(dqleaf\-bank\(dq 127.0.0.1:6379> SMEMBERS $BANKEYS_root\-bank/sub\-bank/leaf\-bank 1) \(dqmy\-key\(dq 127.0.0.1:6379> GET $KEY_root\-bank/sub\-bank/leaf\-bank/my\-key \(dqmy\-value\(dq .ft P .fi .UNINDENT .UNINDENT .sp There are four 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. .IP \(bu 2 \fB$TSTAMP_*\fP stores the last updated timestamp 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 key 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 timestamp_prefix: \fB$TSTAMP\fP The prefix for the last modified timestamp for keys. .sp New in version 3005. .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.timestamp_prefix: #TICKS 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) Effectively a noop. Return an empty dictionary. .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 .INDENT 0.0 .TP .B salt.cache.redis_cache.updated(bank, key) Return the Unix Epoch timestamp of when the key was last updated. Return None if key is not found. .UNINDENT .SS cloud modules .TS center; |l|l|. _ T{ \fI\%aliyun\fP T} T{ AliYun ECS Cloud Module T} _ T{ \fI\%clc\fP T} T{ CenturyLink Cloud Module T} _ T{ \fI\%cloudstack\fP T} T{ CloudStack Cloud Module T} _ T{ \fI\%digitalocean\fP T} T{ DigitalOcean Cloud Module T} _ T{ \fI\%dimensiondata\fP T} T{ Dimension Data Cloud Module T} _ T{ \fI\%ec2\fP T} T{ The EC2 Cloud Module T} _ T{ \fI\%gce\fP T} T{ Copyright 2013 Google Inc. T} _ T{ \fI\%gogrid\fP T} T{ GoGrid Cloud Module T} _ T{ \fI\%hetzner\fP T} T{ Hetzner Cloud Module T} _ T{ \fI\%joyent\fP T} T{ Joyent Cloud Module T} _ T{ \fI\%libvirt\fP T} T{ Libvirt Cloud Module T} _ T{ \fI\%linode\fP T} T{ The Linode Cloud Module T} _ T{ \fI\%lxc\fP T} T{ Install Salt on an LXC Container T} _ T{ \fI\%oneandone\fP T} T{ 1&1 Cloud Server Module T} _ T{ \fI\%opennebula\fP T} T{ OpenNebula Cloud Module T} _ T{ \fI\%openstack\fP T} T{ Openstack Cloud Driver T} _ T{ \fI\%packet\fP T} T{ Packet Cloud Module Using Packet\(aqs Python API Client T} _ T{ \fI\%parallels\fP T} T{ Parallels Cloud Module T} _ T{ \fI\%profitbricks\fP T} T{ ProfitBricks Cloud Module T} _ T{ \fI\%proxmox\fP T} T{ T} _ T{ \fI\%pyrax\fP T} T{ Pyrax Cloud Module T} _ T{ \fI\%qingcloud\fP T} T{ QingCloud Cloud Module T} _ T{ \fI\%saltify\fP T} T{ T} _ T{ \fI\%scaleway\fP T} T{ Scaleway Cloud Module T} _ T{ \fI\%softlayer\fP T} T{ SoftLayer Cloud Module T} _ T{ \fI\%softlayer_hw\fP T} T{ SoftLayer HW Cloud Module T} _ T{ \fI\%tencentcloud\fP T} T{ Tencent Cloud Cloud Module T} _ T{ \fI\%vagrant\fP T} T{ Vagrant Cloud Driver T} _ T{ \fI\%virtualbox\fP T} T{ A salt cloud provider that lets you use virtualbox on your machine and act as a cloud. T} _ T{ \fI\%vmware\fP T} T{ VMware Cloud Module T} _ T{ \fI\%vultrpy\fP T} T{ Vultr Cloud Module using python\-vultr bindings T} _ T{ \fI\%xen\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.clc .SS CenturyLink Cloud Module .sp New in version 2018.3.0. .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: \(dqsalt\-cloud \-f get_group_estimate clc group=Dev location=VA1\(dq .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: <your api key > secretkey: <your secret key > 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 :: \(dqminion1\(dq .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 \(dqApps & API\(dq section. The SSH key name can be found under the \(dqSSH Keys\(dq 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. .sp 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: \(dq\-W %h:%p\(dq # 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=\(dqMy Snapshot Description\(dq .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 \fBgp2\fP for General Purpose SSD, \fBio1\fP or \fBio2\fP for Provisioned IOPS SSD, \fBst1\fP for Throughput Optimized HDD, \fBsc1\fP for Cold HDD, or \fBstandard\fP 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 or \fBio2\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{\(dqtag1\(dq: \(dqval1\(dq, \(dqtag2\(dq, \(dqval2\(dq}\(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 \(dq,\(dq. .TP .B owner Return the snapshots owned by the specified owner. Valid values include: self, amazon, <AWS Account ID>. Multiple values must be separated by \(dq,\(dq. .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 \(dq,\(dq. .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 \(dq,\(dq. .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 .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 .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 \(dqdedicated\(dq or \(dqdefault\(dq. 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=\(dqmy description\(dq 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 \(dqnew name\(dq. .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 <provider> .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 \(dqLicense\(dq); 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 \(dqAS IS\(dq 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 \fI\%Google Compute Engine Setup\fP 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: \(dqmy\-project\-id\(dq # 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) Changed in version 2017.7.0. .sp 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) New in version 2017.7.0. .sp 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) New in version 2017.7.0. .sp 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 \(dq\-a destroy\(dq 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. .sp Changed in version 2017.7.0. .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) New in version 2017.7.0. .sp 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 \(dqMy Account\(dq 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_public_ips <provider> .ft P .fi .UNINDENT .UNINDENT .sp To list unavailable (assigned) IPs, use: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_public_ips <provider> state=assigned .ft P .fi .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.hetzner .SS Hetzner Cloud Module .sp The Hetzner cloud module is used to control access to the hetzner cloud. \fI\%https://docs.hetzner.cloud/\fP .INDENT 0.0 .TP .B depends hcloud >= 1.10 .UNINDENT .sp Use of this module requires the \fBkey\fP parameter to be set. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-hetzner\-cloud\-config: key: <your api key> driver: hetzner .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.hetzner.avail_images(call=None) Return a dictionary of available images .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.hetzner.avail_locations(call=None) Return a dictionary of available locations .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.hetzner.avail_sizes(call=None) Return a dictionary of available VM sizes .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.hetzner.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.hetzner.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.hetzner.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.hetzner.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.hetzner.list_nodes(call=None) Return a dictionary of existing VMs in the current project, containing basic details of each VM .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.hetzner.list_nodes_full(call=None) Return a dictionary of existing VMs in the current project, containing full details per VM .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.hetzner.list_ssh_keys(call=None) Return a dictionary of available SSH keys configured in the current project .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.hetzner.reboot(name, call=None, wait=True) 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.hetzner.resize(name, kwargs, call=None) Resize a node. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a resize mymachine size=... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.hetzner.show_instance(name, call=None) Return the details of a specific VM .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.hetzner.start(name, call=None, wait=True) 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.hetzner.stop(name, call=None, wait=True) 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.hetzner.wait_until(name, state, timeout=300) Wait until a specific state has been reached on a node .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: \(dqqemu+ssh://user@remotekvm/system?socket=/var/run/libvirt/libvirt\-sock\(dq 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/<vm name>/destroying\fP\&. Once the virtual machine has been destroyed, another event is fired. The tag for that event is \fIsalt/cloud/<vm name>/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 dictionaries 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 .sp New in version 2017.7.3. .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. .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 \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 has been removed in favor of APIv4. To move to APIv4 now, See the full migration guide here \fI\%https://docs.saltproject.io/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 apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr... password: F00barbazverylongp@ssword .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). 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). 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/ubuntu22.04\fP); official images start with \fBlinode/\fP\&. 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 IP to the VM. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBbackups_enabled\fP: (optional) Whether or not to enable the backup for this VM. Backup can be configured in your Linode account 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. .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/ubuntu22.04 location: us\-east my\-linode\-profile\-advanced: # an advanced configuration provider: my\-linode\-provider size: g6\-standard\-3 image: linode/ubuntu22.04 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 .SS Migrating to APIv4 .sp You will need to generate a new token for your account. See \fI\%https://www.linode.com/docs/products/tools/api/get\-started/#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 Linode Developer Tools and Experience Team <\fI\%dev\-dx@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 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.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 classmethod get_api_instance() .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 set_backup_schedule(label, linode_id, day, window, auto_enable=False) .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. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f clone my\-linode\-config linode_id=1234567 location=us\-central size=g6\-standard\-1 .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.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 \(dqDebian\(dq or \(dqRHEL\(dq 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 \(dqDebian\(dq or \(dqRHEL\(dq 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.set_backup_schedule(name=None, kwargs=None, call=None) Set the backup schedule for a Linode. .INDENT 7.0 .TP .B name The name (label) of the Linode. Can be used instead of \fBlinode_id\fP\&. .TP .B linode_id The ID of the Linode instance to set the backup schedule for. 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 auto_enable If \fBTrue\fP, automatically enable the backup feature for the Linode if it wasn\(aqt already enabled. Optional parameter, default to \fBFalse\fP\&. .TP .B day Possible values: \fBSunday\fP, \fBMonday\fP, \fBTuesday\fP, \fBWednesday\fP, \fBThursday\fP, \fBFriday\fP, \fBSaturday\fP .sp The day of the week that your Linode\(aqs weekly Backup is taken. If not set manually, a day will be chosen for you. Backups are taken every day, but backups taken on this day are preferred when selecting backups to retain for a longer period. .sp If not set manually, then when backups are initially enabled, this may come back as \fBScheduling\fP until the day is automatically selected. .TP .B window Possible values: \fBW0\fP, \fBW2\fP, \fBW4\fP, \fBW6\fP, \fBW8\fP, \fBW10\fP, \fBW12\fP, \fBW14\fP, \fBW16\fP, \fBW18\fP, \fBW20\fP, \fBW22\fP .sp The window in which your backups will be taken, in UTC. A backups window is a two\-hour span of time in which the backup may occur. .sp For example, \fBW10\fP indicates that your backups should be taken between 10:00 and 12:00. If you do not choose a backup window, one will be selected for you automatically. .sp If not set manually, when backups are initially enabled this may come back as \fBScheduling\fP until the window is automatically selected. .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 set_backup_schedule my\-linode\-instance day=Monday window=W20 auto_enable=True .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 set_backup_schedule my\-linode\-provider name=my\-linode\-instance day=Monday window=W20 auto_enable=True salt\-cloud \-f set_backup_schedule my\-linode\-provider linode_id=1225876 day=Monday window=W20 auto_enable=True .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 \(dqDebian\(dq or \(dqRHEL\(dq 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 \fI\%core config documentation\fP\&. .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.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: <your\-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> # ID of the datacenter where the server will be created datacenter_id: <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: <ID> # IP address ID ip_id: <ID> # Load balancer ID load_balancer_id: <ID> # Monitoring policy ID monitoring_policy_id: <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: <my.basedomain.com> [...] .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=\(dqMy New Image\(dq DESCRIPTION=\(dqDescription of the image.\(dq \e PATH=/home/one_user/images/image_name.img\(aq salt\-cloud \-f secgroup_allocate opennebula \e data=\(dqName = test RULE = [PROTOCOL = TCP, RULE_TYPE = inbound, \e RANGE = 1000:2000]\(dq .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=\(dqUbuntu 14.04\(dq PATH=\(dq/home/one_user/images/ubuntu_desktop.img\(dq \e DESCRIPTION=\(dqUbuntu 14.04 for development.\(dq\(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=\(dqUbuntu 14.04\(dq update_type=merge \e data=\(aqNAME=\(dqUbuntu Dev\(dq PATH=\(dq/home/one_user/images/ubuntu_desktop.img\(dq \e DESCRIPTION = \(dqUbuntu 14.04 for development.\(dq\(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=\(dqNAME = test RULE = [PROTOCOL = TCP, RULE_TYPE = inbound, \e RANGE = 1000:2000]\(dq .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=\(dqName = test RULE = [PROTOCOL = TCP, RULE_TYPE = inbound, RANGE = 1000:2000]\(dq .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=\(dq1.0\(dq DISK=[IMAGE=\(dqUbuntu\-14.04\(dq] GRAPHICS=[LISTEN=\(dq0.0.0.0\(dq,TYPE=\(dqvnc\(dq] \e MEMORY=\(dq1024\(dq NETWORK=\(dqyes\(dq NIC=[NETWORK=\(dq192net\(dq,NETWORK_UNAME=\(dqoneadmin\(dq] \e OS=[ARCH=\(dqx86_64\(dq] SUNSTONE_CAPACITY_SELECT=\(dqYES\(dq SUNSTONE_NETWORK_SELECT=\(dqYES\(dq \e VCPU=\(dq1\(dq\(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=\(dq1.0\(dq DISK=[IMAGE=\(dqUbuntu\-14.04\(dq] GRAPHICS=[LISTEN=\(dq0.0.0.0\(dq,TYPE=\(dqvnc\(dq] \e MEMORY=\(dq1024\(dq NETWORK=\(dqyes\(dq NIC=[NETWORK=\(dq192net\(dq,NETWORK_UNAME=\(dqoneadmin\(dq] \e OS=[ARCH=\(dqx86_64\(dq] SUNSTONE_CAPACITY_SELECT=\(dqYES\(dq SUNSTONE_NETWORK_SELECT=\(dqYES\(dq \e VCPU=\(dq1\(dq\(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=\(dqDISK=[DISK_ID=1]\(dq .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=\(dqNIC=[NETWORK_ID=1]\(dq .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=\(dqMy Snapshot Description\(dq .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=\(dqCPU=1 VCPU=1 MEMORY=1024\(dq .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=\(dqAR=[TYPE=IP4, IP=192.168.0.5, SIZE=10]\(dq .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=\(dqLEASES=[IP=192.168.0.5]\(dq .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=\(dqLEASES=[IP=192.168.0.5]\(dq .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=\(dqSIZE=10 AR_ID=8 NETWORK_ID=1\(dq .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 .IP \(bu 2 ignore_cidr: Specify a CIDR range of unreachable private addresses for salt to ignore when connecting .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 If your OpenStack instances only have private IP addresses and a CIDR range of private addresses are not reachable from the salt\-master, you may set your preference to have Salt ignore it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-openstack\-config: ignore_cidr: 192.168.0.0/16 .ft P .fi .UNINDENT .UNINDENT .sp 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.ignore_cidr(vm_, ip) Return True if we are to ignore the specified IP. .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 either an \(aqipv4\(aq (default) or \(aqipv6\(aq address depending on \(aqprotocol\(aq option. The list of \(aqipv4\(aq IPs is filtered by ignore_cidr() to remove any unreachable private addresses. .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. .sp 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: <UUID> # 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: <UUID> # Image alias could be provided instead of image. # Example \(aqubuntu:latest\(aq #image_alias: <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: <ID> # 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: <ID> # 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=\(dqmy description\(dq .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 .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%proxmox Salt Extension\fP\&. .UNINDENT .UNINDENT .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 .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This cloud provider will be removed from Salt in version 3009.0 in favor of the \fI\%saltext.proxmox Salt Extension\fP .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 .sp 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.ignore_cidr(vm_, ip) Return True if we are to ignore the specified IP. .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.preferred_ip(vm_, ips) Return either an \(aqipv4\(aq (default) or \(aqipv6\(aq address depending on \(aqprotocol\(aq option. The list of \(aqipv4\(aq IPs is filtered by ignore_cidr() to remove any unreachable private addresses. .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 (\(dqpulling the plug\(dq). .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 \fI\%Getting Started with Saltify\fP 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 \fI\%Miscellaneous Salt Cloud Options\fP and \fI\%Getting Started with Saltify\fP .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: .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.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 <provider> .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 \(dqvagrant up\(dq 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 \fI\%Getting Started with Vagrant\fP 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.saltproject.io/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: <str> profile: <dict> driver: <provider>:<profile> clonefrom: <vm_name> clonemode: <mode> (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/<vm name>/destroying\fP\&. Once the virtual machine has been destroyed, another event is fired. The tag for that event is \fIsalt/cloud/<vm name>/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 \(dqaction\(dq @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 \(dqaction\(dq @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 \fI\%Getting started with VMware\fP to get started. .INDENT 0.0 .TP .B codeauthor Nitin Madhok <\fI\%nmadhok@g.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 \(dqimport pyVmomi\(dq ; 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 <YOUR\-HOSTSYSTEM\-DNS/IP>: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=\(dqmyHostSystemName\(dq cluster=\(dqmyClusterName\(dq salt\-cloud \-f add_host my\-vmware\-config host=\(dqmyHostSystemName\(dq datacenter=\(dqmyDatacenterName\(dq .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=\(dqmyHostSystemName\(dq .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 \fI\%here.\fP .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=\(dqmyNewCluster\(dq datacenter=\(dqdatacenterName\(dq .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=\(dqMyNewDatacenter\(dq .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=\(dqdatastoreClusterName\(dq datacenter=\(dqdatacenterName\(dq .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=\(dq/yourDatacenterName/host/yourFolderName\(dq\fP .sp To create a Network Folder under a Datacenter, specify \fBpath=\(dq/yourDatacenterName/network/yourFolderName\(dq\fP .sp To create a Storage Folder under a Datacenter, specify \fBpath=\(dq/yourDatacenterName/datastore/yourFolderName\(dq\fP .sp To create a VM and Template Folder under a Datacenter, specify \fBpath=\(dq/yourDatacenterName/vm/yourFolderName\(dq\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=\(dq/Local/a/b/c\(dq salt\-cloud \-f create_folder my\-vmware\-config path=\(dq/MyDatacenter/vm/MyVMFolder\(dq salt\-cloud \-f create_folder my\-vmware\-config path=\(dq/MyDatacenter/host/MyHostFolder\(dq salt\-cloud \-f create_folder my\-vmware\-config path=\(dq/MyDatacenter/network/MyNetworkFolder\(dq salt\-cloud \-f create_folder my\-vmware\-config path=\(dq/MyDatacenter/storage/MyStorageFolder\(dq .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 \(dqpowered on\(dq. 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=\(dqmySnapshot\(dq salt\-cloud \-a create_snapshot vmname snapshot_name=\(dqmySnapshot\(dq [description=\(dqMy snapshot\(dq] [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=\(dqmyHostSystemName\(dq .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=\(dqmyHostSystemName\(dq .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=\(dqmyHostSystemName\(dq .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=\(dqdatacenterName\(dq .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=\(dqhostSystemName\(dq .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=\(dqHBAType\(dq .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=\(dqhostSystemName\(dq type=\(dqHBAtype\(dq .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=\(dqclusterName\(dq .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=\(dqdatacenterName\(dq .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=\(dqvmname\(dq .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=\(dqmyHostSystemName\(dq [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=\(dqmyHostSystemName\(dq .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=\(dqmySnapshot\(dq salt\-cloud \-a remove_snapshot vmname snapshot_name=\(dqmySnapshot\(dq [remove_children=\(dqTrue\(dq] .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=\(dqhostSystemName\(dq salt\-cloud \-f rescan_hba my\-vmware\-config hba=\(dqhbaDeviceName\(dq host=\(dqhostSystemName\(dq .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 \(dqPowered On\(dq. 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 \(dqPowered On\(dq 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=\(dqselectedSnapshot\(dq [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=\(dqmyHostSystemName\(dq [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: <supersecretapi_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 <name of vultr provider> .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 .sp Similarly you can also specify a fiewall group ID using the option firewall_group_id. You can list firewall groups with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_firewall_groups <name of vultr provider> .ft P .fi .UNINDENT .UNINDENT .sp To specify SSH keys to be preinstalled on the server, use the ssh_key_names setting .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 ssh_key_names: dev1,dev2,salt\-master .ft P .fi .UNINDENT .UNINDENT .sp You can list SSH keys available on your account using .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_keypairs <name of vultr provider> .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.avail_firewall_groups(conn=None) return available firewall groups .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_keys(conn=None) return available SSH keys .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 (\(dqplans\(dq 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_firewall_groups(conn=None, call=None) return list of firewall groups .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.list_keypairs(conn=None, call=None) return list of SSH keys .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.show_keypair(kwargs=None, call=None) return list of SSH keys .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.start(*args, **kwargs) Execute a \(dqstart\(dq action on a VM .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.stop(*args, **kwargs) Execute a \(dqstop\(dq 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=\(dqutf\-8 graphical\(dq .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{ \fI\%docker_events\fP T} T{ T} _ T{ \fI\%fluent\fP T} T{ An engine that reads messages from the salt event bus and pushes them onto a fluent endpoint. T} _ T{ \fI\%http_logstash\fP T} T{ HTTP Logstash engine T} _ T{ \fI\%ircbot\fP T} T{ IRC Bot engine T} _ T{ \fI\%junos_syslog\fP T} T{ Junos Syslog Engine T} _ T{ \fI\%libvirt_events\fP T} T{ An engine that listens for libvirt events and resends them to the salt event bus. T} _ T{ \fI\%logentries\fP T} T{ An engine that sends events to the Logentries logging service. T} _ T{ \fI\%logstash_engine\fP T} T{ An engine that reads messages from the salt event bus and pushes them onto a logstash endpoint. T} _ T{ \fI\%napalm_syslog\fP T} T{ NAPALM syslog engine T} _ T{ \fI\%reactor\fP T} T{ Setup Reactor T} _ T{ \fI\%redis_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{ \fI\%script\fP T} T{ Send events based on a script\(aqs stdout T} _ T{ \fI\%slack\fP T} T{ An engine that reads messages from Slack and can act on them T} _ T{ \fI\%slack_bolt_engine\fP T} T{ An engine that reads messages from Slack and can act on them T} _ T{ \fI\%sqs_events\fP T} T{ An engine that continuously reads messages from SQS and fires them as events. T} _ T{ \fI\%stalekey\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{ \fI\%test\fP T} T{ A simple test engine, not intended for real use but as an example T} _ T{ \fI\%thorium\fP T} T{ Manage the Thorium complex event reaction system T} _ T{ \fI\%webhook\fP T} T{ Send events from webhook api T} _ .TE .SS salt.engines.docker_events .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%docker Salt Extension\fP\&. .UNINDENT .UNINDENT .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 <source> @type forward port 24224 </source> <match saltstack.**> @type file path /var/log/td\-agent/saltstack </match> .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 \(dqengine\(dq. This text is appended to \(dqsaltstack.\(dq to form a fluentd tag, ex: \(dqsaltstack.engine\(dq .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: <nick> username: <username> password: <password> host: irc.oftc.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 <stuff> return <stuff> targeted at the user who sent the commands .TP .B event <tag> [<extra>, <data>] fire event on the master or minion event stream with the tag \fIsalt/engines/ircbot/<tag>\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 \- irc.oftc.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 .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 <ip\-of\-the\-salt\-device> 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 class salt.engines.junos_syslog.DatagramProtocol .UNINDENT .INDENT 0.0 .TP .B salt.engines.junos_syslog.start(port=516, **kwargs) .UNINDENT .SS salt.engines.libvirt_events .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 <main_type>/<subtype>. 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(\(dqorg.libvirt\(dq) == 0 && subject.user == \(dqsalt\(dq) { 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 New in version 2016.3.0. .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\%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. .sp New in version 2015.8.0. .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 { \(dq_stamp\(dq: \(dq2017\-05\-26T10:03:18.653045\(dq, \(dqerror\(dq: \(dqBGP_PREFIX_THRESH_EXCEEDED\(dq, \(dqhost\(dq: \(dqvmx01\(dq, \(dqip\(dq: \(dq192.168.140.252\(dq, \(dqmessage_details\(dq: { \(dqdate\(dq: \(dqMay 25\(dq, \(dqhost\(dq: \(dqvmx01\(dq, \(dqmessage\(dq: \(dq192.168.140.254 (External AS 65001): Configured maximum prefix\-limit threshold(22) exceeded for inet\-unicast nlri: 28 (instance master)\(dq, \(dqpri\(dq: \(dq28\(dq, \(dqprocessId\(dq: \(dq2957\(dq, \(dqprocessName\(dq: \(dqrpd\(dq, \(dqtag\(dq: \(dqBGP_PREFIX_THRESH_EXCEEDED\(dq, \(dqtime\(dq: \(dq20:50:41\(dq }, \(dqmodel_name\(dq: \(dqopenconfig_bgp\(dq, \(dqopen_config\(dq: { \(dqbgp\(dq: { \(dqneighbors\(dq: { \(dqneighbor\(dq: { \(dq192.168.140.254\(dq: { \(dqafi_safis\(dq: { \(dqafi_safi\(dq: { \(dqinet\(dq: { \(dqafi_safi_name\(dq: \(dqinet\(dq, \(dqipv4_unicast\(dq: { \(dqprefix_limit\(dq: { \(dqstate\(dq: { \(dqmax_prefixes\(dq: 22 } } }, \(dqstate\(dq: { \(dqprefixes\(dq: { \(dqreceived\(dq: 28 } } } } }, \(dqneighbor_address\(dq: \(dq192.168.140.254\(dq, \(dqstate\(dq: { \(dqpeer_as\(dq: 65001 } } } } } }, \(dqos\(dq: \(dqjunos\(dq, \(dqtimestamp\(dq: \(dq1495741841\(dq } .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 \fI\%Host grains\fP to match the event tag .IP \(bu 2 \fI\%Host DNS grain\fP to match the IP address in the event data .IP \(bu 2 \fI\%Hostname grains\fP to match the event tag .IP \(bu 2 \fI\%Define static grains\fP .IP \(bu 2 \fI\%Write a grains module\fP .IP \(bu 2 \fI\%Targeting minions using pillar data\fP \- 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 \fI\%file_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: \(dqhostname:{{ data[\(aqhost\(aq] }}\(dq \- 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 \fI\%hostname grain\fP field. When the event occurs, the reactor will execute the \fI\%net.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 .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 .sp An engine that reads messages from the redis sentinel pubsub and sends reactor events based on the channels they are subscribed to. .sp New in version 2016.3.0. .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 .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 onchange: false .ft P .fi .UNINDENT .UNINDENT .sp Script engine configs: .INDENT 0.0 .TP .B cmd Script or command to execute .TP .B output Any available saltstack deserializer .TP .B interval How often in seconds to execute the command .TP .B onchange New in version 3006.0. .sp Only fire an event if the tag\-specific output changes. Defaults to False. .UNINDENT .INDENT 0.0 .TP .B salt.engines.script.start(cmd, output=\(aqjson\(aq, interval=1, onchange=False) 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 { \(dqtag\(dq : \(dqlots/of/tacos\(dq, \(dqdata\(dq : { \(dqtoppings\(dq : \(dqcilantro\(dq } } .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 .IP \(bu 2 \fBonchange\fP \-\- Only fire an event if the tag\-specific output changes .UNINDENT .UNINDENT .UNINDENT .SS salt.engines.slack .sp An engine that reads messages from Slack and can act on them .sp New in version 2016.3.0. .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 <event\-system>\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\fP\fI of \fP\fI\%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.slack_bolt_engine .sp An engine that reads messages from Slack and can act on them .sp New in version 3006.0. .INDENT 0.0 .TP .B depends \fI\%slack_bolt\fP Python module .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 This engine requires a Slack app and a Slack 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 log in with account credentials with administrative privileges: .sp \fBhttps://api.slack.com/apps/new\fP .sp Next, click on the \fBFrom scratch\fP option from the \fBCreate an app\fP popup. Give your new app a unique name, eg. \fBSaltSlackEngine\fP, select the workspace where your app will be running, and click \fBCreate App\fP\&. .sp Next, click on \fBSocket Mode\fP and then click on the toggle button for \fBEnable Socket Mode\fP\&. In the dialog give your Socket Mode Token a unique name and then copy and save the app level token. This will be used as the \fBapp_token\fP parameter in the Slack engine configuration. .sp Next, click on \fBEvent Subscriptions\fP and ensure that \fBEnable Events\fP is in the on position. Then add the following bot events, \fBmessage.channel\fP and \fBmessage.im\fP to the \fBSubcribe to bot events\fP list. .sp Next, click on \fBOAuth & Permissions\fP and then under \fBBot Token Scope\fP, click on \fBAdd an OAuth Scope\fP\&. Ensure the following scopes are included: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBchannels:history\fP .IP \(bu 2 \fBchannels:read\fP .IP \(bu 2 \fBchat:write\fP .IP \(bu 2 \fBcommands\fP .IP \(bu 2 \fBfiles:read\fP .IP \(bu 2 \fBfiles:write\fP .IP \(bu 2 \fBim:history\fP .IP \(bu 2 \fBmpim:history\fP .IP \(bu 2 \fBusergroups:read\fP .IP \(bu 2 \fBusers:read\fP .UNINDENT .UNINDENT .UNINDENT .sp Once all the scopes have been added, click the \fBInstall to Workspace\fP button under \fBOAuth Tokens for Your Workspace\fP, then click \fBAllow\fP\&. Copy and save the \fBBot User OAuth Token\fP, this will be used as the \fBbot_token\fP parameter in the Slack engine configuration. .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 <event\-system>\fP\&. The tag for these events 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 minion\(aqs 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 Changed in version 3006.0: Updated to use slack_bolt Python library. .sp This example uses a single group called \fBdefault\fP\&. In addition, other groups are being loaded from pillar data. The users and commands defined within these groups 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_bolt: app_token: \(dqxapp\-x\-xxxxxxxxxxx\-xxxxxxxxxxxxx\-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\(dq bot_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_bolt: groups_pillar: slack_engine_pillar app_token: \(dqxapp\-x\-xxxxxxxxxxx\-xxxxxxxxxxxxx\-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\(dq bot_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_bolt_engine.SlackClient(app_token, bot_token, trigger_string) .INDENT 7.0 .TP .B can_user_run(user, command, groups) 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtag\fP (\fI\%str\fP) \-\- The tag to use when sending events to the Salt event bus. .IP \(bu 2 \fBmsg\fP (\fI\%dict\fP) \-\- The msg dictionary to send to the Salt event bus. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B format_return_text(data, function, **kwargs) Print out YAML using the block mode .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtoken\fP \-\- The return data that needs to be formatted. .IP \(bu 2 \fBtoken\fP \-\- The function that was used to generate the return data. .UNINDENT .UNINDENT .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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgroup_conf\fP (\fI\%dict\fP) \-\- The dictionary containing the groups, group members, and the commands those group members have access to. .IP \(bu 2 \fBgroups_pillar_name\fP (\fI\%str\fP) \-\- can be used to pull group configuration from the specified pillar key. .UNINDENT .UNINDENT .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. .INDENT 7.0 .TP .B Parameters \fBoutstanding_jids\fP (\fI\%list\fP) \-\- The list of job ids to check for completion. .UNINDENT .sp returns a dictionary of job id: result .UNINDENT .INDENT 7.0 .TP .B get_slack_channels(token) Get all channel names from Slack .INDENT 7.0 .TP .B Parameters \fBtoken\fP (\fI\%str\fP) \-\- The Slack token being used to allow Salt to interact with Slack. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get_slack_users(token) Get all users from Slack .INDENT 7.0 .TP .B Parameters \fBtoken\fP \-\- The Slack token being used to allow Salt to interact with Slack. .UNINDENT .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 \fBNone\fP or \fBFalse\fP 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpermitted_group\fP (\fI\%tuple\fP) \-\- A tuple containing the group name and group configuration to check for permission. .IP \(bu 2 \fBcmdline\fP (\fI\%list\fP) \-\- The command sent from Slack formatted as a list. .IP \(bu 2 \fBalias_cmdline\fP (\fI\%str\fP) \-\- An alias to a cmdline. .UNINDENT .UNINDENT .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 .INDENT 7.0 .TP .B Parameters \fBm_data\fP (\fI\%dict\fP) \-\- The message sent from Slack .UNINDENT .UNINDENT .INDENT 7.0 .TP .B message_trigger(message) .UNINDENT .INDENT 7.0 .TP .B parse_args_and_kwargs(cmdline) .INDENT 7.0 .TP .B Parameters \fBcmdline\fP (\fI\%list\fP) \-\- The command sent from Slack formatted as a list. .UNINDENT .sp returns tuple of: args (list), kwargs (dict) .UNINDENT .INDENT 7.0 .TP .B run_command_async(msg) .INDENT 7.0 .TP .B Parameters \fBmsg\fP (\fI\%dict\fP) \-\- The message dictionary that contains the command and all information. .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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmessage_generator\fP (\fIgenerator\fP\fI of \fP\fI\%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 \fBcontrol\fP (\fI\%bool\fP) \-\- If set to True, whether Slack is allowed to control Salt. .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 .UNINDENT .INDENT 0.0 .TP .B salt.engines.slack_bolt_engine.start(app_token, bot_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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapp_token\fP (\fI\%str\fP) \-\- The Slack application token used by Salt to communicate with Slack. .IP \(bu 2 \fBbot_token\fP (\fI\%str\fP) \-\- The Slack bot token used by Salt to communicate with Slack. .IP \(bu 2 \fBcontrol\fP (\fI\%bool\fP) \-\- Determines whether or not commands sent from Slack with the trigger string will control Salt, defaults to False. .IP \(bu 2 \fBtrigger\fP (\fI\%str\fP) \-\- The string that should preface all messages in Slack that should be treated as commands to send to Salt. .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- The string that should preface all messages in Slack that should be treated as commands to send to Salt. .IP \(bu 2 \fBgroup_pillars\fP \-\- A pillar key that can be used to pull group configuration. .IP \(bu 2 \fBfire_all\fP (\fI\%bool\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 <event\-system>\fP\&. The tag for these events will be prefixed with the string specified by the \fBtag\fP config option (default: \fBsalt/engines/slack\fP). .IP \(bu 2 \fBtag\fP (\fI\%str\fP) \-\- The tag to prefix all events sent to the Salt event bus. .UNINDENT .UNINDENT .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 .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 \fI\%minion_data_cache\fP option be enabled. .sp New in version 2017.7.0. .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 .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. \fI\%rest_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 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{ \fI\%groupadd\fP T} T{ Linux, NetBSD, and OpenBSD systems using \fBgroupadd(8)\fP, \fBgroupdel(8)\fP, and \fBgroupmod(8)\fP T} _ T{ \fI\%pw_group\fP T} T{ FreeBSD\-based OSes using \fBpw(8)\fP T} _ T{ \fI\%solaris_group\fP T} T{ Solaris\-based OSes using \fBgroupadd(1M)\fP, \fBgroupdel(1M)\fP, and \fBgroupmod(1M)\fP T} _ T{ \fI\%win_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{ \fI\%kernelpkg_linux_apt\fP T} T{ Debian/Ubuntu\-based distros which use \fBapt\-get\fP for package management T} _ T{ \fI\%kernelpkg_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{ \fI\%aixpkg\fP T} T{ AIX OS using \fBinstallp\fP and \fBrpm\fP T} _ T{ \fI\%aptpkg\fP T} T{ Debian/Ubuntu\-based distros which use \fBapt\-get(8)\fP for package management T} _ T{ \fI\%mac_brew_pkg\fP T} T{ Mac OS software management using \fI\%Homebrew\fP T} _ T{ \fI\%ebuildpkg\fP T} T{ Gentoo\-based systems (utilizes the \fBportage\fP python module as well as \fBemerge(1)\fP) T} _ T{ \fI\%freebsdpkg\fP T} T{ FreeBSD\-based OSes using \fBpkg_add(1)\fP T} _ T{ \fI\%openbsdpkg\fP T} T{ OpenBSD\-based OSes using \fBpkg_add(1)\fP T} _ T{ \fI\%pacmanpkg\fP T} T{ Arch Linux\-based distros using \fBpacman(8)\fP T} _ T{ \fI\%pkgin\fP T} T{ NetBSD\-based OSes using \fBpkgin(1)\fP T} _ T{ \fI\%pkgng\fP T} T{ FreeBSD\-based OSes using \fBpkg(8)\fP T} _ T{ \fI\%pkgutil\fP T} T{ Solaris\-based OSes using \fI\%OpenCSW\fP\(aqs \fBpkgutil(1)\fP T} _ T{ \fI\%solarispkg\fP T} T{ Solaris\-based OSes using \fBpkgadd(1M)\fP T} _ T{ \fI\%solarisipspkg\fP T} T{ Solaris\-based OSes using IPS \fBpkg(1)\fP T} _ T{ \fI\%win_pkg\fP T} T{ Salt\(aqs \fI\%Windows Package Manager\fP T} _ T{ \fI\%yumpkg\fP T} T{ RedHat\-based distros and derivatives using \fByum(8)\fP or \fBdnf(8)\fP T} _ T{ \fI\%zypperpkg\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{ \fI\%debian_service\fP T} T{ Debian Wheezy and earlier T} _ T{ \fI\%freebsdservice\fP T} T{ FreeBSD\-based OSes using \fBservice(8)\fP T} _ T{ \fI\%gentoo_service\fP T} T{ Gentoo Linux using \fBsysvinit\fP and \fBrc\-update(8)\fP T} _ T{ \fI\%mac_service\fP T} T{ Mac OS hosts using \fBlaunchctl(1)\fP T} _ T{ \fI\%netbsdservice\fP T} T{ NetBSD\-based OSes T} _ T{ \fI\%openbsdservice\fP T} T{ OpenBSD\-based OSes T} _ T{ \fI\%rh_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{ \fI\%smf_service\fP T} T{ Solaris\-based OSes which use SMF T} _ T{ \fI\%systemd_service\fP T} T{ Linux distros which use systemd T} _ T{ \fI\%upstart_service\fP T} T{ Ubuntu\-based distros using upstart T} _ T{ \fI\%win_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{ \fI\%aix_shadow\fP T} T{ AIX T} _ T{ \fI\%linux_shadow\fP T} T{ Linux T} _ T{ \fI\%bsd_shadow\fP T} T{ FreeBSD, OpenBSD, NetBSD T} _ T{ \fI\%solaris_shadow\fP T} T{ Solaris\-based OSes T} _ T{ \fI\%win_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{ \fI\%freebsd_sysctl\fP T} T{ FreeBSD T} _ T{ \fI\%linux_sysctl\fP T} T{ Linux T} _ T{ \fI\%mac_sysctl\fP T} T{ macOS T} _ T{ \fI\%netbsd_sysctl\fP T} T{ NetBSD T} _ T{ \fI\%openbsd_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{ \fI\%useradd\fP T} T{ Linux, NetBSD, and OpenBSD systems using \fBuseradd(8)\fP, \fBuserdel(8)\fP, and \fBusermod(8)\fP T} _ T{ \fI\%pw_user\fP T} T{ FreeBSD\-based OSes using \fBpw(8)\fP T} _ T{ \fI\%solaris_user\fP T} T{ Solaris\-based OSes using \fBuseradd(1M)\fP, \fBuserdel(1M)\fP, and \fBusermod(1M)\fP T} _ T{ \fI\%mac_user\fP T} T{ MacOS T} _ T{ \fI\%win_useradd\fP T} T{ Windows T} _ .TE .UNINDENT .UNINDENT .TS center; |l|l|. _ T{ \fI\%acme\fP T} T{ ACME / Let\(aqs Encrypt module T} _ T{ \fI\%aix_group\fP T} T{ Manage groups on Solaris T} _ T{ \fI\%aix_shadow\fP T} T{ Manage account locks on AIX systems T} _ T{ \fI\%aixpkg\fP T} T{ Package support for AIX T} _ T{ \fI\%aliases\fP T} T{ Manage the information in the aliases file T} _ T{ \fI\%alternatives\fP T} T{ Support for Alternatives system T} _ T{ \fI\%ansiblegate\fP T} T{ Ansible Support T} _ T{ \fI\%apache\fP T} T{ Support for Apache T} _ T{ \fI\%apcups\fP T} T{ Module for apcupsd T} _ T{ \fI\%apf\fP T} T{ Support for Advanced Policy Firewall (APF) maintainer Mostafa Hussein <\fI\%mostafa.hussein91@gmail.com\fP> maturity new depends python\-iptables platform Linux T} _ T{ \fI\%apkpkg\fP T} T{ Support for apk T} _ T{ \fI\%aptly\fP T} T{ Aptly Debian repository manager. T} _ T{ \fI\%aptpkg\fP T} T{ Support for APT (Advanced Packaging Tool) T} _ T{ \fI\%archive\fP T} T{ A module to wrap (non\-Windows) archive calls T} _ T{ \fI\%arista_pyeapi\fP T} T{ Arista pyeapi T} _ T{ \fI\%artifactory\fP T} T{ Module for fetching artifacts from Artifactory T} _ T{ \fI\%at\fP T} T{ Wrapper module for at(1) T} _ T{ \fI\%at_solaris\fP T} T{ Wrapper for at(1) on Solaris\-like systems T} _ T{ \fI\%augeas_cfg\fP T} T{ Manages configuration files via augeas T} _ T{ \fI\%aws_sqs\fP T} T{ Support for the Amazon Simple Queue Service. T} _ T{ \fI\%bamboohr\fP T} T{ Support for BambooHR T} _ T{ \fI\%baredoc\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{ \fI\%bcache\fP T} T{ Module for managing BCache sets T} _ T{ \fI\%beacons\fP T} T{ Module for managing the Salt beacons on a minion T} _ T{ \fI\%bigip\fP T} T{ An execution module which can manipulate an f5 bigip via iControl REST T} _ T{ \fI\%bluez_bluetooth\fP T} T{ Support for Bluetooth (using BlueZ in Linux). T} _ T{ \fI\%boto3_elasticache\fP T} T{ Execution module for Amazon Elasticache using boto3 T} _ T{ \fI\%boto3_elasticsearch\fP T} T{ Connection module for Amazon Elasticsearch Service T} _ T{ \fI\%boto3_route53\fP T} T{ Execution module for Amazon Route53 written against Boto 3 T} _ T{ \fI\%boto3_sns\fP T} T{ Connection module for Amazon SNS T} _ T{ \fI\%boto_apigateway\fP T} T{ Connection module for Amazon APIGateway T} _ T{ \fI\%boto_asg\fP T} T{ Connection module for Amazon Autoscale Groups T} _ T{ \fI\%boto_cfn\fP T} T{ Connection module for Amazon Cloud Formation T} _ T{ \fI\%boto_cloudfront\fP T} T{ Connection module for Amazon CloudFront T} _ T{ \fI\%boto_cloudtrail\fP T} T{ Connection module for Amazon CloudTrail T} _ T{ \fI\%boto_cloudwatch\fP T} T{ Connection module for Amazon CloudWatch T} _ T{ \fI\%boto_cloudwatch_event\fP T} T{ Connection module for Amazon CloudWatch Events T} _ T{ \fI\%boto_cognitoidentity\fP T} T{ Connection module for Amazon CognitoIdentity T} _ T{ \fI\%boto_datapipeline\fP T} T{ Connection module for Amazon Data Pipeline T} _ T{ \fI\%boto_dynamodb\fP T} T{ Connection module for Amazon DynamoDB T} _ T{ \fI\%boto_ec2\fP T} T{ Connection module for Amazon EC2 T} _ T{ \fI\%boto_efs\fP T} T{ Connection module for Amazon EFS T} _ T{ \fI\%boto_elasticache\fP T} T{ Connection module for Amazon Elasticache T} _ T{ \fI\%boto_elasticsearch_domain\fP T} T{ Connection module for Amazon Elasticsearch Service T} _ T{ \fI\%boto_elb\fP T} T{ Connection module for Amazon ELB T} _ T{ \fI\%boto_elbv2\fP T} T{ Connection module for Amazon ALB T} _ T{ \fI\%boto_iam\fP T} T{ Connection module for Amazon IAM T} _ T{ \fI\%boto_iot\fP T} T{ Connection module for Amazon IoT T} _ T{ \fI\%boto_kinesis\fP T} T{ Connection module for Amazon Kinesis T} _ T{ \fI\%boto_kms\fP T} T{ Connection module for Amazon KMS T} _ T{ \fI\%boto_lambda\fP T} T{ Connection module for Amazon Lambda T} _ T{ \fI\%boto_rds\fP T} T{ Connection module for Amazon RDS T} _ T{ \fI\%boto_route53\fP T} T{ Connection module for Amazon Route53 T} _ T{ \fI\%boto_s3\fP T} T{ Connection module for Amazon S3 using boto3 T} _ T{ \fI\%boto_s3_bucket\fP T} T{ Connection module for Amazon S3 Buckets T} _ T{ \fI\%boto_secgroup\fP T} T{ Connection module for Amazon Security Groups T} _ T{ \fI\%boto_sns\fP T} T{ Connection module for Amazon SNS T} _ T{ \fI\%boto_sqs\fP T} T{ Connection module for Amazon SQS T} _ T{ \fI\%boto_ssm\fP T} T{ Connection module for Amazon SSM T} _ T{ \fI\%boto_vpc\fP T} T{ Connection module for Amazon VPC T} _ T{ \fI\%bower\fP T} T{ Manage and query Bower packages T} _ T{ \fI\%bridge\fP T} T{ Module for gathering and managing bridging information T} _ T{ \fI\%bsd_shadow\fP T} T{ Manage the password database on BSD systems T} _ T{ \fI\%btrfs\fP T} T{ Module for managing BTRFS file systems. T} _ T{ \fI\%cabal\fP T} T{ Manage and query Cabal packages T} _ T{ \fI\%capirca_acl\fP T} T{ Capirca ACL T} _ T{ \fI\%cassandra_cql\fP T} T{ Cassandra Database Module T} _ T{ \fI\%celery\fP T} T{ Support for scheduling celery tasks. T} _ T{ \fI\%ceph\fP T} T{ Module to provide ceph control with salt. T} _ T{ \fI\%chassis\fP T} T{ Glue execution module to link to the \fI\%fx2 proxymodule\fP\&. T} _ T{ \fI\%chef\fP T} T{ Execute chef in server or solo mode T} _ T{ \fI\%chocolatey\fP T} T{ A module that wraps calls to the Chocolatey package manager (\fI\%http://chocolatey.org\fP) T} _ T{ \fI\%chronos\fP T} T{ Module providing a simple management interface to a chronos cluster. T} _ T{ \fI\%chroot\fP T} T{ Module for chroot :maintainer: Alberto Planas <\fI\%aplanas@suse.com\fP> :maturity: new :depends: None :platform: Linux T} _ T{ \fI\%cimc\fP T} T{ Module to provide Cisco UCS compatibility to Salt T} _ T{ \fI\%ciscoconfparse_mod\fP T} T{ Execution module for \fI\%ciscoconfparse\fP T} _ T{ \fI\%cisconso\fP T} T{ Execution module for Cisco Network Services Orchestrator Proxy minions T} _ T{ \fI\%cloud\fP T} T{ Salt\-specific interface for calling Salt Cloud directly T} _ T{ \fI\%cmdmod\fP T} T{ A module for shelling out. T} _ T{ \fI\%composer\fP T} T{ Use composer to install PHP dependencies for a directory T} _ T{ \fI\%config\fP T} T{ Return config information T} _ T{ \fI\%consul\fP T} T{ Interact with Consul T} _ T{ \fI\%container_resource\fP T} T{ Common resources for LXC and systemd\-nspawn containers T} _ T{ \fI\%cp\fP T} T{ Minion side functions for salt\-cp T} _ T{ \fI\%cpan\fP T} T{ Manage Perl modules using CPAN T} _ T{ \fI\%cron\fP T} T{ Work with cron T} _ T{ \fI\%cryptdev\fP T} T{ Salt module to manage Unix cryptsetup jobs and the crypttab file T} _ T{ \fI\%csf\fP T} T{ Support for Config Server Firewall (CSF) maintainer Mostafa Hussein <\fI\%mostafa.hussein91@gmail.com\fP> maturity new platform Linux T} _ T{ \fI\%cyg\fP T} T{ Manage cygwin packages. T} _ T{ \fI\%daemontools\fP T} T{ daemontools service module. T} _ T{ \fI\%data\fP T} T{ Manage a local persistent data structure that can hold any arbitrary data specific to the minion T} _ T{ \fI\%datadog_api\fP T} T{ An execution module that interacts with the Datadog API T} _ T{ \fI\%ddns\fP T} T{ Support for RFC 2136 dynamic DNS updates. T} _ T{ \fI\%deb_apache\fP T} T{ T} _ T{ \fI\%deb_postgres\fP T} T{ Module to provide Postgres compatibility to salt for debian family specific tools. T} _ T{ \fI\%debconfmod\fP T} T{ Support for Debconf T} _ T{ \fI\%debian_ip\fP T} T{ The networking module for Debian\-based distros T} _ T{ \fI\%debian_service\fP T} T{ Service support for Debian systems (uses update\-rc.d and /sbin/service) T} _ T{ \fI\%debuild_pkgbuild\fP T} T{ Debian Package builder system T} _ T{ \fI\%defaults\fP T} T{ Module to work with salt formula defaults files T} _ T{ \fI\%devinfo\fP T} T{ Module for devinfo :maintainer: Alberto Planas <\fI\%aplanas@suse.com\fP> :maturity: new :depends: None :platform: Linux T} _ T{ \fI\%devmap\fP T} T{ Device\-Mapper module T} _ T{ \fI\%dig\fP T} T{ Compendium of generic DNS utilities. T} _ T{ \fI\%disk\fP T} T{ Module for managing disks and blockdevices T} _ T{ \fI\%djangomod\fP T} T{ Manage Django sites T} _ T{ \fI\%dnsmasq\fP T} T{ Module for managing dnsmasq T} _ T{ \fI\%dnsutil\fP T} T{ Compendium of generic DNS utilities. T} _ T{ \fI\%dockercompose\fP T} T{ T} _ T{ \fI\%dockermod\fP T} T{ T} _ T{ \fI\%dpkg_lowpkg\fP T} T{ Support for DEB packages T} _ T{ \fI\%drac\fP T} T{ Manage Dell DRAC T} _ T{ \fI\%dracr\fP T} T{ Manage Dell DRAC. T} _ T{ \fI\%drbd\fP T} T{ DRBD administration module T} _ T{ \fI\%dummyproxy_pkg\fP T} T{ Package support for the dummy proxy used by the test suite T} _ T{ \fI\%dummyproxy_service\fP T} T{ Provide the service module for the dummy proxy used in integration tests T} _ T{ \fI\%ebuildpkg\fP T} T{ Support for Portage T} _ T{ \fI\%eix\fP T} T{ Support for Eix T} _ T{ \fI\%elasticsearch\fP T} T{ Elasticsearch \- A distributed RESTful search and analytics server T} _ T{ \fI\%environ\fP T} T{ Support for getting and setting the environment variables of the current salt process. T} _ T{ \fI\%eselect\fP T} T{ Support for eselect, Gentoo\(aqs configuration and management tool. T} _ T{ \fI\%esxcluster\fP T} T{ Module used to access the esxcluster proxy connection methods T} _ T{ \fI\%esxdatacenter\fP T} T{ Module used to access the esxdatacenter proxy connection methods T} _ T{ \fI\%esxi\fP T} T{ Glues the VMware vSphere Execution Module to the VMware ESXi Proxy Minions to the \fI\%esxi proxymodule\fP\&. T} _ T{ \fI\%esxvm\fP T} T{ Module used to access the esx proxy connection methods T} _ T{ \fI\%etcd_mod\fP T} T{ Execution module to work with etcd T} _ T{ \fI\%ethtool\fP T} T{ Module for running ethtool command T} _ T{ \fI\%event\fP T} T{ Use the \fI\%Salt Event System\fP to fire events from the master to the minion and vice\-versa. T} _ T{ \fI\%extfs\fP T} T{ Module for managing ext2/3/4 file systems T} _ T{ \fI\%file\fP T} T{ Manage information about regular files, directories, and special files on the minion, set/read user, group, mode, and data T} _ T{ \fI\%firewalld\fP T} T{ Support for firewalld. T} _ T{ \fI\%freebsd_sysctl\fP T} T{ Module for viewing and modifying sysctl parameters T} _ T{ \fI\%freebsd_update\fP T} T{ Support for freebsd\-update utility on FreeBSD. T} _ T{ \fI\%freebsdjail\fP T} T{ The jail module for FreeBSD T} _ T{ \fI\%freebsdkmod\fP T} T{ Module to manage FreeBSD kernel modules T} _ T{ \fI\%freebsdpkg\fP T} T{ Remote package support using \fBpkg_add(1)\fP T} _ T{ \fI\%freebsdports\fP T} T{ Install software from the FreeBSD \fBports(7)\fP system T} _ T{ \fI\%freebsdservice\fP T} T{ The service module for FreeBSD T} _ T{ \fI\%freezer\fP T} T{ Module for freezer :maintainer: Alberto Planas <\fI\%aplanas@suse.com\fP> :maturity: new :depends: None :platform: Linux T} _ T{ \fI\%gcp_addon\fP T} T{ A route is a rule that specifies how certain packets should be handled by the virtual network. T} _ T{ \fI\%gem\fP T} T{ Manage ruby gems. T} _ T{ \fI\%genesis\fP T} T{ Module for managing container and VM images T} _ T{ \fI\%gentoo_service\fP T} T{ Top level package command wrapper, used to translate the os detected by grains to the correct service manager T} _ T{ \fI\%gentoolkitmod\fP T} T{ Support for Gentoolkit T} _ T{ \fI\%git\fP T} T{ Support for the Git SCM T} _ T{ \fI\%github\fP T} T{ Module for interacting with the GitHub v3 API. T} _ T{ \fI\%glanceng\fP T} T{ Glance module for interacting with OpenStack Glance T} _ T{ \fI\%glassfish\fP T} T{ Module for working with the Glassfish/Payara 4.x management API . T} _ T{ \fI\%glusterfs\fP T} T{ Manage a glusterfs pool T} _ T{ \fI\%gnomedesktop\fP T} T{ GNOME implementations T} _ T{ \fI\%google_chat\fP T} T{ Module for sending messages to google chat. T} _ T{ \fI\%gpg\fP T} T{ Manage GPG keychains, add keys, create keys, retrieve keys from keyservers. T} _ T{ \fI\%grafana4\fP T} T{ Module for working with the Grafana v4 API T} _ T{ \fI\%grains\fP T} T{ Return/control aspects of the grains data T} _ T{ \fI\%groupadd\fP T} T{ Manage groups on Linux, OpenBSD and NetBSD T} _ T{ \fI\%grub_legacy\fP T} T{ Support for GRUB Legacy T} _ T{ \fI\%guestfs\fP T} T{ Interact with virtual machine images via libguestfs T} _ T{ \fI\%hadoop\fP T} T{ Support for hadoop T} _ T{ \fI\%haproxyconn\fP T} T{ Support for haproxy T} _ T{ \fI\%hashutil\fP T} T{ A collection of hashing and encoding functions T} _ T{ \fI\%heat\fP T} T{ Module for handling OpenStack Heat calls T} _ T{ \fI\%helm\fP T} T{ Interface with Helm T} _ T{ \fI\%hg\fP T} T{ Support for the Mercurial SCM T} _ T{ \fI\%highstate_doc\fP T} T{ This module renders highstate configuration into a more human readable format. T} _ T{ \fI\%hosts\fP T} T{ Manage the information in the hosts file T} _ T{ \fI\%http\fP T} T{ Module for making various web calls. T} _ T{ \fI\%icinga2\fP T} T{ Module to provide icinga2 compatibility to salt. T} _ T{ \fI\%idem\fP T} T{ Idem Support T} _ T{ \fI\%ifttt\fP T} T{ Support for IFTTT T} _ T{ \fI\%ilo\fP T} T{ Manage HP ILO T} _ T{ \fI\%incron\fP T} T{ Work with incron T} _ T{ \fI\%influxdb08mod\fP T} T{ InfluxDB \- A distributed time series database T} _ T{ \fI\%influxdbmod\fP T} T{ InfluxDB \- A distributed time series database T} _ T{ \fI\%infoblox\fP T} T{ This module have been tested on infoblox API v1.2.1, other versions of the API are likly workable. T} _ T{ \fI\%ini_manage\fP T} T{ Edit ini files T} _ T{ \fI\%inspectlib\fP T} T{ T} _ T{ \fI\%inspectlib.collector\fP T} T{ T} _ T{ \fI\%inspectlib.dbhandle\fP T} T{ T} _ T{ \fI\%inspectlib.entities\fP T} T{ T} _ T{ \fI\%inspectlib.exceptions\fP T} T{ T} _ T{ \fI\%inspectlib.fsdb\fP T} T{ .INDENT 0.0 .TP .B codeauthor Bo Maryniuk <\fI\%bo@suse.de\fP> .UNINDENT T} _ T{ \fI\%inspectlib.kiwiproc\fP T} T{ T} _ T{ \fI\%inspectlib.query\fP T} T{ T} _ T{ \fI\%inspector\fP T} T{ Module for full system inspection. T} _ T{ \fI\%introspect\fP T} T{ Functions to perform introspection on a minion, and return data in a format usable by Salt States T} _ T{ \fI\%iosconfig\fP T} T{ Cisco IOS configuration manipulation helpers T} _ T{ \fI\%ipmi\fP T} T{ Support IPMI commands over LAN. T} _ T{ \fI\%ipset\fP T} T{ Support for ipset T} _ T{ \fI\%iptables\fP T} T{ Support for iptables T} _ T{ \fI\%iwtools\fP T} T{ Support for Wireless Tools for Linux T} _ T{ \fI\%jboss7\fP T} T{ Module for managing JBoss AS 7 through the CLI interface. T} _ T{ \fI\%jboss7_cli\fP T} T{ Module for low\-level interaction with JbossAS7 through CLI. T} _ T{ \fI\%jenkinsmod\fP T} T{ Module for controlling Jenkins T} _ T{ \fI\%jinja\fP T} T{ Module for checking jinja maps and verifying the result of loading JSON/YAML files T} _ T{ \fI\%jira_mod\fP T} T{ JIRA Execution module T} _ T{ \fI\%junos\fP T} T{ Module to interact with Junos devices. T} _ T{ \fI\%k8s\fP T} T{ T} _ T{ \fI\%kapacitor\fP T} T{ Kapacitor execution module. T} _ T{ \fI\%kerberos\fP T} T{ Manage Kerberos KDC T} _ T{ \fI\%kernelpkg_linux_apt\fP T} T{ Manage Linux kernel packages on APT\-based systems T} _ T{ \fI\%kernelpkg_linux_yum\fP T} T{ Manage Linux kernel packages on YUM\-based systems T} _ T{ \fI\%key\fP T} T{ Functions to view the minion\(aqs public key information T} _ T{ \fI\%keyboard\fP T} T{ Module for managing keyboards on supported POSIX\-like systems using systemd, or such as Redhat, Debian and Gentoo. T} _ T{ \fI\%keystone\fP T} T{ Module for handling openstack keystone calls. T} _ T{ \fI\%keystoneng\fP T} T{ Keystone module for interacting with OpenStack Keystone T} _ T{ \fI\%keystore\fP T} T{ Module to interact with keystores T} _ T{ \fI\%kmod\fP T} T{ Module to manage Linux kernel modules T} _ T{ \fI\%kubeadm\fP T} T{ T} _ T{ \fI\%kubernetesmod\fP T} T{ T} _ T{ \fI\%launchctl_service\fP T} T{ Module for the management of MacOS systems that use launchd/launchctl T} _ T{ \fI\%layman\fP T} T{ Support for Layman T} _ T{ \fI\%ldap3\fP T} T{ Query and modify an LDAP database (alternative interface) T} _ T{ \fI\%ldapmod\fP T} T{ Salt interface to LDAP commands T} _ T{ \fI\%libcloud_compute\fP T} T{ Apache Libcloud Compute Management T} _ T{ \fI\%libcloud_dns\fP T} T{ Apache Libcloud DNS Management T} _ T{ \fI\%libcloud_loadbalancer\fP T} T{ Apache Libcloud Load Balancer Management T} _ T{ \fI\%libcloud_storage\fP T} T{ Apache Libcloud Storage Management T} _ T{ \fI\%linux_acl\fP T} T{ Support for Linux File Access Control Lists T} _ T{ \fI\%linux_ip\fP T} T{ The networking module for Non\-RH/Deb Linux distros T} _ T{ \fI\%linux_lvm\fP T} T{ Support for Linux LVM2 T} _ T{ \fI\%linux_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{ \fI\%linux_shadow\fP T} T{ Manage the shadow file on Linux systems T} _ T{ \fI\%linux_sysctl\fP T} T{ Module for viewing and modifying sysctl parameters T} _ T{ \fI\%localemod\fP T} T{ Module for managing locales on POSIX\-like systems. T} _ T{ \fI\%locate\fP T} T{ Module for using the locate utilities T} _ T{ \fI\%logadm\fP T} T{ Module for managing Solaris logadm based log rotations. T} _ T{ \fI\%logmod\fP T} T{ On\-demand logging T} _ T{ \fI\%logrotate\fP T} T{ Module for managing logrotate. T} _ T{ \fI\%lvs\fP T} T{ Support for LVS (Linux Virtual Server) T} _ T{ \fI\%lxc\fP T} T{ Control Linux Containers via Salt T} _ T{ \fI\%lxd\fP T} T{ Module for managing the LXD daemon and its containers. T} _ T{ \fI\%mac_assistive\fP T} T{ This module allows you to manage assistive access on macOS minions with 10.9+ T} _ T{ \fI\%mac_brew_pkg\fP T} T{ Homebrew for macOS T} _ T{ \fI\%mac_desktop\fP T} T{ macOS implementations of various commands in the \(dqdesktop\(dq interface T} _ T{ \fI\%mac_group\fP T} T{ Manage groups on Mac OS 10.7+ T} _ T{ \fI\%mac_keychain\fP T} T{ Install certificates into the keychain on Mac OS T} _ T{ \fI\%mac_pkgutil\fP T} T{ Installer support for macOS. T} _ T{ \fI\%mac_portspkg\fP T} T{ Support for MacPorts under macOS. T} _ T{ \fI\%mac_power\fP T} T{ Module for editing power settings on macOS T} _ T{ \fI\%mac_service\fP T} T{ The service module for macOS T} _ T{ \fI\%mac_shadow\fP T} T{ Manage macOS local directory passwords and policies T} _ T{ \fI\%mac_softwareupdate\fP T} T{ Support for the softwareupdate command on MacOS. T} _ T{ \fI\%mac_sysctl\fP T} T{ Module for viewing and modifying sysctl parameters T} _ T{ \fI\%mac_system\fP T} T{ System module for sleeping, restarting, and shutting down the system on Mac OS X T} _ T{ \fI\%mac_timezone\fP T} T{ Module for editing date/time settings on macOS T} _ T{ \fI\%mac_user\fP T} T{ Manage users on Mac OS 10.7+ T} _ T{ \fI\%mac_xattr\fP T} T{ This module allows you to manage extended attributes on files or directories T} _ T{ \fI\%macdefaults\fP T} T{ Set defaults on Mac OS T} _ T{ \fI\%macpackage\fP T} T{ Install pkg, dmg and .app applications on macOS minions. T} _ T{ \fI\%makeconf\fP T} T{ Support for modifying make.conf under Gentoo T} _ T{ \fI\%mandrill\fP T} T{ Mandrill T} _ T{ \fI\%marathon\fP T} T{ Module providing a simple management interface to a marathon cluster. T} _ T{ \fI\%match\fP T} T{ The match module allows for match routines to be run and determine target specs T} _ T{ \fI\%mattermost\fP T} T{ Module for sending messages to Mattermost T} _ T{ \fI\%mdadm_raid\fP T} T{ Salt module to manage RAID arrays with mdadm T} _ T{ \fI\%mdata\fP T} T{ Module for managaging metadata in SmartOS Zones T} _ T{ \fI\%memcached\fP T} T{ Module for Management of Memcached Keys T} _ T{ \fI\%mine\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{ \fI\%minion\fP T} T{ Module to provide information about minions T} _ T{ \fI\%mod_random\fP T} T{ Provides access to randomness generators. T} _ T{ \fI\%modjk\fP T} T{ Control Modjk via the Apache Tomcat \(dqStatus\(dq worker (\fI\%http://tomcat.apache.org/connectors\-doc/reference/status.html\fP) T} _ T{ \fI\%mongodb\fP T} T{ Module to provide MongoDB functionality to Salt T} _ T{ \fI\%monit\fP T} T{ Monit service module. T} _ T{ \fI\%moosefs\fP T} T{ Module for gathering and managing information about MooseFS T} _ T{ \fI\%mount\fP T} T{ Salt module to manage Unix mounts and the fstab file T} _ T{ \fI\%mssql\fP T} T{ Module to provide MS SQL Server compatibility to salt. T} _ T{ \fI\%msteams\fP T} T{ Module for sending messages to MS Teams T} _ T{ \fI\%munin\fP T} T{ Run munin plugins/checks from salt and format the output as data. T} _ T{ \fI\%mysql\fP T} T{ Module to provide MySQL compatibility to salt. T} _ T{ \fI\%nacl\fP T} T{ This module helps include encrypted passwords in pillars, grains and salt state files. T} _ T{ \fI\%nagios\fP T} T{ Run nagios plugins/checks from salt and get the return as data. T} _ T{ \fI\%nagios_rpc\fP T} T{ Check Host & Service status from Nagios via JSON RPC. T} _ T{ \fI\%namecheap_domains\fP T} T{ Namecheap Domain Management T} _ T{ \fI\%namecheap_domains_dns\fP T} T{ Namecheap DNS Management T} _ T{ \fI\%namecheap_domains_ns\fP T} T{ Namecheap Nameserver Management T} _ T{ \fI\%namecheap_ssl\fP T} T{ Namecheap SSL Certificate Management T} _ T{ \fI\%namecheap_users\fP T} T{ Namecheap User Management T} _ T{ \fI\%napalm_bgp\fP T} T{ NAPALM BGP T} _ T{ \fI\%napalm_formula\fP T} T{ NAPALM Formula helpers T} _ T{ \fI\%napalm_mod\fP T} T{ NAPALM helpers T} _ T{ \fI\%napalm_netacl\fP T} T{ NAPALM ACL T} _ T{ \fI\%napalm_network\fP T} T{ NAPALM Network T} _ T{ \fI\%napalm_ntp\fP T} T{ NAPALM NTP T} _ T{ \fI\%napalm_probes\fP T} T{ NAPALM Probes T} _ T{ \fI\%napalm_route\fP T} T{ NAPALM Route T} _ T{ \fI\%napalm_snmp\fP T} T{ NAPALM SNMP T} _ T{ \fI\%napalm_users\fP T} T{ NAPALM Users T} _ T{ \fI\%napalm_yang_mod\fP T} T{ NAPALM YANG T} _ T{ \fI\%netaddress\fP T} T{ Module for getting information about network addresses. T} _ T{ \fI\%netbox\fP T} T{ NetBox T} _ T{ \fI\%netbsd_sysctl\fP T} T{ Module for viewing and modifying sysctl parameters T} _ T{ \fI\%netbsdservice\fP T} T{ The service module for NetBSD T} _ T{ \fI\%netmiko_mod\fP T} T{ Netmiko Execution Module T} _ T{ \fI\%netscaler\fP T} T{ Module to provide Citrix Netscaler compatibility to Salt (compatible with netscaler 9.2+) T} _ T{ \fI\%network\fP T} T{ Module for gathering and managing network information T} _ T{ \fI\%neutron\fP T} T{ Module for handling OpenStack Neutron calls T} _ T{ \fI\%neutronng\fP T} T{ Neutron module for interacting with OpenStack Neutron T} _ T{ \fI\%nexus\fP T} T{ Module for fetching artifacts from Nexus 3.x T} _ T{ \fI\%nfs3\fP T} T{ Module for managing NFS version 3. T} _ T{ \fI\%nftables\fP T} T{ Support for nftables T} _ T{ \fI\%nginx\fP T} T{ Support for nginx T} _ T{ \fI\%nilrt_ip\fP T} T{ The networking module for NI Linux Real\-Time distro T} _ T{ \fI\%nix\fP T} T{ Work with Nix packages T} _ T{ \fI\%nova\fP T} T{ Module for handling OpenStack Nova calls T} _ T{ \fI\%npm\fP T} T{ Manage and query NPM packages. T} _ T{ \fI\%nspawn\fP T} T{ Manage nspawn containers T} _ T{ \fI\%nxos\fP T} T{ Execution module for Cisco NX OS Switches. T} _ T{ \fI\%nxos_api\fP T} T{ Execution module to manage Cisco Nexus Switches (NX\-OS) over the NX\-API T} _ T{ \fI\%nxos_upgrade\fP T} T{ Execution module to upgrade Cisco NX\-OS Switches. T} _ T{ \fI\%omapi\fP T} T{ This module interacts with an ISC DHCP Server via OMAPI. T} _ T{ \fI\%openbsd_sysctl\fP T} T{ Module for viewing and modifying OpenBSD sysctl parameters T} _ T{ \fI\%openbsdpkg\fP T} T{ Package support for OpenBSD T} _ T{ \fI\%openbsdrcctl_service\fP T} T{ The rcctl service module for OpenBSD T} _ T{ \fI\%openbsdservice\fP T} T{ The service module for OpenBSD T} _ T{ \fI\%openscap\fP T} T{ Module for OpenSCAP Management T} _ T{ \fI\%openstack_config\fP T} T{ Modify, retrieve, or delete values from OpenStack configuration files. T} _ T{ \fI\%openstack_mng\fP T} T{ Module for OpenStack Management T} _ T{ \fI\%openvswitch\fP T} T{ Support for Open vSwitch \- module with basic Open vSwitch commands. T} _ T{ \fI\%opkg\fP T} T{ Support for Opkg T} _ T{ \fI\%opsgenie\fP T} T{ Module for sending data to OpsGenie T} _ T{ \fI\%oracle\fP T} T{ Oracle DataBase connection module T} _ T{ \fI\%osquery\fP T} T{ Support for OSQuery \- \fI\%https://osquery.io\fP\&. T} _ T{ \fI\%out\fP T} T{ Output Module T} _ T{ \fI\%pacmanpkg\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{ \fI\%pagerduty\fP T} T{ Module for Firing Events via PagerDuty T} _ T{ \fI\%pagerduty_util\fP T} T{ Module for manageing PagerDuty resource T} _ T{ \fI\%pam\fP T} T{ Support for pam T} _ T{ \fI\%panos\fP T} T{ Module to provide Palo Alto compatibility to Salt T} _ T{ \fI\%parallels\fP T} T{ Manage Parallels Desktop VMs with \fBprlctl\fP and \fBprlsrvctl\fP\&. T} _ T{ \fI\%parted_partition\fP T} T{ Module for managing partitions on POSIX\-like systems. T} _ T{ \fI\%pcs\fP T} T{ Configure a Pacemaker/Corosync cluster with PCS T} _ T{ \fI\%pdbedit\fP T} T{ Manage accounts in Samba\(aqs passdb using pdbedit T} _ T{ \fI\%pecl\fP T} T{ Manage PHP pecl extensions. T} _ T{ \fI\%peeringdb\fP T} T{ PeeringDB Module T} _ T{ \fI\%pf\fP T} T{ Control the OpenBSD packet filter (PF). T} _ T{ \fI\%philips_hue\fP T} T{ Philips HUE lamps module for proxy. T} _ T{ \fI\%pillar\fP T} T{ Extract the pillar data for this minion T} _ T{ \fI\%pip\fP T} T{ Install Python packages with pip to either the system or a virtualenv T} _ T{ \fI\%pkg_resource\fP T} T{ Resources needed by pkg providers T} _ T{ \fI\%pkgin\fP T} T{ Package support for pkgin based systems, inspired from freebsdpkg module T} _ T{ \fI\%pkgng\fP T} T{ Support for \fBpkgng\fP, the new package manager for FreeBSD T} _ T{ \fI\%pkgutil\fP T} T{ Pkgutil support for Solaris T} _ T{ \fI\%portage_config\fP T} T{ Configure \fBportage(5)\fP T} _ T{ \fI\%postfix\fP T} T{ Support for Postfix T} _ T{ \fI\%postgres\fP T} T{ Module to provide Postgres compatibility to salt. T} _ T{ \fI\%poudriere\fP T} T{ Support for poudriere T} _ T{ \fI\%powerpath\fP T} T{ powerpath support. T} _ T{ \fI\%proxy\fP T} T{ This module allows you to manage proxy settings T} _ T{ \fI\%ps\fP T} T{ A salt interface to psutil, a system and process library. T} _ T{ \fI\%publish\fP T} T{ Publish a command from a minion to a target T} _ T{ \fI\%puppet\fP T} T{ Execute puppet routines T} _ T{ \fI\%purefa\fP T} T{ Management of Pure Storage FlashArray T} _ T{ \fI\%purefb\fP T} T{ Management of Pure Storage FlashBlade T} _ T{ \fI\%pushbullet\fP T} T{ Module for sending messages to Pushbullet (\fI\%https://www.pushbullet.com\fP) T} _ T{ \fI\%pushover_notify\fP T} T{ T} _ T{ \fI\%pw_group\fP T} T{ Manage groups on FreeBSD T} _ T{ \fI\%pw_user\fP T} T{ Manage users with the pw command T} _ T{ \fI\%pyenv\fP T} T{ Manage python installations with pyenv. T} _ T{ \fI\%qemu_img\fP T} T{ Qemu\-img Command Wrapper T} _ T{ \fI\%qemu_nbd\fP T} T{ Qemu Command Wrapper T} _ T{ \fI\%quota\fP T} T{ Module for managing quotas on POSIX\-like systems. T} _ T{ \fI\%rabbitmq\fP T} T{ Module to provide RabbitMQ compatibility to Salt. T} _ T{ \fI\%rallydev\fP T} T{ Support for RallyDev T} _ T{ \fI\%random_org\fP T} T{ Module for retrieving random information from Random.org T} _ T{ \fI\%rbac_solaris\fP T} T{ Module for Solaris\(aq Role\-Based Access Control T} _ T{ \fI\%rbenv\fP T} T{ Manage ruby installations with rbenv. T} _ T{ \fI\%rdp\fP T} T{ Manage RDP Service on Windows servers T} _ T{ \fI\%rebootmgr\fP T} T{ Module for rebootmgr :maintainer: Alberto Planas <\fI\%aplanas@suse.com\fP> :maturity: new :depends: None :platform: Linux T} _ T{ \fI\%redismod\fP T} T{ Module to provide redis functionality to Salt T} _ T{ \fI\%reg\fP T} T{ Manage the Windows registry T} _ T{ \fI\%rest_pkg\fP T} T{ Package support for the REST example T} _ T{ \fI\%rest_sample_utils\fP T} T{ Utility functions for the rest_sample T} _ T{ \fI\%rest_service\fP T} T{ Provide the service module for the proxy\-minion REST sample T} _ T{ \fI\%restartcheck\fP T} T{ checkrestart functionality for Debian and Red Hat Based systems T} _ T{ \fI\%restconf\fP T} T{ Execution module for RESTCONF Proxy minions T} _ T{ \fI\%ret\fP T} T{ Module to integrate with the returner system and retrieve data sent to a salt returner T} _ T{ \fI\%rh_ip\fP T} T{ The networking module for RHEL/Fedora based distros T} _ T{ \fI\%rh_service\fP T} T{ Service support for RHEL\-based systems, including support for both upstart and sysvinit T} _ T{ \fI\%riak\fP T} T{ Riak Salt Module T} _ T{ \fI\%rpm_lowpkg\fP T} T{ Support for rpm T} _ T{ \fI\%rpmbuild_pkgbuild\fP T} T{ RPM Package builder system T} _ T{ \fI\%rsync\fP T} T{ Wrapper for rsync T} _ T{ \fI\%runit\fP T} T{ runit service module (\fI\%http://smarden.org/runit\fP) T} _ T{ \fI\%rvm\fP T} T{ Manage ruby installations and gemsets with RVM, the Ruby Version Manager. T} _ T{ \fI\%s3\fP T} T{ Connection module for Amazon S3 T} _ T{ \fI\%s6\fP T} T{ s6 service module T} _ T{ \fI\%salt_proxy\fP T} T{ Salt proxy module T} _ T{ \fI\%salt_version\fP T} T{ Access Salt\(aqs elemental release code\-names. T} _ T{ \fI\%saltcheck\fP T} T{ A module for testing the logic of states and highstates on salt minions T} _ T{ \fI\%saltcloudmod\fP T} T{ Control a salt cloud system T} _ T{ \fI\%saltutil\fP T} T{ The Saltutil module is used to manage the state of the salt minion itself. T} _ T{ \fI\%schedule\fP T} T{ Module for managing the Salt schedule on a minion T} _ T{ \fI\%scp_mod\fP T} T{ SCP Module T} _ T{ \fI\%scsi\fP T} T{ SCSI administration module T} _ T{ \fI\%sdb\fP T} T{ Module for Manipulating Data via the Salt DB API T} _ T{ \fI\%seed\fP T} T{ Virtual machine image management tools T} _ T{ \fI\%selinux\fP T} T{ Execute calls on selinux T} _ T{ \fI\%sensehat\fP T} T{ Module for controlling the LED matrix or reading environment data on the SenseHat of a Raspberry Pi. T} _ T{ \fI\%sensors\fP T} T{ Read lm\-sensors T} _ T{ \fI\%serverdensity_device\fP T} T{ Wrapper around Server Density API T} _ T{ \fI\%servicenow\fP T} T{ Module for execution of ServiceNow CI (configuration items) T} _ T{ \fI\%slack_notify\fP T} T{ Module for sending messages to Slack T} _ T{ \fI\%slackware_service\fP T} T{ The service module for Slackware T} _ T{ \fI\%slsutil\fP T} T{ Utility functions for use with or in SLS files T} _ T{ \fI\%smartos_imgadm\fP T} T{ Module for running imgadm command on SmartOS T} _ T{ \fI\%smartos_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{ \fI\%smartos_virt\fP T} T{ virst compatibility module for managing VMs on SmartOS T} _ T{ \fI\%smartos_vmadm\fP T} T{ Module for running vmadm command on SmartOS T} _ T{ \fI\%smbios\fP T} T{ Interface to SMBIOS/DMI T} _ T{ \fI\%smf_service\fP T} T{ Service support for Solaris 10 and 11, should work with other systems that use SMF also. T} _ T{ \fI\%smtp\fP T} T{ Module for Sending Messages via SMTP T} _ T{ \fI\%snapper\fP T} T{ Module to manage filesystem snapshots with snapper T} _ T{ \fI\%solaris_fmadm\fP T} T{ Module for running fmadm and fmdump on Solaris T} _ T{ \fI\%solaris_group\fP T} T{ Manage groups on Solaris T} _ T{ \fI\%solaris_shadow\fP T} T{ Manage the password database on Solaris systems T} _ T{ \fI\%solaris_system\fP T} T{ Support for reboot, shutdown, etc T} _ T{ \fI\%solaris_user\fP T} T{ Manage users with the useradd command T} _ T{ \fI\%solarisipspkg\fP T} T{ IPS pkg support for Solaris T} _ T{ \fI\%solarispkg\fP T} T{ Package support for Solaris T} _ T{ \fI\%solr\fP T} T{ Apache Solr Salt Module T} _ T{ \fI\%solrcloud\fP T} T{ Module for solrcloud configuration T} _ T{ \fI\%splunk\fP T} T{ Module for interop with the Splunk API T} _ T{ \fI\%splunk_search\fP T} T{ Module for interop with the Splunk API T} _ T{ \fI\%sqlite3\fP T} T{ Support for SQLite3 T} _ T{ \fI\%ssh\fP T} T{ Manage client ssh components T} _ T{ \fI\%ssh_pkg\fP T} T{ Service support for the REST example T} _ T{ \fI\%ssh_service\fP T} T{ Provide the service module for the proxy\-minion SSH sample . T} _ T{ \fI\%state\fP T} T{ Control the state system on the minion. T} _ T{ \fI\%status\fP T} T{ Module for returning various status data about a minion. T} _ T{ \fI\%statuspage\fP T} T{ StatusPage T} _ T{ \fI\%supervisord\fP T} T{ Provide the service module for system supervisord or supervisord in a virtualenv T} _ T{ \fI\%suse_apache\fP T} T{ T} _ T{ \fI\%suse_ip\fP T} T{ The networking module for SUSE based distros T} _ T{ \fI\%svn\fP T} T{ Subversion SCM T} _ T{ \fI\%swarm\fP T} T{ Docker Swarm Module using Docker\(aqs Python SDK T} _ T{ \fI\%swift\fP T} T{ Module for handling OpenStack Swift calls Author: Anthony Stanton <\fI\%anthony.stanton@gmail.com\fP> T} _ T{ \fI\%sysbench\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{ \fI\%sysfs\fP T} T{ Module for interfacing with SysFS T} _ T{ \fI\%syslog_ng\fP T} T{ Module for getting information about syslog\-ng T} _ T{ \fI\%sysmod\fP T} T{ The sys module provides information about the available functions on the minion T} _ T{ \fI\%sysrc\fP T} T{ sysrc module for FreeBSD T} _ T{ \fI\%system\fP T} T{ Support for reboot, shutdown, etc on POSIX\-like systems. T} _ T{ \fI\%system_profiler\fP T} T{ System Profiler Module T} _ T{ \fI\%systemd_service\fP T} T{ Provides the service module for systemd T} _ T{ \fI\%telegram\fP T} T{ Module for sending messages via Telegram. T} _ T{ \fI\%telemetry\fP T} T{ Connection module for Telemetry T} _ T{ \fI\%temp\fP T} T{ Simple module for creating temporary directories and files T} _ T{ \fI\%test\fP T} T{ Module for running arbitrary tests T} _ T{ \fI\%test_virtual\fP T} T{ Module for testing that a __virtual__ function returning False will not be available via the Salt Loader. T} _ T{ \fI\%testinframod\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{ \fI\%textfsm_mod\fP T} T{ TextFSM T} _ T{ \fI\%timezone\fP T} T{ Module for managing timezone on POSIX\-like systems. T} _ T{ \fI\%tls\fP T} T{ A salt module for SSL/TLS. T} _ T{ \fI\%tomcat\fP T} T{ Support for Tomcat T} _ T{ \fI\%trafficserver\fP T} T{ Apache Traffic Server execution module. T} _ T{ \fI\%transactional_update\fP T} T{ Transactional update T} _ T{ \fI\%travisci\fP T} T{ Commands for working with travisci. T} _ T{ \fI\%tuned\fP T} T{ Interface to Red Hat tuned\-adm module T} _ T{ \fI\%twilio_notify\fP T} T{ Module for notifications via Twilio T} _ T{ \fI\%udev\fP T} T{ Manage and query udev info T} _ T{ \fI\%upstart_service\fP T} T{ Module for the management of upstart systems. T} _ T{ \fI\%uptime\fP T} T{ Wrapper around uptime API T} _ T{ \fI\%useradd\fP T} T{ Manage users with the useradd command T} _ T{ \fI\%uwsgi\fP T} T{ uWSGI stats server \fI\%https://uwsgi\-docs.readthedocs.io/en/latest/StatsServer.html\fP T} _ T{ \fI\%vagrant\fP T} T{ Work with virtual machines managed by Vagrant. T} _ T{ \fI\%varnish\fP T} T{ Support for Varnish T} _ T{ \fI\%vault\fP T} T{ T} _ T{ \fI\%vbox_guest\fP T} T{ VirtualBox Guest Additions installer T} _ T{ \fI\%vboxmanage\fP T} T{ Support for VirtualBox using the VBoxManage command T} _ T{ \fI\%vcenter\fP T} T{ Module used to access the vcenter proxy connection methods T} _ T{ \fI\%victorops\fP T} T{ Support for VictorOps T} _ T{ \fI\%virt\fP T} T{ Work with virtual machines managed by libvirt T} _ T{ \fI\%virtualenv_mod\fP T} T{ Create virtualenv environments. T} _ T{ \fI\%vmctl\fP T} T{ Manage vms running on the OpenBSD VMM hypervisor using vmctl(8). T} _ T{ \fI\%vsphere\fP T} T{ Manage VMware vCenter servers and ESXi hosts. T} _ T{ \fI\%webutil\fP T} T{ Support for htpasswd command. T} _ T{ \fI\%win_appx\fP T} T{ Manage provisioned apps T} _ T{ \fI\%win_auditpol\fP T} T{ A salt module for modifying the audit policies on the machine T} _ T{ \fI\%win_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{ \fI\%win_certutil\fP T} T{ This module allows you to install certificates into the windows certificate manager. T} _ T{ \fI\%win_dacl\fP T} T{ Manage DACLs on Windows T} _ T{ \fI\%win_disk\fP T} T{ Module for gathering disk information on Windows T} _ T{ \fI\%win_dism\fP T} T{ Install features/packages for Windows using DISM, which is useful for minions not running server versions\ of Windows. T} _ T{ \fI\%win_dns_client\fP T} T{ Module for configuring DNS Client on Windows systems T} _ T{ \fI\%win_dsc\fP T} T{ Module for working with Windows PowerShell DSC (Desired State Configuration) T} _ T{ \fI\%win_event\fP T} T{ A module for working with the Windows Event log system. T} _ T{ \fI\%win_file\fP T} T{ Manage information about files on the minion, set/read user, group data, modify the ACL of files/directories T} _ T{ \fI\%win_firewall\fP T} T{ Module for configuring Windows Firewall using \fBnetsh\fP T} _ T{ \fI\%win_groupadd\fP T} T{ Manage groups on Windows T} _ T{ \fI\%win_iis\fP T} T{ Microsoft IIS site management via WebAdministration powershell module T} _ T{ \fI\%win_ip\fP T} T{ The networking module for Windows based systems T} _ T{ \fI\%win_lgpo\fP T} T{ Manage Local Policy on Windows T} _ T{ \fI\%win_lgpo_reg\fP T} T{ LGPO \- Registry.pol T} _ T{ \fI\%win_license\fP T} T{ This module allows you to manage windows licensing via slmgr.vbs T} _ T{ \fI\%win_network\fP T} T{ Module for gathering and managing network information T} _ T{ \fI\%win_ntp\fP T} T{ Management of NTP servers on Windows T} _ T{ \fI\%win_path\fP T} T{ Manage the Windows System PATH T} _ T{ \fI\%win_pkg\fP T} T{ A module to manage software on Windows T} _ T{ \fI\%win_pki\fP T} T{ Microsoft certificate management via the PKI Client PowerShell module. T} _ T{ \fI\%win_powercfg\fP T} T{ This module allows you to control the power settings of a windows minion via powercfg. T} _ T{ \fI\%win_psget\fP T} T{ Module for managing PowerShell through PowerShellGet (PSGet) T} _ T{ \fI\%win_servermanager\fP T} T{ Manage Windows features via the ServerManager powershell module. T} _ T{ \fI\%win_service\fP T} T{ Windows Service module. T} _ T{ \fI\%win_shadow\fP T} T{ Manage the shadow file T} _ T{ \fI\%win_shortcut\fP T} T{ Execution module for creating shortcuts on Windows. T} _ T{ \fI\%win_smtp_server\fP T} T{ Module for managing IIS SMTP server configuration on Windows servers. T} _ T{ \fI\%win_snmp\fP T} T{ Module for managing SNMP service settings on Windows servers. T} _ T{ \fI\%win_status\fP T} T{ Module for returning various status data about a minion. T} _ T{ \fI\%win_system\fP T} T{ Module for managing Windows systems and getting Windows system information. T} _ T{ \fI\%win_task\fP T} T{ Windows Task Scheduler Module . T} _ T{ \fI\%win_timezone\fP T} T{ Module for managing timezone on Windows systems. T} _ T{ \fI\%win_useradd\fP T} T{ Module for managing Windows Users. T} _ T{ \fI\%win_wua\fP T} T{ Module for managing Windows Updates using the Windows Update Agent. T} _ T{ \fI\%win_wusa\fP T} T{ Microsoft Update files management via wusa.exe T} _ T{ \fI\%winrepo\fP T} T{ Module to manage Windows software repo on a Standalone Minion T} _ T{ \fI\%wordpress\fP T} T{ This module is used to manage Wordpress installations T} _ T{ \fI\%x509\fP T} T{ Manage X509 certificates T} _ T{ \fI\%x509_v2\fP T} T{ Manage X.509 certificates T} _ T{ \fI\%xapi_virt\fP T} T{ This module (mostly) uses the XenAPI to manage Xen virtual machines. T} _ T{ \fI\%xbpspkg\fP T} T{ Package support for XBPS package manager (used by VoidLinux) T} _ T{ \fI\%xfs\fP T} T{ Module for managing XFS file systems. T} _ T{ \fI\%xml\fP T} T{ XML file manager T} _ T{ \fI\%xmpp\fP T} T{ Module for Sending Messages via XMPP (a.k.a. T} _ T{ \fI\%yaml\fP T} T{ Yaml helper module for troubleshooting yaml T} _ T{ \fI\%yumpkg\fP T} T{ Support for YUM/DNF T} _ T{ \fI\%zabbix\fP T} T{ T} _ T{ \fI\%zcbuildout\fP T} T{ Management of zc.buildout T} _ T{ \fI\%zenoss\fP T} T{ Module for working with the Zenoss API T} _ T{ \fI\%zfs\fP T} T{ Module for running ZFS command T} _ T{ \fI\%zk_concurrency\fP T} T{ Concurrency controls in zookeeper T} _ T{ \fI\%znc\fP T} T{ znc \- An advanced IRC bouncer T} _ T{ \fI\%zoneadm\fP T} T{ Module for Solaris 10\(aqs zoneadm T} _ T{ \fI\%zonecfg\fP T} T{ Module for Solaris 10\(aqs zonecfg T} _ T{ \fI\%zookeeper\fP T} T{ Zookeeper Module maintainer SaltStack maturity new platform all depends kazoo T} _ T{ \fI\%zpool\fP T} T{ Module for running ZFS zpool command T} _ T{ \fI\%zypperpkg\fP T} T{ Package support for openSUSE via the zypper package manager T} _ .TE .SS salt.modules.acme .SS ACME / Let\(aqs Encrypt module .sp New in version 2016.3.0. .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, manual_auth_hook=None, manual_cleanup_hook=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) .IP \(bu 2 \fBmanual_auth_hook\fP \-\- Path to the manual authentication hook script. .IP \(bu 2 \fBmanual_cleanup_hook\fP \-\- Path to the manual cleanup or post\-authentication hook script. .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 \(dq[gitlab.example.com]\(dq 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 .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aix_group.add(name, gid=None, system=False, root=None, **kwargs) 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 .sp .nf .ft C salt \(aq*\(aq group.members foo \(aquser1,user2,user3,...\(aq .ft P .fi .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 .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 <minion_id> 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 <minion_id> 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 <minion_id> 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 \fI\%here\fP\&. .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 available 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 Changed in version 3005. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Note: currently only functional for rpm packages due to filesets do not have a specific location to check Requires yum of dnf available in order to query a repository .UNINDENT .sp This function will always return an empty string for unfound 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). .sp Changed in version 3005: .INDENT 7.0 .TP .B preference to install rpm packages are to use in the following order: /opt/freeware/bin/dnf /opt/freeware/bin/yum /usr/bin/yum /usr/bin/rpm .UNINDENT .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. .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<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(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 /cecc/repos/aix72/TL3/BASE/installp/ppc/bos.rte.printers_7.2.2.0.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 /cecc/repos/aix72/TL3/BASE/installp/ppc/bos.net salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq salt \(aq*\(aq pkg.install libxml2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aixpkg.latest_version(*names, **kwargs) Return the latest available 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 Changed in version 3005. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Note: currently only functional for rpm packages due to filesets do not have a specific location to check Requires yum of dnf available in order to query a repository .UNINDENT .sp This function will always return an empty string for unfound 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<package_name>\(aq: \(aq<version>\(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 Changed in version 3005: .INDENT 7.0 .TP .B preference to install rpm packages are to use in the following order: /opt/freeware/bin/dnf /opt/freeware/bin/yum /usr/bin/yum /usr/bin/rpm .UNINDENT .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 <fileset/rpm package name> 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[\(dqfoo\(dq, \(dqbar\(dq]\(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 Changed in version 3005. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available <package name> .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Note: currently only functional for rpm packages due to filesets do not have a specific location to check Requires yum of dnf available in order to query a repository .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aixpkg.version(*names, **kwargs) Return the current installed version of the named fileset/rpm package If more than one fileset/rpm package name is specified a dict of name/version pairs is returned. .sp Changed in version 3005. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .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 <name> 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 <path> for <name>. .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 salt.modules.ansiblegate.call(module, *args, **kwargs) Call an Ansible module by invoking it. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmodule\fP \-\- the name of the module. .IP \(bu 2 \fBargs\fP \-\- Arguments to pass to the module .IP \(bu 2 \fBkwargs\fP \-\- keywords to pass to the module .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt * ansible.call ping data=foobar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ansiblegate.discover_playbooks(path=None, locations=None, playbook_extension=None, hosts_filename=None, syntax_check=False) New in version 3005. .sp Discover Ansible playbooks stored under the given path or from multiple paths (locations) .sp This will search for files matching with the playbook file extension under the given root path and will also look for files inside the first level of directories in this path. .sp The return of this function would be a dict like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(dq/home/foobar/\(dq: { \(dqmy_ansible_playbook.yml\(dq: { \(dqfullpath\(dq: \(dq/home/foobar/playbooks/my_ansible_playbook.yml\(dq, \(dqcustom_inventory\(dq: \(dq/home/foobar/playbooks/hosts\(dq }, \(dqanother_playbook.yml\(dq: { \(dqfullpath\(dq: \(dq/home/foobar/playbooks/another_playbook.yml\(dq, \(dqcustom_inventory\(dq: \(dq/home/foobar/playbooks/hosts\(dq }, \(dqlamp_simple/site.yml\(dq: { \(dqfullpath\(dq: \(dq/home/foobar/playbooks/lamp_simple/site.yml\(dq, \(dqcustom_inventory\(dq: \(dq/home/foobar/playbooks/lamp_simple/hosts\(dq }, \(dqlamp_proxy/site.yml\(dq: { \(dqfullpath\(dq: \(dq/home/foobar/playbooks/lamp_proxy/site.yml\(dq, \(dqcustom_inventory\(dq: \(dq/home/foobar/playbooks/lamp_proxy/hosts\(dq } }, \(dq/srv/playbooks/\(dq: { \(dqexample_playbook/example.yml\(dq: { \(dqfullpath\(dq: \(dq/srv/playbooks/example_playbook/example.yml\(dq, \(dqcustom_inventory\(dq: \(dq/srv/playbooks/example_playbook/hosts\(dq } } } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- Path to discover playbooks from. .IP \(bu 2 \fBlocations\fP \-\- List of paths to discover playbooks from. .IP \(bu 2 \fBplaybook_extension\fP \-\- File extension of playbooks file to search for. Default: \(dqyml\(dq .IP \(bu 2 \fBhosts_filename\fP \-\- Filename of custom playbook inventory to search for. Default: \(dqhosts\(dq .IP \(bu 2 \fBsyntax_check\fP \-\- Skip playbooks that do not pass \(dqansible\-playbook \-\-syntax\-check\(dq validation. Default: False .UNINDENT .TP .B Returns The discovered playbooks under the given paths .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqansiblehost\(aq ansible.discover_playbooks path=/srv/playbooks/ salt \(aqansiblehost\(aq ansible.discover_playbooks locations=\(aq[\(dq/srv/playbooks/\(dq, \(dq/srv/foobar\(dq]\(aq .ft P .fi .UNINDENT .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 \-\- The module to get the help .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt * ansible.help ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ansiblegate.list_(pattern=None) Lists available modules. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt * ansible.list salt * ansible.list \(aq*win*\(aq # To get all modules matching \(aqwin\(aq on it\(aqs name .ft P .fi .UNINDENT .UNINDENT .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.playbooks playbook=/srv/playbooks/play.yml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ansiblegate.targets(inventory=\(aq/etc/ansible/hosts\(aq, yaml=False, export=False) New in version 3005. .sp Return the inventory from an Ansible inventory_file .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBinventory\fP \-\- The inventory file to read the inventory from. Default: \(dq/etc/ansible/hosts\(dq .IP \(bu 2 \fByaml\fP \-\- Return the inventory as yaml output. Default: False .IP \(bu 2 \fBexport\fP \-\- Return inventory as export format. Default: False .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqansiblehost\(aq ansible.targets salt \(aqansiblehost\(aq ansible.targets inventory=my_custom_inventory .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=\(dq[{\(aqListen\(aq: \(aq22\(aq}]\(dq .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 .sp 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 .sp 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 .sp 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 .sp 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 .sp 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 .sp 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 .sp 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 .sp 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 \fI\%here\fP\&. .UNINDENT .UNINDENT .sp New in version 2017.7.0. .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 \(dqpkgs\(dq or \(dqsources\(dq 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 \(dqsources\(dq option. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .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[\(dqfoo\(dq, \(dqbar\(dq]\(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[{\(dqfoo\(dq: \(dqsalt://foo.deb\(dq},{\(dqbar\(dq: \(dqsalt://bar.deb\(dq}]\(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<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(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 <package name> salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .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<package_name>\(aq: \(aq<version>\(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.modules.apk.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.owns /usr/bin/apachectl salt \(aq*\(aq pkg.owns /usr/bin/apachectl /usr/bin/basename .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apkpkg.purge(name=None, pkgs=None, **kwargs) Alias to remove .UNINDENT .INDENT 0.0 .TP .B salt.modules.apkpkg.refresh_db(**kwargs) Updates the package list .INDENT 7.0 .IP \(bu 2 \fBTrue\fP: Database updated successfully .IP \(bu 2 \fBFalse\fP: Problem updating database .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.apkpkg.remove(name=None, pkgs=None, purge=False, **kwargs) Remove packages using \fBapk del\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 Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(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<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.aptly .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=\(dqtest\-repo\(dq .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=\(dqtest\-repo\(dq .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=\(dqtest\-repo\(dq comment=\(dqTest main repo\(dq component=\(dqmain\(dq distribution=\(dqtrusty\(dq .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=\(dqtest\-repo\(dq comment=\(dqTest universe repo\(dq component=\(dquniverse\(dq distribution=\(dqxenial\(dq .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 \fI\%here\fP\&. .sp For repository management, the \fBpython\-apt\fP package must be installed. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.aptpkg.SourceEntry(line, file=None) .INDENT 7.0 .TP .B repo_line() Return the repo line for the sources file .UNINDENT .INDENT 7.0 .TP .B str() .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.aptpkg.SourcesList .INDENT 7.0 .TP .B add(type, uri, dist, orig_comps, architectures, signedby) .UNINDENT .INDENT 7.0 .TP .B add_file(file) Add the lines of a file to self.list .UNINDENT .INDENT 7.0 .TP .B remove(source) remove a source from the list of sources .UNINDENT .INDENT 7.0 .TP .B save() write all of the sources from the list of sources to the file. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.add_repo_key(path=None, text=None, keyserver=None, keyid=None, saltenv=\(aqbase\(aq, aptkey=True, keydir=None, keyfile=None) 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. .IP \(bu 2 \fBaptkey\fP (\fI\%bool\fP) \-\- Use the binary apt\-key. .IP \(bu 2 \fBkeydir\fP (\fI\%str\fP) \-\- The directory path to save keys. The default directory is /etc/apt/keyrings/ which is the recommended path for adding third party keys. This argument is only used when aptkey is False. .IP \(bu 2 \fBkeyfile\fP (\fI\%str\fP) \-\- The name of the key to add. This is only required when aptkey is False and you are using a keyserver. This argument is only used when aptkey is False. .UNINDENT .TP .B Returns A boolean representing whether the repo key was added. .TP .B Return type \fI\%bool\fP .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The apt\-key binary is deprecated and will last be available in Debian 11 and Ubuntu 22.04. It is recommended to use aptkey=False when using this module. .UNINDENT .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=\(dq\(aq$KEY1\(aq\(dq 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 Changed in version 3007.0. .sp 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 <value> seconds .UNINDENT .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package name> fromrepo=unstable salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .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 \(dqmyrepo definition\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.del_repo_key(name=None, aptkey=True, keydir=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 .TP .B aptkey Use the binary apt\-key. .TP .B keydir The directory path to save keys. The default directory is /etc/apt/keyrings/ which is the recommended path for adding third party keys. .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The apt\-key binary is deprecated and will last be available in Debian 11 and Ubuntu 22.04. It is recommended to use aptkey=False when using this module. .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.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 \(dqmyrepo definition\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.get_repo_keys(aptkey=True, keydir=None) New in version 2017.7.0. .sp List known repo key details. :param bool aptkey: Use the binary apt\-key. :param str keydir: The directory path to save keys. The default directory is /etc/apt/keyrings/ which is the recommended path for adding third party keys. This argument is only used when aptkey is False. .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<host>\(aq: {\(aq<state>\(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 <package name> .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[\(dqfoo\(dq, \(dqbar\(dq]\(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 <package1> salt \(aq*\(aq pkg.info_installed <package1> <package2> <package3> ... salt \(aq*\(aq pkg.info_installed <package1> 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 \fI\%config 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 \(dqpkgs\(dq or \(dqsources\(dq 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 \(dqsources\(dq 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 <package name> .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 <value> 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 \(dqpkgs\(dq or \(dqsources\(dq 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[\(dqfoo\(dq, \(dqbar\(dq]\(aq salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, {\(dqbar\(dq: \(dq1.2.3\-0ubuntu0\(dq}]\(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[{\(dqfoo\(dq: \(dqsalt://foo.deb\(dq},{\(dqbar\(dq: \(dqsalt://bar.deb\(dq}]\(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<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.latest_version(*names, **kwargs) Changed in version 3007.0. .sp 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 <value> seconds .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package name> fromrepo=unstable salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .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<package_name>\(aq: \(aq<version>\(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 \fI\%pkg.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 <value> 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, aptkey=True, **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:<project>/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 \fI\%config 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 <package name> salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3> salt \(aq*\(aq pkg.purge pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(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 <value> 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 \fI\%config 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 <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.services_need_restart(**kwargs) New in version 3003. .sp List services that use files which have been changed by the package manager. It might be needed to restart them. .sp Requires checkrestart from the debian\-goodies package. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.services_need_restart .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<host>\(aq: {\(aq<package>\(aq: {\(aqnew\(aq: \(aq<new\-state>\(aq, \(aqold\(aq: \(aq<old\-state>\(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{\(dqinstall\(dq: [\(dqnetcat\(dq]}\(aq salt \(aq*\(aq pkg.set_selections selection=\(aq{\(dqhold\(dq: [\(dqopenssh\-server\(dq, \(dqopenssh\-client\(dq]}\(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 <package name> .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[\(dqfoo\(dq, \(dqbar\(dq]\(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 \fI\%config 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<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(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 <value> 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. .TP .B allow_downgrades Allow apt to downgrade packages without a prompt. .sp New in version 3005. .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 <package name> .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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .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, use_etag=False) New in version 2016.11.0. .sp Changed in version 3005. .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. .TP .B use_etag If \fBTrue\fP, remote http/https file sources will attempt to use the ETag header to determine if the remote file needs to be downloaded. This provides a lightweight mechanism for promptly refreshing files changed on a web server without requiring a full hash comparison via the \fBsource_hash\fP parameter. .sp New in version 3005. .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, use_etag=False) New in version 2016.11.0. .sp Changed in version 2016.11.2,3005: 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. .TP .B use_etag If \fBTrue\fP, remote http/https file sources will attempt to use the ETag header to determine if the remote file needs to be downloaded. This provides a lightweight mechanism for promptly refreshing files changed on a web server without requiring a full hash comparison via the \fBsource_hash\fP parameter. .sp New in version 3005. .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 \fI\%pyeapi\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 \fI\%pyeapi 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 \fI\%pyeapi 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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \(dq[\(aqshow version\(aq]\(dq .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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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=\(dq[\(aqntp server 1.2.3.4\(aq, \(aqntp server 5.6.7.8\(aq]\(dq salt \(aq*\(aq pyeapi.config config_file=salt://config.txt salt \(aq*\(aq pyeapi.config config_file=https://bit.ly/2LGLcDy context=\(dq{\(aqservers\(aq: [\(aq1.2.3.4\(aq]}\(dq .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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 \fI\%pyeapi\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 .INDENT 0.0 .TP .B salt.modules.artifactory.set_basic_auth(url, username, password) Sets the username and password for a specific url. Helper method. .sp CLI Example: .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 <timespec> <cmd> [tag=<tag>] [runas=<user>] 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 salt \(aq*\(aq at.at \(aq\(dq22:02\(dq\(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 <jobid> .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 <jobid> <jobid> .. <jobid> 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 <timespec> <cmd> [tag=<tag>] [runas=<user>] 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 <jobid> .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 <jobid> <jobid> .. <jobid> 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 \(dqfrom augeas import Augeas\(dq\(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[\(dqset bind 0.0.0.0\(dq, \(dqset maxmemory 1G\(dq]\(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 \(dqspec[user = \(aq%wheel\(aq]/user\(dq \(dq%wheel\(dq \e \(dqspec[user = \(aq%wheel\(aq]/host_group/host\(dq \(aqALL\(aq \e \(dqspec[user = \(aq%wheel\(aq]/host_group/command[1]\(dq \(aqALL\(aq \e \(dqspec[user = \(aq%wheel\(aq]/host_group/command[1]/tag\(dq \(aqPASSWD\(aq \e \(dqspec[user = \(aq%wheel\(aq]/host_group/command[2]\(dq \(aq/usr/bin/apt\-get\(aq \e \(dqspec[user = \(aq%wheel\(aq]/host_group/command[2]/tag\(dq 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 .sp .nf .ft C salt \(aq*\(aq aws_sqs.create_queue <sqs queue> <region> .ft P .fi .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 <sqs queue> <region> receipthandle=\(aq<sqs ReceiptHandle>\(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 .sp .nf .ft C salt \(aq*\(aq aws_sqs.delete_queue <sqs queue> <region> .ft P .fi .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 .sp .nf .ft C salt \(aq*\(aq aws_sqs.list_queues <region> .ft P .fi .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 .sp .nf .ft C salt \(aq*\(aq aws_sqs.queue_exists <sqs queue> <region> .ft P .fi .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 <sqs queue> <region> salt \(aq*\(aq aws_sqs.receive_message <sqs queue> <region> num=10 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2014.7.0. .UNINDENT .SS salt.modules.bamboohr .sp Support for BambooHR .sp New in version 2015.8.0. .sp Requires a \fBsubdomain\fP and an \fBapikey\fP in \fB/etc/salt/minion\fP: .INDENT 0.0 .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 .sp .nf .ft C salt myminion bamboohr.list_employees .ft P .fi .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 .sp .nf .ft C salt myminion bamboohr.list_employees order_by=id salt myminion bamboohr.list_employees order_by=displayName salt myminion bamboohr.list_employees order_by=workEmail .ft P .fi .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 .sp .nf .ft C salt myminion bamboohr.list_meta_fields .ft P .fi .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 .sp .nf .ft C salt myminion bamboohr.list_users .ft P .fi .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 .sp .nf .ft C salt myminion bamboohr.list_users order_by=id salt myminion bamboohr.list_users order_by=email .ft P .fi .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 .sp .nf .ft C salt myminion bamboohr.show_employee 1138 .ft P .fi .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 .sp .nf .ft C salt myminion bamboohr.show_employee 1138 displayName,dateOfBirth .ft P .fi .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 .sp .nf .ft C 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{\(dqnickname\(dq: \(dqCurly\(dq} salt myminion bamboohr.update_employee 1138 items=\(aq{\(dqnickname\(dq: \(dq\(dq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.baredoc .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: .sp (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 .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. .sp New in version 2016.3.0. .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 \(dq[{\(aqprocesses\(aq: {\(aqsalt\-master\(aq: \(aqstopped\(aq, \(aqapache2\(aq: \(aqstopped\(aq}}]\(dq .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 \(dq[{\(aqsalt\-master\(aq: \(aqstopped\(aq}, {\(aqapache2\(aq: \(aqstopped\(aq}]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.beacons.reset(**kwargs) Reset 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:<label>\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.commit_transaction bigip admin admin my_transaction .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.create_monitor(hostname, username, password, monitor_type, name, **kwargs) A function to connect to a bigip device and create a monitor. .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 monitor_type The type of monitor to create .TP .B name The name of the monitor to create .TP .B kwargs Consult F5 BIGIP user guide for specific options for each monitor type. Typically, tmsh arg names are used. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.create_monitor bigip admin admin http my\-http\-monitor timeout=10 interval=5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.create_node(hostname, username, password, name, address, trans_label=None) A function to connect to a bigip device and create a node. .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 node .TP .B address The address of the node .TP .B trans_label The label of the transaction stored within the grain: \fBbigip_f5_trans:<label>\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.create_node bigip admin admin 10.1.1.2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.create_pool(hostname, username, password, name, members=None, allow_nat=None, allow_snat=None, description=None, gateway_failsafe_device=None, ignore_persisted_weight=None, ip_tos_to_client=None, ip_tos_to_server=None, link_qos_to_client=None, link_qos_to_server=None, load_balancing_mode=None, min_active_members=None, min_up_members=None, min_up_members_action=None, min_up_members_checking=None, monitor=None, profiles=None, queue_depth_limit=None, queue_on_connection_limit=None, queue_time_limit=None, reselect_tries=None, service_down_action=None, slow_ramp_time=None) A function to connect to a bigip device and create a 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 create. .TP .B members List of comma delimited pool members to add to the pool. i.e. 10.1.1.1:80,10.1.1.2:80,10.1.1.3:80 .TP .B allow_nat [yes | no] .TP .B allow_snat [yes | no] .TP .B description [string] .TP .B gateway_failsafe_device [string] .TP .B ignore_persisted_weight [enabled | disabled] .TP .B ip_tos_to_client [pass\-through | [integer]] .TP .B ip_tos_to_server [pass\-through | [integer]] .TP .B link_qos_to_client [pass\-through | [integer]] .TP .B link_qos_to_server [pass\-through | [integer]] .TP .B load_balancing_mode [dynamic\-ratio\-member | dynamic\-ratio\-node | fastest\-app\-response | fastest\-node | least\-connections\-members | least\-connections\-node | least\-sessions | observed\-member | observed\-node | predictive\-member | predictive\-node | ratio\-least\-connections\-member | ratio\-least\-connections\-node | ratio\-member | ratio\-node | ratio\-session | round\-robin | weighted\-least\-connections\-member | weighted\-least\-connections\-node] .TP .B min_active_members [integer] .TP .B min_up_members [integer] .TP .B min_up_members_action [failover | reboot | restart\-all] .TP .B min_up_members_checking [enabled | disabled] .TP .B monitor [name] .TP .B profiles [none | profile_name] .TP .B queue_depth_limit [integer] .TP .B queue_on_connection_limit [enabled | disabled] .TP .B queue_time_limit [integer] .TP .B reselect_tries [integer] .TP .B service_down_action [drop | none | reselect | reset] .TP .B slow_ramp_time [integer] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.create_pool bigip admin admin my\-pool 10.1.1.1:80,10.1.1.2:80,10.1.1.3:80 monitor=http .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.create_profile(hostname, username, password, profile_type, name, **kwargs) A function to connect to a bigip device and create a profile. .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 profile_type The type of profile to create .TP .B name The name of the profile to create .TP .B kwargs \fB[ arg=val ] ... [arg=key1:val1,key2:val2] ...\fP .sp Consult F5 BIGIP user guide for specific options for each monitor type. Typically, tmsh arg names are used. .TP .B Creating Complex Args Profiles can get pretty complicated in terms of the amount of possible config options. Use the following shorthand to create complex arguments such as lists, dictionaries, and lists of dictionaries. An option is also provided to pass raw json as well. .INDENT 7.0 .TP .B lists \fB[i,i,i]\fP: \fBparam=\(aqitem1,item2,item3\(aq\fP .TP .B Dictionary \fB[k:v,k:v,k,v]\fP: \fBparam=\(aqkey\-1:val\-1,key\-2:val2,key\-3:va\-3\(aq\fP .TP .B List of Dictionaries \fB[k:v,k:v|k:v,k:v|k:v,k:v]\fP: \fBparam=\(aqkey\-1:val\-1,key\-2:val\-2|key\-1:val\-1,key\-2:val\-2|key\-1:val\-1,key\-2:val\-2\(aq\fP .TP .B JSON: \fB\(aqj{ ... }j\(aq\fP: \fBcert\-key\-chain=\(aqj{ \(dqdefault\(dq: { \(dqcert\(dq: \(dqdefault.crt\(dq, \(dqchain\(dq: \(dqdefault.crt\(dq, \(dqkey\(dq: \(dqdefault.key\(dq } }j\(aq\fP .TP .B Escaping Delimiters: Use \fB\e,\fP or \fB\e:\fP or \fB\e|\fP to escape characters which shouldn\(aqt be treated as delimiters i.e. \fBciphers=\(aqDEFAULT\e:!SSLv3\(aq\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.create_profile bigip admin admin http my\-http\-profile defaultsFrom=\(aq/Common/http\(aq salt \(aq*\(aq bigip.create_profile bigip admin admin http my\-http\-profile defaultsFrom=\(aq/Common/http\(aq \e enforcement=maxHeaderCount:3200,maxRequests:10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.create_virtual(hostname, username, password, name, destination, pool=None, address_status=None, auto_lasthop=None, bwc_policy=None, cmp_enabled=None, connection_limit=None, dhcp_relay=None, description=None, fallback_persistence=None, flow_eviction_policy=None, gtm_score=None, ip_forward=None, ip_protocol=None, internal=None, twelve_forward=None, last_hop_pool=None, mask=None, mirror=None, nat64=None, persist=None, profiles=None, policies=None, rate_class=None, rate_limit=None, rate_limit_mode=None, rate_limit_dst=None, rate_limit_src=None, rules=None, related_rules=None, reject=None, source=None, source_address_translation=None, source_port=None, state=None, traffic_classes=None, translate_address=None, translate_port=None, vlans=None) A function to connect to a bigip device and create a virtual server. .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 virtual to create .TP .B destination [ [virtual_address_name:port] | [ipv4:port] | [ipv6.port] ] .TP .B pool [ [pool_name] | none] .TP .B address_status [yes | no] .TP .B auto_lasthop [default | enabled | disabled ] .TP .B bwc_policy [none] | string] .TP .B cmp_enabled [yes | no] .TP .B dhcp_relay [yes | no] .TP .B connection_limit [integer] .TP .B description [string] .TP .B state [disabled | enabled] .TP .B fallback_persistence [none | [profile name] ] .TP .B flow_eviction_policy [none | [eviction policy name] ] .TP .B gtm_score [integer] .TP .B ip_forward [yes | no] .TP .B ip_protocol [any | protocol] .TP .B internal [yes | no] .TP .B twelve_forward (12\-forward) [yes | no] .TP .B last_hop\-pool [ [pool_name] | none] .TP .B mask { [ipv4] | [ipv6] } .TP .B mirror { [disabled | enabled | none] } .TP .B nat64 [enabled | disabled] .TP .B persist [none | profile1,profile2,profile3 ... ] .TP .B profiles [none | default | profile1,profile2,profile3 ... ] .TP .B policies [none | default | policy1,policy2,policy3 ... ] .TP .B rate_class [name] .TP .B rate_limit [integer] .TP .B rate_limit_mode [destination | object | object\-destination | object\-source | object\-source\-destination | source | source\-destination] .TP .B rate_limit_dst [integer] .TP .B rate_limitçsrc [integer] .TP .B rules [none | [rule_one,rule_two ...] ] .TP .B related_rules [none | [rule_one,rule_two ...] ] .TP .B reject [yes | no] .TP .B source { [ipv4[/prefixlen]] | [ipv6[/prefixlen]] } .TP .B source_address_translation [none | snat:pool_name | lsn | automap ] .TP .B source_port [change | preserve | preserve\-strict] .TP .B state [enabled | disabled] .TP .B traffic_classes [none | default | class_one,class_two ... ] .TP .B translate_address [enabled | disabled] .TP .B translate_port [enabled | disabled] .TP .B vlans [none | default | [enabled|disabled]:vlan1,vlan2,vlan3 ... ] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.create_virtual bigip admin admin my\-virtual\-3 26.2.2.5:80 \e pool=my\-http\-pool\-http profiles=http,tcp salt \(aq*\(aq bigip.create_virtual bigip admin admin my\-virtual\-3 43.2.2.5:80 \e pool=test\-http\-pool\-http profiles=http,websecurity persist=cookie,hash \e policies=asm_auto_l7_policy__http\-virtual \e rules=_sys_APM_ExchangeSupport_helper,_sys_https_redirect \e related_rules=_sys_APM_activesync,_sys_APM_ExchangeSupport_helper \e source_address_translation=snat:my\-snat\-pool \e translate_address=enabled translate_port=enabled \e traffic_classes=my\-class,other\-class \e vlans=enabled:external,internal .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.delete_monitor(hostname, username, password, monitor_type, name) A function to connect to a bigip device and delete an existing monitor. .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 monitor_type The type of monitor to delete .TP .B name The name of the monitor to delete .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.delete_monitor bigip admin admin http my\-http\-monitor .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.delete_node(hostname, username, password, name, trans_label=None) A function to connect to a bigip device and delete a specific node. .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 node which will be deleted. .TP .B trans_label The label of the transaction stored within the grain: \fBbigip_f5_trans:<label>\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.delete_node bigip admin admin my\-node .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.delete_pool(hostname, username, password, name) A function to connect to a bigip device and delete a specific 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 which will be deleted .UNINDENT .sp CLI Example .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.delete_node bigip admin admin my\-pool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.delete_pool_member(hostname, username, password, name, member) A function to connect to a bigip device and delete a specific 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 pool member to delete .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.delete_pool_member bigip admin admin my\-pool 10.2.2.2:80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.delete_profile(hostname, username, password, profile_type, name) A function to connect to a bigip device and delete an existing profile. .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 profile_type The type of profile to delete .TP .B name The name of the profile to delete .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.delete_profile bigip admin admin http my\-http\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.delete_transaction(hostname, username, password, label) A function to connect to a bigip device and delete 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:<label>\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.delete_transaction bigip admin admin my_transaction .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.delete_virtual(hostname, username, password, name) A function to connect to a bigip device and delete a specific virtual. .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 virtual to delete .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.delete_virtual bigip admin admin my\-virtual .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.list_monitor(hostname, username, password, monitor_type, name=None) A function to connect to a bigip device and list an existing monitor. If no name is provided than all monitors of the specified type will be listed. .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 monitor_type The type of monitor(s) to list .TP .B name The name of the monitor to list .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.list_monitor bigip admin admin http my\-http\-monitor .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.list_node(hostname, username, password, name=None, trans_label=None) A function to connect to a bigip device and list all nodes or a specific node. .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 node to list. If no name is specified than all nodes will be listed. .TP .B trans_label The label of the transaction stored within the grain: \fBbigip_f5_trans:<label>\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.list_node bigip admin admin my\-node .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.list_pool(hostname, username, password, name=None) A function to connect to a bigip device and list all pools or a specific 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 list. If no name is specified then all pools will be listed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.list_pool bigip admin admin my\-pool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.list_profile(hostname, username, password, profile_type, name=None) A function to connect to a bigip device and list an existing profile. If no name is provided than all profiles of the specified type will be listed. .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 profile_type The type of profile(s) to list .TP .B name The name of the profile to list .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.list_profile bigip admin admin http my\-http\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.list_transaction(hostname, username, password, label) A function to connect to a bigip device and list 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:<label>\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.list_transaction bigip admin admin my_transaction .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.list_virtual(hostname, username, password, name=None) A function to connect to a bigip device and list all virtuals or a specific virtual. .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 virtual to list. If no name is specified than all virtuals will be listed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.list_virtual bigip admin admin my\-virtual .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.modify_monitor(hostname, username, password, monitor_type, name, **kwargs) A function to connect to a bigip device and modify an existing monitor. .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 monitor_type The type of monitor to modify .TP .B name The name of the monitor to modify .TP .B kwargs Consult F5 BIGIP user guide for specific options for each monitor type. Typically, tmsh arg names are used. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.modify_monitor bigip admin admin http my\-http\-monitor timout=16 interval=6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.modify_node(hostname, username, password, name, connection_limit=None, description=None, dynamic_ratio=None, logging=None, monitor=None, rate_limit=None, ratio=None, session=None, state=None, trans_label=None) A function to connect to a bigip device and modify an existing node. .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 node to modify .TP .B connection_limit [integer] .TP .B description [string] .TP .B dynamic_ratio [integer] .TP .B logging [enabled | disabled] .TP .B monitor [[name] | none | default] .TP .B rate_limit [integer] .TP .B ratio [integer] .TP .B session [user\-enabled | user\-disabled] .TP .B state [user\-down | user\-up ] .TP .B trans_label The label of the transaction stored within the grain: \fBbigip_f5_trans:<label>\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.modify_node bigip admin admin 10.1.1.2 ratio=2 logging=enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.modify_pool(hostname, username, password, name, allow_nat=None, allow_snat=None, description=None, gateway_failsafe_device=None, ignore_persisted_weight=None, ip_tos_to_client=None, ip_tos_to_server=None, link_qos_to_client=None, link_qos_to_server=None, load_balancing_mode=None, min_active_members=None, min_up_members=None, min_up_members_action=None, min_up_members_checking=None, monitor=None, profiles=None, queue_depth_limit=None, queue_on_connection_limit=None, queue_time_limit=None, reselect_tries=None, service_down_action=None, slow_ramp_time=None) A function to connect to a bigip device and modify 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 allow_nat [yes | no] .TP .B allow_snat [yes | no] .TP .B description [string] .TP .B gateway_failsafe_device [string] .TP .B ignore_persisted_weight [yes | no] .TP .B ip_tos_to_client [pass\-through | [integer]] .TP .B ip_tos_to_server [pass\-through | [integer]] .TP .B link_qos_to_client [pass\-through | [integer]] .TP .B link_qos_to_server [pass\-through | [integer]] .TP .B load_balancing_mode [dynamic\-ratio\-member | dynamic\-ratio\-node | fastest\-app\-response | fastest\-node | least\-connections\-members | least\-connections\-node | least\-sessions | observed\-member | observed\-node | predictive\-member | predictive\-node | ratio\-least\-connections\-member | ratio\-least\-connections\-node | ratio\-member | ratio\-node | ratio\-session | round\-robin | weighted\-least\-connections\-member | weighted\-least\-connections\-node] .TP .B min_active_members [integer] .TP .B min_up_members [integer] .TP .B min_up_members_action [failover | reboot | restart\-all] .TP .B min_up_members_checking [enabled | disabled] .TP .B monitor [name] .TP .B profiles [none | profile_name] .TP .B queue_on_connection_limit [enabled | disabled] .TP .B queue_depth_limit [integer] .TP .B queue_time_limit [integer] .TP .B reselect_tries [integer] .TP .B service_down_action [drop | none | reselect | reset] .TP .B slow_ramp_time [integer] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.modify_pool bigip admin admin my\-pool 10.1.1.1:80,10.1.1.2:80,10.1.1.3:80 min_active_members=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.modify_pool_member(hostname, username, password, name, member, connection_limit=None, description=None, dynamic_ratio=None, inherit_profile=None, logging=None, monitor=None, priority_group=None, profiles=None, rate_limit=None, ratio=None, session=None, state=None) A function to connect to a bigip device and modify an existing member of a 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 modify i.e. 10.1.1.2:80 .TP .B connection_limit [integer] .TP .B description [string] .TP .B dynamic_ratio [integer] .TP .B inherit_profile [enabled | disabled] .TP .B logging [enabled | disabled] .TP .B monitor [name] .TP .B priority_group [integer] .TP .B profiles [none | profile_name] .TP .B rate_limit [integer] .TP .B ratio [integer] .TP .B session [user\-enabled | user\-disabled] .TP .B state [ user\-up | user\-down ] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.modify_pool_member bigip admin admin my\-pool 10.2.2.1:80 state=use\-down session=user\-disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.modify_profile(hostname, username, password, profile_type, name, **kwargs) A function to connect to a bigip device and create a profile. .sp A function to connect to a bigip device and create a profile. .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 profile_type The type of profile to create .TP .B name The name of the profile to create .TP .B kwargs \fB[ arg=val ] ... [arg=key1:val1,key2:val2] ...\fP .sp Consult F5 BIGIP user guide for specific options for each monitor type. Typically, tmsh arg names are used. .UNINDENT .sp Creating Complex Args .INDENT 7.0 .INDENT 3.5 Profiles can get pretty complicated in terms of the amount of possible config options. Use the following shorthand to create complex arguments such as lists, dictionaries, and lists of dictionaries. An option is also provided to pass raw json as well. .INDENT 0.0 .TP .B lists \fB[i,i,i]\fP: \fBparam=\(aqitem1,item2,item3\(aq\fP .TP .B Dictionary \fB[k:v,k:v,k,v]\fP: \fBparam=\(aqkey\-1:val\-1,key\-2:val2,key\-3:va\-3\(aq\fP .TP .B List of Dictionaries \fB[k:v,k:v|k:v,k:v|k:v,k:v]\fP: \fBparam=\(aqkey\-1:val\-1,key\-2:val\-2|key\-1:val\-1,key\-2:val\-2|key\-1:val\-1,key\-2:val\-2\(aq\fP .TP .B JSON: \fB\(aqj{ ... }j\(aq\fP: \fBcert\-key\-chain=\(aqj{ \(dqdefault\(dq: { \(dqcert\(dq: \(dqdefault.crt\(dq, \(dqchain\(dq: \(dqdefault.crt\(dq, \(dqkey\(dq: \(dqdefault.key\(dq } }j\(aq\fP .TP .B Escaping Delimiters: Use \fB\e,\fP or \fB\e:\fP or \fB\e|\fP to escape characters which shouldn\(aqt be treated as delimiters i.e. \fBciphers=\(aqDEFAULT\e:!SSLv3\(aq\fP .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.modify_profile bigip admin admin http my\-http\-profile defaultsFrom=\(aq/Common/http\(aq salt \(aq*\(aq bigip.modify_profile bigip admin admin http my\-http\-profile defaultsFrom=\(aq/Common/http\(aq \e enforcement=maxHeaderCount:3200,maxRequests:10 salt \(aq*\(aq bigip.modify_profile bigip admin admin client\-ssl my\-client\-ssl\-1 retainCertificate=false \e ciphers=\(aqDEFAULT\e:!SSLv3\(aq cert_key_chain=\(aqj{ \(dqdefault\(dq: { \(dqcert\(dq: \(dqdefault.crt\(dq, \(dqchain\(dq: \(dqdefault.crt\(dq, \(dqkey\(dq: \(dqdefault.key\(dq } }j\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.modify_virtual(hostname, username, password, name, destination=None, pool=None, address_status=None, auto_lasthop=None, bwc_policy=None, cmp_enabled=None, connection_limit=None, dhcp_relay=None, description=None, fallback_persistence=None, flow_eviction_policy=None, gtm_score=None, ip_forward=None, ip_protocol=None, internal=None, twelve_forward=None, last_hop_pool=None, mask=None, mirror=None, nat64=None, persist=None, profiles=None, policies=None, rate_class=None, rate_limit=None, rate_limit_mode=None, rate_limit_dst=None, rate_limit_src=None, rules=None, related_rules=None, reject=None, source=None, source_address_translation=None, source_port=None, state=None, traffic_classes=None, translate_address=None, translate_port=None, vlans=None) A function to connect to a bigip device and modify an existing virtual server. .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 virtual to modify .TP .B destination [ [virtual_address_name:port] | [ipv4:port] | [ipv6.port] ] .TP .B pool [ [pool_name] | none] .TP .B address_status [yes | no] .TP .B auto_lasthop [default | enabled | disabled ] .TP .B bwc_policy [none] | string] .TP .B cmp_enabled [yes | no] .TP .B dhcp_relay [yes | no} .TP .B connection_limit [integer] .TP .B description [string] .TP .B state [disabled | enabled] .TP .B fallback_persistence [none | [profile name] ] .TP .B flow_eviction_policy [none | [eviction policy name] ] .TP .B gtm_score [integer] .TP .B ip_forward [yes | no] .TP .B ip_protocol [any | protocol] .TP .B internal [yes | no] .TP .B twelve_forward (12\-forward) [yes | no] .TP .B last_hop\-pool [ [pool_name] | none] .TP .B mask { [ipv4] | [ipv6] } .TP .B mirror { [disabled | enabled | none] } .TP .B nat64 [enabled | disabled] .TP .B persist [none | profile1,profile2,profile3 ... ] .TP .B profiles [none | default | profile1,profile2,profile3 ... ] .TP .B policies [none | default | policy1,policy2,policy3 ... ] .TP .B rate_class [name] .TP .B rate_limit [integer] .TP .B rate_limitr_mode [destination | object | object\-destination | object\-source | object\-source\-destination | source | source\-destination] .TP .B rate_limit_dst [integer] .TP .B rate_limit_src [integer] .TP .B rules [none | [rule_one,rule_two ...] ] .TP .B related_rules [none | [rule_one,rule_two ...] ] .TP .B reject [yes | no] .TP .B source { [ipv4[/prefixlen]] | [ipv6[/prefixlen]] } .TP .B source_address_translation [none | snat:pool_name | lsn | automap ] .TP .B source_port [change | preserve | preserve\-strict] .TP .B state [enabled | disable] .TP .B traffic_classes [none | default | class_one,class_two ... ] .TP .B translate_address [enabled | disabled] .TP .B translate_port [enabled | disabled] .TP .B vlans [none | default | [enabled|disabled]:vlan1,vlan2,vlan3 ... ] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.modify_virtual bigip admin admin my\-virtual source_address_translation=none salt \(aq*\(aq bigip.modify_virtual bigip admin admin my\-virtual rules=my\-rule,my\-other\-rule .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.replace_pool_members(hostname, username, password, name, members) A function to connect to a bigip device and replace members of an existing pool with new members. .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 members List of comma delimited pool members to replace existing members with. i.e. 10.1.1.1:80,10.1.1.2:80,10.1.1.3:80 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.replace_pool_members bigip admin admin my\-pool 10.2.2.1:80,10.2.2.2:80,10.2.2.3:80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.start_transaction(hostname, username, password, label) A function to connect to a bigip device and start a new 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 name / alias for this transaction. The actual transaction id will be stored within a grain called \fBbigip_f5_trans:<label>\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.start_transaction bigip admin admin my_transaction .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.bluez_bluetooth .sp Support for Bluetooth (using BlueZ in Linux). .sp The following packages are required packages for this module: .INDENT 0.0 .INDENT 3.5 bluez >= 5.7 bluez\-libs >= 5.7 bluez\-utils >= 5.7 pybluez >= 0.18 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez_bluetooth.address_() Get the many addresses of the Bluetooth adapter .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.address .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez_bluetooth.block(bdaddr) Block a specific bluetooth device by BD Address .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.block DE:AD:BE:EF:CA:FE .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez_bluetooth.discoverable(dev) Enable this bluetooth device to be discoverable. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.discoverable hci0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez_bluetooth.noscan(dev) Turn off scanning modes on this device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.noscan hci0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez_bluetooth.pair(address, key) Pair the bluetooth adapter with a device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.pair DE:AD:BE:EF:CA:FE 1234 .ft P .fi .UNINDENT .UNINDENT .sp Where DE:AD:BE:EF:CA:FE is the address of the device to pair with, and 1234 is the passphrase. .sp TODO: This function is currently broken, as the bluez\-simple\-agent program no longer ships with BlueZ >= 5.0. It needs to be refactored. .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez_bluetooth.power(dev, mode) Power a bluetooth device on or off .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.power hci0 on salt \(aq*\(aq bluetooth.power hci0 off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez_bluetooth.scan() Scan for bluetooth devices in the area .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.scan .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez_bluetooth.start() Start the bluetooth service. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.start .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez_bluetooth.stop() Stop the bluetooth service. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.stop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez_bluetooth.unblock(bdaddr) Unblock a specific bluetooth device by BD Address .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.unblock DE:AD:BE:EF:CA:FE .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez_bluetooth.unpair(address) Unpair the bluetooth adapter from a device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.unpair DE:AD:BE:EF:CA:FE .ft P .fi .UNINDENT .UNINDENT .sp Where DE:AD:BE:EF:CA:FE is the address of the device to unpair. .sp TODO: This function is currently broken, as the bluez\-simple\-agent program no longer ships with BlueZ >= 5.0. It needs to be refactored. .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez_bluetooth.version() Return Bluez version from bluetoothd \-v .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetoothd.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto3_elasticache .SS Execution module for Amazon Elasticache using boto3 .sp New in version 2017.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit elasticache credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C elasticache.keyid: GKTADJGHEIQSXMKKRBJ08H elasticache.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C elasticache.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.add_tags_to_resource(name, region=None, key=None, keyid=None, profile=None, **args) Add tags to an Elasticache resource. .sp Note that this function is essentially useless as it requires a full AWS ARN for the resource being operated on, but there is no provided API or programmatic way to find the ARN for a given object from its name or ID alone. It requires specific knowledge about the account number, AWS partition, and other magic details to generate. .sp If you happen to have those at hand though, feel free to utilize this function... .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.add_tags_to_resource name\(aq=arn:aws:elasticache:us\-west\-2:0123456789:snapshot:mySnapshot\(aq Tags=\(dq[{\(aqKey\(aq: \(aqTeamOwner\(aq, \(aqValue\(aq: \(aqinfrastructure\(aq}]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.authorize_cache_security_group_ingress(name, region=None, key=None, keyid=None, profile=None, **args) Authorize network ingress from an ec2 security group to a cache security group. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.authorize_cache_security_group_ingress mycachesecgrp EC2SecurityGroupName=someEC2sg EC2SecurityGroupOwnerId=SOMEOWNERID .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.cache_cluster_exists(name, conn=None, region=None, key=None, keyid=None, profile=None) Check to see if a cache cluster exists. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.cache_cluster_exists myelasticache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.cache_security_group_exists(name, region=None, key=None, keyid=None, profile=None) Check to see if an ElastiCache security group exists. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.cache_security_group_exists mysecuritygroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.cache_subnet_group_exists(name, region=None, key=None, keyid=None, profile=None) Check to see if an ElastiCache subnet group exists. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.cache_subnet_group_exists my\-subnet\-group .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.copy_snapshot(name, region=None, key=None, keyid=None, profile=None, **args) Make a copy of an existing snapshot. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.copy_snapshot name=mySnapshot TargetSnapshotName=copyOfMySnapshot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.create_cache_cluster(name, wait=600, security_groups=None, region=None, key=None, keyid=None, profile=None, **args) Create a cache cluster. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.create_cache_cluster name=myCacheCluster Engine=redis CacheNodeType=cache.t2.micro NumCacheNodes=1 SecurityGroupIds=\(aq[sg\-11223344]\(aq CacheSubnetGroupName=myCacheSubnetGroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.create_cache_parameter_group(name, region=None, key=None, keyid=None, profile=None, **args) Create a cache parameter group. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.create_cache_parameter_group name=myParamGroup CacheParameterGroupFamily=redis2.8 Description=\(dqMy Parameter Group\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.create_cache_security_group(name, region=None, key=None, keyid=None, profile=None, **args) Create a cache security group. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.create_cache_security_group mycachesecgrp Description=\(aqMy Cache Security Group\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.create_cache_subnet_group(name, subnets=None, region=None, key=None, keyid=None, profile=None, **args) Create an ElastiCache subnet group .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.create_cache_subnet_group name=my\-subnet\-group CacheSubnetGroupDescription=\(dqdescription\(dq subnets=\(aq[myVPCSubnet1,myVPCSubnet2]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.create_replication_group(name, wait=600, security_groups=None, region=None, key=None, keyid=None, profile=None, **args) Create a replication group. Params are extensive and variable \- see \fI\%http://boto3.readthedocs.io/en/latest/reference/services/elasticache.html\fP?#ElastiCache.Client.create_replication_group for in\-depth usage documentation. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.create_replication_group name=myelasticache ReplicationGroupDescription=description .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.delete_cache_cluster(name, wait=600, region=None, key=None, keyid=None, profile=None, **args) Delete a cache cluster. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.delete myelasticache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.delete_cache_parameter_group(name, region=None, key=None, keyid=None, profile=None, **args) Delete a cache parameter group. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.delete_cache_parameter_group myParamGroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.delete_cache_security_group(name, region=None, key=None, keyid=None, profile=None, **args) Delete a cache security group. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.delete_cache_security_group myelasticachesg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.delete_cache_subnet_group(name, region=None, key=None, keyid=None, profile=None, **args) Delete an ElastiCache subnet group. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.delete_subnet_group my\-subnet\-group region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.delete_replication_group(name, wait=600, region=None, key=None, keyid=None, profile=None, **args) Delete an ElastiCache replication group, optionally taking a snapshot first. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.delete_replication_group my\-replication\-group .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.describe_cache_clusters(name=None, conn=None, region=None, key=None, keyid=None, profile=None, **args) Return details about all (or just one) Elasticache cache clusters. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.describe_cache_clusters salt myminion boto3_elasticache.describe_cache_clusters myelasticache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.describe_cache_parameter_groups(name=None, conn=None, region=None, key=None, keyid=None, profile=None) Return details about all (or just one) Elasticache cache clusters. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.describe_cache_parameter_groups salt myminion boto3_elasticache.describe_cache_parameter_groups myParameterGroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.describe_cache_security_groups(name=None, conn=None, region=None, key=None, keyid=None, profile=None) Return details about all (or just one) Elasticache cache clusters. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.describe_cache_security_groups salt myminion boto3_elasticache.describe_cache_security_groups mycachesecgrp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.describe_cache_subnet_groups(name=None, conn=None, region=None, key=None, keyid=None, profile=None) Return details about all (or just one) Elasticache replication groups. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.describe_cache_subnet_groups region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.describe_replication_groups(name=None, conn=None, region=None, key=None, keyid=None, profile=None) Return details about all (or just one) Elasticache replication groups. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.describe_replication_groups salt myminion boto3_elasticache.describe_replication_groups myelasticache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.list_cache_subnet_groups(region=None, key=None, keyid=None, profile=None) Return a list of all cache subnet group names .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.list_cache_subnet_groups region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.list_tags_for_resource(name, region=None, key=None, keyid=None, profile=None, **args) List tags on an Elasticache resource. .sp Note that this function is essentially useless as it requires a full AWS ARN for the resource being operated on, but there is no provided API or programmatic way to find the ARN for a given object from its name or ID alone. It requires specific knowledge about the account number, AWS partition, and other magic details to generate. .sp If you happen to have those handy, feel free to utilize this however... .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.list_tags_for_resource name\(aq=arn:aws:elasticache:us\-west\-2:0123456789:snapshot:mySnapshot\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.modify_cache_cluster(name, wait=600, security_groups=None, region=None, key=None, keyid=None, profile=None, **args) Update a cache cluster in place. .INDENT 7.0 .TP .B Notes: {ApplyImmediately: False} is pretty danged silly in the context of salt. You can pass it, but for fairly obvious reasons the results over multiple runs will be undefined and probably contrary to your desired state. Reducing the number of nodes requires an EXPLICIT CacheNodeIdsToRemove be passed, which until a reasonable heuristic for programmatically deciding which nodes to remove has been established, MUST be decided and populated intentionally before a state call, and removed again before the next. In practice this is not particularly useful and should probably be avoided. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.create_cache_cluster name=myCacheCluster NotificationTopicStatus=inactive .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.modify_cache_subnet_group(name, subnets=None, region=None, key=None, keyid=None, profile=None, **args) Modify an ElastiCache subnet group .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.modify_cache_subnet_group name=my\-subnet\-group subnets=\(aq[myVPCSubnet3]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.modify_replication_group(name, wait=600, security_groups=None, region=None, key=None, keyid=None, profile=None, **args) Modify a replication group. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.modify_replication_group name=myelasticache ReplicationGroupDescription=newDescription .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.remove_tags_from_resource(name, region=None, key=None, keyid=None, profile=None, **args) Remove tags from an Elasticache resource. .sp Note that this function is essentially useless as it requires a full AWS ARN for the resource being operated on, but there is no provided API or programmatic way to find the ARN for a given object from its name or ID alone. It requires specific knowledge about the account number, AWS partition, and other magic details to generate. .sp If you happen to have those at hand though, feel free to utilize this function... .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.remove_tags_from_resource name\(aq=arn:aws:elasticache:us\-west\-2:0123456789:snapshot:mySnapshot\(aq TagKeys=\(dq[\(aqTeamOwner\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.replication_group_exists(name, region=None, key=None, keyid=None, profile=None) Check to see if a replication group exists. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.replication_group_exists myelasticache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticache.revoke_cache_security_group_ingress(name, region=None, key=None, keyid=None, profile=None, **args) Revoke network ingress from an ec2 security group to a cache security group. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticache.revoke_cache_security_group_ingress mycachesecgrp EC2SecurityGroupName=someEC2sg EC2SecurityGroupOwnerId=SOMEOWNERID .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto3_elasticsearch .sp Connection module for Amazon Elasticsearch Service .sp New in version 3001. .INDENT 0.0 .TP .B configuration This module accepts explicit IAM credentials but can also utilize IAM roles assigned to the instance trough Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at: .INDENT 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C es.keyid: GKTADJGHEIQSXMKKRBJ08H es.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C es.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B All methods return a dict with: \(aqresult\(aq key containing a boolean indicating success or failure, \(aqerror\(aq key containing the errormessage returned by boto on error, \(aqresponse\(aq key containing the data of the response returned by boto on success. .UNINDENT .TP .B codeauthor Herbert Buurman <\fI\%herbert.buurman@ogd.nl\fP> .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.add_tags(domain_name=None, arn=None, tags=None, region=None, key=None, keyid=None, profile=None) Attaches tags to an existing Elasticsearch domain. Tags are a set of case\-sensitive key value pairs. An Elasticsearch domain may have up to 10 tags. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain_name\fP (\fI\%str\fP) \-\- The name of the Elasticsearch domain you want to add tags to. .IP \(bu 2 \fBarn\fP (\fI\%str\fP) \-\- The ARN of the Elasticsearch domain you want to add tags to. Specifying this overrides \fBdomain_name\fP\&. .IP \(bu 2 \fBtags\fP (\fI\%dict\fP) \-\- The dict of tags to add to the Elasticsearch domain. .UNINDENT .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticsearch.add_tags domain_name=mydomain tags=\(aq{\(dqfoo\(dq: \(dqbar\(dq, \(dqbaz\(dq: \(dqqux\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.cancel_elasticsearch_service_software_update(domain_name, region=None, keyid=None, key=None, profile=None) Cancels a scheduled service software update for an Amazon ES domain. You can only perform this operation before the AutomatedUpdateDate and when the UpdateStatus is in the PENDING_UPDATE state. .INDENT 7.0 .TP .B Parameters \fBdomain_name\fP (\fI\%str\fP) \-\- The name of the domain that you want to stop the latest service software update on. .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with the current service software options. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.check_upgrade_eligibility(domain_name, elasticsearch_version, region=None, keyid=None, key=None, profile=None) Helper function to determine in one call if an Elasticsearch domain can be upgraded to the specified Elasticsearch version. .sp This assumes that the Elasticsearch domain is at rest at the moment this function is called. I.e. The domain is not in the process of : .INDENT 7.0 .IP \(bu 2 being created. .IP \(bu 2 being updated. .IP \(bu 2 another upgrade running, or a check thereof. .IP \(bu 2 being deleted. .UNINDENT .sp Behind the scenes, this does 3 things: .INDENT 7.0 .IP \(bu 2 Check if \fBelasticsearch_version\fP is among the compatible elasticsearch versions. .IP \(bu 2 Perform a check if the Elasticsearch domain is eligible for the upgrade. .IP \(bu 2 Check the result of the check and return the result as a boolean. .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The Elasticsearch domain name to check. .IP \(bu 2 \fBelasticsearch_version\fP (\fI\%str\fP) \-\- The Elasticsearch version to upgrade to. .UNINDENT .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with boolean result of the check. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticsearch.check_upgrade_eligibility mydomain \(aq6.7\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.create_elasticsearch_domain(domain_name, elasticsearch_version=None, elasticsearch_cluster_config=None, ebs_options=None, access_policies=None, snapshot_options=None, vpc_options=None, cognito_options=None, encryption_at_rest_options=None, node_to_node_encryption_options=None, advanced_options=None, log_publishing_options=None, blocking=False, region=None, key=None, keyid=None, profile=None) Given a valid config, create a domain. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain_name\fP (\fI\%str\fP) \-\- The name of the Elasticsearch domain that you are creating. Domain names are unique across the domains owned by an account within an AWS region. Domain names must start with a letter or number and can contain the following characters: a\-z (lowercase), 0\-9, and \- (hyphen). .IP \(bu 2 \fBelasticsearch_version\fP (\fI\%str\fP) \-\- String of format X.Y to specify version for the Elasticsearch domain eg. \(dq1.5\(dq or \(dq2.3\(dq. .IP \(bu 2 \fBelasticsearch_cluster_config\fP (\fI\%dict\fP) \-\- .sp Dictionary specifying the configuration options for an Elasticsearch domain. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 InstanceType (str): The instance type for an Elasticsearch cluster. .IP \(bu 2 InstanceCount (int): The instance type for an Elasticsearch cluster. .IP \(bu 2 DedicatedMasterEnabled (bool): Indicate whether a dedicated master node is enabled. .IP \(bu 2 ZoneAwarenessEnabled (bool): Indicate whether zone awareness is enabled. If this is not enabled, the Elasticsearch domain will only be in one availability zone. .IP \(bu 2 ZoneAwarenessConfig (dict): Specifies the zone awareness configuration for a domain when zone awareness is enabled. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 AvailabilityZoneCount (int): An integer value to indicate the number of availability zones for a domain when zone awareness is enabled. This should be equal to number of subnets if VPC endpoints is enabled. Allowed values: 2, 3 .UNINDENT .IP \(bu 2 DedicatedMasterType (str): The instance type for a dedicated master node. .IP \(bu 2 DedicatedMasterCount (int): Total number of dedicated master nodes, active and on standby, for the cluster. .UNINDENT .IP \(bu 2 \fBebs_options\fP (\fI\%dict\fP) \-\- .sp Dict specifying the options to enable or disable and specifying the type and size of EBS storage volumes. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 EBSEnabled (bool): Specifies whether EBS\-based storage is enabled. .IP \(bu 2 VolumeType (str): Specifies the volume type for EBS\-based storage. .IP \(bu 2 VolumeSize (int): Integer to specify the size of an EBS volume. .IP \(bu 2 Iops (int): Specifies the IOPD for a Provisioned IOPS EBS volume (SSD). .UNINDENT .IP \(bu 2 \fBaccess_policies\fP (\fI\%str\fP\fI or \fP\fI\%dict\fP) \-\- Dict or JSON string with the IAM access policy. .IP \(bu 2 \fBsnapshot_options\fP (\fI\%dict\fP) \-\- .sp Dict specifying the snapshot options. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 AutomatedSnapshotStartHour (int): Specifies the time, in UTC format, when the service takes a daily automated snapshot of the specified Elasticsearch domain. Default value is 0 hours. .UNINDENT .IP \(bu 2 \fBvpc_options\fP (\fI\%dict\fP) \-\- .sp Dict with the options to specify the subnets and security groups for the VPC endpoint. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 SubnetIds (list): The list of subnets for the VPC endpoint. .IP \(bu 2 SecurityGroupIds (list): The list of security groups for the VPC endpoint. .UNINDENT .IP \(bu 2 \fBcognito_options\fP (\fI\%dict\fP) \-\- .sp Dict with options to specify the cognito user and identity pools for Kibana authentication. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 Enabled (bool): Specifies the option to enable Cognito for Kibana authentication. .IP \(bu 2 UserPoolId (str): Specifies the Cognito user pool ID for Kibana authentication. .IP \(bu 2 IdentityPoolId (str): Specifies the Cognito identity pool ID for Kibana authentication. .IP \(bu 2 RoleArn (str): Specifies the role ARN that provides Elasticsearch permissions for accessing Cognito resources. .UNINDENT .IP \(bu 2 \fBencryption_at_rest_options\fP (\fI\%dict\fP) \-\- .sp Dict specifying the encryption at rest options. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 Enabled (bool): Specifies the option to enable Encryption At Rest. .IP \(bu 2 KmsKeyId (str): Specifies the KMS Key ID for Encryption At Rest options. .UNINDENT .IP \(bu 2 \fBnode_to_node_encryption_options\fP (\fI\%dict\fP) \-\- .sp Dict specifying the node to node encryption options. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 Enabled (bool): Specify True to enable node\-to\-node encryption. .UNINDENT .IP \(bu 2 \fBadvanced_options\fP (\fI\%dict\fP) \-\- Dict with option to allow references to indices in an HTTP request body. Must be False when configuring access to individual sub\-resources. By default, the value is True. See \fI\%http://docs.aws.amazon.com/elasticsearch\-service/latest/developerguide\fP /es\-createupdatedomains.html#es\-createdomain\-configure\-advanced\-options for more information. .IP \(bu 2 \fBlog_publishing_options\fP (\fI\%dict\fP) \-\- .sp Dict with options for various type of logs. The keys denote the type of log file and can be one of the following: .INDENT 2.0 .IP \(bu 2 INDEX_SLOW_LOGS .IP \(bu 2 SEARCH_SLOW_LOGS .IP \(bu 2 ES_APPLICATION_LOGS .UNINDENT .sp The value assigned to each key is a dict with the following case sensitive keys: .INDENT 2.0 .IP \(bu 2 CloudWatchLogsLogGroupArn (str): The ARN of the Cloudwatch log group to which the log needs to be published. .IP \(bu 2 Enabled (bool): Specifies whether given log publishing option is enabled or not. .UNINDENT .IP \(bu 2 \fBblocking\fP (\fI\%bool\fP) \-\- Whether or not to wait (block) until the Elasticsearch domain has been created. .UNINDENT .UNINDENT .sp Note: Not all instance types allow enabling encryption at rest. See \fI\%https://docs.aws.amazon.com\fP /elasticsearch\-service/latest/developerguide/aes\-supported\-instance\-types.html .INDENT 7.0 .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with the domain status configuration. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticsearch.create_elasticsearch_domain mydomain \e elasticsearch_cluster_config=\(aq{ \e \(dqInstanceType\(dq: \(dqt2.micro.elasticsearch\(dq, \e \(dqInstanceCount\(dq: 1, \e \(dqDedicatedMasterEnabled\(dq: False, \e \(dqZoneAwarenessEnabled\(dq: False}\(aq \e ebs_options=\(aq{ \e \(dqEBSEnabled\(dq: True, \e \(dqVolumeType\(dq: \(dqgp2\(dq, \e \(dqVolumeSize\(dq: 10, \e \(dqIops\(dq: 0}\(aq \e access_policies=\(aq{ \e \(dqVersion\(dq: \(dq2012\-10\-17\(dq, \e \(dqStatement\(dq: [ \e {\(dqEffect\(dq: \(dqAllow\(dq, \e \(dqPrincipal\(dq: {\(dqAWS\(dq: \(dq*\(dq}, \e \(dqAction\(dq: \(dqes:*\(dq, \e \(dqResource\(dq: \(dqarn:aws:es:us\-east\-1:111111111111:domain/mydomain/*\(dq, \e \(dqCondition\(dq: {\(dqIpAddress\(dq: {\(dqaws:SourceIp\(dq: [\(dq127.0.0.1\(dq]}}}]}\(aq \e snapshot_options=\(aq{\(dqAutomatedSnapshotStartHour\(dq: 0}\(aq \e advanced_options=\(aq{\(dqrest.action.multi.allow_explicit_index\(dq: \(dqtrue\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.delete_elasticsearch_domain(domain_name, blocking=False, region=None, key=None, keyid=None, profile=None) Permanently deletes the specified Elasticsearch domain and all of its data. Once a domain is deleted, it cannot be recovered. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain_name\fP (\fI\%str\fP) \-\- The name of the domain to delete. .IP \(bu 2 \fBblocking\fP (\fI\%bool\fP) \-\- Whether or not to wait (block) until the Elasticsearch domain has been deleted. .UNINDENT .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.delete_elasticsearch_service_role(region=None, keyid=None, key=None, profile=None) Deletes the service\-linked role that Elasticsearch Service uses to manage and maintain VPC domains. Role deletion will fail if any existing VPC domains use the role. You must delete any such Elasticsearch domains before deleting the role. .INDENT 7.0 .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.describe_elasticsearch_domain(domain_name, region=None, keyid=None, key=None, profile=None) Given a domain name gets its status description. .INDENT 7.0 .TP .B Parameters \fBdomain_name\fP (\fI\%str\fP) \-\- The name of the domain to get the status of. .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary ith key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with the domain status information. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.describe_elasticsearch_domain_config(domain_name, region=None, keyid=None, key=None, profile=None) Provides cluster configuration information about the specified Elasticsearch domain, such as the state, creation date, update version, and update date for cluster options. .INDENT 7.0 .TP .B Parameters \fBdomain_name\fP (\fI\%str\fP) \-\- The name of the domain to describe. .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with the current configuration information. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.describe_elasticsearch_domains(domain_names, region=None, keyid=None, key=None, profile=None) Returns domain configuration information about the specified Elasticsearch domains, including the domain ID, domain endpoint, and domain ARN. .INDENT 7.0 .TP .B Parameters \fBdomain_names\fP (\fI\%list\fP) \-\- List of domain names to get information for. .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with the list of domain status information. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticsearch.describe_elasticsearch_domains \(aq[\(dqdomain_a\(dq, \(dqdomain_b\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.describe_elasticsearch_instance_type_limits(instance_type, elasticsearch_version, domain_name=None, region=None, keyid=None, key=None, profile=None) Describe Elasticsearch Limits for a given InstanceType and ElasticsearchVersion. When modifying existing Domain, specify the \(ga\(ga DomainName \(ga\(ga to know what Limits are supported for modifying. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBinstance_type\fP (\fI\%str\fP) \-\- The instance type for an Elasticsearch cluster for which Elasticsearch \fBLimits\fP are needed. .IP \(bu 2 \fBelasticsearch_version\fP (\fI\%str\fP) \-\- Version of Elasticsearch for which \fBLimits\fP are needed. .IP \(bu 2 \fBdomain_name\fP (\fI\%str\fP) \-\- Represents the name of the Domain that we are trying to modify. This should be present only if we are querying for Elasticsearch \fBLimits\fP for existing domain. .UNINDENT .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with the limits information. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticsearch.describe_elasticsearch_instance_type_limits \e instance_type=r3.8xlarge.elasticsearch \e elasticsearch_version=\(aq6.2\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.describe_reserved_elasticsearch_instance_offerings(reserved_elasticsearch_instance_offering_id=None, region=None, keyid=None, key=None, profile=None) Lists available reserved Elasticsearch instance offerings. .INDENT 7.0 .TP .B Parameters \fBreserved_elasticsearch_instance_offering_id\fP (\fI\%str\fP) \-\- The offering identifier filter value. Use this parameter to show only the available offering that matches the specified reservation identifier. .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with the list of offerings information. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.describe_reserved_elasticsearch_instances(reserved_elasticsearch_instance_id=None, region=None, keyid=None, key=None, profile=None) Returns information about reserved Elasticsearch instances for this account. .INDENT 7.0 .TP .B Parameters \fBreserved_elasticsearch_instance_id\fP (\fI\%str\fP) \-\- The reserved instance identifier filter value. Use this parameter to show only the reservation that matches the specified reserved Elasticsearch instance ID. .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with a list of information on reserved instances. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .TP .B Note Version 1.9.174 of boto3 has a bug in that reserved_elasticsearch_instance_id is considered a required argument, even though the documentation says otherwise. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.exists(domain_name, region=None, key=None, keyid=None, profile=None) Given a domain name, check to see if the given domain exists. .INDENT 7.0 .TP .B Parameters \fBdomain_name\fP (\fI\%str\fP) \-\- The name of the domain to check. .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.get_compatible_elasticsearch_versions(domain_name=None, region=None, keyid=None, key=None, profile=None) Returns a list of upgrade compatible Elastisearch versions. You can optionally pass a \fBdomain_name\fP to get all upgrade compatible Elasticsearch versions for that specific domain. .INDENT 7.0 .TP .B Parameters \fBdomain_name\fP (\fI\%str\fP) \-\- The name of an Elasticsearch domain. .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with a list of compatible versions. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.get_upgrade_history(domain_name, region=None, keyid=None, key=None, profile=None) Retrieves the complete history of the last 10 upgrades that were performed on the domain. .INDENT 7.0 .TP .B Parameters \fBdomain_name\fP (\fI\%str\fP) \-\- The name of an Elasticsearch domain. Domain names are unique across the domains owned by an account within an AWS region. Domain names start with a letter or number and can contain the following characters: a\-z (lowercase), 0\-9, and \- (hyphen). .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with a list of upgrade histories. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.get_upgrade_status(domain_name, region=None, keyid=None, key=None, profile=None) Retrieves the latest status of the last upgrade or upgrade eligibility check that was performed on the domain. .INDENT 7.0 .TP .B Parameters \fBdomain_name\fP (\fI\%str\fP) \-\- The name of an Elasticsearch domain. Domain names are unique across the domains owned by an account within an AWS region. Domain names start with a letter or number and can contain the following characters: a\-z (lowercase), 0\-9, and \- (hyphen). .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with upgrade status information. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.list_domain_names(region=None, keyid=None, key=None, profile=None) Returns the name of all Elasticsearch domains owned by the current user\(aqs account. .INDENT 7.0 .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with a list of domain names. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.list_elasticsearch_instance_types(elasticsearch_version, domain_name=None, region=None, keyid=None, key=None, profile=None) List all Elasticsearch instance types that are supported for given ElasticsearchVersion. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBelasticsearch_version\fP (\fI\%str\fP) \-\- Version of Elasticsearch for which list of supported elasticsearch instance types are needed. .IP \(bu 2 \fBdomain_name\fP (\fI\%str\fP) \-\- DomainName represents the name of the Domain that we are trying to modify. This should be present only if we are querying for list of available Elasticsearch instance types when modifying existing domain. .UNINDENT .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with a list of Elasticsearch instance types. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.list_elasticsearch_versions(region=None, keyid=None, key=None, profile=None) List all supported Elasticsearch versions. .INDENT 7.0 .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with a list of Elasticsearch versions. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.list_tags(domain_name=None, arn=None, region=None, key=None, keyid=None, profile=None) Returns all tags for the given Elasticsearch domain. .INDENT 7.0 .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with a dict of tags. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.purchase_reserved_elasticsearch_instance_offering(reserved_elasticsearch_instance_offering_id, reservation_name, instance_count=None, region=None, keyid=None, key=None, profile=None) Allows you to purchase reserved Elasticsearch instances. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBreserved_elasticsearch_instance_offering_id\fP (\fI\%str\fP) \-\- The ID of the reserved Elasticsearch instance offering to purchase. .IP \(bu 2 \fBreservation_name\fP (\fI\%str\fP) \-\- A customer\-specified identifier to track this reservation. .IP \(bu 2 \fBinstance_count\fP (\fI\%int\fP) \-\- The number of Elasticsearch instances to reserve. .UNINDENT .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with purchase information. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.remove_tags(tag_keys, domain_name=None, arn=None, region=None, key=None, keyid=None, profile=None) Removes the specified set of tags from the specified Elasticsearch domain. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtag_keys\fP (\fI\%list\fP) \-\- List with tag keys you want to remove from the Elasticsearch domain. .IP \(bu 2 \fBdomain_name\fP (\fI\%str\fP) \-\- The name of the Elasticsearch domain you want to remove tags from. .IP \(bu 2 \fBarn\fP (\fI\%str\fP) \-\- The ARN of the Elasticsearch domain you want to remove tags from. Specifying this overrides \fBdomain_name\fP\&. .UNINDENT .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticsearch.remove_tags \(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq domain_name=my_domain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.start_elasticsearch_service_software_update(domain_name, region=None, keyid=None, key=None, profile=None) Schedules a service software update for an Amazon ES domain. .INDENT 7.0 .TP .B Parameters \fBdomain_name\fP (\fI\%str\fP) \-\- The name of the domain that you want to update to the latest service software. .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with service software information. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.update_elasticsearch_domain_config(domain_name, elasticsearch_cluster_config=None, ebs_options=None, vpc_options=None, access_policies=None, snapshot_options=None, cognito_options=None, advanced_options=None, log_publishing_options=None, blocking=False, region=None, key=None, keyid=None, profile=None) Modifies the cluster configuration of the specified Elasticsearch domain, for example setting the instance type and the number of instances. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain_name\fP (\fI\%str\fP) \-\- The name of the Elasticsearch domain that you are creating. Domain names are unique across the domains owned by an account within an AWS region. Domain names must start with a letter or number and can contain the following characters: a\-z (lowercase), 0\-9, and \- (hyphen). .IP \(bu 2 \fBelasticsearch_cluster_config\fP (\fI\%dict\fP) \-\- .sp Dictionary specifying the configuration options for an Elasticsearch domain. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 InstanceType (str): The instance type for an Elasticsearch cluster. .IP \(bu 2 InstanceCount (int): The instance type for an Elasticsearch cluster. .IP \(bu 2 DedicatedMasterEnabled (bool): Indicate whether a dedicated master node is enabled. .IP \(bu 2 ZoneAwarenessEnabled (bool): Indicate whether zone awareness is enabled. .IP \(bu 2 ZoneAwarenessConfig (dict): Specifies the zone awareness configuration for a domain when zone awareness is enabled. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 AvailabilityZoneCount (int): An integer value to indicate the number of availability zones for a domain when zone awareness is enabled. This should be equal to number of subnets if VPC endpoints is enabled. .UNINDENT .IP \(bu 2 DedicatedMasterType (str): The instance type for a dedicated master node. .IP \(bu 2 DedicatedMasterCount (int): Total number of dedicated master nodes, active and on standby, for the cluster. .UNINDENT .IP \(bu 2 \fBebs_options\fP (\fI\%dict\fP) \-\- .sp Dict specifying the options to enable or disable and specifying the type and size of EBS storage volumes. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 EBSEnabled (bool): Specifies whether EBS\-based storage is enabled. .IP \(bu 2 VolumeType (str): Specifies the volume type for EBS\-based storage. .IP \(bu 2 VolumeSize (int): Integer to specify the size of an EBS volume. .IP \(bu 2 Iops (int): Specifies the IOPD for a Provisioned IOPS EBS volume (SSD). .UNINDENT .IP \(bu 2 \fBsnapshot_options\fP (\fI\%dict\fP) \-\- .sp Dict specifying the snapshot options. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 AutomatedSnapshotStartHour (int): Specifies the time, in UTC format, when the service takes a daily automated snapshot of the specified Elasticsearch domain. Default value is 0 hours. .UNINDENT .IP \(bu 2 \fBvpc_options\fP (\fI\%dict\fP) \-\- .sp Dict with the options to specify the subnets and security groups for the VPC endpoint. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 SubnetIds (list): The list of subnets for the VPC endpoint. .IP \(bu 2 SecurityGroupIds (list): The list of security groups for the VPC endpoint. .UNINDENT .IP \(bu 2 \fBcognito_options\fP (\fI\%dict\fP) \-\- .sp Dict with options to specify the cognito user and identity pools for Kibana authentication. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 Enabled (bool): Specifies the option to enable Cognito for Kibana authentication. .IP \(bu 2 UserPoolId (str): Specifies the Cognito user pool ID for Kibana authentication. .IP \(bu 2 IdentityPoolId (str): Specifies the Cognito identity pool ID for Kibana authentication. .IP \(bu 2 RoleArn (str): Specifies the role ARN that provides Elasticsearch permissions for accessing Cognito resources. .UNINDENT .IP \(bu 2 \fBadvanced_options\fP (\fI\%dict\fP) \-\- Dict with option to allow references to indices in an HTTP request body. Must be False when configuring access to individual sub\-resources. By default, the value is True. See \fI\%http://docs.aws.amazon.com/elasticsearch\-service/latest/developerguide\fP /es\-createupdatedomains.html#es\-createdomain\-configure\-advanced\-options for more information. .IP \(bu 2 \fBaccess_policies\fP (\fIstr/dict\fP) \-\- Dict or JSON string with the IAM access policy. .IP \(bu 2 \fBlog_publishing_options\fP (\fI\%dict\fP) \-\- .sp Dict with options for various type of logs. The keys denote the type of log file and can be one of the following: .INDENT 2.0 .INDENT 3.5 INDEX_SLOW_LOGS, SEARCH_SLOW_LOGS, ES_APPLICATION_LOGS. .UNINDENT .UNINDENT .sp The value assigned to each key is a dict with the following case sensitive keys: .INDENT 2.0 .IP \(bu 2 CloudWatchLogsLogGroupArn (str): The ARN of the Cloudwatch log group to which the log needs to be published. .IP \(bu 2 Enabled (bool): Specifies whether given log publishing option is enabled or not. .UNINDENT .IP \(bu 2 \fBblocking\fP (\fI\%bool\fP) \-\- Whether or not to wait (block) until the Elasticsearch domain has been updated. .UNINDENT .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with the domain configuration. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticsearch.update_elasticsearch_domain_config mydomain \e elasticsearch_cluster_config=\(aq{\e \(dqInstanceType\(dq: \(dqt2.micro.elasticsearch\(dq, \e \(dqInstanceCount\(dq: 1, \e \(dqDedicatedMasterEnabled\(dq: false, \(dqZoneAwarenessEnabled\(dq: false}\(aq \e ebs_options=\(aq{\e \(dqEBSEnabled\(dq: true, \e \(dqVolumeType\(dq: \(dqgp2\(dq, \e \(dqVolumeSize\(dq: 10, \e \(dqIops\(dq: 0}\(aq \e access_policies=\(aq{\(dqVersion\(dq: \(dq2012\-10\-17\(dq, \(dqStatement\(dq: [{\e \(dqEffect\(dq: \(dqAllow\(dq, \(dqPrincipal\(dq: {\(dqAWS\(dq: \(dq*\(dq}, \(dqAction\(dq: \(dqes:*\(dq, \e \(dqResource\(dq: \(dqarn:aws:es:us\-east\-1:111111111111:domain/mydomain/*\(dq, \e \(dqCondition\(dq: {\(dqIpAddress\(dq: {\(dqaws:SourceIp\(dq: [\(dq127.0.0.1\(dq]}}}]}\(aq \e snapshot_options=\(aq{\(dqAutomatedSnapshotStartHour\(dq: 0}\(aq \e advanced_options=\(aq{\(dqrest.action.multi.allow_explicit_index\(dq: \(dqtrue\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.upgrade_elasticsearch_domain(domain_name, target_version, perform_check_only=None, blocking=False, region=None, keyid=None, key=None, profile=None) Allows you to either upgrade your domain or perform an Upgrade eligibility check to a compatible Elasticsearch version. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain_name\fP (\fI\%str\fP) \-\- The name of an Elasticsearch domain. Domain names are unique across the domains owned by an account within an AWS region. Domain names start with a letter or number and can contain the following characters: a\-z (lowercase), 0\-9, and \- (hyphen). .IP \(bu 2 \fBtarget_version\fP (\fI\%str\fP) \-\- The version of Elasticsearch that you intend to upgrade the domain to. .IP \(bu 2 \fBperform_check_only\fP (\fI\%bool\fP) \-\- This flag, when set to True, indicates that an Upgrade Eligibility Check needs to be performed. This will not actually perform the Upgrade. .IP \(bu 2 \fBblocking\fP (\fI\%bool\fP) \-\- Whether or not to wait (block) until the Elasticsearch domain has been upgraded. .UNINDENT .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon success, also contains a key \(aqreponse\(aq with the domain configuration. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_elasticsearch.upgrade_elasticsearch_domain mydomain \e target_version=\(aq6.7\(aq \e perform_check_only=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_elasticsearch.wait_for_upgrade(domain_name, region=None, keyid=None, key=None, profile=None) Block until an upgrade\-in\-progress for domain \fBname\fP is finished. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the domain to wait for. .TP .B Rtype dict .TP .B Returns Dictionary with key \(aqresult\(aq and as value a boolean denoting success or failure. Upon failure, also contains a key \(aqerror\(aq with the error message as value. .UNINDENT .sp New in version 3001. .UNINDENT .SS salt.modules.boto3_route53 .sp Execution module for Amazon Route53 written against Boto 3 .sp New in version 2017.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit route53 credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C route53.keyid: GKTADJGHEIQSXMKKRBJ08H route53.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C route53.region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify key, keyid and region via a profile, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp Note that Route53 essentially ignores all (valid) settings for \(aqregion\(aq, since there is only one Endpoint (in us\-east\-1 if you care) and any (valid) region setting will just send you there. It is entirely safe to set it to None as well. .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_route53.associate_vpc_with_hosted_zone(HostedZoneId=None, Name=None, VPCId=None, VPCName=None, VPCRegion=None, Comment=None, region=None, key=None, keyid=None, profile=None) Associates an Amazon VPC with a private hosted zone. .sp To perform the association, the VPC and the private hosted zone must already exist. You can\(aqt convert a public hosted zone into a private hosted zone. If you want to associate a VPC from one AWS account with a zone from a another, the AWS account owning the hosted zone must first submit a CreateVPCAssociationAuthorization (using create_vpc_association_authorization() or by other means, such as the AWS console). With that done, the account owning the VPC can then call associate_vpc_with_hosted_zone() to create the association. .sp Note that if both sides happen to be within the same account, associate_vpc_with_hosted_zone() is enough on its own, and there is no need for the CreateVPCAssociationAuthorization step. .sp Also note that looking up hosted zones by name (e.g. using the Name parameter) only works within a single account \- if you\(aqre associating a VPC to a zone in a different account, as outlined above, you unfortunately MUST use the HostedZoneId parameter exclusively. .INDENT 7.0 .TP .B HostedZoneId The unique Zone Identifier for the Hosted Zone. .TP .B Name The domain name associated with the Hosted Zone(s). .TP .B VPCId When working with a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with VPCName. .TP .B VPCName When working with a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with VPCId. .TP .B VPCRegion When working with a private hosted zone, the region of the associated VPC is required. If not provided, an effort will be made to determine it from VPCId or VPCName, if possible. If this fails, you\(aqll need to provide an explicit value for VPCRegion. .TP .B Comment Any comments you want to include about the change being made. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_route53.associate_vpc_with_hosted_zone Name=example.org. VPCName=myVPC VPCRegion=us\-east\-1 Comment=\(dqWhoo\-hoo! I added another VPC.\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_route53.change_resource_record_sets(HostedZoneId=None, Name=None, PrivateZone=None, ChangeBatch=None, region=None, key=None, keyid=None, profile=None) See the \fI\%AWS Route53 API docs\fP as well as the \fI\%Boto3 documentation\fP for all the details... .sp The syntax for a ChangeBatch parameter is as follows, but note that the permutations of allowed parameters and combinations thereof are quite varied, so perusal of the above linked docs is highly recommended for any non\-trival configurations. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(dqComment\(dq: \(dqstring\(dq, \(dqChanges\(dq: [ { \(dqAction\(dq: \(dqCREATE\(dq|\(dqDELETE\(dq|\(dqUPSERT\(dq, \(dqResourceRecordSet\(dq: { \(dqName\(dq: \(dqstring\(dq, \(dqType\(dq: \(dqSOA\(dq|\(dqA\(dq|\(dqTXT\(dq|\(dqNS\(dq|\(dqCNAME\(dq|\(dqMX\(dq|\(dqNAPTR\(dq|\(dqPTR\(dq|\(dqSRV\(dq|\(dqSPF\(dq|\(dqAAAA\(dq, \(dqSetIdentifier\(dq: \(dqstring\(dq, \(dqWeight\(dq: 123, \(dqRegion\(dq: \(dqus\-east\-1\(dq|\(dqus\-east\-2\(dq|\(dqus\-west\-1\(dq|\(dqus\-west\-2\(dq|\(dqca\-central\-1\(dq|\(dqeu\-west\-1\(dq|\(dqeu\-west\-2\(dq|\(dqeu\-central\-1\(dq|\(dqap\-southeast\-1\(dq|\(dqap\-southeast\-2\(dq|\(dqap\-northeast\-1\(dq|\(dqap\-northeast\-2\(dq|\(dqsa\-east\-1\(dq|\(dqcn\-north\-1\(dq|\(dqap\-south\-1\(dq, \(dqGeoLocation\(dq: { \(dqContinentCode\(dq: \(dqstring\(dq, \(dqCountryCode\(dq: \(dqstring\(dq, \(dqSubdivisionCode\(dq: \(dqstring\(dq }, \(dqFailover\(dq: \(dqPRIMARY\(dq|\(dqSECONDARY\(dq, \(dqTTL\(dq: 123, \(dqResourceRecords\(dq: [ { \(dqValue\(dq: \(dqstring\(dq }, ], \(dqAliasTarget\(dq: { \(dqHostedZoneId\(dq: \(dqstring\(dq, \(dqDNSName\(dq: \(dqstring\(dq, \(dqEvaluateTargetHealth\(dq: True|False }, \(dqHealthCheckId\(dq: \(dqstring\(dq, \(dqTrafficPolicyInstanceId\(dq: \(dqstring\(dq } }, ] } .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo=\(aq{ \(dqName\(dq: \(dqmy\-cname.example.org.\(dq, \(dqTTL\(dq: 600, \(dqType\(dq: \(dqCNAME\(dq, \(dqResourceRecords\(dq: [ { \(dqValue\(dq: \(dqmy\-host.example.org\(dq } ] }\(aq foo=\(gaecho $foo\(ga # Remove newlines salt myminion boto3_route53.change_resource_record_sets DomainName=example.org. keyid=A1234567890ABCDEF123 key=xblahblahblah ChangeBatch=\(dq{\(aqChanges\(aq: [{\(aqAction\(aq: \(aqUPSERT\(aq, \(aqResourceRecordSet\(aq: $foo}]}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_route53.create_hosted_zone(Name, VPCId=None, VPCName=None, VPCRegion=None, CallerReference=None, Comment=\(aq\(aq, PrivateZone=False, DelegationSetId=None, region=None, key=None, keyid=None, profile=None) Create a new Route53 Hosted Zone. Returns a Python data structure with information about the newly created Hosted Zone. .INDENT 7.0 .TP .B Name The name of the domain. This should be a fully\-specified domain, and should terminate with a period. This is the name you have registered with your DNS registrar. It is also the name you will delegate from your registrar to the Amazon Route 53 delegation servers returned in response to this request. .TP .B VPCId When creating a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with VPCName. Ignored if passed for a non\-private zone. .TP .B VPCName When creating a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with VPCId. Ignored if passed for a non\-private zone. .TP .B VPCRegion When creating a private hosted zone, the region of the associated VPC is required. If not provided, an effort will be made to determine it from VPCId or VPCName, if possible. If this fails, you\(aqll need to provide an explicit value for this option. Ignored if passed for a non\-private zone. .TP .B CallerReference A unique string that identifies the request and that allows create_hosted_zone() calls to be retried without the risk of executing the operation twice. This is a required parameter when creating new Hosted Zones. Maximum length of 128. .TP .B Comment Any comments you want to include about the hosted zone. .TP .B PrivateZone Boolean \- Set to True if creating a private hosted zone. .TP .B DelegationSetId If you want to associate a reusable delegation set with this hosted zone, the ID that Amazon Route 53 assigned to the reusable delegation set when you created it. Note that XXX TODO create_delegation_set() is not yet implemented, so you\(aqd need to manually create any delegation sets before utilizing this. .TP .B region Region endpoint to connect to. .TP .B key AWS key to bind with. .TP .B keyid AWS keyid to bind with. .TP .B profile Dict, or pillar key pointing to a dict, containing AWS region/key/keyid. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_route53.create_hosted_zone example.org. .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_route53.delete_hosted_zone(Id, region=None, key=None, keyid=None, profile=None) Delete a Route53 hosted zone. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_route53.delete_hosted_zone Z1234567890 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_route53.delete_hosted_zone_by_domain(Name, PrivateZone=None, region=None, key=None, keyid=None, profile=None) Delete a Route53 hosted zone by domain name, and PrivateZone status if provided. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_route53.delete_hosted_zone_by_domain example.org. .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_route53.disassociate_vpc_from_hosted_zone(HostedZoneId=None, Name=None, VPCId=None, VPCName=None, VPCRegion=None, Comment=None, region=None, key=None, keyid=None, profile=None) Disassociates an Amazon VPC from a private hosted zone. .sp You can\(aqt disassociate the last VPC from a private hosted zone. You also can\(aqt convert a private hosted zone into a public hosted zone. .sp Note that looking up hosted zones by name (e.g. using the Name parameter) only works XXX FACTCHECK within a single AWS account \- if you\(aqre disassociating a VPC in one account from a hosted zone in a different account you unfortunately MUST use the HostedZoneId parameter exclusively. XXX FIXME DOCU .INDENT 7.0 .TP .B HostedZoneId The unique Zone Identifier for the Hosted Zone. .TP .B Name The domain name associated with the Hosted Zone(s). .TP .B VPCId When working with a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with VPCName. .TP .B VPCName When working with a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with VPCId. .TP .B VPCRegion When working with a private hosted zone, the region of the associated VPC is required. If not provided, an effort will be made to determine it from VPCId or VPCName, if possible. If this fails, you\(aqll need to provide an explicit value for VPCRegion. .TP .B Comment Any comments you want to include about the change being made. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_route53.disassociate_vpc_from_hosted_zone Name=example.org. VPCName=myVPC VPCRegion=us\-east\-1 Comment=\(dqWhoops! Don\(aqt wanna talk to this\-here zone no more.\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_route53.find_hosted_zone(Id=None, Name=None, PrivateZone=None, region=None, key=None, keyid=None, profile=None) Find a hosted zone with the given characteristics. .INDENT 7.0 .TP .B Id The unique Zone Identifier for the Hosted Zone. Exclusive with Name. .TP .B Name The domain name associated with the Hosted Zone. Exclusive with Id. Note this has the potential to match more then one hosted zone (e.g. a public and a private if both exist) which will raise an error unless PrivateZone has also been passed in order split the different. .TP .B PrivateZone Boolean \- Set to True if searching for a private hosted zone. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile Dict, or pillar key pointing to a dict, containing AWS region/key/keyid. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_route53.find_hosted_zone Name=salt.org. profile=\(aq{\(dqregion\(dq: \(dqus\-east\-1\(dq, \(dqkeyid\(dq: \(dqA12345678AB\(dq, \(dqkey\(dq: \(dqxblahblahblah\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_route53.get_hosted_zone(Id, region=None, key=None, keyid=None, profile=None) Return detailed info about the given zone. .INDENT 7.0 .TP .B Id The unique Zone Identifier for the Hosted Zone. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile Dict, or pillar key pointing to a dict, containing AWS region/key/keyid. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_route53.get_hosted_zone Z1234567690 profile=\(aq{\(dqregion\(dq: \(dqus\-east\-1\(dq, \(dqkeyid\(dq: \(dqA12345678AB\(dq, \(dqkey\(dq: \(dqxblahblahblah\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_route53.get_hosted_zones_by_domain(Name, region=None, key=None, keyid=None, profile=None) Find any zones with the given domain name and return detailed info about them. Note that this can return multiple Route53 zones, since a domain name can be used in both public and private zones. .INDENT 7.0 .TP .B Name The domain name associated with the Hosted Zone(s). .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile Dict, or pillar key pointing to a dict, containing AWS region/key/keyid. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_route53.get_hosted_zones_by_domain salt.org. profile=\(aq{\(dqregion\(dq: \(dqus\-east\-1\(dq, \(dqkeyid\(dq: \(dqA12345678AB\(dq, \(dqkey\(dq: \(dqxblahblahblah\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_route53.get_resource_records(HostedZoneId=None, Name=None, StartRecordName=None, StartRecordType=None, PrivateZone=None, region=None, key=None, keyid=None, profile=None) Get all resource records from a given zone matching the provided StartRecordName (if given) or all records in the zone (if not), optionally filtered by a specific StartRecordType. This will return any and all RRs matching, regardless of their special AWS flavors (weighted, geolocation, alias, etc.) so your code should be prepared for potentially large numbers of records back from this function \- for example, if you\(aqve created a complex geolocation mapping with lots of entries all over the world providing the same server name to many different regional clients. .sp If you want EXACTLY ONE record to operate on, you\(aqll need to implement any logic required to pick the specific RR you care about from those returned. .sp Note that if you pass in Name without providing a value for PrivateZone (either True or False), CommandExecutionError can be raised in the case of both public and private zones matching the domain. XXX FIXME DOCU .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_route53.get_records test.example.org example.org A .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_route53.list_hosted_zones(DelegationSetId=None, region=None, key=None, keyid=None, profile=None) Return detailed info about all zones in the bound account. .INDENT 7.0 .TP .B DelegationSetId If you\(aqre using reusable delegation sets and you want to list all of the hosted zones that are associated with a reusable delegation set, specify the ID of that delegation set. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile Dict, or pillar key pointing to a dict, containing AWS region/key/keyid. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_route53.describe_hosted_zones profile=\(aq{\(dqregion\(dq: \(dqus\-east\-1\(dq, \(dqkeyid\(dq: \(dqA12345678AB\(dq, \(dqkey\(dq: \(dqxblahblahblah\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_route53.update_hosted_zone_comment(Id=None, Name=None, Comment=None, PrivateZone=None, region=None, key=None, keyid=None, profile=None) Update the comment on an existing Route 53 hosted zone. .INDENT 7.0 .TP .B Id The unique Zone Identifier for the Hosted Zone. .TP .B Name The domain name associated with the Hosted Zone(s). .TP .B Comment Any comments you want to include about the hosted zone. .TP .B PrivateZone Boolean \- Set to True if changing a private hosted zone. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_route53.update_hosted_zone_comment Name=example.org. Comment=\(dqThis is an example comment for an example zone\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto3_sns .sp Connection module for Amazon SNS .INDENT 0.0 .TP .B configuration This module accepts explicit sns credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sns.keyid: GKTADJGHEIQSXMKKRBJ08H sns.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sns.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.create_topic(Name, region=None, key=None, keyid=None, profile=None) Create an SNS topic. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_sns.create_topic mytopic region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.delete_topic(TopicArn, region=None, key=None, keyid=None, profile=None) Delete an SNS topic. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_sns.delete_topic mytopic region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.describe_topic(name, region=None, key=None, keyid=None, profile=None) Returns details about a specific SNS topic, specified by name or ARN. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt my_favorite_client boto3_sns.describe_topic a_sns_topic_of_my_choice .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.get_subscription_attributes(SubscriptionArn, region=None, key=None, keyid=None, profile=None) Returns all of the properties of a subscription. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_sns.get_subscription_attributes somesubscription region=us\-west\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.get_topic_attributes(TopicArn, region=None, key=None, keyid=None, profile=None) Returns all of the properties of a topic. Topic properties returned might differ based on the authorization of the user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_sns.get_topic_attributes someTopic region=us\-west\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.list_subscriptions(region=None, key=None, keyid=None, profile=None) Returns a list of the requester\(aqs topics .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_sns.list_subscriptions region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.list_subscriptions_by_topic(TopicArn, region=None, key=None, keyid=None, profile=None) Returns a list of the subscriptions to a specific topic .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_sns.list_subscriptions_by_topic mytopic region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.list_topics(region=None, key=None, keyid=None, profile=None) Returns a list of the requester\(aqs topics .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_sns.list_topics .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.set_subscription_attributes(SubscriptionArn, AttributeName, AttributeValue, region=None, key=None, keyid=None, profile=None) Set an attribute of a subscription to a new value. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_sns.set_subscription_attributes someSubscription RawMessageDelivery jsonStringValue .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.set_topic_attributes(TopicArn, AttributeName, AttributeValue, region=None, key=None, keyid=None, profile=None) Set an attribute of a topic to a new value. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_sns.set_topic_attributes someTopic DisplayName myDisplayNameValue .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.subscribe(TopicArn, Protocol, Endpoint, region=None, key=None, keyid=None, profile=None) Subscribe to a Topic. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_sns.subscribe mytopic https https://www.example.com/sns\-endpoint .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.topic_exists(name, region=None, key=None, keyid=None, profile=None) Check to see if an SNS topic exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_sns.topic_exists mytopic region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto3_sns.unsubscribe(SubscriptionArn, region=None, key=None, keyid=None, profile=None) Unsubscribe a specific SubscriptionArn of a topic. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto3_sns.unsubscribe my_subscription_arn region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_apigateway .sp Connection module for Amazon APIGateway .sp New in version 2016.11.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 boto >= 2.8.0 .IP \(bu 2 boto3 >= 1.2.1 .IP \(bu 2 botocore >= 1.4.49 .UNINDENT .TP .B configuration This module accepts explicit Lambda credentials but can also utilize IAM roles assigned to the instance trough Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at: .INDENT 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C apigateway.keyid: GKTADJGHEIQSXMKKRBJ08H apigateway.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C apigateway.region: us\-west\-2 .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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-west\-2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Changed in version 2015.8.0: All methods now return a dictionary. Create and delete methods return: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C created: true .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C created: false error: message: error message .ft P .fi .UNINDENT .UNINDENT .sp Request methods (e.g., \fBdescribe_apigateway\fP) return: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apigateway: \- {...} \- {...} .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C error: message: error message .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.activate_api_deployment(restApiId, stageName, deploymentId, region=None, key=None, keyid=None, profile=None) Activates previously deployed deployment for a given stage .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.activate_api_deployent restApiId stagename deploymentId .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.api_exists(name, description=None, region=None, key=None, keyid=None, profile=None) Check to see if the given Rest API Name and optionally description exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.exists myapi_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.api_model_exists(restApiId, modelName, region=None, key=None, keyid=None, profile=None) Check to see if the given modelName exists in the given restApiId .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.api_model_exists restApiId modelName .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.associate_api_key_stagekeys(apiKey, stagekeyslist, region=None, key=None, keyid=None, profile=None) associate the given stagekeyslist to the given apiKey. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.associate_stagekeys_api_key \e api_key \(aq[\(dqrestapi id/stage name\(dq, ...]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.attach_usage_plan_to_apis(plan_id, apis, region=None, key=None, keyid=None, profile=None) Attaches given usage plan to each of the apis provided in a list of apiId and stage values .sp New in version 2017.7.0. .INDENT 7.0 .TP .B apis a list of dictionaries, where each dictionary contains the following: .INDENT 7.0 .TP .B apiId a string, which is the id of the created API in AWS ApiGateway .TP .B stage a string, which is the stage that the created API is deployed to. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.attach_usage_plan_to_apis plan_id=\(aqusage plan id\(aq apis=\(aq[{\(dqapiId\(dq: \(dqsome id 1\(dq, \(dqstage\(dq: \(dqsome stage 1\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.create_api(name, description, cloneFrom=None, region=None, key=None, keyid=None, profile=None) Create a new REST API Service with the given name .sp Returns {created: True} if the rest api was created and returns {created: False} if the rest api was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.create_api myapi_name api_description .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.create_api_deployment(restApiId, stageName, stageDescription=\(aq\(aq, description=\(aq\(aq, cacheClusterEnabled=False, cacheClusterSize=\(aq0.5\(aq, variables=None, region=None, key=None, keyid=None, profile=None) Creates a new API deployment. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.create_api_deployent restApiId stagename stageDescription=\(aq\(aq \e description=\(aq\(aq cacheClusterEnabled=True|False cacheClusterSize=0.5 variables=\(aq{\(dqname\(dq: \(dqvalue\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.create_api_integration(restApiId, resourcePath, httpMethod, integrationType, integrationHttpMethod, uri, credentials, requestParameters=None, requestTemplates=None, region=None, key=None, keyid=None, profile=None) Creates an integration for a given method in a given API. If integrationType is MOCK, uri and credential parameters will be ignored. .sp uri is in the form of (substitute APIGATEWAY_REGION and LAMBDA_FUNC_ARN) \(dqarn:aws:apigateway:APIGATEWAY_REGION:lambda:path/2015\-03\-31/functions/LAMBDA_FUNC_ARN/invocations\(dq .sp credentials is in the form of an iam role name or role arn. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.create_api_integration restApiId resourcePath httpMethod \e integrationType integrationHttpMethod uri credentials [\(aq{}\(aq [\(aq{}\(aq]] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.create_api_integration_response(restApiId, resourcePath, httpMethod, statusCode, selectionPattern, responseParameters=None, responseTemplates=None, region=None, key=None, keyid=None, profile=None) Creates an integration response for a given method in a given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.create_api_integration_response restApiId resourcePath httpMethod \e statusCode selectionPattern [\(aq{}\(aq [\(aq{}\(aq]] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.create_api_key(name, description, enabled=True, stageKeys=None, region=None, key=None, keyid=None, profile=None) Create an API key given name and description. .sp An optional enabled argument can be provided. If provided, the valid values are True|False. This argument defaults to True. .sp An optional stageKeys argument can be provided in the form of list of dictionary with \(aqrestApiId\(aq and \(aqstageName\(aq as keys. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.create_api_key name description salt myminion boto_apigateway.create_api_key name description enabled=False salt myminion boto_apigateway.create_api_key name description \e stageKeys=\(aq[{\(dqrestApiId\(dq: \(dqid\(dq, \(dqstageName\(dq: \(dqstagename\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.create_api_method(restApiId, resourcePath, httpMethod, authorizationType, apiKeyRequired=False, requestParameters=None, requestModels=None, region=None, key=None, keyid=None, profile=None) Creates API method for a resource in the given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.create_api_method restApiId resourcePath, httpMethod, authorizationType, \e apiKeyRequired=False, requestParameters=\(aq{\(dqname\(dq, \(dqvalue\(dq}\(aq, requestModels=\(aq{\(dqcontent\-type\(dq, \(dqvalue\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.create_api_method_response(restApiId, resourcePath, httpMethod, statusCode, responseParameters=None, responseModels=None, region=None, key=None, keyid=None, profile=None) Create API method response for a method on a given resource in the given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.create_api_method_response restApiId resourcePath httpMethod \e statusCode responseParameters=\(aq{\(dqname\(dq, \(dqTrue|False\(dq}\(aq responseModels=\(aq{\(dqcontent\-type\(dq, \(dqmodel\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.create_api_model(restApiId, modelName, modelDescription, schema, contentType=\(aqapplication/json\(aq, region=None, key=None, keyid=None, profile=None) Create a new model in a given API with a given schema, currently only contentType supported is \(aqapplication/json\(aq .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.create_api_model restApiId modelName modelDescription \(aq<schema>\(aq \(aqcontent\-type\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.create_api_resources(restApiId, path, region=None, key=None, keyid=None, profile=None) Given rest api id, and an absolute resource path, create all the resources and return all resources in the resourcepath, returns False on failure. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.create_api_resources myapi_id resource_path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.create_api_stage(restApiId, stageName, deploymentId, description=\(aq\(aq, cacheClusterEnabled=False, cacheClusterSize=\(aq0.5\(aq, variables=None, region=None, key=None, keyid=None, profile=None) Creates a new API stage for a given restApiId and deploymentId. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.create_api_stage restApiId stagename deploymentId \e description=\(aq\(aq cacheClusterEnabled=True|False cacheClusterSize=\(aq0.5\(aq variables=\(aq{\(dqname\(dq: \(dqvalue\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.create_usage_plan(name, description=None, throttle=None, quota=None, region=None, key=None, keyid=None, profile=None) Creates a new usage plan with throttling and quotas optionally applied .sp New in version 2017.7.0. .INDENT 7.0 .TP .B name Name of the usage plan .TP .B throttle A dictionary consisting of the following keys: .INDENT 7.0 .TP .B rateLimit requests per second at steady rate, float .TP .B burstLimit maximum number of requests per second, integer .UNINDENT .TP .B quota A dictionary consisting of the following keys: .INDENT 7.0 .TP .B limit number of allowed requests per specified quota period [required if quota parameter is present] .TP .B offset number of requests to be subtracted from limit at the beginning of the period [optional] .TP .B period quota period, must be one of DAY, WEEK, or MONTH. [required if quota parameter is present .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.create_usage_plan name=\(aqusage plan name\(aq throttle=\(aq{\(dqrateLimit\(dq: 10.0, \(dqburstLimit\(dq: 10}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.delete_api(name, description=None, region=None, key=None, keyid=None, profile=None) Delete all REST API Service with the given name and an optional API description .sp Returns {deleted: True, count: deleted_count} if apis were deleted, and returns {deleted: False} if error or not found. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.delete_api myapi_name salt myminion boto_apigateway.delete_api myapi_name description=\(aqapi description\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.delete_api_deployment(restApiId, deploymentId, region=None, key=None, keyid=None, profile=None) Deletes API deployment for a given restApiId and deploymentID .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.delete_api_deployent restApiId deploymentId .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.delete_api_integration(restApiId, resourcePath, httpMethod, region=None, key=None, keyid=None, profile=None) Deletes an integration for a given method in a given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.delete_api_integration restApiId resourcePath httpMethod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.delete_api_integration_response(restApiId, resourcePath, httpMethod, statusCode, region=None, key=None, keyid=None, profile=None) Deletes an integration response for a given method in a given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.delete_api_integration_response restApiId resourcePath httpMethod statusCode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.delete_api_key(apiKey, region=None, key=None, keyid=None, profile=None) Deletes a given apiKey .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.delete_api_key apikeystring .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.delete_api_method(restApiId, resourcePath, httpMethod, region=None, key=None, keyid=None, profile=None) Delete API method for a resource in the given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.delete_api_method restApiId resourcePath httpMethod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.delete_api_method_response(restApiId, resourcePath, httpMethod, statusCode, region=None, key=None, keyid=None, profile=None) Delete API method response for a resource in the given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.delete_api_method_response restApiId resourcePath httpMethod statusCode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.delete_api_model(restApiId, modelName, region=None, key=None, keyid=None, profile=None) Delete a model identified by name in a given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.delete_api_model restApiId modelName .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.delete_api_resources(restApiId, path, region=None, key=None, keyid=None, profile=None) Given restApiId and an absolute resource path, delete the resources starting from the absolute resource path. If resourcepath is the root resource \(aq/\(aq, the function will return False. Returns False on failure. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.delete_api_resources myapi_id, resource_path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.delete_api_stage(restApiId, stageName, region=None, key=None, keyid=None, profile=None) Deletes stage identified by stageName from API identified by restApiId .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.delete_api_stage restApiId stageName .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.delete_usage_plan(plan_id, region=None, key=None, keyid=None, profile=None) Deletes usage plan identified by plan_id .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.delete_usage_plan plan_id=\(aqusage plan id\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_deployment(restApiId, deploymentId, region=None, key=None, keyid=None, profile=None) Get API deployment for a given restApiId and deploymentId. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_deployent restApiId deploymentId .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_deployments(restApiId, region=None, key=None, keyid=None, profile=None) Gets information about the defined API Deployments. Return list of api deployments. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_deployments restApiId .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_integration(restApiId, resourcePath, httpMethod, region=None, key=None, keyid=None, profile=None) Get an integration for a given method in a given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_integration restApiId resourcePath httpMethod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_integration_response(restApiId, resourcePath, httpMethod, statusCode, region=None, key=None, keyid=None, profile=None) Get an integration response for a given method in a given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_integration_response restApiId resourcePath httpMethod statusCode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_key(apiKey, region=None, key=None, keyid=None, profile=None) Gets info about the given api key .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_key apigw_api_key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_keys(region=None, key=None, keyid=None, profile=None) Gets information about the defined API Keys. Return list of apiKeys. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_keys .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_method(restApiId, resourcePath, httpMethod, region=None, key=None, keyid=None, profile=None) Get API method for a resource in the given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_method restApiId resourcePath httpMethod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_method_response(restApiId, resourcePath, httpMethod, statusCode, region=None, key=None, keyid=None, profile=None) Get API method response for a resource in the given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_method_response restApiId resourcePath httpMethod statusCode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_model(restApiId, modelName, flatten=True, region=None, key=None, keyid=None, profile=None) Get a model by name for a given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_model restApiId modelName [True] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_models(restApiId, region=None, key=None, keyid=None, profile=None) Get all models for a given API .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_models restApiId .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_resource(restApiId, path, region=None, key=None, keyid=None, profile=None) Given rest api id, and an absolute resource path, returns the resource id for the given path. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_resource myapi_id resource_path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_resource_method(restApiId, resourcePath, httpMethod, region=None, key=None, keyid=None, profile=None) Given rest api id, resource path, and http method (must be one of DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT), return the method for the api/resource path if defined. Return False if method is not defined. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_resource_method myapi_id resource_path httpmethod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_resources(restApiId, region=None, key=None, keyid=None, profile=None) Given rest api id, return all resources for this api. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_resources myapi_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_stage(restApiId, stageName, region=None, key=None, keyid=None, profile=None) Get API stage for a given apiID and stage name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_stage restApiId stageName .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_api_stages(restApiId, deploymentId, region=None, key=None, keyid=None, profile=None) Get all API stages for a given apiID and deploymentID .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_api_stages restApiId deploymentId .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_apis(name=None, description=None, region=None, key=None, keyid=None, profile=None) Returns all rest apis in the defined region. If optional parameter name is included, returns all rest apis matching the name in the defined region. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_apis salt myminion boto_apigateway.describe_apis name=\(aqapi name\(aq salt myminion boto_apigateway.describe_apis name=\(aqapi name\(aq description=\(aqdesc str\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.describe_usage_plans(name=None, plan_id=None, region=None, key=None, keyid=None, profile=None) Returns a list of existing usage plans, optionally filtered to match a given plan name .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.describe_usage_plans salt myminion boto_apigateway.describe_usage_plans name=\(aqusage plan name\(aq salt myminion boto_apigateway.describe_usage_plans plan_id=\(aqusage plan id\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.detach_usage_plan_from_apis(plan_id, apis, region=None, key=None, keyid=None, profile=None) Detaches given usage plan from each of the apis provided in a list of apiId and stage value .sp New in version 2017.7.0. .INDENT 7.0 .TP .B apis a list of dictionaries, where each dictionary contains the following: .INDENT 7.0 .TP .B apiId a string, which is the id of the created API in AWS ApiGateway .TP .B stage a string, which is the stage that the created API is deployed to. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.detach_usage_plan_to_apis plan_id=\(aqusage plan id\(aq apis=\(aq[{\(dqapiId\(dq: \(dqsome id 1\(dq, \(dqstage\(dq: \(dqsome stage 1\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.disable_api_key(apiKey, region=None, key=None, keyid=None, profile=None) disable the given apiKey. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.enable_api_key api_key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.disassociate_api_key_stagekeys(apiKey, stagekeyslist, region=None, key=None, keyid=None, profile=None) disassociate the given stagekeyslist to the given apiKey. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.disassociate_stagekeys_api_key \e api_key \(aq[\(dqrestapi id/stage name\(dq, ...]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.enable_api_key(apiKey, region=None, key=None, keyid=None, profile=None) enable the given apiKey. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.enable_api_key api_key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.flush_api_stage_cache(restApiId, stageName, region=None, key=None, keyid=None, profile=None) Flushes cache for the stage identified by stageName from API identified by restApiId .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.flush_api_stage_cache restApiId stageName .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.overwrite_api_stage_variables(restApiId, stageName, variables, region=None, key=None, keyid=None, profile=None) Overwrite the stage variables for the given restApiId and stage name with the given variables, variables must be in the form of a dictionary. Overwrite will always remove all the existing stage variables associated with the given restApiId and stage name, follow by the adding of all the variables specified in the variables dictionary .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.overwrite_api_stage_variables restApiId stageName variables=\(aq{\(dqname\(dq: \(dqvalue\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.update_api_key_description(apiKey, description, region=None, key=None, keyid=None, profile=None) update the given apiKey with the given description. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.update_api_key_description api_key description .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.update_api_model_schema(restApiId, modelName, schema, region=None, key=None, keyid=None, profile=None) update the schema (in python dictionary format) for the given model in the given restApiId .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.update_api_model_schema restApiId modelName schema .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_apigateway.update_usage_plan(plan_id, throttle=None, quota=None, region=None, key=None, keyid=None, profile=None) Updates an existing usage plan with throttling and quotas .sp New in version 2017.7.0. .INDENT 7.0 .TP .B plan_id Id of the created usage plan .TP .B throttle A dictionary consisting of the following keys: .INDENT 7.0 .TP .B rateLimit requests per second at steady rate, float .TP .B burstLimit maximum number of requests per second, integer .UNINDENT .TP .B quota A dictionary consisting of the following keys: .INDENT 7.0 .TP .B limit number of allowed requests per specified quota period [required if quota parameter is present] .TP .B offset number of requests to be subtracted from limit at the beginning of the period [optional] .TP .B period quota period, must be one of DAY, WEEK, or MONTH. [required if quota parameter is present .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_apigateway.update_usage_plan plan_id=\(aqusage plan id\(aq throttle=\(aq{\(dqrateLimit\(dq: 10.0, \(dqburstLimit\(dq: 10}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_asg .sp Connection module for Amazon Autoscale Groups .sp New in version 2014.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit autoscale credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C asg.keyid: GKTADJGHEIQSXMKKRBJ08H asg.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C asg.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.create(name, launch_config_name, availability_zones, min_size, max_size, desired_capacity=None, load_balancers=None, default_cooldown=None, health_check_type=None, health_check_period=None, placement_group=None, vpc_zone_identifier=None, tags=None, termination_policies=None, suspended_processes=None, scaling_policies=None, scheduled_actions=None, region=None, notification_arn=None, notification_types=None, key=None, keyid=None, profile=None) Create an autoscale group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_asg.create myasg mylc \(aq[\(dqus\-east\-1a\(dq, \(dqus\-east\-1e\(dq]\(aq 1 10 load_balancers=\(aq[\(dqmyelb\(dq, \(dqmyelb2\(dq]\(aq tags=\(aq[{\(dqkey\(dq: \(dqName\(dq, value=\(dqmyasg\(dq, \(dqpropagate_at_launch\(dq: True}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.create_launch_configuration(name, image_id, key_name=None, vpc_id=None, vpc_name=None, security_groups=None, user_data=None, instance_type=\(aqm1.small\(aq, kernel_id=None, ramdisk_id=None, block_device_mappings=None, instance_monitoring=False, spot_price=None, instance_profile_name=None, ebs_optimized=False, associate_public_ip_address=None, volume_type=None, delete_on_termination=True, iops=None, use_block_device_types=False, region=None, key=None, keyid=None, profile=None) Create a launch configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_asg.create_launch_configuration mylc image_id=ami\-0b9c9f62 key_name=\(aqmykey\(aq security_groups=\(aq[\(dqmygroup\(dq]\(aq instance_type=\(aqc3.2xlarge\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.delete(name, force=False, region=None, key=None, keyid=None, profile=None) Delete an autoscale group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_asg.delete myasg region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.delete_launch_configuration(name, region=None, key=None, keyid=None, profile=None) Delete a launch configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_asg.delete_launch_configuration mylc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.describe_launch_configuration(name, region=None, key=None, keyid=None, profile=None) Dump details of a given launch configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_asg.describe_launch_configuration mylc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.enter_standby(name, instance_ids, should_decrement_desired_capacity=False, region=None, key=None, keyid=None, profile=None) Switch desired instances to StandBy mode .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_asg.enter_standby my_autoscale_group_name \(aq[\(dqi\-xxxxxx\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.exists(name, region=None, key=None, keyid=None, profile=None) Check to see if an autoscale group exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_asg.exists myasg region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.exit_standby(name, instance_ids, should_decrement_desired_capacity=False, region=None, key=None, keyid=None, profile=None) Exit desired instances from StandBy mode .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_asg.exit_standby my_autoscale_group_name \(aq[\(dqi\-xxxxxx\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.get_all_groups(region=None, key=None, keyid=None, profile=None) Return all AutoScale Groups visible in the account (as a list of boto.ec2.autoscale.group.AutoScalingGroup). .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_asg.get_all_groups region=us\-east\-1 \-\-output yaml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.get_all_launch_configurations(region=None, key=None, keyid=None, profile=None) Fetch and return all Launch Configuration with details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_asg.get_all_launch_configurations .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.get_cloud_init_mime(cloud_init) Get a mime multipart encoded string from a cloud\-init dict. Currently supports boothooks, scripts and cloud\-config. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto.get_cloud_init_mime <cloud init> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.get_config(name, region=None, key=None, keyid=None, profile=None) Get the configuration for an autoscale group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_asg.get_config myasg region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.get_instances(name, lifecycle_state=\(aqInService\(aq, health_status=\(aqHealthy\(aq, attribute=\(aqprivate_ip_address\(aq, attributes=None, region=None, key=None, keyid=None, profile=None) return attribute of all instances in the named autoscale group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_asg.get_instances my_autoscale_group_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.get_scaling_policy_arn(as_group, scaling_policy_name, region=None, key=None, keyid=None, profile=None) Return the arn for a scaling policy in a specific autoscale group or None if not found. Mainly used as a helper method for boto_cloudwatch_alarm, for linking alarms to scaling policies. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq boto_asg.get_scaling_policy_arn mygroup mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.launch_configuration_exists(name, region=None, key=None, keyid=None, profile=None) Check for a launch configuration\(aqs existence. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_asg.launch_configuration_exists mylc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.list_groups(region=None, key=None, keyid=None, profile=None) Return all AutoScale Groups visible in the account (as a list of names). .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_asg.list_groups region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.list_launch_configurations(region=None, key=None, keyid=None, profile=None) List all Launch Configurations. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_asg.list_launch_configurations .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_asg.update(name, launch_config_name, availability_zones, min_size, max_size, desired_capacity=None, load_balancers=None, default_cooldown=None, health_check_type=None, health_check_period=None, placement_group=None, vpc_zone_identifier=None, tags=None, termination_policies=None, suspended_processes=None, scaling_policies=None, scheduled_actions=None, notification_arn=None, notification_types=None, region=None, key=None, keyid=None, profile=None) Update an autoscale group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_asg.update myasg mylc \(aq[\(dqus\-east\-1a\(dq, \(dqus\-east\-1e\(dq]\(aq 1 10 load_balancers=\(aq[\(dqmyelb\(dq, \(dqmyelb2\(dq]\(aq tags=\(aq[{\(dqkey\(dq: \(dqName\(dq, value=\(dqmyasg\(dq, \(dqpropagate_at_launch\(dq: True}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_cfn .sp Connection module for Amazon Cloud Formation .sp New in version 2015.5.0. .INDENT 0.0 .TP .B configuration This module accepts explicit AWS credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cfn.keyid: GKTADJGHEIQSXMKKRBJ08H cfn.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cfn.region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cfn.create(name, template_body=None, template_url=None, parameters=None, notification_arns=None, disable_rollback=None, timeout_in_minutes=None, capabilities=None, tags=None, on_failure=None, stack_policy_body=None, stack_policy_url=None, region=None, key=None, keyid=None, profile=None) Create a CFN stack. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cfn.create mystack template_url=\(aqhttps://s3.amazonaws.com/bucket/template.cft\(aq region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cfn.delete(name, region=None, key=None, keyid=None, profile=None) Delete a CFN stack. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cfn.delete mystack region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cfn.describe(name, region=None, key=None, keyid=None, profile=None) Describe a stack. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cfn.describe mystack region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cfn.exists(name, region=None, key=None, keyid=None, profile=None) Check to see if a stack exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cfn.exists mystack region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cfn.get_template(name, region=None, key=None, keyid=None, profile=None) Check to see if attributes are set on a CFN stack. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cfn.get_template mystack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cfn.update_stack(name, template_body=None, template_url=None, parameters=None, notification_arns=None, disable_rollback=False, timeout_in_minutes=None, capabilities=None, tags=None, use_previous_template=None, stack_policy_during_update_body=None, stack_policy_during_update_url=None, stack_policy_body=None, stack_policy_url=None, region=None, key=None, keyid=None, profile=None) Update a CFN stack. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cfn.update_stack mystack template_url=\(aqhttps://s3.amazonaws.com/bucket/template.cft\(aq region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cfn.validate_template(template_body=None, template_url=None, region=None, key=None, keyid=None, profile=None) Validate cloudformation template .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cfn.validate_template mystack\-template .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_cloudfront .sp Connection module for Amazon CloudFront .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends boto3 .TP .B configuration This module accepts explicit AWS credentials but can also utilize IAM roles assigned to the instance through Instance Profiles or it can read them from the ~/.aws/credentials file or from these environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available at: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ iam\-roles\-for\-amazon\-ec2.html http://boto3.readthedocs.io/en/latest/guide/ configuration.html#guide\-configuration .ft P .fi .UNINDENT .UNINDENT .sp If IAM roles are not used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cloudfront.keyid: GKTADJGHEIQSXMKKRBJ08H cloudfront.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cloudfront.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudfront.create_distribution(name, config, tags=None, region=None, key=None, keyid=None, profile=None) Create a CloudFront distribution with the given name, config, and (optionally) tags. .INDENT 7.0 .TP .B name Name for the CloudFront distribution .TP .B config Configuration for the distribution .TP .B tags Tags to associate with the distribution .TP .B region Region to connect to .TP .B key Secret key to use .TP .B keyid Access key to use .TP .B profile A dict with region, key, and keyid, or a pillar key (string) that contains such a dict. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudfront.create_distribution name=mydistribution profile=awsprofile config=\(aq{\(dqComment\(dq:\(dqpartial configuration\(dq,\(dqEnabled\(dq:true}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudfront.export_distributions(region=None, key=None, keyid=None, profile=None) Get details of all CloudFront distributions. Produces results that can be used to create an SLS file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_cloudfront.export_distributions \-\-out=txt | sed \(dqs/local: //\(dq > cloudfront_distributions.sls .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudfront.get_distribution(name, region=None, key=None, keyid=None, profile=None) Get information about a CloudFront distribution (configuration, tags) with a given name. .INDENT 7.0 .TP .B name Name of the CloudFront distribution .TP .B region Region to connect to .TP .B key Secret key to use .TP .B keyid Access key to use .TP .B profile A dict with region, key, and keyid, or a pillar key (string) that contains such a dict. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudfront.get_distribution name=mydistribution profile=awsprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudfront.update_distribution(name, config, tags=None, region=None, key=None, keyid=None, profile=None) Update the config (and optionally tags) for the CloudFront distribution with the given name. .INDENT 7.0 .TP .B name Name of the CloudFront distribution .TP .B config Configuration for the distribution .TP .B tags Tags to associate with the distribution .TP .B region Region to connect to .TP .B key Secret key to use .TP .B keyid Access key to use .TP .B profile A dict with region, key, and keyid, or a pillar key (string) that contains such a dict. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudfront.update_distribution name=mydistribution profile=awsprofile config=\(aq{\(dqComment\(dq:\(dqpartial configuration\(dq,\(dqEnabled\(dq:true}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_cloudtrail .sp Connection module for Amazon CloudTrail .sp New in version 2016.3.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 boto .IP \(bu 2 boto3 .UNINDENT .UNINDENT .sp The dependencies listed above can be installed via package or pip. .INDENT 0.0 .TP .B configuration This module accepts explicit Lambda credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cloudtrail.keyid: GKTADJGHEIQSXMKKRBJ08H cloudtrail.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cloudtrail.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudtrail.add_tags(Name, region=None, key=None, keyid=None, profile=None, **kwargs) Add tags to a trail .sp Returns {tagged: true} if the trail was tagged and returns {tagged: False} if the trail was not tagged. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.add_tags my_trail tag_a=tag_value tag_b=tag_value .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudtrail.create(Name, S3BucketName, S3KeyPrefix=None, SnsTopicName=None, IncludeGlobalServiceEvents=None, IsMultiRegionTrail=None, EnableLogFileValidation=None, CloudWatchLogsLogGroupArn=None, CloudWatchLogsRoleArn=None, KmsKeyId=None, region=None, key=None, keyid=None, profile=None) Given a valid config, create a trail. .sp Returns {created: true} if the trail was created and returns {created: False} if the trail was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.create my_trail my_bucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudtrail.delete(Name, region=None, key=None, keyid=None, profile=None) Given a trail name, delete it. .sp Returns {deleted: true} if the trail was deleted and returns {deleted: false} if the trail was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.delete mytrail .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudtrail.describe(Name, region=None, key=None, keyid=None, profile=None) Given a trail name describe its properties. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.describe mytrail .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudtrail.exists(Name, region=None, key=None, keyid=None, profile=None) Given a trail name, check to see if the given trail exists. .sp Returns True if the given trail exists and returns False if the given trail does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.exists mytrail .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudtrail.list(region=None, key=None, keyid=None, profile=None) List all trails .sp Returns list of trails .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C policies: \- {...} \- {...} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudtrail.list_tags(Name, region=None, key=None, keyid=None, profile=None) List tags of a trail .INDENT 7.0 .TP .B Returns .INDENT 7.0 .IP \(bu 2 {...} .IP \(bu 2 {...} .UNINDENT .TP .B Return type tags .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.list_tags my_trail .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudtrail.remove_tags(Name, region=None, key=None, keyid=None, profile=None, **kwargs) Remove tags from a trail .sp Returns {tagged: true} if the trail was tagged and returns {tagged: False} if the trail was not tagged. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.remove_tags my_trail tag_a=tag_value tag_b=tag_value .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudtrail.start_logging(Name, region=None, key=None, keyid=None, profile=None) Start logging for a trail .sp Returns {started: true} if the trail was started and returns {started: False} if the trail was not started. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.start_logging my_trail .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudtrail.status(Name, region=None, key=None, keyid=None, profile=None) Given a trail name describe its properties. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.describe mytrail .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudtrail.stop_logging(Name, region=None, key=None, keyid=None, profile=None) Stop logging for a trail .sp Returns {stopped: true} if the trail was stopped and returns {stopped: False} if the trail was not stopped. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.stop_logging my_trail .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudtrail.update(Name, S3BucketName, S3KeyPrefix=None, SnsTopicName=None, IncludeGlobalServiceEvents=None, IsMultiRegionTrail=None, EnableLogFileValidation=None, CloudWatchLogsLogGroupArn=None, CloudWatchLogsRoleArn=None, KmsKeyId=None, region=None, key=None, keyid=None, profile=None) Given a valid config, update a trail. .sp Returns {created: true} if the trail was created and returns {created: False} if the trail was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.update my_trail my_bucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_cloudwatch .sp Connection module for Amazon CloudWatch .sp New in version 2014.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cloudwatch.keyid: GKTADJGHEIQSXMKKRBJ08H cloudwatch.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cloudwatch.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch.convert_to_arn(arns, region=None, key=None, keyid=None, profile=None) Convert a list of strings into actual arns. Converts convenience names such as \(aqscaling_policy:...\(aq .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq convert_to_arn \(aqscaling_policy:\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch.create_or_update_alarm(connection=None, name=None, metric=None, namespace=None, statistic=None, comparison=None, threshold=None, period=None, evaluation_periods=None, unit=None, description=\(aq\(aq, dimensions=None, alarm_actions=None, insufficient_data_actions=None, ok_actions=None, region=None, key=None, keyid=None, profile=None) Create or update a cloudwatch alarm. .INDENT 7.0 .TP .B Params are the same as: \fI\%https://boto.readthedocs.io/en/latest/ref/cloudwatch.html#boto.ec2.cloudwatch.alarm.MetricAlarm\fP\&. .UNINDENT .sp Dimensions must be a dict. If the value of Dimensions is a string, it will be json decoded to produce a dict. alarm_actions, insufficient_data_actions, and ok_actions must be lists of string. If the passed\-in value is a string, it will be split on \(dq,\(dq to produce a list. The strings themselves for alarm_actions, insufficient_data_actions, and ok_actions must be Amazon resource names (ARN\(aqs); however, this method also supports an arn lookup notation, as follows: .INDENT 7.0 .INDENT 3.5 arn:aws:.... ARN as per http://docs.aws.amazon.com/general/latest/gr/aws\-arns\-and\-namespaces.html scaling_policy:<as_name>:<scaling_policy_name> The named autoscale group scaling policy, for the named group (e.g. scaling_policy:my\-asg:ScaleDown) .UNINDENT .UNINDENT .sp This is convenient for setting up autoscaling as follows. First specify a boto_asg.present state for an ASG with scaling_policies, and then set up boto_cloudwatch_alarm.present states which have alarm_actions that reference the scaling_policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudwatch.create_alarm name=myalarm ... region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch.delete_alarm(name, region=None, key=None, keyid=None, profile=None) Delete a cloudwatch alarm .sp CLI example to delete a queue: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudwatch.delete_alarm myalarm region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch.get_alarm(name, region=None, key=None, keyid=None, profile=None) Get alarm details. Also can be used to check to see if an alarm exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudwatch.get_alarm myalarm region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch.get_all_alarms(region=None, prefix=None, key=None, keyid=None, profile=None) Get all alarm details. Produces results that can be used to create an sls file. .sp If prefix parameter is given, alarm names in the output will be prepended with the prefix; alarms that have the prefix will be skipped. This can be used to convert existing alarms to be managed by salt, as follows: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 .INDENT 3.0 .TP .B Make a \(dqbackup\(dq of all existing alarms $ salt\-call boto_cloudwatch.get_all_alarms \-\-out=txt | sed \(dqs/local: //\(dq > legacy_alarms.sls .UNINDENT .IP 2. 3 .INDENT 3.0 .TP .B Get all alarms with new prefixed names $ salt\-call boto_cloudwatch.get_all_alarms \(dqprefix=**MANAGED BY SALT** \(dq \-\-out=txt | sed \(dqs/local: //\(dq > managed_alarms.sls .UNINDENT .IP 3. 3 .INDENT 3.0 .TP .B Insert the managed alarms into cloudwatch $ salt\-call state.template managed_alarms.sls .UNINDENT .IP 4. 3 Manually verify that the new alarms look right .IP 5. 3 Delete the original alarms $ sed s/present/absent/ legacy_alarms.sls > remove_legacy_alarms.sls $ salt\-call state.template remove_legacy_alarms.sls .IP 6. 3 Get all alarms again, verify no changes $ salt\-call boto_cloudwatch.get_all_alarms \-\-out=txt | sed \(dqs/local: //\(dq > final_alarms.sls $ diff final_alarms.sls managed_alarms.sls .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudwatch.get_all_alarms region=us\-east\-1 \-\-out=txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_cloudwatch_event .sp Connection module for Amazon CloudWatch Events .sp New in version 2016.11.0. .INDENT 0.0 .TP .B configuration This module accepts explicit credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cloudwatch_event.keyid: GKTADJGHEIQSXMKKRBJ08H cloudwatch_event.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cloudwatch_event.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch_event.create_or_update(Name, ScheduleExpression=None, EventPattern=None, Description=None, RoleArn=None, State=None, region=None, key=None, keyid=None, profile=None) Given a valid config, create an event rule. .sp Returns {created: true} if the rule was created and returns {created: False} if the rule was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudwatch_event.create_or_update my_rule .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch_event.delete(Name, region=None, key=None, keyid=None, profile=None) Given a rule name, delete it. .sp Returns {deleted: true} if the rule was deleted and returns {deleted: false} if the rule was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudwatch_event.delete myrule .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch_event.describe(Name, region=None, key=None, keyid=None, profile=None) Given a rule name describe its properties. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudwatch_event.describe myrule .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch_event.exists(Name, region=None, key=None, keyid=None, profile=None) Given a rule name, check to see if the given rule exists. .sp Returns True if the given rule exists and returns False if the given rule does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudwatch_event.exists myevent region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch_event.list_rules(region=None, key=None, keyid=None, profile=None) List, with details, all Cloudwatch Event rules visible in the current scope. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudwatch_event.list_rules region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch_event.list_targets(Rule, region=None, key=None, keyid=None, profile=None) Given a rule name list the targets of that rule. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudwatch_event.list_targets myrule .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch_event.put_targets(Rule, Targets, region=None, key=None, keyid=None, profile=None) Add the given targets to the given rule .sp Returns a dictionary describing any failures. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudwatch_event.put_targets myrule [{\(aqId\(aq: \(aqtarget1\(aq, \(aqArn\(aq: \(aqarn:***\(aq}] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cloudwatch_event.remove_targets(Rule, Ids, region=None, key=None, keyid=None, profile=None) Given a rule name remove the named targets from the target list .sp Returns a dictionary describing any failures. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudwatch_event.remove_targets myrule [\(aqTarget1\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_cognitoidentity .sp Connection module for Amazon CognitoIdentity .sp New in version 2016.11.0. .INDENT 0.0 .TP .B configuration This module accepts explicit CognitoIdentity credentials but can also utilize IAM roles assigned to the instance trough Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at: .INDENT 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cognitoidentity.keyid: GKTADJGHEIQSXMKKRBJ08H cognitoidentity.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cognitoidentity.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Changed in version 2015.8.0: All methods now return a dictionary. Create, delete, set, and update methods return: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C created: true .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C created: false error: message: error message .ft P .fi .UNINDENT .UNINDENT .sp Request methods (e.g., \fIdescribe_identity_pools\fP) return: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C identity_pools: \- {...} \- {...} .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C error: message: error message .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cognitoidentity.create_identity_pool(IdentityPoolName, AllowUnauthenticatedIdentities=False, SupportedLoginProviders=None, DeveloperProviderName=None, OpenIdConnectProviderARNs=None, region=None, key=None, keyid=None, profile=None) Creates a new identity pool. All parameters except for IdentityPoolName is optional. SupportedLoginProviders should be a dictionary mapping provider names to provider app IDs. OpenIdConnectProviderARNs should be a list of OpenID Connect provider ARNs. .sp Returns the created identity pool if successful .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cognitoidentity.create_identity_pool my_id_pool_name DeveloperProviderName=custom_developer_provider .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cognitoidentity.delete_identity_pools(IdentityPoolName, IdentityPoolId=None, region=None, key=None, keyid=None, profile=None) Given an identity pool name, (optionally if an identity pool id is given, the given name will be ignored) .sp Deletes all identity pools matching the given name, or the specific identity pool with the given identity pool id. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cognitoidentity.delete_identity_pools my_id_pool_name salt myminion boto_cognitoidentity.delete_identity_pools \(aq\(aq IdentityPoolId=my_id_pool_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cognitoidentity.describe_identity_pools(IdentityPoolName, IdentityPoolId=None, region=None, key=None, keyid=None, profile=None) Given an identity pool name, (optionally if an identity pool id is given, the given name will be ignored) .sp Returns a list of matched identity pool name\(aqs pool properties .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cognitoidentity.describe_identity_pools my_id_pool_name salt myminion boto_cognitoidentity.describe_identity_pools \(aq\(aq IdentityPoolId=my_id_pool_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cognitoidentity.get_identity_pool_roles(IdentityPoolName, IdentityPoolId=None, region=None, key=None, keyid=None, profile=None) Given an identity pool name, (optionally if an identity pool id if given, the given name will be ignored) .sp Returns a list of matched identity pool name\(aqs associated roles .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cognitoidentity.get_identity_pool_roles my_id_pool_name salt myminion boto_cognitoidentity.get_identity_pool_roles \(aq\(aq IdentityPoolId=my_id_pool_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cognitoidentity.set_identity_pool_roles(IdentityPoolId, AuthenticatedRole=None, UnauthenticatedRole=None, region=None, key=None, keyid=None, profile=None) Given an identity pool id, set the given AuthenticatedRole and UnauthenticatedRole (the Role can be an iam arn, or a role name) If AuthenticatedRole or UnauthenticatedRole is not given, the authenticated and/or the unauthenticated role associated previously with the pool will be cleared. .sp Returns set True if successful, set False if unsuccessful with the associated errors. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cognitoidentity.set_identity_pool_roles my_id_pool_roles # this clears the roles salt myminion boto_cognitoidentity.set_identity_pool_roles my_id_pool_id AuthenticatedRole=my_auth_role UnauthenticatedRole=my_unauth_role # this set both roles salt myminion boto_cognitoidentity.set_identity_pool_roles my_id_pool_id AuthenticatedRole=my_auth_role # this will set the auth role and clear the unauth role salt myminion boto_cognitoidentity.set_identity_pool_roles my_id_pool_id UnauthenticatedRole=my_unauth_role # this will set the unauth role and clear the auth role .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_cognitoidentity.update_identity_pool(IdentityPoolId, IdentityPoolName=None, AllowUnauthenticatedIdentities=False, SupportedLoginProviders=None, DeveloperProviderName=None, OpenIdConnectProviderARNs=None, region=None, key=None, keyid=None, profile=None) Updates the given IdentityPoolId\(aqs properties. All parameters except for IdentityPoolId, is optional. SupportedLoginProviders should be a dictionary mapping provider names to provider app IDs. OpenIdConnectProviderARNs should be a list of OpenID Connect provider ARNs. .sp To clear SupportedLoginProviders pass \(aq{}\(aq .sp To clear OpenIdConnectProviderARNs pass \(aq[]\(aq .sp boto3 api prevents DeveloperProviderName to be updated after it has been set for the first time. .sp Returns the updated identity pool if successful .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cognitoidentity.update_identity_pool my_id_pool_id my_id_pool_name DeveloperProviderName=custom_developer_provider .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_datapipeline .sp Connection module for Amazon Data Pipeline .sp New in version 2016.3.0. .INDENT 0.0 .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_datapipeline.activate_pipeline(pipeline_id, region=None, key=None, keyid=None, profile=None) Start processing pipeline tasks. This function is idempotent. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_datapipeline.activate_pipeline my_pipeline_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_datapipeline.create_pipeline(name, unique_id, description=\(aq\(aq, region=None, key=None, keyid=None, profile=None) Create a new, empty pipeline. This function is idempotent. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_datapipeline.create_pipeline my_name my_unique_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_datapipeline.delete_pipeline(pipeline_id, region=None, key=None, keyid=None, profile=None) Delete a pipeline, its pipeline definition, and its run history. This function is idempotent. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_datapipeline.delete_pipeline my_pipeline_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_datapipeline.describe_pipelines(pipeline_ids, region=None, key=None, keyid=None, profile=None) Retrieve metadata about one or more pipelines. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_datapipeline.describe_pipelines [\(aqmy_pipeline_id\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_datapipeline.get_pipeline_definition(pipeline_id, version=\(aqlatest\(aq, region=None, key=None, keyid=None, profile=None) Get the definition of the specified pipeline. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_datapipeline.get_pipeline_definition my_pipeline_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_datapipeline.list_pipelines(region=None, key=None, keyid=None, profile=None) Get a list of pipeline ids and names for all pipelines. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_datapipeline.list_pipelines profile=myprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_datapipeline.pipeline_id_from_name(name, region=None, key=None, keyid=None, profile=None) Get the pipeline id, if it exists, for the given name. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_datapipeline.pipeline_id_from_name my_pipeline_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_datapipeline.put_pipeline_definition(pipeline_id, pipeline_objects, parameter_objects=None, parameter_values=None, region=None, key=None, keyid=None, profile=None) Add tasks, schedules, and preconditions to the specified pipeline. This function is idempotent and will replace an existing definition. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_datapipeline.put_pipeline_definition my_pipeline_id my_pipeline_objects .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_dynamodb .sp Connection module for Amazon DynamoDB .sp New in version 2015.5.0. .INDENT 0.0 .TP .B configuration This module accepts explicit DynamoDB credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C 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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_dynamodb.create_global_secondary_index(table_name, global_index, region=None, key=None, keyid=None, profile=None) Creates a single global secondary index on a DynamoDB table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_dynamodb.create_global_secondary_index table_name / index_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_dynamodb.create_table(table_name, region=None, key=None, keyid=None, profile=None, read_capacity_units=None, write_capacity_units=None, hash_key=None, hash_key_data_type=None, range_key=None, range_key_data_type=None, local_indexes=None, global_indexes=None) Creates a DynamoDB table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_dynamodb.create_table table_name / region=us\-east\-1 / hash_key=id / hash_key_data_type=N / range_key=created_at / range_key_data_type=N / read_capacity_units=1 / write_capacity_units=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_dynamodb.delete(table_name, region=None, key=None, keyid=None, profile=None) Delete a DynamoDB table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_dynamodb.delete table_name region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_dynamodb.describe(table_name, region=None, key=None, keyid=None, profile=None) Describe a DynamoDB table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_dynamodb.describe table_name region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_dynamodb.exists(table_name, region=None, key=None, keyid=None, profile=None) Check to see if a table exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_dynamodb.exists table_name region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_dynamodb.extract_index(index_data, global_index=False) Instantiates and returns an AllIndex object given a valid index configuration .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_dynamodb.extract_index index .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_dynamodb.list_tags_of_resource(resource_arn, region=None, key=None, keyid=None, profile=None) Returns a dictionary of all tags currently attached to a given resource. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_dynamodb.list_tags_of_resource resource_arn=arn:aws:dynamodb:us\-east\-1:012345678901:table/my\-table .ft P .fi .UNINDENT .UNINDENT .sp New in version 3006.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_dynamodb.tag_resource(resource_arn, tags, region=None, key=None, keyid=None, profile=None) Sets given tags (provided as list or dict) on the given resource. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_dynamodb.tag_resource resource_arn=arn:aws:dynamodb:us\-east\-1:012345678901:table/my\-table tags=\(aq{Name: my\-table, Owner: Ops}\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 3006.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_dynamodb.untag_resource(resource_arn, tag_keys, region=None, key=None, keyid=None, profile=None) Removes given tags (provided as list) from the given resource. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_dynamodb.untag_resource resource_arn=arn:aws:dynamodb:us\-east\-1:012345678901:table/my\-table tag_keys=\(aq[Name, Owner]\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 3006.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_dynamodb.update(table_name, throughput=None, global_indexes=None, region=None, key=None, keyid=None, profile=None) Update a DynamoDB table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_dynamodb.update table_name region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_dynamodb.update_global_secondary_index(table_name, global_indexes, region=None, key=None, keyid=None, profile=None) Updates the throughput of the given global secondary indexes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_dynamodb.update_global_secondary_index table_name / indexes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_ec2 .sp Connection module for Amazon EC2 .sp New in version 2015.8.0. .INDENT 0.0 .TP .B configuration This module accepts explicit EC2 credentials but 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 \fI\%here\fP\&. .UNINDENT .sp If IAM roles are not used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ec2.keyid: GKTADJGHEIQSXMKKRBJ08H ec2.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 ec2.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends boto .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.allocate_eip_address(domain=None, region=None, key=None, keyid=None, profile=None) Allocate a new Elastic IP address and associate it with your account. .INDENT 7.0 .TP .B domain (string) Optional param \- if set to exactly \(aqvpc\(aq, the address will be allocated to the VPC. The default simply maps the EIP to your account container. .TP .B returns (dict) dict of \(aqinteresting\(aq information about the newly allocated EIP, with probably the most interesting keys being \(aqpublic_ip\(aq; and \(aqallocation_id\(aq iff \(aqdomain=vpc\(aq was passed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ec2.allocate_eip_address domain=vpc .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.assign_private_ip_addresses(network_interface_name=None, network_interface_id=None, private_ip_addresses=None, secondary_private_ip_address_count=None, allow_reassignment=False, region=None, key=None, keyid=None, profile=None) Assigns one or more secondary private IP addresses to a network interface. .INDENT 7.0 .TP .B network_interface_id (string) \- ID of the network interface to associate the IP with (exclusive with \(aqnetwork_interface_name\(aq) .TP .B network_interface_name (string) \- Name of the network interface to associate the IP with (exclusive with \(aqnetwork_interface_id\(aq) .TP .B private_ip_addresses (list) \- Assigns the specified IP addresses as secondary IP addresses to the network interface (exclusive with \(aqsecondary_private_ip_address_count\(aq) .TP .B secondary_private_ip_address_count (int) \- The number of secondary IP addresses to assign to the network interface. (exclusive with \(aqprivate_ip_addresses\(aq) .TP .B allow_reassociation (bool) – Allow a currently associated EIP to be re\-associated with the new instance or interface. .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.assign_private_ip_addresses network_interface_name=my_eni private_ip_addresses=private_ip salt myminion boto_ec2.assign_private_ip_addresses network_interface_name=my_eni secondary_private_ip_address_count=2 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.associate_eip_address(instance_id=None, instance_name=None, public_ip=None, allocation_id=None, network_interface_id=None, network_interface_name=None, private_ip_address=None, allow_reassociation=False, region=None, key=None, keyid=None, profile=None) Associate an Elastic IP address with a currently running instance or a network interface. This requires exactly one of either \(aqpublic_ip\(aq or \(aqallocation_id\(aq, depending on whether you’re associating a VPC address or a plain EC2 address. .INDENT 7.0 .TP .B instance_id (string) – ID of the instance to associate with (exclusive with \(aqinstance_name\(aq) .TP .B instance_name (string) – Name tag of the instance to associate with (exclusive with \(aqinstance_id\(aq) .TP .B public_ip (string) – Public IP address, for standard EC2 based allocations. .TP .B allocation_id (string) – Allocation ID for a VPC\-based EIP. .TP .B network_interface_id (string) \- ID of the network interface to associate the EIP with .TP .B network_interface_name (string) \- Name of the network interface to associate the EIP with .TP .B private_ip_address (string) – The primary or secondary private IP address to associate with the Elastic IP address. .TP .B allow_reassociation (bool) – Allow a currently associated EIP to be re\-associated with the new instance or interface. .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.associate_eip_address instance_name=bubba.ho.tep allocation_id=eipalloc\-ef382c8a .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.attach_network_interface(device_index, name=None, network_interface_id=None, instance_name=None, instance_id=None, region=None, key=None, keyid=None, profile=None) Attach an Elastic Network Interface. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.attach_network_interface my_eni instance_name=salt\-master device_index=0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.attach_volume(volume_id, instance_id, device, region=None, key=None, keyid=None, profile=None) Attach an EBS volume to an EC2 instance. \&.. .INDENT 7.0 .TP .B volume_id (string) – The ID of the EBS volume to be attached. .TP .B instance_id (string) – The ID of the EC2 instance to attach the volume to. .TP .B device (string) – The device on the instance through which the volume is exposed (e.g. /dev/sdh) .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ec2.attach_volume vol\-12345678 i\-87654321 /dev/sdh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.create_image(ami_name, instance_id=None, instance_name=None, tags=None, region=None, key=None, keyid=None, profile=None, description=None, no_reboot=False, dry_run=False, filters=None) Given instance properties that define exactly one instance, create AMI and return AMI\-id. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.create_image ami_name instance_name=myinstance salt myminion boto_ec2.create_image another_ami_name tags=\(aq{\(dqmytag\(dq: \(dqvalue\(dq}\(aq description=\(aqthis is my ami\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.create_key(key_name, save_path, region=None, key=None, keyid=None, profile=None) Creates a key and saves it to a given path. Returns the private key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.create_key mykey /root/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.create_network_interface(name, subnet_id=None, subnet_name=None, private_ip_address=None, description=None, groups=None, region=None, key=None, keyid=None, profile=None) Create an Elastic Network Interface. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.create_network_interface my_eni subnet\-12345 description=my_eni groups=[\(aqmy_group\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.create_tags(resource_ids, tags, region=None, key=None, keyid=None, profile=None) Create new metadata tags for the specified resource ids. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B resource_ids (string) or (list) – List of resource IDs. A plain string will be converted to a list of one element. .TP .B tags (dict) – Dictionary of name/value pairs. To create only a tag name, pass \(aq\(aq as the value. .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ec2.create_tags vol\-12345678 \(aq{\(dqName\(dq: \(dqmyVolume01\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.create_volume(zone_name, size=None, snapshot_id=None, volume_type=None, iops=None, encrypted=False, kms_key_id=None, wait_for_creation=False, region=None, key=None, keyid=None, profile=None) Create an EBS volume to an availability zone. .INDENT 7.0 .TP .B zone_name (string) – The Availability zone name of the EBS volume to be created. .TP .B size .INDENT 7.0 .TP .B (int) – The size of the new volume, in GiB. If you\(aqre creating the volume from a snapshot and don\(aqt specify a volume size, the default is the snapshot size. .UNINDENT .TP .B snapshot_id (string) – The snapshot ID from which the new volume will be created. .TP .B volume_type .INDENT 7.0 .TP .B (string) \- The type of the volume. Valid volume types for AWS can be found here: \fI\%http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html\fP .UNINDENT .TP .B iops (int) \- The provisioned IOPS you want to associate with this volume. .TP .B encrypted (bool) \- Specifies whether the volume should be encrypted. .TP .B kms_key_id .INDENT 7.0 .TP .B (string) \- If encrypted is True, this KMS Key ID may be specified to encrypt volume with this key e.g.: arn:aws:kms:us\-east\-1:012345678910:key/abcd1234\-a123\-456a\-a12b\-a123b4cd56ef .UNINDENT .TP .B wait_for_creation (bool) \- Whether or not to wait for volume creation to complete. .TP .B returns (string) \- created volume id on success, error message on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ec2.create_volume us\-east\-1a size=10 salt\-call boto_ec2.create_volume us\-east\-1a snapshot_id=snap\-0123abcd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.delete_key(key_name, region=None, key=None, keyid=None, profile=None) Deletes a key. Always returns True .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.delete_key mykey .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.delete_network_interface(name=None, network_interface_id=None, region=None, key=None, keyid=None, profile=None) Create an Elastic Network Interface. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.create_network_interface my_eni subnet\-12345 description=my_eni groups=[\(aqmy_group\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.delete_tags(resource_ids, tags, region=None, key=None, keyid=None, profile=None) Delete metadata tags for the specified resource ids. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B resource_ids (string) or (list) – List of resource IDs. A plain string will be converted to a list of one element. .TP .B tags .INDENT 7.0 .TP .B (dict) or (list) – Either a dictionary containing name/value pairs or a list containing just tag names. If you pass in a dictionary, the values must match the actual tag values or the tag will not be deleted. If you pass in a value of None for the tag value, all tags with that name will be deleted. .UNINDENT .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ec2.delete_tags vol\-12345678 \(aq{\(dqName\(dq: \(dqmyVolume01\(dq}\(aq salt\-call boto_ec2.delete_tags vol\-12345678 \(aq[\(dqName\(dq,\(dqMountPoint\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.delete_volume(volume_id, instance_id=None, device=None, force=False, region=None, key=None, keyid=None, profile=None) Detach an EBS volume from an EC2 instance. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B volume_id (string) – The ID of the EBS volume to be deleted. .TP .B force (bool) – Forces deletion even if the device has not yet been detached from its instance. .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ec2.delete_volume vol\-12345678 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.detach_network_interface(name=None, network_interface_id=None, attachment_id=None, force=False, region=None, key=None, keyid=None, profile=None) Detach an Elastic Network Interface. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.detach_network_interface my_eni .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.detach_volume(volume_id, instance_id=None, device=None, force=False, wait_for_detachement=False, region=None, key=None, keyid=None, profile=None) Detach an EBS volume from an EC2 instance. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B volume_id (string) – The ID of the EBS volume to be detached. .TP .B instance_id (string) – The ID of the EC2 instance from which it will be detached. .TP .B device (string) – The device on the instance through which the volume is exposted (e.g. /dev/sdh) .TP .B force .INDENT 7.0 .TP .B (bool) – Forces detachment if the previous detachment attempt did not occur cleanly. This option can lead to data loss or a corrupted file system. Use this option only as a last resort to detach a volume from a failed instance. The instance will not have an opportunity to flush file system caches nor file system meta data. If you use this option, you must perform file system check and repair procedures. .UNINDENT .TP .B wait_for_detachement (bool) \- Whether or not to wait for volume detachement to complete. .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ec2.detach_volume vol\-12345678 i\-87654321 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.disassociate_eip_address(public_ip=None, association_id=None, region=None, key=None, keyid=None, profile=None) Disassociate an Elastic IP address from a currently running instance. This requires exactly one of either \(aqassociation_id\(aq or \(aqpublic_ip\(aq, depending on whether you’re dealing with a VPC or EC2 Classic address. .INDENT 7.0 .TP .B public_ip (string) – Public IP address, for EC2 Classic allocations. .TP .B association_id (string) – Association ID for a VPC\-bound EIP. .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.disassociate_eip_address association_id=eipassoc\-e3ba2d16 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.exists(instance_id=None, name=None, tags=None, region=None, key=None, keyid=None, profile=None, in_states=None, filters=None) Given an instance id, check to see if the given instance id exists. .sp Returns True if the given instance with the given id, name, or tags exists; otherwise, False is returned. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.exists myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.find_images(ami_name=None, executable_by=None, owners=None, image_ids=None, tags=None, region=None, key=None, keyid=None, profile=None, return_objs=False) Given image properties, find and return matching AMI ids .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.find_images tags=\(aq{\(dqmytag\(dq: \(dqvalue\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.find_instances(instance_id=None, name=None, tags=None, region=None, key=None, keyid=None, profile=None, return_objs=False, in_states=None, filters=None) Given instance properties, find and return matching instance ids .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.find_instances # Lists all instances salt myminion boto_ec2.find_instances name=myinstance salt myminion boto_ec2.find_instances tags=\(aq{\(dqmytag\(dq: \(dqvalue\(dq}\(aq salt myminion boto_ec2.find_instances filters=\(aq{\(dqvpc\-id\(dq: \(dqvpc\-12345678\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_all_eip_addresses(addresses=None, allocation_ids=None, region=None, key=None, keyid=None, profile=None) Get public addresses of some, or all EIPs associated with the current account. .INDENT 7.0 .TP .B addresses (list) \- Optional list of addresses. If provided, only the addresses associated with those in the list will be returned. .TP .B allocation_ids (list) \- Optional list of allocation IDs. If provided, only the addresses associated with the given allocation IDs will be returned. .TP .B returns (list) \- A list of the requested EIP addresses .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ec2.get_all_eip_addresses .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_all_tags(filters=None, region=None, key=None, keyid=None, profile=None) Describe all tags matching the filter criteria, or all tags in the account otherwise. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B filters (dict) \- Additional constraints on which volumes to return. Note that valid filters vary extensively depending on the resource type. When in doubt, search first without a filter and then use the returned data to help fine\-tune your search. You can generally garner the resource type from its ID (e.g. \fIvol\-XXXXX\fP is a volume, \fIi\-XXXXX\fP is an instance, etc. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ec2.get_all_tags \(aq{\(dqtag:Name\(dq: myInstanceNameTag, resource\-type: instance}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_all_volumes(volume_ids=None, filters=None, return_objs=False, region=None, key=None, keyid=None, profile=None) Get a list of all EBS volumes, optionally filtered by provided \(aqfilters\(aq param .sp New in version 2016.11.0. .INDENT 7.0 .TP .B volume_ids (list) \- Optional list of volume_ids. If provided, only the volumes associated with those in the list will be returned. .TP .B filters (dict) \- Additional constraints on which volumes to return. Valid filters are: .UNINDENT .INDENT 7.0 .IP \(bu 2 attachment.attach\-time \- The time stamp when the attachment initiated. .IP \(bu 2 attachment.delete\-on\-termination \- Whether the volume is deleted on instance termination. .IP \(bu 2 attachment.device \- The device name that is exposed to the instance (for example, /dev/sda1). .IP \(bu 2 attachment.instance\-id \- The ID of the instance the volume is attached to. .IP \(bu 2 attachment.status \- The attachment state (attaching | attached | detaching | detached). .IP \(bu 2 availability\-zone \- The Availability Zone in which the volume was created. .IP \(bu 2 create\-time \- The time stamp when the volume was created. .IP \(bu 2 encrypted \- The encryption status of the volume. .IP \(bu 2 size \- The size of the volume, in GiB. .IP \(bu 2 snapshot\-id \- The snapshot from which the volume was created. .IP \(bu 2 status \- The status of the volume (creating | available | in\-use | deleting | deleted | error). .IP \(bu 2 \fI\%tag:key=value\fP \- The key/value combination of a tag assigned to the resource. .IP \(bu 2 volume\-id \- The volume ID. .IP \(bu 2 volume\-type \- The Amazon EBS volume type. This can be \fBgp2\fP for General Purpose SSD, \fBio1\fP for Provisioned IOPS SSD, \fBst1\fP for Throughput Optimized HDD, \fBsc1\fP for Cold HDD, or \fBstandard\fP for Magnetic volumes. .UNINDENT .INDENT 7.0 .TP .B return_objs (bool) \- Changes the return type from list of volume IDs to list of boto.ec2.volume.Volume objects .TP .B returns (list) \- A list of the requested values: Either the volume IDs or, if return_objs is \fBTrue\fP, boto.ec2.volume.Volume objects. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ec2.get_all_volumes filters=\(aq{\(dqtag:Name\(dq: \(dqmyVolume01\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_attribute(attribute, instance_name=None, instance_id=None, region=None, key=None, keyid=None, profile=None, filters=None) Get an EC2 instance attribute. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.get_attribute sourceDestCheck instance_name=my_instance .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Available attributes: .INDENT 7.0 .IP \(bu 2 instanceType .IP \(bu 2 kernel .IP \(bu 2 ramdisk .IP \(bu 2 userData .IP \(bu 2 disableApiTermination .IP \(bu 2 instanceInitiatedShutdownBehavior .IP \(bu 2 rootDeviceName .IP \(bu 2 blockDeviceMapping .IP \(bu 2 productCodes .IP \(bu 2 sourceDestCheck .IP \(bu 2 groupSet .IP \(bu 2 ebsOptimized .IP \(bu 2 sriovNetSupport .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_eip_address_info(addresses=None, allocation_ids=None, region=None, key=None, keyid=None, profile=None) Get \(aqinteresting\(aq info about some, or all EIPs associated with the current account. .INDENT 7.0 .TP .B addresses (list) \- Optional list of addresses. If provided, only the addresses associated with those in the list will be returned. .TP .B allocation_ids (list) \- Optional list of allocation IDs. If provided, only the addresses associated with the given allocation IDs will be returned. .TP .B returns (list of dicts) \- A list of dicts, each containing the info for one of the requested EIPs. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ec2.get_eip_address_info addresses=52.4.2.15 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_id(name=None, tags=None, region=None, key=None, keyid=None, profile=None, in_states=None, filters=None) Given instance properties, return the instance id if it exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.get_id myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_key(key_name, region=None, key=None, keyid=None, profile=None) Check to see if a key exists. Returns fingerprint and name if it does and False if it doesn\(aqt .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.get_key mykey .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_keys(keynames=None, filters=None, region=None, key=None, keyid=None, profile=None) Gets all keys or filters them by name and returns a list. keynames (list):: A list of the names of keypairs to retrieve. If not provided, all key pairs will be returned. filters (dict) :: Optional filters that can be used to limit the results returned. Filters are provided in the form of a dictionary consisting of filter names as the key and filter values as the value. The set of allowable filter names/values is dependent on the request being performed. Check the EC2 API guide for details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.get_keys .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_network_interface(name=None, network_interface_id=None, region=None, key=None, keyid=None, profile=None) Get an Elastic Network Interface. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.get_network_interface name=my_eni .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_network_interface_id(name, region=None, key=None, keyid=None, profile=None) Get an Elastic Network Interface id from its name tag. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.get_network_interface_id name=my_eni .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_tags(instance_id=None, keyid=None, key=None, profile=None, region=None) Given an instance_id, return a list of tags associated with that instance. .INDENT 7.0 .TP .B returns (list) \- list of tags as key/value pairs .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.get_tags instance_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_unassociated_eip_address(domain=\(aqstandard\(aq, region=None, key=None, keyid=None, profile=None) Return the first unassociated EIP .INDENT 7.0 .TP .B domain Indicates whether the address is an EC2 address or a VPC address (standard|vpc). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ec2.get_unassociated_eip_address .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.get_zones(region=None, key=None, keyid=None, profile=None) Get a list of AZs for the configured region. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.get_zones .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.import_key(key_name, public_key_material, region=None, key=None, keyid=None, profile=None) Imports the public key from an RSA key pair that you created with a third\-party tool. Supported formats: \- OpenSSH public key format (e.g., the format in ~/.ssh/authorized_keys) \- Base64 encoded DER format \- SSH public key file format as specified in RFC4716 \- DSA keys are not supported. Make sure your key generator is set up to create RSA keys. Supported lengths: 1024, 2048, and 4096. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.import mykey publickey .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.modify_network_interface_attribute(name=None, network_interface_id=None, attr=None, value=None, region=None, key=None, keyid=None, profile=None) Modify an attribute of an Elastic Network Interface. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.modify_network_interface_attribute my_eni attr=description value=\(aqexample description\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.release_eip_address(public_ip=None, allocation_id=None, region=None, key=None, keyid=None, profile=None) Free an Elastic IP address. Pass either a public IP address to release an EC2 Classic EIP, or an AllocationId to release a VPC EIP. .INDENT 7.0 .TP .B public_ip (string) \- The public IP address \- for EC2 elastic IPs. .TP .B allocation_id (string) \- The Allocation ID \- for VPC elastic IPs. .TP .B returns (bool) \- True on success, False on failure .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.release_eip_address allocation_id=eipalloc\-ef382c8a .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.run(image_id, name=None, tags=None, key_name=None, security_groups=None, user_data=None, instance_type=\(aqm1.small\(aq, placement=None, kernel_id=None, ramdisk_id=None, monitoring_enabled=None, vpc_id=None, vpc_name=None, subnet_id=None, subnet_name=None, private_ip_address=None, block_device_map=None, disable_api_termination=None, instance_initiated_shutdown_behavior=None, placement_group=None, client_token=None, security_group_ids=None, security_group_names=None, additional_info=None, tenancy=None, instance_profile_arn=None, instance_profile_name=None, ebs_optimized=None, network_interface_id=None, network_interface_name=None, region=None, key=None, keyid=None, profile=None, network_interfaces=None) Create and start an EC2 instance. .sp Returns True if the instance was created; otherwise False. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.run ami\-b80c2b87 name=myinstance .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B image_id (string) – The ID of the image to run. .TP .B name (string) \- The name of the instance. .TP .B tags (dict of key: value pairs) \- tags to apply to the instance. .TP .B key_name (string) – The name of the key pair with which to launch instances. .TP .B security_groups (list of strings) – The names of the EC2 classic security groups with which to associate instances .TP .B user_data (string) – The Base64\-encoded MIME user data to be made available to the instance(s) in this reservation. .TP .B instance_type (string) – The type of instance to run. Note that some image types (e.g. hvm) only run on some instance types. .TP .B placement (string) – The Availability Zone to launch the instance into. .TP .B kernel_id (string) – The ID of the kernel with which to launch the instances. .TP .B ramdisk_id (string) – The ID of the RAM disk with which to launch the instances. .TP .B monitoring_enabled (bool) – Enable detailed CloudWatch monitoring on the instance. .TP .B vpc_id (string) \- ID of a VPC to bind the instance to. Exclusive with vpc_name. .TP .B vpc_name (string) \- Name of a VPC to bind the instance to. Exclusive with vpc_id. .TP .B subnet_id (string) – The subnet ID within which to launch the instances for VPC. .TP .B subnet_name (string) – The name of a subnet within which to launch the instances for VPC. .TP .B private_ip_address (string) – If you’re using VPC, you can optionally use this parameter to assign the instance a specific available IP address from the subnet (e.g. 10.0.0.25). .TP .B block_device_map (boto.ec2.blockdevicemapping.BlockDeviceMapping) – A BlockDeviceMapping data structure describing the EBS volumes associated with the Image. (string) \- A string representation of a BlockDeviceMapping structure (dict) \- A dict describing a BlockDeviceMapping structure .sp YAML example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C device\-maps: /dev/sdb: ephemeral_name: ephemeral0 /dev/sdc: ephemeral_name: ephemeral1 /dev/sdd: ephemeral_name: ephemeral2 /dev/sde: ephemeral_name: ephemeral3 /dev/sdf: size: 20 volume_type: gp2 .ft P .fi .UNINDENT .UNINDENT .TP .B disable_api_termination (bool) – If True, the instances will be locked and will not be able to be terminated via the API. .TP .B instance_initiated_shutdown_behavior (string) – Specifies whether the instance stops or terminates on instance\-initiated shutdown. Valid values are: stop, terminate .TP .B placement_group (string) – If specified, this is the name of the placement group in which the instance(s) will be launched. .TP .B client_token (string) – Unique, case\-sensitive identifier you provide to ensure idempotency of the request. Maximum 64 ASCII characters. .TP .B security_group_ids (list of strings) – The ID(s) of the VPC security groups with which to associate instances. .TP .B security_group_names (list of strings) – The name(s) of the VPC security groups with which to associate instances. .TP .B additional_info (string) – Specifies additional information to make available to the instance(s). .TP .B tenancy (string) – The tenancy of the instance you want to launch. An instance with a tenancy of ‘dedicated’ runs on single\-tenant hardware and can only be launched into a VPC. Valid values are:”default” or “dedicated”. NOTE: To use dedicated tenancy you MUST specify a VPC subnet\-ID as well. .TP .B instance_profile_arn (string) – The Amazon resource name (ARN) of the IAM Instance Profile (IIP) to associate with the instances. .TP .B instance_profile_name (string) – The name of the IAM Instance Profile (IIP) to associate with the instances. .TP .B ebs_optimized (bool) – 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 EBS I/O performance. This optimization isn’t available with all instance types. .TP .B network_interfaces (boto.ec2.networkinterface.NetworkInterfaceCollection) – A NetworkInterfaceCollection data structure containing the ENI specifications for the instance. .TP .B network_interface_id (string) \- ID of the network interface to attach to the instance .TP .B network_interface_name (string) \- Name of the network interface to attach to the instance .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.set_attribute(attribute, attribute_value, instance_name=None, instance_id=None, region=None, key=None, keyid=None, profile=None, filters=None) Set an EC2 instance attribute. Returns whether the operation succeeded or not. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.set_attribute sourceDestCheck False instance_name=my_instance .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Available attributes: .INDENT 7.0 .IP \(bu 2 instanceType .IP \(bu 2 kernel .IP \(bu 2 ramdisk .IP \(bu 2 userData .IP \(bu 2 disableApiTermination .IP \(bu 2 instanceInitiatedShutdownBehavior .IP \(bu 2 rootDeviceName .IP \(bu 2 blockDeviceMapping .IP \(bu 2 productCodes .IP \(bu 2 sourceDestCheck .IP \(bu 2 groupSet .IP \(bu 2 ebsOptimized .IP \(bu 2 sriovNetSupport .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.set_volumes_tags(tag_maps, authoritative=False, dry_run=False, region=None, key=None, keyid=None, profile=None) New in version 2016.11.0. .INDENT 7.0 .TP .B tag_maps (list) List of dicts of filters and tags, where \(aqfilters\(aq is a dict suitable for passing to the \(aqfilters\(aq argument of get_all_volumes() above, and \(aqtags\(aq is a dict of tags to be set on volumes (via create_tags/delete_tags) as matched by the given filters. The filter syntax is extended to permit passing either a list of volume_ids or an instance_name (with instance_name being the Name tag of the instance to which the desired volumes are mapped). Each mapping in the list is applied separately, so multiple sets of volumes can be all tagged differently with one call to this function. If filtering by instance Name, You may additionally limit the instances matched by passing in a list of desired instance states. The default set of states is (\(aqpending\(aq, \(aqrebooting\(aq, \(aqrunning\(aq, \(aqstopping\(aq, \(aqstopped\(aq). .UNINDENT .sp YAML example fragment: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- filters: attachment.instance_id: i\-abcdef12 tags: Name: dev\-int\-abcdef12.aws\-foo.com \- filters: attachment.device: /dev/sdf tags: ManagedSnapshots: true BillingGroup: bubba.hotep@aws\-foo.com in_states: \- stopped \- terminated \- filters: instance_name: prd\-foo\-01.aws\-foo.com tags: Name: prd\-foo\-01.aws\-foo.com BillingGroup: infra\-team@aws\-foo.com \- filters: volume_ids: [ vol\-12345689, vol\-abcdef12 ] tags: BillingGroup: infra\-team@aws\-foo.com .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B authoritative (bool) If true, any existing tags on the matched volumes, and not explicitly requested here, will be removed. .TP .B dry_run (bool) If true, don\(aqt change anything, just return a dictionary describing any changes which would have been applied. .TP .B returns (dict) A dict describing status and any changes. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.terminate(instance_id=None, name=None, region=None, key=None, keyid=None, profile=None, filters=None) Terminate the instance described by instance_id or name. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.terminate name=myinstance salt myminion boto_ec2.terminate instance_id=i\-a46b9f .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ec2.unassign_private_ip_addresses(network_interface_name=None, network_interface_id=None, private_ip_addresses=None, region=None, key=None, keyid=None, profile=None) Unassigns one or more secondary private IP addresses from a network interface .INDENT 7.0 .TP .B network_interface_id (string) \- ID of the network interface to associate the IP with (exclusive with \(aqnetwork_interface_name\(aq) .TP .B network_interface_name (string) \- Name of the network interface to associate the IP with (exclusive with \(aqnetwork_interface_id\(aq) .TP .B private_ip_addresses (list) \- Assigns the specified IP addresses as secondary IP addresses to the network interface. .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_ec2.unassign_private_ip_addresses network_interface_name=my_eni private_ip_addresses=private_ip .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.0. .UNINDENT .SS salt.modules.boto_efs .sp Connection module for Amazon EFS .sp New in version 2017.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit EFS credentials but can also utilize IAM roles assigned to the instance through Instance Profiles or it can read them from the ~/.aws/credentials file or from these environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available at: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C http://docs.aws.amazon.com/efs/latest/ug/ access\-control\-managing\-permissions.html http://boto3.readthedocs.io/en/latest/guide/ configuration.html#guide\-configuration .ft P .fi .UNINDENT .UNINDENT .sp If IAM roles are not used you need to specify them either in a pillar or in the minion\(aqs config file .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C efs.keyid: GKTADJGHEIQSXMKKRBJ08H efs.key: askd+ghsdfjkghWupU/asdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C efs.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askd+ghsdfjkghWupU/asdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_efs.create_file_system(name, performance_mode=\(aqgeneralPurpose\(aq, keyid=None, key=None, profile=None, region=None, creation_token=None, **kwargs) Creates a new, empty file system. .INDENT 7.0 .TP .B name (string) \- The name for the new file system .TP .B performance_mode (string) \- The PerformanceMode of the file system. Can be either generalPurpose or maxIO .TP .B creation_token (string) \- A unique name to be used as reference when creating an EFS. This will ensure idempotency. Set to name if not specified otherwise .TP .B returns (dict) \- A dict of the data for the elastic file system .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq boto_efs.create_file_system efs\-name generalPurpose .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_efs.create_mount_target(filesystemid, subnetid, ipaddress=None, securitygroups=None, keyid=None, key=None, profile=None, region=None, **kwargs) Creates a mount target for a file system. You can then mount the file system on EC2 instances via the mount target. .sp You can create one mount target in each Availability Zone in your VPC. All EC2 instances in a VPC within a given Availability Zone share a single mount target for a given file system. .sp If you have multiple subnets in an Availability Zone, you create a mount target in one of the subnets. EC2 instances do not need to be in the same subnet as the mount target in order to access their file system. .INDENT 7.0 .TP .B filesystemid (string) \- ID of the file system for which to create the mount target. .TP .B subnetid (string) \- ID of the subnet to add the mount target in. .TP .B ipaddress .INDENT 7.0 .TP .B (string) \- Valid IPv4 address within the address range of the specified subnet. .UNINDENT .TP .B securitygroups .INDENT 7.0 .TP .B (list[string]) \- Up to five VPC security group IDs, of the form sg\-xxxxxxxx. These must be for the same VPC as subnet specified. .UNINDENT .TP .B returns (dict) \- A dict of the response data .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq boto_efs.create_mount_target filesystemid subnetid .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_efs.create_tags(filesystemid, tags, keyid=None, key=None, profile=None, region=None, **kwargs) Creates or overwrites tags associated with a file system. Each tag is a key\-value pair. If a tag key specified in the request already exists on the file system, this operation overwrites its value with the value provided in the request. .INDENT 7.0 .TP .B filesystemid (string) \- ID of the file system for whose tags will be modified. .TP .B tags (dict) \- The tags to add to the file system .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq boto_efs.create_tags .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_efs.delete_file_system(filesystemid, keyid=None, key=None, profile=None, region=None, **kwargs) Deletes a file system, permanently severing access to its contents. Upon return, the file system no longer exists and you can\(aqt access any contents of the deleted file system. You can\(aqt delete a file system that is in use. That is, if the file system has any mount targets, you must first delete them. .INDENT 7.0 .TP .B filesystemid (string) \- ID of the file system to delete. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq boto_efs.delete_file_system filesystemid .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_efs.delete_mount_target(mounttargetid, keyid=None, key=None, profile=None, region=None, **kwargs) Deletes the specified mount target. .sp This operation forcibly breaks any mounts of the file system via the mount target that is being deleted, which might disrupt instances or applications using those mounts. To avoid applications getting cut off abruptly, you might consider unmounting any mounts of the mount target, if feasible. The operation also deletes the associated network interface. Uncommitted writes may be lost, but breaking a mount target using this operation does not corrupt the file system itself. The file system you created remains. You can mount an EC2 instance in your VPC via another mount target. .INDENT 7.0 .TP .B mounttargetid (string) \- ID of the mount target to delete .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq boto_efs.delete_mount_target mounttargetid .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_efs.delete_tags(filesystemid, tags, keyid=None, key=None, profile=None, region=None, **kwargs) Deletes the specified tags from a file system. .INDENT 7.0 .TP .B filesystemid (string) \- ID of the file system for whose tags will be removed. .TP .B tags (list[string]) \- The tag keys to delete to the file system .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq boto_efs.delete_tags .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_efs.get_file_systems(filesystemid=None, keyid=None, key=None, profile=None, region=None, creation_token=None, **kwargs) Get all EFS properties or a specific instance property if filesystemid is specified .INDENT 7.0 .TP .B filesystemid (string) \- ID of the file system to retrieve properties .TP .B creation_token (string) \- A unique token that identifies an EFS. If fileysystem created via create_file_system this would either be explictitly passed in or set to name. You can limit your search with this. .TP .B returns (list[dict]) \- list of all elastic file system properties .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq boto_efs.get_file_systems efs\-id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_efs.get_mount_targets(filesystemid=None, mounttargetid=None, keyid=None, key=None, profile=None, region=None, **kwargs) Get all the EFS mount point properties for a specific filesystemid or the properties for a specific mounttargetid. One or the other must be specified .INDENT 7.0 .TP .B filesystemid .INDENT 7.0 .TP .B (string) \- ID of the file system whose mount targets to list Must be specified if mounttargetid is not .UNINDENT .TP .B mounttargetid .INDENT 7.0 .TP .B (string) \- ID of the mount target to have its properties returned Must be specified if filesystemid is not .UNINDENT .TP .B returns (list[dict]) \- list of all mount point properties .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq boto_efs.get_mount_targets .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_efs.get_tags(filesystemid, keyid=None, key=None, profile=None, region=None, **kwargs) Return the tags associated with an EFS instance. .INDENT 7.0 .TP .B filesystemid (string) \- ID of the file system whose tags to list .TP .B returns (list) \- list of tags as key/value pairs .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq boto_efs.get_tags efs\-id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_efs.set_security_groups(mounttargetid, securitygroup, keyid=None, key=None, profile=None, region=None, **kwargs) Modifies the set of security groups in effect for a mount target .INDENT 7.0 .TP .B mounttargetid (string) \- ID of the mount target whose security groups will be modified .TP .B securitygroups (list[string]) \- list of no more than 5 VPC security group IDs. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq boto_efs.set_security_groups my\-mount\-target\-id my\-sec\-group .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_elasticache .sp Connection module for Amazon Elasticache .sp New in version 2014.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit elasticache credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C elasticache.keyid: GKTADJGHEIQSXMKKRBJ08H elasticache.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C elasticache.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.authorize_cache_security_group_ingress(name, ec2_security_group_name, ec2_security_group_owner_id, region=None, key=None, keyid=None, profile=None) Authorize network ingress from an ec2 security group to a cache security group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.authorize_cache_security_group_ingress myelasticachesg myec2sg 879879 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.create(name, num_cache_nodes=None, engine=None, cache_node_type=None, replication_group_id=None, engine_version=None, cache_parameter_group_name=None, cache_subnet_group_name=None, cache_security_group_names=None, security_group_ids=None, snapshot_arns=None, preferred_availability_zone=None, preferred_maintenance_window=None, port=None, notification_topic_arn=None, auto_minor_version_upgrade=None, wait=None, region=None, key=None, keyid=None, profile=None) Create a cache cluster. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.create myelasticache 1 redis cache.t1.micro cache_security_group_names=\(aq[\(dqmyelasticachesg\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.create_cache_security_group(name, description, region=None, key=None, keyid=None, profile=None) Create a cache security group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.create_cache_security_group myelasticachesg \(aqMy Cache Security Group\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.create_replication_group(name, primary_cluster_id, replication_group_description, wait=None, region=None, key=None, keyid=None, profile=None) Create replication group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.create_replication_group myelasticache myprimarycluster description .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.create_subnet_group(name, description, subnet_ids=None, subnet_names=None, tags=None, region=None, key=None, keyid=None, profile=None) Create an ElastiCache subnet group .sp CLI example to create an ElastiCache subnet group: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.create_subnet_group my\-subnet\-group \(dqgroup description\(dq subnet_ids=\(aq[subnet\-12345678, subnet\-87654321]\(aq region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.delete(name, wait=False, region=None, key=None, keyid=None, profile=None) Delete a cache cluster. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.delete myelasticache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.delete_cache_security_group(name, region=None, key=None, keyid=None, profile=None) Delete a cache security group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.delete_cache_security_group myelasticachesg \(aqMy Cache Security Group\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.delete_replication_group(name, region=None, key=None, keyid=None, profile=None) Delete an ElastiCache replication group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.delete_replication_group my\-replication\-group region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.delete_subnet_group(name, region=None, key=None, keyid=None, profile=None) Delete an ElastiCache subnet group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.delete_subnet_group my\-subnet\-group region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.describe_replication_group(name, region=None, key=None, keyid=None, profile=None, parameter=None) Get replication group information. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.describe_replication_group mygroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.exists(name, region=None, key=None, keyid=None, profile=None) Check to see if a cache cluster exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.exists myelasticache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.get_all_cache_subnet_groups(name=None, region=None, key=None, keyid=None, profile=None) Return a list of all cache subnet groups with details .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.get_all_subnet_groups region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.get_cache_subnet_group(name, region=None, key=None, keyid=None, profile=None) Get information about a cache subnet group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.get_cache_subnet_group mycache_subnet_group .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.get_config(name, region=None, key=None, keyid=None, profile=None) Get the configuration for a cache cluster. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.get_config myelasticache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.get_group_host(name, region=None, key=None, keyid=None, profile=None) Get hostname from replication cache group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.get_group_host myelasticachegroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.get_node_host(name, region=None, key=None, keyid=None, profile=None) Get hostname from cache node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.get_node_host myelasticache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.group_exists(name, region=None, key=None, keyid=None, profile=None) Check to see if a replication group exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.group_exists myelasticache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.list_cache_subnet_groups(name=None, region=None, key=None, keyid=None, profile=None) Return a list of all cache subnet group names .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.list_subnet_groups region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.revoke_cache_security_group_ingress(name, ec2_security_group_name, ec2_security_group_owner_id, region=None, key=None, keyid=None, profile=None) Revoke network ingress from an ec2 security group to a cache security group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.revoke_cache_security_group_ingress myelasticachesg myec2sg 879879 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticache.subnet_group_exists(name, tags=None, region=None, key=None, keyid=None, profile=None) Check to see if an ElastiCache subnet group exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticache.subnet_group_exists my\-param\-group region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_elasticsearch_domain .sp Connection module for Amazon Elasticsearch Service .sp New in version 2016.11.0. .INDENT 0.0 .TP .B configuration This module accepts explicit AWS credentials but can also utilize IAM roles assigned to the instance trough Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at: .INDENT 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C lambda.keyid: GKTADJGHEIQSXMKKRBJ08H lambda.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C lambda.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp Create and delete methods return: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C created: true .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C created: false error: message: error message .ft P .fi .UNINDENT .UNINDENT .sp Request methods (e.g., \fIdescribe_function\fP) return: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C domain: \- {...} \- {...} .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C error: message: error message .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticsearch_domain.add_tags(DomainName=None, ARN=None, region=None, key=None, keyid=None, profile=None, **kwargs) Add tags to a domain .sp Returns {tagged: true} if the domain was tagged and returns {tagged: False} if the domain was not tagged. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticsearch_domain.add_tags mydomain tag_a=tag_value tag_b=tag_value .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticsearch_domain.create(DomainName, ElasticsearchClusterConfig=None, EBSOptions=None, AccessPolicies=None, SnapshotOptions=None, AdvancedOptions=None, region=None, key=None, keyid=None, profile=None, ElasticsearchVersion=None) Given a valid config, create a domain. .sp Returns {created: true} if the domain was created and returns {created: False} if the domain was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticsearch_domain.create mydomain \e {\(aqInstanceType\(aq: \(aqt2.micro.elasticsearch\(aq, \(aqInstanceCount\(aq: 1, \e \(aqDedicatedMasterEnabled\(aq: false, \(aqZoneAwarenessEnabled\(aq: false} \e {\(aqEBSEnabled\(aq: true, \(aqVolumeType\(aq: \(aqgp2\(aq, \(aqVolumeSize\(aq: 10, \e \(aqIops\(aq: 0} \e {\(dqVersion\(dq: \(dq2012\-10\-17\(dq, \(dqStatement\(dq: [{\(dqEffect\(dq: \(dqAllow\(dq, \(dqPrincipal\(dq: {\(dqAWS\(dq: \(dq*\(dq}, \(dqAction\(dq: \(dqes:*\(dq, \e \(dqResource\(dq: \(dqarn:aws:es:us\-east\-1:111111111111:domain/mydomain/*\(dq, \e \(dqCondition\(dq: {\(dqIpAddress\(dq: {\(dqaws:SourceIp\(dq: [\(dq127.0.0.1\(dq]}}}]} \e {\(dqAutomatedSnapshotStartHour\(dq: 0} \e {\(dqrest.action.multi.allow_explicit_index\(dq: \(dqtrue\(dq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticsearch_domain.delete(DomainName, region=None, key=None, keyid=None, profile=None) Given a domain name, delete it. .sp Returns {deleted: true} if the domain was deleted and returns {deleted: false} if the domain was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticsearch_domain.delete mydomain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticsearch_domain.describe(DomainName, region=None, key=None, keyid=None, profile=None) Given a domain name describe its properties. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticsearch_domain.describe mydomain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticsearch_domain.exists(DomainName, region=None, key=None, keyid=None, profile=None) Given a domain name, check to see if the given domain exists. .sp Returns True if the given domain exists and returns False if the given function does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticsearch_domain.exists mydomain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticsearch_domain.list_tags(DomainName=None, ARN=None, region=None, key=None, keyid=None, profile=None) List tags of a trail .INDENT 7.0 .TP .B Returns .INDENT 7.0 .IP \(bu 2 {...} .IP \(bu 2 {...} .UNINDENT .TP .B Return type tags .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.list_tags my_trail .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticsearch_domain.remove_tags(TagKeys, DomainName=None, ARN=None, region=None, key=None, keyid=None, profile=None) Remove tags from a trail .sp Returns {tagged: true} if the trail was tagged and returns {tagged: False} if the trail was not tagged. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_cloudtrail.remove_tags my_trail tag_a=tag_value tag_b=tag_value .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticsearch_domain.status(DomainName, region=None, key=None, keyid=None, profile=None) Given a domain name describe its status. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticsearch_domain.status mydomain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elasticsearch_domain.update(DomainName, ElasticsearchClusterConfig=None, EBSOptions=None, AccessPolicies=None, SnapshotOptions=None, AdvancedOptions=None, region=None, key=None, keyid=None, profile=None) Update the named domain to the configuration. .sp Returns {updated: true} if the domain was updated and returns {updated: False} if the domain was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elasticsearch_domain.update mydomain \e {\(aqInstanceType\(aq: \(aqt2.micro.elasticsearch\(aq, \(aqInstanceCount\(aq: 1, \e \(aqDedicatedMasterEnabled\(aq: false, \(aqZoneAwarenessEnabled\(aq: false} \e {\(aqEBSEnabled\(aq: true, \(aqVolumeType\(aq: \(aqgp2\(aq, \(aqVolumeSize\(aq: 10, \e \(aqIops\(aq: 0} \e {\(dqVersion\(dq: \(dq2012\-10\-17\(dq, \(dqStatement\(dq: [{\(dqEffect\(dq: \(dqAllow\(dq, \(dqPrincipal\(dq: {\(dqAWS\(dq: \(dq*\(dq}, \(dqAction\(dq: \(dqes:*\(dq, \e \(dqResource\(dq: \(dqarn:aws:es:us\-east\-1:111111111111:domain/mydomain/*\(dq, \e \(dqCondition\(dq: {\(dqIpAddress\(dq: {\(dqaws:SourceIp\(dq: [\(dq127.0.0.1\(dq]}}}]} \e {\(dqAutomatedSnapshotStartHour\(dq: 0} \e {\(dqrest.action.multi.allow_explicit_index\(dq: \(dqtrue\(dq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_elb .sp Connection module for Amazon ELB .sp New in version 2014.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit elb credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C elb.keyid: GKTADJGHEIQSXMKKRBJ08H elb.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C elb.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto >= 2.33.0 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.apply_security_groups(name, security_groups, region=None, key=None, keyid=None, profile=None) Apply security groups to ELB. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.apply_security_groups myelb \(aq[\(dqmysecgroup1\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.attach_subnets(name, subnets, region=None, key=None, keyid=None, profile=None) Attach ELB to subnets. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.attach_subnets myelb \(aq[\(dqmysubnet\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.create(name, availability_zones, listeners, subnets=None, security_groups=None, scheme=\(aqinternet\-facing\(aq, region=None, key=None, keyid=None, profile=None) Create an ELB .sp CLI example to create an ELB: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.create myelb \(aq[\(dqus\-east\-1a\(dq, \(dqus\-east\-1e\(dq]\(aq \(aq{\(dqelb_port\(dq: 443, \(dqelb_protocol\(dq: \(dqHTTPS\(dq, ...}\(aq region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.create_listeners(name, listeners, region=None, key=None, keyid=None, profile=None) Create listeners on an ELB. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.create_listeners myelb \(aq[[\(dqHTTPS\(dq, \(dqHTTP\(dq, 443, 80, \(dqarn:aws:iam::11 11111:server\-certificate/mycert\(dq]]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.create_policy(name, policy_name, policy_type, policy, region=None, key=None, keyid=None, profile=None) Create an ELB policy. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.create_policy myelb mypolicy LBCookieStickinessPolicyType \(aq{\(dqCookieExpirationPeriod\(dq: 3600}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.delete(name, region=None, key=None, keyid=None, profile=None) Delete an ELB. .sp CLI example to delete an ELB: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.delete myelb region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.delete_listeners(name, ports, region=None, key=None, keyid=None, profile=None) Delete listeners on an ELB. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.delete_listeners myelb \(aq[80,443]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.delete_policy(name, policy_name, region=None, key=None, keyid=None, profile=None) Delete an ELB policy. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.delete_policy myelb mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.delete_tags(name, tags, region=None, key=None, keyid=None, profile=None) Add the tags on an ELB .INDENT 7.0 .TP .B name name of the ELB .TP .B tags list of tags to remove .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.delete_tags my\-elb\-name [\(aqTagToRemove1\(aq, \(aqTagToRemove2\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.deregister_instances(name, instances, region=None, key=None, keyid=None, profile=None) Deregister instances with an ELB. Instances is either a string instance id or a list of string instance id\(aqs. .sp Returns: .INDENT 7.0 .IP \(bu 2 \fBTrue\fP: instance(s) deregistered successfully .IP \(bu 2 \fBFalse\fP: instance(s) failed to be deregistered .IP \(bu 2 \fBNone\fP: instance(s) not valid or not registered, no action taken .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.deregister_instances myelb instance_id salt myminion boto_elb.deregister_instances myelb \(dq[instance_id, instance_id]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.detach_subnets(name, subnets, region=None, key=None, keyid=None, profile=None) Detach ELB from subnets. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.detach_subnets myelb \(aq[\(dqmysubnet\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.disable_availability_zones(name, availability_zones, region=None, key=None, keyid=None, profile=None) Disable availability zones for ELB. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.disable_availability_zones myelb \(aq[\(dqus\-east\-1a\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.enable_availability_zones(name, availability_zones, region=None, key=None, keyid=None, profile=None) Enable availability zones for ELB. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.enable_availability_zones myelb \(aq[\(dqus\-east\-1a\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.exists(name, region=None, key=None, keyid=None, profile=None) Check to see if an ELB exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.exists myelb region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.get_all_elbs(region=None, key=None, keyid=None, profile=None) Return all load balancers associated with an account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.get_all_elbs region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.get_attributes(name, region=None, key=None, keyid=None, profile=None) Check to see if attributes are set on an ELB. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.get_attributes myelb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.get_elb_config(name, region=None, key=None, keyid=None, profile=None) Get an ELB configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.exists myelb region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.get_health_check(name, region=None, key=None, keyid=None, profile=None) Get the health check configured for this ELB. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.get_health_check myelb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.get_instance_health(name, region=None, key=None, keyid=None, profile=None, instances=None) Get a list of instances and their health state .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.get_instance_health myelb salt myminion boto_elb.get_instance_health myelb region=us\-east\-1 instances=\(dq[instance_id,instance_id]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.list_elbs(region=None, key=None, keyid=None, profile=None) Return names of all load balancers associated with an account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.list_elbs region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.listener_dict_to_tuple(listener) Convert an ELB listener dict into a listener tuple used by certain parts of the AWS ELB API. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.listener_dict_to_tuple \(aq{\(dqelb_port\(dq:80,\(dqinstance_port\(dq:80,\(dqelb_protocol\(dq:\(dqHTTP\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.register_instances(name, instances, region=None, key=None, keyid=None, profile=None) Register instances with an ELB. Instances is either a string instance id or a list of string instance id\(aqs. .sp Returns: .INDENT 7.0 .IP \(bu 2 \fBTrue\fP: instance(s) registered successfully .IP \(bu 2 \fBFalse\fP: instance(s) failed to be registered .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.register_instances myelb instance_id salt myminion boto_elb.register_instances myelb \(dq[instance_id,instance_id]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.set_attributes(name, attributes, region=None, key=None, keyid=None, profile=None) Set attributes on an ELB. .INDENT 7.0 .TP .B name (string) Name of the ELB instance to set attributes for .TP .B attributes A dict of attributes to set. .sp Valid attributes are: .INDENT 7.0 .TP .B access_log (dict) .INDENT 7.0 .TP .B enabled (bool) Enable storage of access logs. .TP .B s3_bucket_name (string) The name of the S3 bucket to place logs. .TP .B s3_bucket_prefix (string) Prefix for the log file name. .TP .B emit_interval (int) Interval for storing logs in S3 in minutes. Valid values are 5 and 60. .UNINDENT .TP .B connection_draining (dict) .INDENT 7.0 .TP .B enabled (bool) Enable connection draining. .TP .B timeout (int) Maximum allowed time in seconds for sending existing connections to an instance that is deregistering or unhealthy. Default is 300. .UNINDENT .TP .B cross_zone_load_balancing (dict) .INDENT 7.0 .TP .B enabled (bool) Enable cross\-zone load balancing. .UNINDENT .UNINDENT .UNINDENT .sp CLI example to set attributes on an ELB: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.set_attributes myelb \(aq{\(dqaccess_log\(dq: {\(dqenabled\(dq: \(dqtrue\(dq, \(dqs3_bucket_name\(dq: \(dqmybucket\(dq, \(dqs3_bucket_prefix\(dq: \(dqmylogs/\(dq, \(dqemit_interval\(dq: \(dq5\(dq}}\(aq region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.set_backend_policy(name, port, policies=None, region=None, key=None, keyid=None, profile=None) Set the policies of an ELB backend server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.set_backend_policy myelb 443 \(dq[policy1,policy2]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.set_health_check(name, health_check, region=None, key=None, keyid=None, profile=None) Set attributes on an ELB. .sp CLI example to set attributes on an ELB: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.set_health_check myelb \(aq{\(dqtarget\(dq: \(dqHTTP:80/\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.set_instances(name, instances, test=False, region=None, key=None, keyid=None, profile=None) Set the instances assigned to an ELB to exactly the list given .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.set_instances myelb region=us\-east\-1 instances=\(dq[instance_id,instance_id]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.set_listener_policy(name, port, policies=None, region=None, key=None, keyid=None, profile=None) Set the policies of an ELB listener. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.set_listener_policy myelb 443 \(dq[policy1,policy2]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elb.set_tags(name, tags, region=None, key=None, keyid=None, profile=None) Add the tags on an ELB .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name name of the ELB .TP .B tags dict of name/value pair tags .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elb.set_tags my\-elb\-name \(dq{\(aqTag1\(aq: \(aqValue\(aq, \(aqTag2\(aq: \(aqAnother Value\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_elbv2 .sp Connection module for Amazon ALB .sp New in version 2017.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit elb credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C elbv2.keyid: GKTADJGHEIQSXMKKRBJ08H elbv2.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs elbv2.region: us\-west\-2 .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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elbv2.create_target_group(name, protocol, port, vpc_id, region=None, key=None, keyid=None, profile=None, health_check_protocol=\(aqHTTP\(aq, health_check_port=\(aqtraffic\-port\(aq, health_check_path=\(aq/\(aq, health_check_interval_seconds=30, health_check_timeout_seconds=5, healthy_threshold_count=5, unhealthy_threshold_count=2) Create target group if not present. .INDENT 7.0 .TP .B name (string) \- The name of the target group. .TP .B protocol (string) \- The protocol to use for routing traffic to the targets .TP .B port (int) \- The port on which the targets receive traffic. This port is used unless you specify a port override when registering the traffic. .TP .B vpc_id (string) \- The identifier of the virtual private cloud (VPC). .TP .B health_check_protocol (string) \- The protocol the load balancer uses when performing health check on targets. The default is the HTTP protocol. .TP .B health_check_port (string) \- The port the load balancer uses when performing health checks on targets. The default is \(aqtraffic\-port\(aq, which indicates the port on which each target receives traffic from the load balancer. .TP .B health_check_path (string) \- The ping path that is the destination on the targets for health checks. The default is /. .TP .B health_check_interval_seconds (integer) \- The approximate amount of time, in seconds, between health checks of an individual target. The default is 30 seconds. .TP .B health_check_timeout_seconds (integer) \- The amount of time, in seconds, during which no response from a target means a failed health check. The default is 5 seconds. .TP .B healthy_threshold_count (integer) \- The number of consecutive health checks successes required before considering an unhealthy target healthy. The default is 5. .TP .B unhealthy_threshold_count (integer) \- The number of consecutive health check failures required before considering a target unhealthy. The default is 2. .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elbv2.create_target_group learn1give1 protocol=HTTP port=54006 vpc_id=vpc\-deadbeef .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elbv2.delete_target_group(name, region=None, key=None, keyid=None, profile=None) Delete target group. .INDENT 7.0 .TP .B name (string) \- Target Group Name or Amazon Resource Name (ARN). .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elbv2.delete_target_group arn:aws:elasticloadbalancing:us\-west\-2:644138682826:targetgroup/learn1give1\-api/414788a16b5cf163 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elbv2.deregister_targets(name, targets, region=None, key=None, keyid=None, profile=None) Deregister targets to a target froup of an ALB. \fBtargets\fP is either a instance id string or a list of instance id\(aqs. .sp Returns: .INDENT 7.0 .IP \(bu 2 \fBTrue\fP: instance(s) deregistered successfully .IP \(bu 2 \fBFalse\fP: instance(s) failed to be deregistered .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elbv2.deregister_targets myelb instance_id salt myminion boto_elbv2.deregister_targets myelb \(dq[instance_id,instance_id]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elbv2.describe_target_health(name, targets=None, region=None, key=None, keyid=None, profile=None) Get the curret health check status for targets in a target group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elbv2.describe_target_health arn:aws:elasticloadbalancing:us\-west\-2:644138682826:targetgroup/learn1give1\-api/414788a16b5cf163 targets=[\(dqi\-isdf23ifjf\(dq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elbv2.register_targets(name, targets, region=None, key=None, keyid=None, profile=None) Register targets to a target froup of an ALB. \fBtargets\fP is either a instance id string or a list of instance id\(aqs. .sp Returns: .INDENT 7.0 .IP \(bu 2 \fBTrue\fP: instance(s) registered successfully .IP \(bu 2 \fBFalse\fP: instance(s) failed to be registered .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elbv2.register_targets myelb instance_id salt myminion boto_elbv2.register_targets myelb \(dq[instance_id,instance_id]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_elbv2.target_group_exists(name, region=None, key=None, keyid=None, profile=None) Check to see if an target group exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_elbv2.target_group_exists arn:aws:elasticloadbalancing:us\-west\-2:644138682826:targetgroup/learn1give1\-api/414788a16b5cf163 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_iam .sp Connection module for Amazon IAM .sp New in version 2014.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit iam credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C iam.keyid: GKTADJGHEIQSXMKKRBJ08H iam.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs iam.region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify key, keyid and region via a profile, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.add_user_to_group(user_name, group_name, region=None, key=None, keyid=None, profile=None) Add user to group. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.add_user_to_group myuser mygroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.associate_profile_to_role(profile_name, role_name, region=None, key=None, keyid=None, profile=None) Associate an instance profile with an IAM role. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.associate_profile_to_role myirole myiprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.attach_group_policy(policy_name, group_name, region=None, key=None, keyid=None, profile=None) Attach a managed policy to a group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.attach_group_policy mypolicy mygroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.attach_role_policy(policy_name, role_name, region=None, key=None, keyid=None, profile=None) Attach a managed policy to a role. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.attach_role_policy mypolicy myrole .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.attach_user_policy(policy_name, user_name, region=None, key=None, keyid=None, profile=None) Attach a managed policy to a user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.attach_user_policy mypolicy myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.build_policy(region=None, key=None, keyid=None, profile=None) Build a default assume role policy. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.build_policy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.create_access_key(user_name, region=None, key=None, keyid=None, profile=None) Create access key id for a user. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.create_access_key myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.create_group(group_name, path=None, region=None, key=None, keyid=None, profile=None) Create a group. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.create_group group .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.create_instance_profile(name, region=None, key=None, keyid=None, profile=None) Create an instance profile. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.create_instance_profile myiprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.create_login_profile(user_name, password, region=None, key=None, keyid=None, profile=None) Creates a login profile for the specified user, give the user the ability to access AWS services and the AWS Management Console. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.create_login_profile user_name password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.create_policy(policy_name, policy_document, path=None, description=None, region=None, key=None, keyid=None, profile=None) Create a policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminios boto_iam.create_policy mypolicy \(aq{\(dqVersion\(dq: \(dq2012\-10\-17\(dq, \(dqStatement\(dq: [{ \(dqEffect\(dq: \(dqAllow\(dq, \(dqAction\(dq: [\(dqs3:Get*\(dq, \(dqs3:List*\(dq], \(dqResource\(dq: [\(dqarn:aws:s3:::my\-bucket/shared/*\(dq]},]}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.create_policy_version(policy_name, policy_document, set_as_default=None, region=None, key=None, keyid=None, profile=None) Create a policy version. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminios boto_iam.create_policy_version mypolicy \(aq{\(dqVersion\(dq: \(dq2012\-10\-17\(dq, \(dqStatement\(dq: [{ \(dqEffect\(dq: \(dqAllow\(dq, \(dqAction\(dq: [\(dqs3:Get*\(dq, \(dqs3:List*\(dq], \(dqResource\(dq: [\(dqarn:aws:s3:::my\-bucket/shared/*\(dq]},]}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.create_role(name, policy_document=None, path=None, region=None, key=None, keyid=None, profile=None) Create an instance role. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.create_role myrole .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.create_role_policy(role_name, policy_name, policy, region=None, key=None, keyid=None, profile=None) Create or modify a role policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.create_role_policy myirole mypolicy \(aq{\(dqMyPolicy\(dq: \(dqStatement\(dq: [{\(dqAction\(dq: [\(dqsqs:*\(dq], \(dqEffect\(dq: \(dqAllow\(dq, \(dqResource\(dq: [\(dqarn:aws:sqs:*:*:*\(dq], \(dqSid\(dq: \(dqMyPolicySqs1\(dq}]}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.create_saml_provider(name, saml_metadata_document, region=None, key=None, keyid=None, profile=None) Create SAML provider .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.create_saml_provider my_saml_provider_name saml_metadata_document .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.create_user(user_name, path=None, region=None, key=None, keyid=None, profile=None) Create a user. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.create_user myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.deactivate_mfa_device(user_name, serial, region=None, key=None, keyid=None, profile=None) Deactivates the specified MFA device and removes it from association with the user. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.deactivate_mfa_device user_name serial_num .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_access_key(access_key_id, user_name=None, region=None, key=None, keyid=None, profile=None) Delete access key id from a user. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_access_key myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_group(group_name, region=None, key=None, keyid=None, profile=None) Delete a group policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_group mygroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_group_policy(group_name, policy_name, region=None, key=None, keyid=None, profile=None) Delete a group policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_group_policy mygroup mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_instance_profile(name, region=None, key=None, keyid=None, profile=None) Delete an instance profile. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_instance_profile myiprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_login_profile(user_name, region=None, key=None, keyid=None, profile=None) Deletes a login profile for the specified user. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_login_profile user_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_policy(policy_name, region=None, key=None, keyid=None, profile=None) Delete a policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_policy mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_policy_version(policy_name, version_id, region=None, key=None, keyid=None, profile=None) Delete a policy version. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_policy_version mypolicy v1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_role(name, region=None, key=None, keyid=None, profile=None) Delete an IAM role. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_role myirole .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_role_policy(role_name, policy_name, region=None, key=None, keyid=None, profile=None) Delete a role policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_role_policy myirole mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_saml_provider(name, region=None, key=None, keyid=None, profile=None) Delete SAML provider .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_saml_provider my_saml_provider_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_server_cert(cert_name, region=None, key=None, keyid=None, profile=None) Deletes a certificate from Amazon. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_server_cert mycert_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_user(user_name, region=None, key=None, keyid=None, profile=None) Delete a user. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_user myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_user_policy(user_name, policy_name, region=None, key=None, keyid=None, profile=None) Delete a user policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_user_policy myuser mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.delete_virtual_mfa_device(serial, region=None, key=None, keyid=None, profile=None) Deletes the specified virtual MFA device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.delete_virtual_mfa_device serial_num .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.describe_role(name, region=None, key=None, keyid=None, profile=None) Get information for a role. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.describe_role myirole .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.detach_group_policy(policy_name, group_name, region=None, key=None, keyid=None, profile=None) Detach a managed policy to a group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.detach_group_policy mypolicy mygroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.detach_role_policy(policy_name, role_name, region=None, key=None, keyid=None, profile=None) Detach a managed policy to a role. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.detach_role_policy mypolicy myrole .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.detach_user_policy(policy_name, user_name, region=None, key=None, keyid=None, profile=None) Detach a managed policy to a user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.detach_user_policy mypolicy myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.disassociate_profile_from_role(profile_name, role_name, region=None, key=None, keyid=None, profile=None) Disassociate an instance profile from an IAM role. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.disassociate_profile_from_role myirole myiprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.export_roles(path_prefix=\(aq/\(aq, region=None, key=None, keyid=None, profile=None) Get all IAM role details. Produces results that can be used to create an sls file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_iam.export_roles \-\-out=txt | sed \(dqs/local: //\(dq > iam_roles.sls .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.export_users(path_prefix=\(aq/\(aq, region=None, key=None, keyid=None, profile=None) Get all IAM user details. Produces results that can be used to create an sls file. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_iam.export_users \-\-out=txt | sed \(dqs/local: //\(dq > iam_users.sls .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_account_id(region=None, key=None, keyid=None, profile=None) Get a the AWS account id associated with the used credentials. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_account_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_account_policy(region=None, key=None, keyid=None, profile=None) Get account policy for the AWS account. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_account_policy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_all_access_keys(user_name, marker=None, max_items=None, region=None, key=None, keyid=None, profile=None) Get all access keys from a user. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_all_access_keys myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_all_group_policies(group_name, region=None, key=None, keyid=None, profile=None) Get a list of policy names from a group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_all_group_policies mygroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_all_groups(path_prefix=\(aq/\(aq, region=None, key=None, keyid=None, profile=None) Get and return all IAM group details, starting at the optional path. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_iam.get_all_groups .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_all_instance_profiles(path_prefix=\(aq/\(aq, region=None, key=None, keyid=None, profile=None) Get and return all IAM instance profiles, starting at the optional path. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_iam.get_all_instance_profiles .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_all_mfa_devices(user_name, region=None, key=None, keyid=None, profile=None) Get all MFA devices associated with an IAM user. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_all_mfa_devices user_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_all_roles(path_prefix=None, region=None, key=None, keyid=None, profile=None) Get and return all IAM role details, starting at the optional path. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_iam.get_all_roles .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_all_user_policies(user_name, marker=None, max_items=None, region=None, key=None, keyid=None, profile=None) Get all user policies. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_all_user_policies myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_all_users(path_prefix=\(aq/\(aq, region=None, key=None, keyid=None, profile=None) Get and return all IAM user details, starting at the optional path. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_iam.get_all_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_group(group_name, region=None, key=None, keyid=None, profile=None) Get group information. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_group mygroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_group_members(group_name, region=None, key=None, keyid=None, profile=None) Get group information. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_group mygroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_group_policy(group_name, policy_name, region=None, key=None, keyid=None, profile=None) Retrieves the specified policy document for the specified group. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_group_policy mygroup policyname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_policy(policy_name, region=None, key=None, keyid=None, profile=None) Check to see if policy exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.instance_profile_exists myiprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_policy_version(policy_name, version_id, region=None, key=None, keyid=None, profile=None) Check to see if policy exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.instance_profile_exists myiprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_role_policy(role_name, policy_name, region=None, key=None, keyid=None, profile=None) Get a role policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_role_policy myirole mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_saml_provider(name, region=None, key=None, keyid=None, profile=None) Get SAML provider document. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_saml_provider arn .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_saml_provider_arn(name, region=None, key=None, keyid=None, profile=None) Get SAML provider .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_saml_provider_arn my_saml_provider_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_server_certificate(cert_name, region=None, key=None, keyid=None, profile=None) Returns certificate information from Amazon .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_server_certificate mycert_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_user(user_name=None, region=None, key=None, keyid=None, profile=None) Get user information. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_user myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.get_user_policy(user_name, policy_name, region=None, key=None, keyid=None, profile=None) Retrieves the specified policy document for the specified user. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.get_user_policy myuser mypolicyname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.instance_profile_exists(name, region=None, key=None, keyid=None, profile=None) Check to see if an instance profile exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.instance_profile_exists myiprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.list_attached_group_policies(group_name, path_prefix=None, entity_filter=None, region=None, key=None, keyid=None, profile=None) List entities attached to the given group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.list_entities_for_policy mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.list_attached_role_policies(role_name, path_prefix=None, entity_filter=None, region=None, key=None, keyid=None, profile=None) List entities attached to the given role. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.list_entities_for_policy mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.list_attached_user_policies(user_name, path_prefix=None, entity_filter=None, region=None, key=None, keyid=None, profile=None) List entities attached to the given user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.list_entities_for_policy mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.list_entities_for_policy(policy_name, path_prefix=None, entity_filter=None, region=None, key=None, keyid=None, profile=None) List entities that a policy is attached to. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.list_entities_for_policy mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.list_instance_profiles(path_prefix=\(aq/\(aq, region=None, key=None, keyid=None, profile=None) List all IAM instance profiles, starting at the optional path. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_iam.list_instance_profiles .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.list_policies(region=None, key=None, keyid=None, profile=None) List policies. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.list_policies .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.list_policy_versions(policy_name, region=None, key=None, keyid=None, profile=None) List versions of a policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.list_policy_versions mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.list_role_policies(role_name, region=None, key=None, keyid=None, profile=None) Get a list of policy names from a role. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.list_role_policies myirole .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.list_saml_providers(region=None, key=None, keyid=None, profile=None) List SAML providers. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.list_saml_providers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.policy_exists(policy_name, region=None, key=None, keyid=None, profile=None) Check to see if policy exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.instance_profile_exists myiprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.policy_version_exists(policy_name, version_id, region=None, key=None, keyid=None, profile=None) Check to see if policy exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.instance_profile_exists myiprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.profile_associated(role_name, profile_name, region, key, keyid, profile) Check to see if an instance profile is associated with an IAM role. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.profile_associated myirole myiprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.put_group_policy(group_name, policy_name, policy_json, region=None, key=None, keyid=None, profile=None) Adds or updates the specified policy document for the specified group. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.put_group_policy mygroup policyname policyrules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.put_user_policy(user_name, policy_name, policy_json, region=None, key=None, keyid=None, profile=None) Adds or updates the specified policy document for the specified user. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.put_user_policy myuser policyname policyrules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.remove_user_from_group(group_name, user_name, region=None, key=None, keyid=None, profile=None) Remove user from group. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.remove_user_from_group mygroup myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.role_exists(name, region=None, key=None, keyid=None, profile=None) Check to see if an IAM role exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.role_exists myirole .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.set_default_policy_version(policy_name, version_id, region=None, key=None, keyid=None, profile=None) Set the default version of a policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.set_default_policy_version mypolicy v1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.update_account_password_policy(allow_users_to_change_password=None, hard_expiry=None, max_password_age=None, minimum_password_length=None, password_reuse_prevention=None, require_lowercase_characters=None, require_numbers=None, require_symbols=None, require_uppercase_characters=None, region=None, key=None, keyid=None, profile=None) Update the password policy for the AWS account. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.update_account_password_policy True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.update_assume_role_policy(role_name, policy_document, region=None, key=None, keyid=None, profile=None) Update an assume role policy for a role. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.update_assume_role_policy myrole \(aq{\(dqStatement\(dq:\(dq...\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.update_saml_provider(name, saml_metadata_document, region=None, key=None, keyid=None, profile=None) Update SAML provider. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.update_saml_provider my_saml_provider_name saml_metadata_document .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.upload_server_cert(cert_name, cert_body, private_key, cert_chain=None, path=None, region=None, key=None, keyid=None, profile=None) Upload a certificate to Amazon. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.upload_server_cert mycert_name crt priv_key .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcert_name\fP \-\- The name for the server certificate. Do not include the path in this value. .IP \(bu 2 \fBcert_body\fP \-\- The contents of the public key certificate in PEM\-encoded format. .IP \(bu 2 \fBprivate_key\fP \-\- The contents of the private key in PEM\-encoded format. .IP \(bu 2 \fBcert_chain\fP \-\- The contents of the certificate chain. This is typically a concatenation of the PEM\-encoded public key certificates of the chain. .IP \(bu 2 \fBpath\fP \-\- The path for the server certificate. .IP \(bu 2 \fBregion\fP \-\- The name of the region to connect to. .IP \(bu 2 \fBkey\fP \-\- The key to be used in order to connect .IP \(bu 2 \fBkeyid\fP \-\- The keyid to be used in order to connect .IP \(bu 2 \fBprofile\fP \-\- The profile that contains a dict of region, key, keyid .UNINDENT .TP .B Returns True / False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iam.user_exists_in_group(user_name, group_name, region=None, key=None, keyid=None, profile=None) Check if user exists in group. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iam.user_exists_in_group myuser mygroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_iot .sp Connection module for Amazon IoT .sp New in version 2016.3.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 boto .IP \(bu 2 boto3 .UNINDENT .UNINDENT .sp The dependencies listed above can be installed via package or pip. .INDENT 0.0 .TP .B configuration This module accepts explicit Lambda credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C iot.keyid: GKTADJGHEIQSXMKKRBJ08H iot.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C iot.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.attach_principal_policy(policyName, principal, region=None, key=None, keyid=None, profile=None) Attach the specified policy to the specified principal (certificate or other credential.) .sp Returns {attached: true} if the policy was attached {attached: False} if the policy was not attached. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.attach_principal_policy mypolicy mycognitoID .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.create_policy(policyName, policyDocument, region=None, key=None, keyid=None, profile=None) Given a valid config, create a policy. .sp Returns {created: true} if the policy was created and returns {created: False} if the policy was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.create_policy my_policy \e \(aq{\(dqVersion\(dq:\(dq2015\-12\-12\(dq,\e \(dqStatement\(dq:[{\(dqEffect\(dq:\(dqAllow\(dq,\e \(dqAction\(dq:[\(dqiot:Publish\(dq],\e \(dqResource\(dq:[\(dqarn:::::topic/foo/bar\(dq]}]}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.create_policy_version(policyName, policyDocument, setAsDefault=False, region=None, key=None, keyid=None, profile=None) Given a valid config, create a new version of a policy. .sp Returns {created: true} if the policy version was created and returns {created: False} if the policy version was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.create_policy_version my_policy \e \(aq{\(dqStatement\(dq:[{\(dqEffect\(dq:\(dqAllow\(dq,\(dqAction\(dq:[\(dqiot:Publish\(dq],\(dqResource\(dq:[\(dqarn:::::topic/foo/bar\(dq]}]}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.create_thing_type(thingTypeName, thingTypeDescription, searchableAttributesList, region=None, key=None, keyid=None, profile=None) Given a valid config, create a thing type. .sp Returns {created: true} if the thing type was created and returns {created: False} if the thing type was not created. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.create_thing_type mythingtype \e thingtype_description_string \(aq[\(dqsearchable_attr_1\(dq, \(dqsearchable_attr_2\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.create_topic_rule(ruleName, sql, actions, description, ruleDisabled=False, region=None, key=None, keyid=None, profile=None) Given a valid config, create a topic rule. .sp Returns {created: true} if the rule was created and returns {created: False} if the rule was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.create_topic_rule my_rule \(dqSELECT * FROM \(aqsome/thing\(aq\(dq \e \(aq[{\(dqlambda\(dq:{\(dqfunctionArn\(dq:\(dqarn:::::something\(dq}},{\(dqsns\(dq:{\e \(dqtargetArn\(dq:\(dqarn:::::something\(dq,\(dqroleArn\(dq:\(dqarn:::::something\(dq}}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.delete_policy(policyName, region=None, key=None, keyid=None, profile=None) Given a policy name, delete it. .sp Returns {deleted: true} if the policy was deleted and returns {deleted: false} if the policy was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.delete_policy mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.delete_policy_version(policyName, policyVersionId, region=None, key=None, keyid=None, profile=None) Given a policy name and version, delete it. .sp Returns {deleted: true} if the policy version was deleted and returns {deleted: false} if the policy version was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.delete_policy_version mypolicy version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.delete_thing_type(thingTypeName, region=None, key=None, keyid=None, profile=None) Given a thing type name, delete it. .sp Returns {deleted: true} if the thing type was deleted and returns {deleted: false} if the thing type was not deleted. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.delete_thing_type mythingtype .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.delete_topic_rule(ruleName, region=None, key=None, keyid=None, profile=None) Given a rule name, delete it. .sp Returns {deleted: true} if the rule was deleted and returns {deleted: false} if the rule was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.delete_rule myrule .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.deprecate_thing_type(thingTypeName, undoDeprecate=False, region=None, key=None, keyid=None, profile=None) Given a thing type name, deprecate it when undoDeprecate is False and undeprecate it when undoDeprecate is True. .sp Returns {deprecated: true} if the thing type was deprecated and returns {deprecated: false} if the thing type was not deprecated. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.deprecate_thing_type mythingtype .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.describe_policy(policyName, region=None, key=None, keyid=None, profile=None) Given a policy name describe its properties. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.describe_policy mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.describe_policy_version(policyName, policyVersionId, region=None, key=None, keyid=None, profile=None) Given a policy name and version describe its properties. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.describe_policy_version mypolicy version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.describe_thing_type(thingTypeName, region=None, key=None, keyid=None, profile=None) Given a thing type name describe its properties. .sp Returns a dictionary of interesting properties. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.describe_thing_type mythingtype .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.describe_topic_rule(ruleName, region=None, key=None, keyid=None, profile=None) Given a topic rule name describe its properties. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.describe_topic_rule myrule .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.detach_principal_policy(policyName, principal, region=None, key=None, keyid=None, profile=None) Detach the specified policy from the specified principal (certificate or other credential.) .sp Returns {detached: true} if the policy was detached {detached: False} if the policy was not detached. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.detach_principal_policy mypolicy mycognitoID .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.list_policies(region=None, key=None, keyid=None, profile=None) List all policies .sp Returns list of policies .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.list_policies .ft P .fi .UNINDENT .UNINDENT .sp Example Return: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C policies: \- {...} \- {...} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.list_policy_versions(policyName, region=None, key=None, keyid=None, profile=None) List the versions available for the given policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.list_policy_versions mypolicy .ft P .fi .UNINDENT .UNINDENT .sp Example Return: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C policyVersions: \- {...} \- {...} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.list_principal_policies(principal, region=None, key=None, keyid=None, profile=None) List the policies attached to the given principal. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.list_principal_policies myprincipal .ft P .fi .UNINDENT .UNINDENT .sp Example Return: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C policies: \- {...} \- {...} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.list_topic_rules(topic=None, ruleDisabled=None, region=None, key=None, keyid=None, profile=None) List all rules (for a given topic, if specified) .sp Returns list of rules .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.list_topic_rules .ft P .fi .UNINDENT .UNINDENT .sp Example Return: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C rules: \- {...} \- {...} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.policy_exists(policyName, region=None, key=None, keyid=None, profile=None) Given a policy name, check to see if the given policy exists. .sp Returns True if the given policy exists and returns False if the given policy does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.policy_exists mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.policy_version_exists(policyName, policyVersionId, region=None, key=None, keyid=None, profile=None) Given a policy name and version ID, check to see if the given policy version exists. .sp Returns True if the given policy version exists and returns False if the given policy version does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.policy_version_exists mypolicy versionid .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.replace_topic_rule(ruleName, sql, actions, description, ruleDisabled=False, region=None, key=None, keyid=None, profile=None) Given a valid config, replace a topic rule with the new values. .sp Returns {created: true} if the rule was created and returns {created: False} if the rule was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.replace_topic_rule my_rule \(aqSELECT * FROM some.thing\(aq \e \(aq[{\(dqlambda\(dq:{\(dqfunctionArn\(dq:\(dqarn:::::something\(dq}},{\(dqsns\(dq:{\e \(dqtargetArn\(dq:\(dqarn:::::something\(dq,\(dqroleArn\(dq:\(dqarn:::::something\(dq}}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.set_default_policy_version(policyName, policyVersionId, region=None, key=None, keyid=None, profile=None) Sets the specified version of the specified policy as the policy\(aqs default (operative) version. This action affects all certificates that the policy is attached to. .sp Returns {changed: true} if the policy version was set {changed: False} if the policy version was not set. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.set_default_policy_version mypolicy versionid .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.thing_type_exists(thingTypeName, region=None, key=None, keyid=None, profile=None) Given a thing type name, check to see if the given thing type exists .sp Returns True if the given thing type exists and returns False if the given thing type does not exist. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.thing_type_exists mythingtype .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_iot.topic_rule_exists(ruleName, region=None, key=None, keyid=None, profile=None) Given a rule name, check to see if the given rule exists. .sp Returns True if the given rule exists and returns False if the given rule does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_iot.topic_rule_exists myrule .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_kinesis .sp Connection module for Amazon Kinesis .sp New in version 2017.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit Kinesis credentials but can also utilize IAM roles assigned to the instance trough Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at: .INDENT 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C kinesis.keyid: GKTADJGHEIQSXMKKRBJ08H kinesis.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C kinesis.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kinesis.create_stream(stream_name, num_shards, region=None, key=None, keyid=None, profile=None) Create a stream with name stream_name and initial number of shards num_shards. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kinesis.create_stream my_stream N region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kinesis.decrease_stream_retention_period(stream_name, retention_hours, region=None, key=None, keyid=None, profile=None) Decrease stream retention period to retention_hours .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kinesis.decrease_stream_retention_period my_stream N region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kinesis.delete_stream(stream_name, region=None, key=None, keyid=None, profile=None) Delete the stream with name stream_name. This cannot be undone! All data will be lost!! .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kinesis.delete_stream my_stream region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kinesis.disable_enhanced_monitoring(stream_name, metrics, region=None, key=None, keyid=None, profile=None) Disable enhanced monitoring for the specified shard\-level metrics on stream stream_name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kinesis.disable_enhanced_monitoring my_stream [\(dqmetrics\(dq, \(dqto\(dq, \(dqdisable\(dq] region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kinesis.enable_enhanced_monitoring(stream_name, metrics, region=None, key=None, keyid=None, profile=None) Enable enhanced monitoring for the specified shard\-level metrics on stream stream_name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kinesis.enable_enhanced_monitoring my_stream [\(dqmetrics\(dq, \(dqto\(dq, \(dqenable\(dq] region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kinesis.exists(stream_name, region=None, key=None, keyid=None, profile=None) Check if the stream exists. Returns False and the error if it does not. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kinesis.exists my_stream region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kinesis.get_info_for_reshard(stream_details) Collect some data: number of open shards, key range, etc. Modifies stream_details to add a sorted list of OpenShards. Returns (min_hash_key, max_hash_key, stream_details) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kinesis.get_info_for_reshard existing_stream_details .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kinesis.get_stream_when_active(stream_name, region=None, key=None, keyid=None, profile=None) Get complete stream info from AWS, returning only when the stream is in the ACTIVE state. Continues to retry when stream is updating or creating. If the stream is deleted during retries, the loop will catch the error and break. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kinesis.get_stream_when_active my_stream region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kinesis.increase_stream_retention_period(stream_name, retention_hours, region=None, key=None, keyid=None, profile=None) Increase stream retention period to retention_hours .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kinesis.increase_stream_retention_period my_stream N region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kinesis.list_streams(region=None, key=None, keyid=None, profile=None) Return a list of all streams visible to the current account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kinesis.list_streams .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kinesis.long_int(hash_key) The hash key is a 128\-bit int, sent as a string. It\(aqs necessary to convert to int/long for comparison operations. This helper method handles python 2/3 incompatibility .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kinesis.long_int some_MD5_hash_as_string .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns long object if python 2.X, int object if python 3.X .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kinesis.reshard(stream_name, desired_size, force=False, region=None, key=None, keyid=None, profile=None) Reshard a kinesis stream. Each call to this function will wait until the stream is ACTIVE, then make a single split or merge operation. This function decides where to split or merge with the assumption that the ultimate goal is a balanced partition space. .sp For safety, user must past in force=True; otherwise, the function will dry run. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kinesis.reshard my_stream N True region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns True if a split or merge was found/performed, False if nothing is needed .UNINDENT .UNINDENT .SS salt.modules.boto_kms .sp Connection module for Amazon KMS .sp New in version 2015.8.0. .INDENT 0.0 .TP .B configuration This module accepts explicit kms credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C kms.keyid: GKTADJGHEIQSXMKKRBJ08H kms.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C kms.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .UNINDENT .UNINDENT .UNINDENT .TP .B depends boto .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.create_alias(alias_name, target_key_id, region=None, key=None, keyid=None, profile=None) Create a display name for a key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.create_alias \(aqalias/mykey\(aq key_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.create_grant(key_id, grantee_principal, retiring_principal=None, operations=None, constraints=None, grant_tokens=None, region=None, key=None, keyid=None, profile=None) Adds a grant to a key to specify who can access the key and under what conditions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.create_grant \(aqalias/mykey\(aq \(aqarn:aws:iam::1111111:/role/myrole\(aq operations=\(aq[\(dqEncrypt\(dq,\(dqDecrypt\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.create_key(policy=None, description=None, key_usage=None, region=None, key=None, keyid=None, profile=None) Creates a master key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.create_key \(aq{\(dqStatement\(dq:...}\(aq \(dqMy master key\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.decrypt(ciphertext_blob, encryption_context=None, grant_tokens=None, region=None, key=None, keyid=None, profile=None) Decrypt ciphertext. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.decrypt encrypted_ciphertext .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.describe_key(key_id, region=None, key=None, keyid=None, profile=None) Get detailed information about a key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.describe_key \(aqalias/mykey\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.disable_key(key_id, region=None, key=None, keyid=None, profile=None) Mark key as disabled. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.disable_key \(aqalias/mykey\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.disable_key_rotation(key_id, region=None, key=None, keyid=None, profile=None) Disable key rotation for specified key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.disable_key_rotation \(aqalias/mykey\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.enable_key(key_id, region=None, key=None, keyid=None, profile=None) Mark key as enabled. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.enable_key \(aqalias/mykey\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.enable_key_rotation(key_id, region=None, key=None, keyid=None, profile=None) Disable key rotation for specified key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.enable_key_rotation \(aqalias/mykey\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.encrypt(key_id, plaintext, encryption_context=None, grant_tokens=None, region=None, key=None, keyid=None, profile=None) Encrypt plaintext into cipher text using specified key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.encrypt \(aqalias/mykey\(aq \(aqmyplaindata\(aq \(aq{\(dqaws:username\(dq:\(dqmyuser\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.generate_data_key(key_id, encryption_context=None, number_of_bytes=None, key_spec=None, grant_tokens=None, region=None, key=None, keyid=None, profile=None) Generate a secure data key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.generate_data_key \(aqalias/mykey\(aq number_of_bytes=1024 key_spec=AES_128 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.generate_data_key_without_plaintext(key_id, encryption_context=None, number_of_bytes=None, key_spec=None, grant_tokens=None, region=None, key=None, keyid=None, profile=None) Generate a secure data key without a plaintext copy of the key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.generate_data_key_without_plaintext \(aqalias/mykey\(aq number_of_bytes=1024 key_spec=AES_128 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.generate_random(number_of_bytes=None, region=None, key=None, keyid=None, profile=None) Generate a random string. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.generate_random number_of_bytes=1024 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.get_key_policy(key_id, policy_name, region=None, key=None, keyid=None, profile=None) Get the policy for the specified key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.get_key_policy \(aqalias/mykey\(aq mypolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.get_key_rotation_status(key_id, region=None, key=None, keyid=None, profile=None) Get status of whether or not key rotation is enabled for a key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.get_key_rotation_status \(aqalias/mykey\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.key_exists(key_id, region=None, key=None, keyid=None, profile=None) Check for the existence of a key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.key_exists \(aqalias/mykey\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.list_grants(key_id, limit=None, marker=None, region=None, key=None, keyid=None, profile=None) List grants for the specified key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.list_grants \(aqalias/mykey\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.list_key_policies(key_id, limit=None, marker=None, region=None, key=None, keyid=None, profile=None) List key_policies for the specified key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.list_key_policies \(aqalias/mykey\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.put_key_policy(key_id, policy_name, policy, region=None, key=None, keyid=None, profile=None) Attach a key policy to the specified key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.put_key_policy \(aqalias/mykey\(aq default \(aq{\(dqStatement\(dq:...}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.re_encrypt(ciphertext_blob, destination_key_id, source_encryption_context=None, destination_encryption_context=None, grant_tokens=None, region=None, key=None, keyid=None, profile=None) Reencrypt encrypted data with a new master key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.re_encrypt \(aqencrypted_data\(aq \(aqalias/mynewkey\(aq default \(aq{\(dqStatement\(dq:...}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.revoke_grant(key_id, grant_id, region=None, key=None, keyid=None, profile=None) Revoke a grant from a key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.revoke_grant \(aqalias/mykey\(aq 8u89hf\-j09j... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_kms.update_key_description(key_id, description, region=None, key=None, keyid=None, profile=None) Update a key\(aqs description. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_kms.update_key_description \(aqalias/mykey\(aq \(aqMy key\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_lambda .sp Connection module for Amazon Lambda .sp New in version 2016.3.0. .INDENT 0.0 .TP .B depends .UNINDENT .INDENT 0.0 .IP \(bu 2 boto .IP \(bu 2 boto3 .UNINDENT .sp The dependencies listed above can be installed via package or pip. .INDENT 0.0 .TP .B configuration This module accepts explicit Lambda credentials but 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 \fI\%here\fP\&. .UNINDENT .sp If IAM roles are not used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lambda.keyid: GKTADJGHEIQSXMKKRBJ08H lambda.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 lambda.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, either as a passed in dict, or as a string to pull from pillars or minion config: .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 Changed in version 2015.8.0: All methods now return a dictionary. Create and delete methods return: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C created: true .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C created: false error: message: error message .ft P .fi .UNINDENT .UNINDENT .sp Request methods (e.g., \fIdescribe_function\fP) return: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C function: \- {...} \- {...} .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C error: message: error message .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.add_permission(FunctionName, StatementId, Action, Principal, SourceArn=None, SourceAccount=None, Qualifier=None, region=None, key=None, keyid=None, profile=None) Add a permission to a lambda function. .sp Returns {added: true} if the permission was added and returns {added: False} if the permission was not added. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lamba.add_permission my_function my_id \(dqlambda:*\(dq \e s3.amazonaws.com aws:arn::::bucket\-name \e aws\-account\-id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.alias_exists(FunctionName, Name, region=None, key=None, keyid=None, profile=None) Given a function name and alias name, check to see if the given alias exists. .sp Returns True if the given alias exists and returns False if the given alias does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lambda.alias_exists myfunction myalias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.create_alias(FunctionName, Name, FunctionVersion, Description=\(aq\(aq, region=None, key=None, keyid=None, profile=None) Given a valid config, create an alias to a function. .sp Returns {created: true} if the alias was created and returns {created: False} if the alias was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lamba.create_alias my_function my_alias $LATEST \(dqAn alias\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.create_event_source_mapping(EventSourceArn, FunctionName, StartingPosition, Enabled=True, BatchSize=100, region=None, key=None, keyid=None, profile=None) Identifies a stream as an event source for a Lambda function. It can be either an Amazon Kinesis stream or an Amazon DynamoDB stream. AWS Lambda invokes the specified function when records are posted to the stream. .sp Returns {created: true} if the event source mapping was created and returns {created: False} if the event source mapping was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lamba.create_event_source_mapping arn::::eventsource myfunction LATEST .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.create_function(FunctionName, Runtime, Role, Handler, ZipFile=None, S3Bucket=None, S3Key=None, S3ObjectVersion=None, Description=\(aq\(aq, Timeout=3, MemorySize=128, Publish=False, WaitForRole=False, RoleRetries=5, region=None, key=None, keyid=None, profile=None, VpcConfig=None, Environment=None) New in version 2017.7.0. .sp Given a valid config, create a function. .INDENT 7.0 .TP .B Environment The parent object that contains your environment\(aqs configuration settings. This is a dictionary of the form: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqVariables\(aq: { \(aqVariableName\(aq: \(aqVariableValue\(aq } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Returns \fB{\(aqcreated\(aq: True}\fP if the function was created and \fB{created: False}\fP if the function was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lamba.create_function my_function python2.7 my_role my_file.my_function my_function.zip salt myminion boto_lamba.create_function my_function python2.7 my_role my_file.my_function salt://files/my_function.zip .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.delete_alias(FunctionName, Name, region=None, key=None, keyid=None, profile=None) Given a function name and alias name, delete the alias. .sp Returns {deleted: true} if the alias was deleted and returns {deleted: false} if the alias was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lambda.delete_alias myfunction myalias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.delete_event_source_mapping(UUID=None, EventSourceArn=None, FunctionName=None, region=None, key=None, keyid=None, profile=None) Given an event source mapping ID or an event source ARN and FunctionName, delete the event source mapping .sp Returns {deleted: true} if the mapping was deleted and returns {deleted: false} if the mapping was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lambda.delete_event_source_mapping 260c423d\-e8b5\-4443\-8d6a\-5e91b9ecd0fa .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.delete_function(FunctionName, Qualifier=None, region=None, key=None, keyid=None, profile=None) Given a function name and optional version qualifier, delete it. .sp Returns {deleted: true} if the function was deleted and returns {deleted: false} if the function was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lambda.delete_function myfunction .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.describe_alias(FunctionName, Name, region=None, key=None, keyid=None, profile=None) Given a function name and alias name describe the properties of the alias. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lambda.describe_alias myalias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.describe_event_source_mapping(UUID=None, EventSourceArn=None, FunctionName=None, region=None, key=None, keyid=None, profile=None) Given an event source mapping ID or an event source ARN and FunctionName, obtain the current settings of that mapping. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lambda.describe_event_source_mapping uuid .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.describe_function(FunctionName, region=None, key=None, keyid=None, profile=None) Given a function name describe its properties. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lambda.describe_function myfunction .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.event_source_mapping_exists(UUID=None, EventSourceArn=None, FunctionName=None, region=None, key=None, keyid=None, profile=None) Given an event source mapping ID or an event source ARN and FunctionName, check whether the mapping exists. .sp Returns True if the given alias exists and returns False if the given alias does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lambda.alias_exists myfunction myalias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.function_exists(FunctionName, region=None, key=None, keyid=None, profile=None) Given a function name, check to see if the given function name exists. .sp Returns True if the given function exists and returns False if the given function does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lambda.function_exists myfunction .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.get_event_source_mapping_ids(EventSourceArn, FunctionName, region=None, key=None, keyid=None, profile=None) Given an event source and function name, return a list of mapping IDs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lambda.get_event_source_mapping_ids arn:::: myfunction .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.get_permissions(FunctionName, Qualifier=None, region=None, key=None, keyid=None, profile=None) Get resource permissions for the given lambda function .sp Returns dictionary of permissions, by statement ID .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lamba.get_permissions my_function permissions: {...} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.list_function_versions(FunctionName, region=None, key=None, keyid=None, profile=None) List the versions available for the given function. .sp Returns list of function versions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C versions: \- {...} \- {...} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.list_functions(region=None, key=None, keyid=None, profile=None) List all Lambda functions visible in the current scope. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lambda.list_functions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.remove_permission(FunctionName, StatementId, Qualifier=None, region=None, key=None, keyid=None, profile=None) Remove a permission from a lambda function. .sp Returns {removed: true} if the permission was removed and returns {removed: False} if the permission was not removed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lamba.remove_permission my_function my_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.update_alias(FunctionName, Name, FunctionVersion=None, Description=None, region=None, key=None, keyid=None, profile=None) Update the named alias to the configuration. .sp Returns {updated: true} if the alias was updated and returns {updated: False} if the alias was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lamba.update_alias my_lambda my_alias $LATEST .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.update_event_source_mapping(UUID, FunctionName=None, Enabled=None, BatchSize=None, region=None, key=None, keyid=None, profile=None) Update the event source mapping identified by the UUID. .sp Returns {updated: true} if the alias was updated and returns {updated: False} if the alias was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lamba.update_event_source_mapping uuid FunctionName=new_function .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.update_function_code(FunctionName, ZipFile=None, S3Bucket=None, S3Key=None, S3ObjectVersion=None, Publish=False, region=None, key=None, keyid=None, profile=None) Upload the given code to the named lambda function. .sp Returns {updated: true} if the function was updated and returns {updated: False} if the function was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lamba.update_function_code my_function ZipFile=function.zip .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_lambda.update_function_config(FunctionName, Role=None, Handler=None, Description=None, Timeout=None, MemorySize=None, region=None, key=None, keyid=None, profile=None, VpcConfig=None, WaitForRole=False, RoleRetries=5, Environment=None) New in version 2017.7.0. .sp Update the named lambda function to the configuration. .INDENT 7.0 .TP .B Environment The parent object that contains your environment\(aqs configuration settings. This is a dictionary of the form: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqVariables\(aq: { \(aqVariableName\(aq: \(aqVariableValue\(aq } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Returns \fB{\(aqupdated\(aq: True}\fP if the function was updated, and \fB{\(aqupdated\(aq: False}\fP if the function was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_lamba.update_function_config my_function my_role my_file.my_function \(dqmy lambda function\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_rds .sp Connection module for Amazon RDS .sp New in version 2015.8.0. .INDENT 0.0 .TP .B configuration This module accepts explicit rds credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C rds.keyid: GKTADJGHEIQSXMKKRBJ08H rds.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C rds.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.create(name, allocated_storage, db_instance_class, engine, master_username, master_user_password, db_name=None, db_security_groups=None, vpc_security_group_ids=None, vpc_security_groups=None, availability_zone=None, db_subnet_group_name=None, preferred_maintenance_window=None, db_parameter_group_name=None, backup_retention_period=None, preferred_backup_window=None, port=None, multi_az=None, engine_version=None, auto_minor_version_upgrade=None, license_model=None, iops=None, option_group_name=None, character_set_name=None, publicly_accessible=None, wait_status=None, tags=None, db_cluster_identifier=None, storage_type=None, tde_credential_arn=None, tde_credential_password=None, storage_encrypted=None, kms_key_id=None, domain=None, copy_tags_to_snapshot=None, monitoring_interval=None, monitoring_role_arn=None, domain_iam_role_name=None, region=None, promotion_tier=None, key=None, keyid=None, profile=None) Create an RDS Instance .sp CLI example to create an RDS Instance: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.create myrds 10 db.t2.micro MySQL sqlusr sqlpassw .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.create_option_group(name, engine_name, major_engine_version, option_group_description, tags=None, region=None, key=None, keyid=None, profile=None) Create an RDS option group .sp CLI example to create an RDS option group: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.create_option_group my\-opt\-group mysql 5.6 \(dqgroup description\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.create_parameter_group(name, db_parameter_group_family, description, tags=None, region=None, key=None, keyid=None, profile=None) Create an RDS parameter group .sp CLI example to create an RDS parameter group: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.create_parameter_group my\-param\-group mysql5.6 \(dqgroup description\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.create_read_replica(name, source_name, db_instance_class=None, availability_zone=None, port=None, auto_minor_version_upgrade=None, iops=None, option_group_name=None, publicly_accessible=None, tags=None, db_subnet_group_name=None, storage_type=None, copy_tags_to_snapshot=None, monitoring_interval=None, monitoring_role_arn=None, region=None, key=None, keyid=None, profile=None) Create an RDS read replica .sp CLI example to create an RDS read replica: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.create_read_replica replicaname source_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.create_subnet_group(name, description, subnet_ids, tags=None, region=None, key=None, keyid=None, profile=None) Create an RDS subnet group .sp CLI example to create an RDS subnet group: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.create_subnet_group my\-subnet\-group \(dqgroup description\(dq \(aq[subnet\-12345678, subnet\-87654321]\(aq region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.delete(name, skip_final_snapshot=None, final_db_snapshot_identifier=None, region=None, key=None, keyid=None, profile=None, tags=None, wait_for_deletion=True, timeout=180) Delete an RDS instance. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.delete myrds skip_final_snapshot=True region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.delete_option_group(name, region=None, key=None, keyid=None, profile=None) Delete an RDS option group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.delete_option_group my\-opt\-group region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.delete_parameter_group(name, region=None, key=None, keyid=None, profile=None) Delete an RDS parameter group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.delete_parameter_group my\-param\-group region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.delete_subnet_group(name, region=None, key=None, keyid=None, profile=None) Delete an RDS subnet group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.delete_subnet_group my\-subnet\-group region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.describe(name, tags=None, region=None, key=None, keyid=None, profile=None) Return RDS instance details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.describe myrds .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.describe_db_instances(name=None, filters=None, jmespath=\(aqDBInstances\(aq, region=None, key=None, keyid=None, profile=None) Return a detailed listing of some, or all, DB Instances visible in the current scope. Arbitrary subelements or subsections of the returned dataset can be selected by passing in a valid JMSEPath filter as well. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.describe_db_instances jmespath=\(aqDBInstances[*].DBInstanceIdentifier\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.describe_db_subnet_groups(name=None, filters=None, jmespath=\(aqDBSubnetGroups\(aq, region=None, key=None, keyid=None, profile=None) Return a detailed listing of some, or all, DB Subnet Groups visible in the current scope. Arbitrary subelements or subsections of the returned dataset can be selected by passing in a valid JMSEPath filter as well. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.describe_db_subnet_groups .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.describe_parameter_group(name, Filters=None, MaxRecords=None, Marker=None, region=None, key=None, keyid=None, profile=None) Returns a list of \fIDBParameterGroup\fP descriptions. CLI example to description of parameter group: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.describe_parameter_group parametergroupname region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.describe_parameters(name, Source=None, MaxRecords=None, Marker=None, region=None, key=None, keyid=None, profile=None) Returns a list of \fIDBParameterGroup\fP parameters. CLI example to description of parameters .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.describe_parameters parametergroupname region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.exists(name, tags=None, region=None, key=None, keyid=None, profile=None) Check to see if an RDS exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.exists myrds region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.get_endpoint(name, tags=None, region=None, key=None, keyid=None, profile=None) Return the endpoint of an RDS instance. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.get_endpoint myrds .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.modify_db_instance(name, allocated_storage=None, allow_major_version_upgrade=None, apply_immediately=None, auto_minor_version_upgrade=None, backup_retention_period=None, ca_certificate_identifier=None, character_set_name=None, copy_tags_to_snapshot=None, db_cluster_identifier=None, db_instance_class=None, db_name=None, db_parameter_group_name=None, db_port_number=None, db_security_groups=None, db_subnet_group_name=None, domain=None, domain_iam_role_name=None, engine_version=None, iops=None, kms_key_id=None, license_model=None, master_user_password=None, monitoring_interval=None, monitoring_role_arn=None, multi_az=None, new_db_instance_identifier=None, option_group_name=None, preferred_backup_window=None, preferred_maintenance_window=None, promotion_tier=None, publicly_accessible=None, storage_encrypted=None, storage_type=None, tde_credential_arn=None, tde_credential_password=None, vpc_security_group_ids=None, region=None, key=None, keyid=None, profile=None) Modify settings for a DB instance. CLI example to description of parameters .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.modify_db_instance db_instance_identifier region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.option_group_exists(name, tags=None, region=None, key=None, keyid=None, profile=None) Check to see if an RDS option group exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.option_group_exists myoptiongr region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.parameter_group_exists(name, tags=None, region=None, key=None, keyid=None, profile=None) Check to see if an RDS parameter group exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.parameter_group_exists myparametergroup region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.subnet_group_exists(name, tags=None, region=None, key=None, keyid=None, profile=None) Check to see if an RDS subnet group exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.subnet_group_exists my\-param\-group region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_rds.update_parameter_group(name, parameters, apply_method=\(aqpending\-reboot\(aq, tags=None, region=None, key=None, keyid=None, profile=None) Update an RDS parameter group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_rds.update_parameter_group my\-param\-group parameters=\(aq{\(dqback_log\(dq:1, \(dqbinlog_cache_size\(dq:4096}\(aq region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_route53 .sp Connection module for Amazon Route53 .sp New in version 2014.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit route53 credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C route53.keyid: GKTADJGHEIQSXMKKRBJ08H route53.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C route53.region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp If a region is not specified, the default is \(aquniversal\(aq, which is what the boto_route53 library expects, rather than None. .sp It\(aqs also possible to specify key, keyid and region via a profile, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_route53.add_record(name, value, zone, record_type, identifier=None, ttl=None, region=None, key=None, keyid=None, profile=None, wait_for_sync=True, split_dns=False, private_zone=False, retry_on_rate_limit=None, rate_limit_retries=None, retry_on_errors=True, error_retries=5) Add a record to a zone. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_route53.add_record test.example.org 1.1.1.1 example.org A .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B retry_on_errors Continue to query if the zone exists after an error is raised. The previously used argument \fIretry_on_rate_limit\fP was deprecated for this argument. Users can still use \fIretry_on_rate_limit\fP to ensure backwards compatibility, but please migrate to using the favored \fIretry_on_errors\fP argument instead. .TP .B error_retries Number of times to attempt to query if the zone exists. The previously used argument \fIrate_limit_retries\fP was deprecated for this arguments. Users can still use \fIrate_limit_retries\fP to ensure backwards compatibility, but please migrate to using the favored \fIerror_retries\fP argument instead. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_route53.create_healthcheck(ip_addr=None, fqdn=None, region=None, key=None, keyid=None, profile=None, port=53, hc_type=\(aqTCP\(aq, resource_path=\(aq\(aq, string_match=None, request_interval=30, failure_threshold=3, retry_on_errors=True, error_retries=5) Create a Route53 healthcheck .sp New in version 2018.3.0. .sp ip_addr .INDENT 7.0 .INDENT 3.5 IP address to check. ip_addr or fqdn is required. .UNINDENT .UNINDENT .sp fqdn .INDENT 7.0 .INDENT 3.5 Domain name of the endpoint to check. ip_addr or fqdn is required .UNINDENT .UNINDENT .sp port .INDENT 7.0 .INDENT 3.5 Port to check .UNINDENT .UNINDENT .sp hc_type .INDENT 7.0 .INDENT 3.5 Healthcheck type. HTTP | HTTPS | HTTP_STR_MATCH | HTTPS_STR_MATCH | TCP .UNINDENT .UNINDENT .sp resource_path .INDENT 7.0 .INDENT 3.5 Path to check .UNINDENT .UNINDENT .sp string_match .INDENT 7.0 .INDENT 3.5 If hc_type is HTTP_STR_MATCH or HTTPS_STR_MATCH, the string to search for in the response body from the specified resource .UNINDENT .UNINDENT .sp request_interval .INDENT 7.0 .INDENT 3.5 The number of seconds between the time that Amazon Route 53 gets a response from your endpoint and the time that it sends the next health\-check request. .UNINDENT .UNINDENT .sp failure_threshold .INDENT 7.0 .INDENT 3.5 The number of consecutive health checks that an endpoint must pass or fail for Amazon Route 53 to change the current status of the endpoint from unhealthy to healthy or vice versa. .UNINDENT .UNINDENT .sp region .INDENT 7.0 .INDENT 3.5 Region endpoint to connect to .UNINDENT .UNINDENT .sp key .INDENT 7.0 .INDENT 3.5 AWS key .UNINDENT .UNINDENT .sp keyid .INDENT 7.0 .INDENT 3.5 AWS keyid .UNINDENT .UNINDENT .sp profile .INDENT 7.0 .INDENT 3.5 AWS pillar profile .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_route53.create_healthcheck 192.168.0.1 salt myminion boto_route53.create_healthcheck 192.168.0.1 port=443 hc_type=HTTPS resource_path=/ fqdn=blog.saltstack.furniture .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_route53.create_hosted_zone(domain_name, caller_ref=None, comment=\(aq\(aq, private_zone=False, vpc_id=None, vpc_name=None, vpc_region=None, region=None, key=None, keyid=None, profile=None) Create a new Route53 Hosted Zone. Returns a Python data structure with information about the newly created Hosted Zone. .INDENT 7.0 .TP .B domain_name The name of the domain. This must be fully\-qualified, terminating with a period. This is the name you have registered with your domain registrar. It is also the name you will delegate from your registrar to the Amazon Route 53 delegation servers returned in response to this request. .TP .B caller_ref A unique string that identifies the request and that allows create_hosted_zone() calls to be retried without the risk of executing the operation twice. It can take several minutes for the change to replicate globally, and change from PENDING to INSYNC status. Thus it\(aqs best to provide some value for this where possible, since duplicate calls while the first is in PENDING status will be accepted and can lead to multiple copies of the zone being created. On the other hand, if a zone is created with a given caller_ref, then deleted, a second attempt to create a zone with the same caller_ref will fail until that caller_ref is flushed from the Route53 system, which can take upwards of 24 hours. .TP .B comment Any comments you want to include about the hosted zone. .TP .B private_zone Set True if creating a private hosted zone. .TP .B vpc_id When creating a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with vpe_name. Ignored when creating a non\-private zone. .TP .B vpc_name When creating a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with vpe_id. Ignored when creating a non\-private zone. .TP .B vpc_region When creating a private hosted zone, the region of the associated VPC is required. If not provided, an effort will be made to determine it from vpc_id or vpc_name, where possible. If this fails, you\(aqll need to provide an explicit value for this option. Ignored when creating a non\-private zone. .TP .B region Region endpoint to connect to. .TP .B key AWS key to bind with. .TP .B keyid AWS keyid to bind with. .TP .B profile Dict, or pillar key pointing to a dict, containing AWS region/key/keyid. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_route53.create_hosted_zone example.org .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_route53.create_zone(zone, private=False, vpc_id=None, vpc_region=None, region=None, key=None, keyid=None, profile=None) Create a Route53 hosted zone. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B zone DNS zone to create .TP .B private True/False if the zone will be a private zone .TP .B vpc_id VPC ID to associate the zone to (required if private is True) .TP .B vpc_region VPC Region (required if private is True) .TP .B region region endpoint to connect to .TP .B key AWS key .TP .B keyid AWS keyid .TP .B profile AWS pillar profile .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_route53.create_zone example.org .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_route53.delete_record(name, zone, record_type, identifier=None, all_records=False, region=None, key=None, keyid=None, profile=None, wait_for_sync=True, split_dns=False, private_zone=False, retry_on_rate_limit=None, rate_limit_retries=None, retry_on_errors=True, error_retries=5) Modify a record in a zone. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_route53.delete_record test.example.org example.org A .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B retry_on_errors Continue to query if the zone exists after an error is raised. The previously used argument \fIretry_on_rate_limit\fP was deprecated for this argument. Users can still use \fIretry_on_rate_limit\fP to ensure backwards compatibility, but please migrate to using the favored \fIretry_on_errors\fP argument instead. .TP .B error_retries Number of times to attempt to query if the zone exists. The previously used argument \fIrate_limit_retries\fP was deprecated for this arguments. Users can still use \fIrate_limit_retries\fP to ensure backwards compatibility, but please migrate to using the favored \fIerror_retries\fP argument instead. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_route53.delete_zone(zone, region=None, key=None, keyid=None, profile=None) Delete a Route53 hosted zone. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_route53.delete_zone example.org .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_route53.describe_hosted_zones(zone_id=None, domain_name=None, region=None, key=None, keyid=None, profile=None) Return detailed info about one, or all, zones in the bound account. If neither zone_id nor domain_name is provided, return all zones. Note that the return format is slightly different between the \(aqall\(aq and \(aqsingle\(aq description types. .INDENT 7.0 .TP .B zone_id The unique identifier for the Hosted Zone .TP .B domain_name The FQDN of the Hosted Zone (including final period) .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_route53.describe_hosted_zones domain_name=foo.bar.com. profile=\(aq{\(dqregion\(dq: \(dqus\-east\-1\(dq, \(dqkeyid\(dq: \(dqA12345678AB\(dq, \(dqkey\(dq: \(dqxblahblahblah\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_route53.get_record(name, zone, record_type, fetch_all=False, region=None, key=None, keyid=None, profile=None, split_dns=False, private_zone=False, identifier=None, retry_on_rate_limit=None, rate_limit_retries=None, retry_on_errors=True, error_retries=5) Get a record from a zone. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_route53.get_record test.example.org example.org A .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B retry_on_errors Continue to query if the zone exists after an error is raised. The previously used argument \fIretry_on_rate_limit\fP was deprecated for this argument. Users can still use \fIretry_on_rate_limit\fP to ensure backwards compatibility, but please migrate to using the favored \fIretry_on_errors\fP argument instead. .TP .B error_retries Number of times to attempt to query if the zone exists. The previously used argument \fIrate_limit_retries\fP was deprecated for this arguments. Users can still use \fIrate_limit_retries\fP to ensure backwards compatibility, but please migrate to using the favored \fIerror_retries\fP argument instead. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_route53.list_all_zones_by_id(region=None, key=None, keyid=None, profile=None) List, by their IDs, all hosted zones in the bound account. .INDENT 7.0 .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_route53.list_all_zones_by_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_route53.list_all_zones_by_name(region=None, key=None, keyid=None, profile=None) List, by their FQDNs, all hosted zones in the bound account. .INDENT 7.0 .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_route53.list_all_zones_by_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_route53.update_record(name, value, zone, record_type, identifier=None, ttl=None, region=None, key=None, keyid=None, profile=None, wait_for_sync=True, split_dns=False, private_zone=False, retry_on_rate_limit=None, rate_limit_retries=None, retry_on_errors=True, error_retries=5) Modify a record in a zone. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_route53.modify_record test.example.org 1.1.1.1 example.org A .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B retry_on_errors Continue to query if the zone exists after an error is raised. The previously used argument \fIretry_on_rate_limit\fP was deprecated for this argument. Users can still use \fIretry_on_rate_limit\fP to ensure backwards compatibility, but please migrate to using the favored \fIretry_on_errors\fP argument instead. .TP .B error_retries Number of times to attempt to query if the zone exists. The previously used argument \fIrate_limit_retries\fP was deprecated for this arguments. Users can still use \fIrate_limit_retries\fP to ensure backwards compatibility, but please migrate to using the favored \fIerror_retries\fP argument instead. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_route53.zone_exists(zone, region=None, key=None, keyid=None, profile=None, retry_on_rate_limit=None, rate_limit_retries=None, retry_on_errors=True, error_retries=5) Check for the existence of a Route53 hosted zone. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_route53.zone_exists example.org .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B retry_on_errors Continue to query if the zone exists after an error is raised. The previously used argument \fIretry_on_rate_limit\fP was deprecated for this argument. Users can still use \fIretry_on_rate_limit\fP to ensure backwards compatibility, but please migrate to using the favored \fIretry_on_errors\fP argument instead. .TP .B error_retries Number of times to attempt to query if the zone exists. The previously used argument \fIrate_limit_retries\fP was deprecated for this arguments. Users can still use \fIrate_limit_retries\fP to ensure backwards compatibility, but please migrate to using the favored \fIerror_retries\fP argument instead. .UNINDENT .UNINDENT .SS salt.modules.boto_s3 .sp Connection module for Amazon S3 using boto3 .sp New in version 2018.3.0. .INDENT 0.0 .TP .B configuration This module accepts explicit AWS credentials but can also utilize IAM roles assigned to the instance through Instance Profiles or it can read them from the ~/.aws/credentials file or from these environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available at: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ iam\-roles\-for\-amazon\-ec2.html http://boto3.readthedocs.io/en/latest/guide/ configuration.html#guide\-configuration .ft P .fi .UNINDENT .UNINDENT .sp If IAM roles are not used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C s3.keyid: GKTADJGHEIQSXMKKRBJ08H s3.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C s3.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3.get_object_metadata(name, extra_args=None, region=None, key=None, keyid=None, profile=None) Get metadata about an S3 object. Returns None if the object does not exist. .sp You can pass AWS SSE\-C related args and/or RequestPayer in extra_args. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3.get_object_metadata \e my_bucket/path/to/object \e region=us\-east\-1 \e key=key \e keyid=keyid \e profile=profile \e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3.upload_file(source, name, extra_args=None, region=None, key=None, keyid=None, profile=None) Upload a local file as an S3 object. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3.upload_file \e /path/to/local/file \e my_bucket/path/to/object \e region=us\-east\-1 \e key=key \e keyid=keyid \e profile=profile \e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_s3_bucket .sp Connection module for Amazon S3 Buckets .sp New in version 2016.3.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 boto .IP \(bu 2 boto3 .UNINDENT .UNINDENT .sp The dependencies listed above can be installed via package or pip. .INDENT 0.0 .TP .B configuration This module accepts explicit Lambda credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C s3.keyid: GKTADJGHEIQSXMKKRBJ08H s3.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C s3.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.create(Bucket, ACL=None, LocationConstraint=None, GrantFullControl=None, GrantRead=None, GrantReadACP=None, GrantWrite=None, GrantWriteACP=None, region=None, key=None, keyid=None, profile=None) Given a valid config, create an S3 Bucket. .sp Returns {created: true} if the bucket was created and returns {created: False} if the bucket was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.create my_bucket \e GrantFullControl=\(aqemailaddress=example@example.com\(aq \e GrantRead=\(aquri=\(dqhttp://acs.amazonaws.com/groups/global/AllUsers\(dq\(aq \e GrantReadACP=\(aqemailaddress=\(dqexampl@example.com\(dq,id=\(dq2345678909876432\(dq\(aq \e LocationConstraint=us\-west\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.delete(Bucket, MFA=None, RequestPayer=None, Force=False, region=None, key=None, keyid=None, profile=None) Given a bucket name, delete it, optionally emptying it first. .sp Returns {deleted: true} if the bucket was deleted and returns {deleted: false} if the bucket was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.delete mybucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.delete_cors(Bucket, region=None, key=None, keyid=None, profile=None) Delete the CORS configuration for the given bucket .sp Returns {deleted: true} if CORS was deleted and returns {deleted: False} if CORS was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.delete_cors my_bucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.delete_lifecycle_configuration(Bucket, region=None, key=None, keyid=None, profile=None) Delete the lifecycle configuration for the given bucket .sp Returns {deleted: true} if Lifecycle was deleted and returns {deleted: False} if Lifecycle was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.delete_lifecycle_configuration my_bucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.delete_objects(Bucket, Delete, MFA=None, RequestPayer=None, region=None, key=None, keyid=None, profile=None) Delete objects in a given S3 bucket. .sp Returns {deleted: true} if all objects were deleted and {deleted: false, failed: [key, ...]} otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.delete_objects mybucket \(aq{Objects: [Key: myobject]}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.delete_policy(Bucket, region=None, key=None, keyid=None, profile=None) Delete the policy from the given bucket .sp Returns {deleted: true} if policy was deleted and returns {deleted: False} if policy was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.delete_policy my_bucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.delete_replication(Bucket, region=None, key=None, keyid=None, profile=None) Delete the replication config from the given bucket .sp Returns {deleted: true} if replication configuration was deleted and returns {deleted: False} if replication configuration was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.delete_replication my_bucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.delete_tagging(Bucket, region=None, key=None, keyid=None, profile=None) Delete the tags from the given bucket .sp Returns {deleted: true} if tags were deleted and returns {deleted: False} if tags were not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.delete_tagging my_bucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.delete_website(Bucket, region=None, key=None, keyid=None, profile=None) Remove the website configuration from the given bucket .sp Returns {deleted: true} if website configuration was deleted and returns {deleted: False} if website configuration was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.delete_website my_bucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.describe(Bucket, region=None, key=None, keyid=None, profile=None) Given a bucket name describe its properties. .sp Returns a dictionary of interesting properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.describe mybucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.empty(Bucket, MFA=None, RequestPayer=None, region=None, key=None, keyid=None, profile=None) Delete all objects in a given S3 bucket. .sp Returns {deleted: true} if all objects were deleted and {deleted: false, failed: [key, ...]} otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.empty mybucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.exists(Bucket, region=None, key=None, keyid=None, profile=None) Given a bucket name, check to see if the given bucket exists. .sp Returns True if the given bucket exists and returns False if the given bucket does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.exists mybucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.list(region=None, key=None, keyid=None, profile=None) List all buckets owned by the authenticated sender of the request. .sp Returns list of buckets .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Owner: {...} Buckets: \- {...} \- {...} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.list_object_versions(Bucket, Delimiter=None, EncodingType=None, Prefix=None, region=None, key=None, keyid=None, profile=None) List objects in a given S3 bucket. .sp Returns a list of objects. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.list_object_versions mybucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.list_objects(Bucket, Delimiter=None, EncodingType=None, Prefix=None, FetchOwner=False, StartAfter=None, region=None, key=None, keyid=None, profile=None) List objects in a given S3 bucket. .sp Returns a list of objects. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.list_objects mybucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.put_acl(Bucket, ACL=None, AccessControlPolicy=None, GrantFullControl=None, GrantRead=None, GrantReadACP=None, GrantWrite=None, GrantWriteACP=None, region=None, key=None, keyid=None, profile=None) Given a valid config, update the ACL for a bucket. .sp Returns {updated: true} if the ACL was updated and returns {updated: False} if the ACL was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.put_acl my_bucket \(aqpublic\(aq \e GrantFullControl=\(aqemailaddress=example@example.com\(aq \e GrantRead=\(aquri=\(dqhttp://acs.amazonaws.com/groups/global/AllUsers\(dq\(aq \e GrantReadACP=\(aqemailaddress=\(dqexampl@example.com\(dq,id=\(dq2345678909876432\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.put_cors(Bucket, CORSRules, region=None, key=None, keyid=None, profile=None) Given a valid config, update the CORS rules for a bucket. .sp Returns {updated: true} if CORS was updated and returns {updated: False} if CORS was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.put_cors my_bucket \(aq[{\e \(dqAllowedHeaders\(dq:[],\e \(dqAllowedMethods\(dq:[\(dqGET\(dq],\e \(dqAllowedOrigins\(dq:[\(dq*\(dq],\e \(dqExposeHeaders\(dq:[],\e \(dqMaxAgeSeconds\(dq:123,\e }]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.put_lifecycle_configuration(Bucket, Rules, region=None, key=None, keyid=None, profile=None) Given a valid config, update the Lifecycle rules for a bucket. .sp Returns {updated: true} if Lifecycle was updated and returns {updated: False} if Lifecycle was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.put_lifecycle_configuration my_bucket \(aq[{\e \(dqExpiration\(dq: {...},\e \(dqID\(dq: \(dqidstring\(dq,\e \(dqPrefix\(dq: \(dqprefixstring\(dq,\e \(dqStatus\(dq: \(dqenabled\(dq,\e \(dqTransitions\(dq: [{...},],\e \(dqNoncurrentVersionTransitions\(dq: [{...},],\e \(dqNoncurrentVersionExpiration\(dq: {...},\e }]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.put_logging(Bucket, TargetBucket=None, TargetPrefix=None, TargetGrants=None, region=None, key=None, keyid=None, profile=None) Given a valid config, update the logging parameters for a bucket. .sp Returns {updated: true} if parameters were updated and returns {updated: False} if parameters were not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.put_logging my_bucket log_bucket \(aq[{...}]\(aq prefix .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.put_notification_configuration(Bucket, TopicConfigurations=None, QueueConfigurations=None, LambdaFunctionConfigurations=None, region=None, key=None, keyid=None, profile=None) Given a valid config, update the notification parameters for a bucket. .sp Returns {updated: true} if parameters were updated and returns {updated: False} if parameters were not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.put_notification_configuration my_bucket [{...}] \e [{...}] \e [{...}] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.put_policy(Bucket, Policy, region=None, key=None, keyid=None, profile=None) Given a valid config, update the policy for a bucket. .sp Returns {updated: true} if policy was updated and returns {updated: False} if policy was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.put_policy my_bucket {...} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.put_replication(Bucket, Role, Rules, region=None, key=None, keyid=None, profile=None) Given a valid config, update the replication configuration for a bucket. .sp Returns {updated: true} if replication configuration was updated and returns {updated: False} if replication configuration was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.put_replication my_bucket my_role [...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.put_request_payment(Bucket, Payer, region=None, key=None, keyid=None, profile=None) Given a valid config, update the request payment configuration for a bucket. .sp Returns {updated: true} if request payment configuration was updated and returns {updated: False} if request payment configuration was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.put_request_payment my_bucket Requester .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.put_tagging(Bucket, region=None, key=None, keyid=None, profile=None, **kwargs) Given a valid config, update the tags for a bucket. .sp Returns {updated: true} if tags were updated and returns {updated: False} if tags were not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.put_tagging my_bucket my_role [...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.put_versioning(Bucket, Status, MFADelete=None, MFA=None, region=None, key=None, keyid=None, profile=None) Given a valid config, update the versioning configuration for a bucket. .sp Returns {updated: true} if versioning configuration was updated and returns {updated: False} if versioning configuration was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.put_versioning my_bucket Enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_s3_bucket.put_website(Bucket, ErrorDocument=None, IndexDocument=None, RedirectAllRequestsTo=None, RoutingRules=None, region=None, key=None, keyid=None, profile=None) Given a valid config, update the website configuration for a bucket. .sp Returns {updated: true} if website configuration was updated and returns {updated: False} if website configuration was not updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_s3_bucket.put_website my_bucket IndexDocument=\(aq{\(dqSuffix\(dq:\(dqindex.html\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_secgroup .sp Connection module for Amazon Security Groups .sp New in version 2014.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit ec2 credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C secgroup.keyid: GKTADJGHEIQSXMKKRBJ08H secgroup.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C secgroup.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_secgroup.authorize(name=None, source_group_name=None, source_group_owner_id=None, ip_protocol=None, from_port=None, to_port=None, cidr_ip=None, group_id=None, source_group_group_id=None, region=None, key=None, keyid=None, profile=None, vpc_id=None, vpc_name=None, egress=False) Add a new rule to an existing security group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_secgroup.authorize mysecgroup ip_protocol=tcp from_port=80 to_port=80 cidr_ip=\(aq[\(aq10.0.0.0/8\(aq, \(aq192.168.0.0/24\(aq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_secgroup.convert_to_group_ids(groups, vpc_id=None, vpc_name=None, region=None, key=None, keyid=None, profile=None) Given a list of security groups and a vpc_id, convert_to_group_ids will convert all list items in the given list to security group ids. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_secgroup.convert_to_group_ids mysecgroup vpc\-89yhh7h .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_secgroup.create(name, description, vpc_id=None, vpc_name=None, region=None, key=None, keyid=None, profile=None) Create a security group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_secgroup.create mysecgroup \(aqMy Security Group\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_secgroup.delete(name=None, group_id=None, region=None, key=None, keyid=None, profile=None, vpc_id=None, vpc_name=None) Delete a security group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_secgroup.delete mysecgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_secgroup.delete_tags(tags, name=None, group_id=None, vpc_name=None, vpc_id=None, region=None, key=None, keyid=None, profile=None) Deletes tags from a security group. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B tags a list of tags to remove .TP .B name the name of the security group .TP .B group_id the group id of the security group (in lie of a name/vpc combo) .TP .B vpc_name the name of the vpc to search the named group for .TP .B vpc_id the id of the vpc, in lieu of the vpc_name .TP .B region the amazon region .TP .B key amazon key .TP .B keyid amazon keyid .TP .B profile amazon profile .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_secgroup.delete_tags [\(aqTAG_TO_DELETE1\(aq,\(aqTAG_TO_DELETE2\(aq] security_group_name vpc_id=vpc\-13435 profile=my_aws_profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_secgroup.exists(name=None, region=None, key=None, keyid=None, profile=None, vpc_id=None, vpc_name=None, group_id=None) Check to see if a security group exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_secgroup.exists mysecgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_secgroup.get_all_security_groups(groupnames=None, group_ids=None, filters=None, region=None, key=None, keyid=None, profile=None) Return a list of all Security Groups matching the given criteria and filters. .sp Note that the \fBgroupnames\fP argument only functions correctly for EC2 Classic and default VPC Security Groups. To find groups by name in other VPCs you\(aqll want to use the \fBgroup\-name\fP filter instead. .sp The valid keys for the \fBfilters\fP argument can be found in \fI\%AWS\(aqs API documentation\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_secgroup.get_all_security_groups filters=\(aq{group\-name: mygroup}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_secgroup.get_config(name=None, group_id=None, region=None, key=None, keyid=None, profile=None, vpc_id=None, vpc_name=None) Get the configuration for a security group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_secgroup.get_config mysecgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_secgroup.get_group_id(name, vpc_id=None, vpc_name=None, region=None, key=None, keyid=None, profile=None) Get a Group ID given a Group Name or Group Name and VPC ID .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_secgroup.get_group_id mysecgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_secgroup.revoke(name=None, source_group_name=None, source_group_owner_id=None, ip_protocol=None, from_port=None, to_port=None, cidr_ip=None, group_id=None, source_group_group_id=None, region=None, key=None, keyid=None, profile=None, vpc_id=None, vpc_name=None, egress=False) Remove a rule from an existing security group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_secgroup.revoke mysecgroup ip_protocol=tcp from_port=80 to_port=80 cidr_ip=\(aq10.0.0.0/8\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_secgroup.set_tags(tags, name=None, group_id=None, vpc_name=None, vpc_id=None, region=None, key=None, keyid=None, profile=None) Sets tags on a security group. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B tags a dict of key:value pair of tags to set on the security group .TP .B name the name of the security group .TP .B group_id the group id of the security group (in lie of a name/vpc combo) .TP .B vpc_name the name of the vpc to search the named group for .TP .B vpc_id the id of the vpc, in lieu of the vpc_name .TP .B region the amazon region .TP .B key amazon key .TP .B keyid amazon keyid .TP .B profile amazon profile .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_secgroup.set_tags \(dq{\(aqTAG1\(aq: \(aqValue1\(aq, \(aqTAG2\(aq: \(aqValue2\(aq}\(dq security_group_name vpc_id=vpc\-13435 profile=my_aws_profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_sns .sp Connection module for Amazon SNS .INDENT 0.0 .TP .B configuration This module accepts explicit sns credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sns.keyid: GKTADJGHEIQSXMKKRBJ08H sns.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sns.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sns.create(name, region=None, key=None, keyid=None, profile=None) Create an SNS topic. .sp CLI example to create a topic: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sns.create mytopic region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sns.delete(name, region=None, key=None, keyid=None, profile=None) Delete an SNS topic. .sp CLI example to delete a topic: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sns.delete mytopic region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sns.exists(name, region=None, key=None, keyid=None, profile=None) Check to see if an SNS topic exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sns.exists mytopic region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sns.get_all_subscriptions_by_topic(name, region=None, key=None, keyid=None, profile=None) Get list of all subscriptions to a specific topic. .sp CLI example to delete a topic: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sns.get_all_subscriptions_by_topic mytopic region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sns.get_all_topics(region=None, key=None, keyid=None, profile=None) Returns a list of the all topics.. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sns.get_all_topics .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sns.get_arn(name, region=None, key=None, keyid=None, profile=None) Returns the full ARN for a given topic name. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sns.get_arn mytopic .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sns.subscribe(topic, protocol, endpoint, region=None, key=None, keyid=None, profile=None) Subscribe to a Topic. .sp CLI example to delete a topic: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sns.subscribe mytopic https https://www.example.com/sns\-endpoint region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sns.unsubscribe(topic, subscription_arn, region=None, key=None, keyid=None, profile=None) Unsubscribe a specific SubscriptionArn of a topic. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sns.unsubscribe my_topic my_subscription_arn region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .SS salt.modules.boto_sqs .sp Connection module for Amazon SQS .sp New in version 2014.7.0. .INDENT 0.0 .TP .B configuration This module accepts explicit sqs credentials but 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 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.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 7.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sqs.create(name, attributes=None, region=None, key=None, keyid=None, profile=None) Create an SQS queue. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sqs.create myqueue region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sqs.delete(name, region=None, key=None, keyid=None, profile=None) Delete an SQS queue. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sqs.delete myqueue region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sqs.exists(name, region=None, key=None, keyid=None, profile=None) Check to see if a queue exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sqs.exists myqueue region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sqs.get_attributes(name, region=None, key=None, keyid=None, profile=None) Return attributes currently set on an SQS queue. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sqs.get_attributes myqueue .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sqs.list_(prefix=\(aq\(aq, region=None, key=None, keyid=None, profile=None) Return a list of the names of all visible queues. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sqs.list region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_sqs.set_attributes(name, attributes, region=None, key=None, keyid=None, profile=None) Set attributes on an SQS queue. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_sqs.set_attributes myqueue \(aq{ReceiveMessageWaitTimeSeconds: 20}\(aq region=us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_ssm .sp Connection module for Amazon SSM .INDENT 0.0 .TP .B configuration This module uses 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 7.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 .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ssm.delete_parameter(Name, region=None, key=None, keyid=None, profile=None) Removes a parameter from the SSM parameter store .sp New in version 3000. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ssm.delete_parameter test\-param .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ssm.get_parameter(name, withdecryption=False, resp_json=False, region=None, key=None, keyid=None, profile=None) Retrieves a parameter from SSM Parameter Store .sp New in version 3000. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ssm.get_parameter test\-param withdescription=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_ssm.put_parameter(Name, Value, Description=None, Type=\(aqString\(aq, KeyId=None, Overwrite=False, AllowedPattern=None, region=None, key=None, keyid=None, profile=None) Sets a parameter in the SSM parameter store .sp New in version 3000. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call boto_ssm.put_parameter test\-param test_value Type=SecureString KeyId=alias/aws/ssm Description=\(aqtest encrypted key\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.boto_vpc .sp Connection module for Amazon VPC .sp New in version 2014.7.0. .INDENT 0.0 .TP .B depends .UNINDENT .INDENT 0.0 .IP \(bu 2 boto >= 2.8.0 .IP \(bu 2 boto3 >= 1.2.6 .UNINDENT .INDENT 0.0 .TP .B configuration This module accepts explicit VPC credentials but 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 \fI\%here\fP\&. .UNINDENT .sp If IAM roles are not used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vpc.keyid: GKTADJGHEIQSXMKKRBJ08H vpc.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 vpc.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, either as a passed in dict, or as a string to pull from pillars or minion config: .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 Changed in version 2015.8.0: All methods now return a dictionary. Create and delete methods return: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C created: true .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C created: false error: message: error message .ft P .fi .UNINDENT .UNINDENT .sp Request methods (e.g., \fIdescribe_vpc\fP) return: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vpcs: \- {...} \- {...} .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C error: message: error message .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .sp Functions to request, accept, delete and describe VPC peering connections. Named VPC peering connections can be requested using these modules. VPC owner accounts can accept VPC peering connections (named or otherwise). .sp Examples showing creation of VPC peering connection .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Create a named VPC peering connection salt myminion boto_vpc.request_vpc_peering_connection vpc\-4a3e622e vpc\-be82e9da name=my_vpc_connection # Without a name salt myminion boto_vpc.request_vpc_peering_connection vpc\-4a3e622e vpc\-be82e9da # Specify a region salt myminion boto_vpc.request_vpc_peering_connection vpc\-4a3e622e vpc\-be82e9da region=us\-west\-2 .ft P .fi .UNINDENT .UNINDENT .sp Check to see if VPC peering connection is pending .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.is_peering_connection_pending name=salt\-vpc # Specify a region salt myminion boto_vpc.is_peering_connection_pending name=salt\-vpc region=us\-west\-2 # specify an id salt myminion boto_vpc.is_peering_connection_pending conn_id=pcx\-8a8939e3 .ft P .fi .UNINDENT .UNINDENT .sp Accept VPC peering connection .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.accept_vpc_peering_connection name=salt\-vpc # Specify a region salt myminion boto_vpc.accept_vpc_peering_connection name=salt\-vpc region=us\-west\-2 # specify an id salt myminion boto_vpc.accept_vpc_peering_connection conn_id=pcx\-8a8939e3 .ft P .fi .UNINDENT .UNINDENT .sp Deleting VPC peering connection via this module .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Delete a named VPC peering connection salt myminion boto_vpc.delete_vpc_peering_connection name=salt\-vpc # Specify a region salt myminion boto_vpc.delete_vpc_peering_connection name=salt\-vpc region=us\-west\-2 # specify an id salt myminion boto_vpc.delete_vpc_peering_connection conn_id=pcx\-8a8939e3 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.accept_vpc_peering_connection(conn_id=\(aq\(aq, name=\(aq\(aq, region=None, key=None, keyid=None, profile=None, dry_run=False) Request a VPC peering connection between two VPCs. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconn_id\fP \-\- The ID to use. String type. .IP \(bu 2 \fBname\fP \-\- The name of this VPC peering connection. String type. .IP \(bu 2 \fBregion\fP \-\- The AWS region to use. Type string. .IP \(bu 2 \fBkey\fP \-\- The key to use for this connection. Type string. .IP \(bu 2 \fBkeyid\fP \-\- The key id to use. .IP \(bu 2 \fBprofile\fP \-\- The profile to use. .IP \(bu 2 \fBdry_run\fP \-\- The dry_run flag to set. .UNINDENT .TP .B Returns dict .UNINDENT .sp Warning: Please specify either the \fBvpc_peering_connection_id\fP or \fBname\fP but not both. Specifying both will result in an error! .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.accept_vpc_peering_connection name=salt\-vpc # Specify a region salt myminion boto_vpc.accept_vpc_peering_connection name=salt\-vpc region=us\-west\-2 # specify an id salt myminion boto_vpc.accept_vpc_peering_connection conn_id=pcx\-8a8939e3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.associate_dhcp_options_to_vpc(dhcp_options_id, vpc_id=None, vpc_name=None, region=None, key=None, keyid=None, profile=None) Given valid DHCP options id and a valid VPC id, associate the DHCP options record with the VPC. .sp Returns True if the DHCP options record were associated and returns False if the DHCP options record was not associated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.associate_dhcp_options_to_vpc \(aqdhcp\-a0bl34pp\(aq \(aqvpc\-6b1fe402\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.associate_network_acl_to_subnet(network_acl_id=None, subnet_id=None, network_acl_name=None, subnet_name=None, region=None, key=None, keyid=None, profile=None) Given a network acl and subnet ids or names, associate a network acl to a subnet. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.associate_network_acl_to_subnet \e network_acl_id=\(aqacl\-5fb85d36\(aq subnet_id=\(aqsubnet\-6a1fe403\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.associate_network_acl_to_subnet \e network_acl_id=\(aqmyacl\(aq subnet_id=\(aqmysubnet\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.associate_route_table(route_table_id=None, subnet_id=None, route_table_name=None, subnet_name=None, region=None, key=None, keyid=None, profile=None) Given a route table and subnet name or id, associates the route table with the subnet. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.associate_route_table \(aqrtb\-1f382e7d\(aq \(aqsubnet\-6a1fe403\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.associate_route_table route_table_name=\(aqmyrtb\(aq \e subnet_name=\(aqmysubnet\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.check_vpc(vpc_id=None, vpc_name=None, region=None, key=None, keyid=None, profile=None) Check whether a VPC with the given name or id exists. Returns the vpc_id or None. Raises SaltInvocationError if both vpc_id and vpc_name are None. Optionally raise a CommandExecutionError if the VPC does not exist. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.check_vpc vpc_name=myvpc profile=awsprofile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.create(cidr_block, instance_tenancy=None, vpc_name=None, enable_dns_support=None, enable_dns_hostnames=None, tags=None, region=None, key=None, keyid=None, profile=None) Given a valid CIDR block, create a VPC. .sp An optional instance_tenancy argument can be provided. If provided, the valid values are \(aqdefault\(aq or \(aqdedicated\(aq .sp An optional vpc_name argument can be provided. .sp Returns {created: true} if the VPC was created and returns {created: False} if the VPC was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.create \(aq10.0.0.0/24\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.create_customer_gateway(vpn_connection_type, ip_address, bgp_asn, customer_gateway_name=None, tags=None, region=None, key=None, keyid=None, profile=None) Given a valid VPN connection type, a static IP address and a customer gateway’s Border Gateway Protocol (BGP) Autonomous System Number, create a customer gateway. .sp Returns the customer gateway id if the customer gateway was created and returns False if the customer gateway was not created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.create_customer_gateway \(aqipsec.1\(aq, \(aq12.1.2.3\(aq, 65534 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.create_dhcp_options(domain_name=None, domain_name_servers=None, ntp_servers=None, netbios_name_servers=None, netbios_node_type=None, dhcp_options_name=None, tags=None, vpc_id=None, vpc_name=None, region=None, key=None, keyid=None, profile=None) Given valid DHCP options, create a DHCP options record, optionally associating it with an existing VPC. .sp Returns True if the DHCP options record was created and returns False if the DHCP options record was not deleted. .sp Changed in version 2015.8.0: Added vpc_name and vpc_id arguments .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.create_dhcp_options domain_name=\(aqexample.com\(aq \e domain_name_servers=\(aq[1.2.3.4]\(aq ntp_servers=\(aq[5.6.7.8]\(aq \e netbios_name_servers=\(aq[10.0.0.1]\(aq netbios_node_type=1 \e vpc_name=\(aqmyvpc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.create_internet_gateway(internet_gateway_name=None, vpc_id=None, vpc_name=None, tags=None, region=None, key=None, keyid=None, profile=None) Create an Internet Gateway, optionally attaching it to an existing VPC. .sp Returns the internet gateway id if the internet gateway was created and returns False if the internet gateways was not created. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.create_internet_gateway \e internet_gateway_name=myigw vpc_name=myvpc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.create_nat_gateway(subnet_id=None, subnet_name=None, allocation_id=None, region=None, key=None, keyid=None, profile=None) Create a NAT Gateway within an existing subnet. If allocation_id is specified, the elastic IP address it references is associated with the gateway. Otherwise, a new allocation_id is created and used. .sp This function requires boto3 to be installed. .sp Returns the nat gateway id if the nat gateway was created and returns False if the nat gateway was not created. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.create_nat_gateway subnet_name=mysubnet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.create_network_acl(vpc_id=None, vpc_name=None, network_acl_name=None, subnet_id=None, subnet_name=None, tags=None, region=None, key=None, keyid=None, profile=None) Given a vpc_id, creates a network acl. .sp Returns the network acl id if successful, otherwise returns False. .sp Changed in version 2015.8.0: Added vpc_name, subnet_id, and subnet_name arguments .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.create_network_acl \(aqvpc\-6b1fe402\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.create_network_acl_entry(network_acl_id=None, rule_number=None, protocol=None, rule_action=None, cidr_block=None, egress=None, network_acl_name=None, icmp_code=None, icmp_type=None, port_range_from=None, port_range_to=None, region=None, key=None, keyid=None, profile=None) Creates a network acl entry. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.create_network_acl_entry \(aqacl\-5fb85d36\(aq \(aq32767\(aq \e \(aqall\(aq \(aqdeny\(aq \(aq0.0.0.0/0\(aq egress=true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.create_route(route_table_id=None, destination_cidr_block=None, route_table_name=None, gateway_id=None, internet_gateway_name=None, instance_id=None, interface_id=None, vpc_peering_connection_id=None, vpc_peering_connection_name=None, region=None, key=None, keyid=None, profile=None, nat_gateway_id=None, nat_gateway_subnet_name=None, nat_gateway_subnet_id=None) Creates a route. .sp If a nat gateway is specified, boto3 must be installed .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.create_route \(aqrtb\-1f382e7d\(aq \(aq10.0.0.0/16\(aq gateway_id=\(aqvgw\-a1b2c3\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.create_route_table(vpc_id=None, vpc_name=None, route_table_name=None, tags=None, region=None, key=None, keyid=None, profile=None) Creates a route table. .sp Changed in version 2015.8.0: Added vpc_name argument .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.create_route_table vpc_id=\(aqvpc\-6b1fe402\(aq \e route_table_name=\(aqmyroutetable\(aq salt myminion boto_vpc.create_route_table vpc_name=\(aqmyvpc\(aq \e route_table_name=\(aqmyroutetable\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.create_subnet(vpc_id=None, cidr_block=None, vpc_name=None, availability_zone=None, subnet_name=None, tags=None, region=None, key=None, keyid=None, profile=None, auto_assign_public_ipv4=False) Given a valid VPC ID or Name and a CIDR block, create a subnet for the VPC. .sp An optional availability zone argument can be provided. .sp Returns True if the VPC subnet was created and returns False if the VPC subnet was not created. .sp Changed in version 2015.8.0: Added vpc_name argument .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.create_subnet vpc_id=\(aqvpc\-6b1fe402\(aq \e subnet_name=\(aqmysubnet\(aq cidr_block=\(aq10.0.0.0/25\(aq salt myminion boto_vpc.create_subnet vpc_name=\(aqmyvpc\(aq \e subnet_name=\(aqmysubnet\(aq, cidr_block=\(aq10.0.0.0/25\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.customer_gateway_exists(customer_gateway_id=None, customer_gateway_name=None, region=None, key=None, keyid=None, profile=None) Given a customer gateway ID, check if the customer gateway ID exists. .sp Returns True if the customer gateway ID exists; Returns False otherwise. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.customer_gateway_exists cgw\-b6a247df salt myminion boto_vpc.customer_gateway_exists customer_gatway_name=mycgw .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.delete(vpc_id=None, name=None, vpc_name=None, tags=None, region=None, key=None, keyid=None, profile=None) Given a VPC ID or VPC name, delete the VPC. .sp Returns {deleted: true} if the VPC was deleted and returns {deleted: false} if the VPC was not deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.delete vpc_id=\(aqvpc\-6b1fe402\(aq salt myminion boto_vpc.delete name=\(aqmyvpc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.delete_customer_gateway(customer_gateway_id=None, customer_gateway_name=None, region=None, key=None, keyid=None, profile=None) Given a customer gateway ID or name, delete the customer gateway. .sp Returns True if the customer gateway was deleted and returns False if the customer gateway was not deleted. .sp Changed in version 2015.8.0: Added customer_gateway_name argument .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.delete_customer_gateway \(aqcgw\-b6a247df\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.delete_dhcp_options(dhcp_options_id=None, dhcp_options_name=None, region=None, key=None, keyid=None, profile=None) Delete dhcp options by id or name. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.delete_dhcp_options \(aqdopt\-b6a247df\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.delete_internet_gateway(internet_gateway_id=None, internet_gateway_name=None, detach=False, region=None, key=None, keyid=None, profile=None) Delete an internet gateway (by name or id). .sp Returns True if the internet gateway was deleted and otherwise False. .sp New in version 2015.8.0. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.delete_internet_gateway internet_gateway_id=igw\-1a2b3c salt myminion boto_vpc.delete_internet_gateway internet_gateway_name=myigw .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.delete_nat_gateway(nat_gateway_id, release_eips=False, region=None, key=None, keyid=None, profile=None, wait_for_delete=False, wait_for_delete_retries=5) Delete a nat gateway (by id). .sp Returns True if the internet gateway was deleted and otherwise False. .sp This function requires boto3 to be installed. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B nat_gateway_id Id of the NAT Gateway .TP .B release_eips whether to release the elastic IPs associated with the given NAT Gateway Id .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B wait_for_delete whether to wait for delete of the NAT gateway to be in failed or deleted state after issuing the delete call. .TP .B wait_for_delete_retries NAT gateway may take some time to be go into deleted or failed state. During the deletion process, subsequent release of elastic IPs may fail; this state will automatically retry this number of times to ensure the NAT gateway is in deleted or failed state before proceeding. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.delete_nat_gateway nat_gateway_id=igw\-1a2b3c .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.delete_network_acl(network_acl_id=None, network_acl_name=None, disassociate=False, region=None, key=None, keyid=None, profile=None) Delete a network acl based on the network_acl_id or network_acl_name provided. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.delete_network_acl network_acl_id=\(aqacl\-5fb85d36\(aq \e disassociate=false .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.delete_network_acl network_acl_name=\(aqmyacl\(aq \e disassociate=true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.delete_network_acl_entry(network_acl_id=None, rule_number=None, egress=None, network_acl_name=None, region=None, key=None, keyid=None, profile=None) Deletes a network acl entry. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.delete_network_acl_entry \(aqacl\-5fb85d36\(aq \(aq32767\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.delete_route(route_table_id=None, destination_cidr_block=None, route_table_name=None, region=None, key=None, keyid=None, profile=None) Deletes a route. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.delete_route \(aqrtb\-1f382e7d\(aq \(aq10.0.0.0/16\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.delete_route_table(route_table_id=None, route_table_name=None, region=None, key=None, keyid=None, profile=None) Deletes a route table. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.delete_route_table route_table_id=\(aqrtb\-1f382e7d\(aq salt myminion boto_vpc.delete_route_table route_table_name=\(aqmyroutetable\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.delete_subnet(subnet_id=None, subnet_name=None, region=None, key=None, keyid=None, profile=None) Given a subnet ID or name, delete the subnet. .sp Returns True if the subnet was deleted and returns False if the subnet was not deleted. .sp Changed in version 2015.8.0: Added subnet_name argument .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.delete_subnet \(aqsubnet\-6a1fe403\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.delete_vpc_peering_connection(conn_id=None, conn_name=None, region=None, key=None, keyid=None, profile=None, dry_run=False) Delete a VPC peering connection. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B conn_id The connection ID to check. Exclusive with conn_name. .TP .B conn_name The connection name to check. Exclusive with conn_id. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B dry_run If True, skip application and simply return projected status. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Create a named VPC peering connection salt myminion boto_vpc.delete_vpc_peering_connection conn_name=salt\-vpc # Specify a region salt myminion boto_vpc.delete_vpc_peering_connection conn_name=salt\-vpc region=us\-west\-2 # specify an id salt myminion boto_vpc.delete_vpc_peering_connection conn_id=pcx\-8a8939e3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.describe(vpc_id=None, vpc_name=None, region=None, key=None, keyid=None, profile=None) Describe a VPC\(aqs properties. If no VPC ID/Name is spcified then describe the default VPC. .sp Returns a dictionary of interesting properties. .sp Changed in version 2015.8.0: Added vpc_name argument .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.describe vpc_id=vpc\-123456 salt myminion boto_vpc.describe vpc_name=myvpc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.describe_nat_gateways(nat_gateway_id=None, subnet_id=None, subnet_name=None, vpc_id=None, vpc_name=None, states=(\(aqpending\(aq, \(aqavailable\(aq), region=None, key=None, keyid=None, profile=None) Return a description of nat gateways matching the selection criteria .sp This function requires boto3 to be installed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.describe_nat_gateways nat_gateway_id=\(aqnat\-03b02643b43216fe7\(aq salt myminion boto_vpc.describe_nat_gateways subnet_id=\(aqsubnet\-5b05942d\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.describe_route_tables(route_table_id=None, route_table_name=None, vpc_id=None, tags=None, region=None, key=None, keyid=None, profile=None) Given route table properties, return details of all matching route tables. .sp This function requires boto3 to be installed. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.describe_route_tables vpc_id=\(aqvpc\-a6a9efc3\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.describe_subnet(subnet_id=None, subnet_name=None, region=None, key=None, keyid=None, profile=None) Given a subnet id or name, describe its properties. .sp Returns a dictionary of interesting properties. .sp New in version 2015.8.0. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.describe_subnet subnet_id=subnet\-123456 salt myminion boto_vpc.describe_subnet subnet_name=mysubnet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.describe_subnets(subnet_ids=None, subnet_names=None, vpc_id=None, cidr=None, region=None, key=None, keyid=None, profile=None) Given a VPC ID or subnet CIDR, returns a list of associated subnets and their details. Return all subnets if VPC ID or CIDR are not provided. If a subnet id or CIDR is provided, only its associated subnet details will be returned. .sp New in version 2015.8.0. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.describe_subnets .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.describe_subnets subnet_ids=[\(aqsubnet\-ba1987ab\(aq, \(aqsubnet\-ba1987cd\(aq] .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.describe_subnets vpc_id=vpc\-123456 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.describe_subnets cidr=10.0.0.0/21 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.describe_vpc_peering_connection(name, region=None, key=None, keyid=None, profile=None) Returns any VPC peering connection id(s) for the given VPC peering connection name. .sp VPC peering connection ids are only returned for connections that are in the \fBactive\fP, \fBpending\-acceptance\fP or \fBprovisioning\fP state. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The string name for this VPC peering connection .IP \(bu 2 \fBregion\fP \-\- The aws region to use .IP \(bu 2 \fBkey\fP \-\- Your aws key .IP \(bu 2 \fBkeyid\fP \-\- The key id associated with this aws account .IP \(bu 2 \fBprofile\fP \-\- The profile to use .UNINDENT .TP .B Returns dict .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.describe_vpc_peering_connection salt\-vpc # Specify a region salt myminion boto_vpc.describe_vpc_peering_connection salt\-vpc region=us\-west\-2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.describe_vpcs(vpc_id=None, name=None, cidr=None, tags=None, region=None, key=None, keyid=None, profile=None) Describe all VPCs, matching the filter criteria if provided. .sp Returns a list of dictionaries with interesting properties. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.describe_vpcs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.dhcp_options_exists(dhcp_options_id=None, name=None, dhcp_options_name=None, tags=None, region=None, key=None, keyid=None, profile=None) Check if a dhcp option exists. .sp Returns True if the dhcp option exists; Returns False otherwise. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.dhcp_options_exists dhcp_options_id=\(aqdhcp\-a0bl34pp\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.disassociate_network_acl(subnet_id=None, vpc_id=None, subnet_name=None, vpc_name=None, region=None, key=None, keyid=None, profile=None) Given a subnet ID, disassociates a network acl. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.disassociate_network_acl \(aqsubnet\-6a1fe403\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.disassociate_route_table(association_id, region=None, key=None, keyid=None, profile=None) Disassociates a route table. .INDENT 7.0 .TP .B association_id The Route Table Association ID to disassociate .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.disassociate_route_table \(aqrtbassoc\-d8ccddba\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.exists(vpc_id=None, name=None, cidr=None, tags=None, region=None, key=None, keyid=None, profile=None) Given a VPC ID, check to see if the given VPC ID exists. .sp Returns True if the given VPC ID exists and returns False if the given VPC ID does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.exists myvpc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.get_dhcp_options(dhcp_options_name=None, dhcp_options_id=None, region=None, key=None, keyid=None, profile=None) Return a dict with the current values of the requested DHCP options set .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.get_dhcp_options \(aqmyfunnydhcpoptionsname\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.get_id(name=None, cidr=None, tags=None, region=None, key=None, keyid=None, profile=None) Given VPC properties, return the VPC id if a match is found. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.get_id myvpc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.get_resource_id(resource, name=None, resource_id=None, region=None, key=None, keyid=None, profile=None) Get an AWS id for a VPC resource by type and name. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.get_resource_id internet_gateway myigw .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.get_subnet_association(subnets, region=None, key=None, keyid=None, profile=None) Given a subnet (aka: a vpc zone identifier) or list of subnets, returns vpc association. .sp Returns a VPC ID if the given subnets are associated with the same VPC ID. Returns False on an error or if the given subnets are associated with different VPC IDs. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.get_subnet_association subnet\-61b47516 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.get_subnet_association [\(aqsubnet\-61b47516\(aq,\(aqsubnet\-2cb9785b\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.is_peering_connection_pending(conn_id=None, conn_name=None, region=None, key=None, keyid=None, profile=None) Check if a VPC peering connection is in the pending state. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B conn_id The connection ID to check. Exclusive with conn_name. .TP .B conn_name The connection name to check. Exclusive with conn_id. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.is_peering_connection_pending conn_name=salt\-vpc # Specify a region salt myminion boto_vpc.is_peering_connection_pending conn_name=salt\-vpc region=us\-west\-2 # specify an id salt myminion boto_vpc.is_peering_connection_pending conn_id=pcx\-8a8939e3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.nat_gateway_exists(nat_gateway_id=None, subnet_id=None, subnet_name=None, vpc_id=None, vpc_name=None, states=(\(aqpending\(aq, \(aqavailable\(aq), region=None, key=None, keyid=None, profile=None) Checks if a nat gateway exists. .sp This function requires boto3 to be installed. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.nat_gateway_exists nat_gateway_id=\(aqnat\-03b02643b43216fe7\(aq salt myminion boto_vpc.nat_gateway_exists subnet_id=\(aqsubnet\-5b05942d\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.network_acl_exists(network_acl_id=None, name=None, network_acl_name=None, tags=None, region=None, key=None, keyid=None, profile=None) Checks if a network acl exists. .sp Returns True if the network acl exists or returns False if it doesn\(aqt exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.network_acl_exists network_acl_id=\(aqacl\-5fb85d36\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.peering_connection_pending_from_vpc(conn_id=None, conn_name=None, vpc_id=None, vpc_name=None, region=None, key=None, keyid=None, profile=None) Check if a VPC peering connection is in the pending state, and requested from the given VPC. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B conn_id The connection ID to check. Exclusive with conn_name. .TP .B conn_name The connection name to check. Exclusive with conn_id. .TP .B vpc_id Is this the ID of the requesting VPC for this peering connection. Exclusive with vpc_name. .TP .B vpc_name Is this the Name of the requesting VPC for this peering connection. Exclusive with vpc_id. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.is_peering_connection_pending name=salt\-vpc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.replace_network_acl_entry(network_acl_id=None, rule_number=None, protocol=None, rule_action=None, cidr_block=None, egress=None, network_acl_name=None, icmp_code=None, icmp_type=None, port_range_from=None, port_range_to=None, region=None, key=None, keyid=None, profile=None) Replaces a network acl entry. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.replace_network_acl_entry \(aqacl\-5fb85d36\(aq \(aq32767\(aq \e \(aqall\(aq \(aqdeny\(aq \(aq0.0.0.0/0\(aq egress=true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.replace_route(route_table_id=None, destination_cidr_block=None, route_table_name=None, gateway_id=None, instance_id=None, interface_id=None, region=None, key=None, keyid=None, profile=None, vpc_peering_connection_id=None) Replaces a route. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.replace_route \(aqrtb\-1f382e7d\(aq \(aq10.0.0.0/16\(aq gateway_id=\(aqvgw\-a1b2c3\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.replace_route_table_association(association_id, route_table_id, region=None, key=None, keyid=None, profile=None) Replaces a route table association. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.replace_route_table_association \(aqrtbassoc\-d8ccddba\(aq \(aqrtb\-1f382e7d\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.request_vpc_peering_connection(requester_vpc_id=None, requester_vpc_name=None, peer_vpc_id=None, peer_vpc_name=None, name=None, peer_owner_id=None, peer_region=None, region=None, key=None, keyid=None, profile=None, dry_run=False) Request a VPC peering connection between two VPCs. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B requester_vpc_id ID of the requesting VPC. Exclusive with requester_vpc_name. .TP .B requester_vpc_name Name tag of the requesting VPC. Exclusive with requester_vpc_id. .TP .B peer_vpc_id ID of the VPC to create VPC peering connection with. This can be a VPC in another account. Exclusive with peer_vpc_name. .TP .B peer_vpc_name Name tag of the VPC to create VPC peering connection with. This can only be a VPC in the same account and same region, else resolving it into a vpc ID will almost certainly fail. Exclusive with peer_vpc_id. .TP .B name The name to use for this VPC peering connection. .TP .B peer_owner_id ID of the owner of the peer VPC. Defaults to your account ID, so a value is required if peering with a VPC in a different account. .TP .B peer_region Region of peer VPC. For inter\-region vpc peering connections. Not required for intra\-region peering connections. .sp New in version 3005. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B dry_run If True, skip application and return status. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Create a named VPC peering connection salt myminion boto_vpc.request_vpc_peering_connection vpc\-4a3e622e vpc\-be82e9da name=my_vpc_connection # Without a name salt myminion boto_vpc.request_vpc_peering_connection vpc\-4a3e622e vpc\-be82e9da # Specify a region salt myminion boto_vpc.request_vpc_peering_connection vpc\-4a3e622e vpc\-be82e9da region=us\-west\-2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.resource_exists(resource, name=None, resource_id=None, tags=None, region=None, key=None, keyid=None, profile=None) Given a resource type and name, return {exists: true} if it exists, {exists: false} if it does not exist, or {error: {message: error text} on error. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.resource_exists internet_gateway myigw .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.route_exists(destination_cidr_block, route_table_name=None, route_table_id=None, gateway_id=None, instance_id=None, interface_id=None, tags=None, region=None, key=None, keyid=None, profile=None, vpc_peering_connection_id=None) Checks if a route exists. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.route_exists destination_cidr_block=\(aq10.0.0.0/20\(aq gateway_id=\(aqlocal\(aq route_table_name=\(aqtest\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.route_table_exists(route_table_id=None, name=None, route_table_name=None, tags=None, region=None, key=None, keyid=None, profile=None) Checks if a route table exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.route_table_exists route_table_id=\(aqrtb\-1f382e7d\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.boto_vpc.subnet_exists(subnet_id=None, name=None, subnet_name=None, cidr=None, tags=None, zones=None, region=None, key=None, keyid=None, profile=None) Check if a subnet exists. .sp Returns True if the subnet exists, otherwise returns False. .sp Changed in version 2015.8.0: Added subnet_name argument Deprecated name argument .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion boto_vpc.subnet_exists subnet_id=\(aqsubnet\-6a1fe403\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.bower .SS Manage and query Bower packages .sp This module manages the installed packages using Bower. Note that npm, git and bower must be installed for this module to be available. .INDENT 0.0 .TP .B salt.modules.bower.install(pkg, dir, pkgs=None, runas=None, env=None) Install a Bower package. .sp If no package is specified, the dependencies (from bower.json) of the package in the given directory will be installed. .INDENT 7.0 .TP .B pkg A package name in any format accepted by Bower, including a version identifier .TP .B dir The target directory in which to install the package .TP .B pkgs A list of package names in the same format as the \fBpkg\fP parameter .TP .B runas The user to run Bower with .TP .B env Environment variables to set when invoking Bower. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bower.install underscore /path/to/project salt \(aq*\(aq bower.install jquery#2.0 /path/to/project .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bower.list_(dir, runas=None, env=None) List installed Bower packages. .INDENT 7.0 .TP .B dir The directory whose packages will be listed .TP .B runas The user to run Bower with .TP .B env Environment variables to set when invoking Bower. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bower.list /path/to/project .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bower.prune(dir, runas=None, env=None) New in version 2017.7.0. .sp Remove extraneous local Bower packages, i.e. those not referenced in bower.json .INDENT 7.0 .TP .B dir The directory whose packages will be pruned .TP .B runas The user to run Bower with .TP .B env Environment variables to set when invoking Bower. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bower.prune /path/to/project .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bower.uninstall(pkg, dir, runas=None, env=None) Uninstall a Bower package. .INDENT 7.0 .TP .B pkg A package name in any format accepted by Bower .TP .B dir The target directory from which to uninstall the package .TP .B runas The user to run Bower with .TP .B env Environment variables to set when invoking Bower. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bower.uninstall underscore /path/to/project .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.bridge .sp Module for gathering and managing bridging information .INDENT 0.0 .TP .B salt.modules.bridge.add(br=None) Creates a bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.add br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.addif(br=None, iface=None) Adds an interface to a bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.addif br0 eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.delete(br=None) Deletes a bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.delete br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.delif(br=None, iface=None) Removes an interface from a bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.delif br0 eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.find_interfaces(*args) Returns the bridge to which the interfaces are bond to .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.find_interfaces eth0 [eth1...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.interfaces(br=None) Returns interfaces attached to a bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.interfaces br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.list_() Returns the machine\(aqs bridges list .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.show(br=None) Returns bridges interfaces along with enslaved physical interfaces. If no interface is given, all bridges are shown, else only the specified bridge values are returned. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.show salt \(aq*\(aq bridge.show br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.stp(br=None, state=\(aqdisable\(aq, iface=None) Sets Spanning Tree Protocol state for a bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.stp br0 enable salt \(aq*\(aq bridge.stp br0 disable .ft P .fi .UNINDENT .UNINDENT .sp For BSD\-like operating systems, it is required to add the interface on which to enable the STP. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.stp bridge0 enable fxp0 salt \(aq*\(aq bridge.stp bridge0 disable fxp0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.bsd_shadow .sp Manage the password database on BSD systems .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage passwords on a minion, and it is using a different module (or gives an error similar to \fI\(aqshadow.info\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bsd_shadow.default_hash() Returns the default hash used for unset passwords .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.default_hash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bsd_shadow.del_password(name) New in version 2015.8.2. .sp Delete the password from name user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.del_password username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bsd_shadow.gen_password(password, crypt_salt=None, algorithm=\(aqsha512\(aq) Generate hashed password .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When called this function is called directly via remote\-execution, the password argument may be displayed in the system\(aqs process list. This may be a security risk on certain systems. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B password Plaintext password to be hashed. .TP .B crypt_salt Crpytographic salt. If not given, a random 8\-character salt will be generated. .TP .B algorithm The following hash algorithms are supported: .INDENT 7.0 .IP \(bu 2 md5 .IP \(bu 2 blowfish (not in mainline glibc, only available in distros that add it) .IP \(bu 2 sha256 .IP \(bu 2 sha512 (default) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.gen_password \(aqI_am_password\(aq salt \(aq*\(aq shadow.gen_password \(aqI_am_password\(aq crypt_salt=\(aqI_am_salt\(aq algorithm=sha256 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bsd_shadow.info(name) Return information for the specified user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.info someuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bsd_shadow.set_change(name, change) Sets the time at which the password expires (in seconds since the UNIX epoch). See \fBman 8 usermod\fP on NetBSD and OpenBSD or \fBman 8 pw\fP on FreeBSD. .sp A value of \fB0\fP sets the password to never expire. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_change username 1419980400 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bsd_shadow.set_expire(name, expire) Sets the time at which the account expires (in seconds since the UNIX epoch). See \fBman 8 usermod\fP on NetBSD and OpenBSD or \fBman 8 pw\fP on FreeBSD. .sp A value of \fB0\fP sets the account to never expire. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_expire username 1419980400 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bsd_shadow.set_password(name, password) Set the password for a named user. The password must be a properly defined hash. A password hash can be generated with \fI\%gen_password()\fP\&. .sp It is important to make sure that a supported cipher is used. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_password someuser \(aq$1$UYCIxa628.9qXjpQCjM4a..\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.btrfs .sp Module for managing BTRFS file systems. .INDENT 0.0 .TP .B salt.modules.btrfs.add(mountpoint, *devices, **kwargs) Add a devices to a BTRFS filesystem. .sp General options: .INDENT 7.0 .IP \(bu 2 \fBnodiscard\fP: Do not perform whole device TRIM .IP \(bu 2 \fBforce\fP: Force overwrite existing filesystem on the disk .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.add /mountpoint /dev/sda1 /dev/sda2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.convert(device, permanent=False, keeplf=False) Convert ext2/3/4 to BTRFS. Device should be mounted. .sp Filesystem can be converted temporarily so the further processing and rollback is possible, or permanently, where previous extended filesystem image gets deleted. Please note, permanent conversion takes a while as BTRFS filesystem needs to be properly rebalanced afterwards. .sp General options: .INDENT 7.0 .IP \(bu 2 \fBpermanent\fP: Specify if the migration should be permanent (false by default) .IP \(bu 2 .INDENT 2.0 .TP \fBkeeplf\fP: Keep \fBlost+found\fP of the partition (removed by default, but still in the image, if not permanent migration) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.convert /dev/sda1 salt \(aq*\(aq btrfs.convert /dev/sda1 permanent=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.defragment(path) Defragment mounted BTRFS filesystem. In order to defragment a filesystem, device should be properly mounted and writable. .sp If passed a device name, then defragmented whole filesystem, mounted on in. If passed a moun tpoint of the filesystem, then only this mount point is defragmented. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.defragment /dev/sda1 salt \(aq*\(aq btrfs.defragment /path/on/filesystem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.delete(mountpoint, *devices, **kwargs) Remove devices from a BTRFS filesystem. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.delete /mountpoint /dev/sda1 /dev/sda2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.devices() Get known BTRFS formatted devices on the system. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.devices .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.features() List currently available BTRFS features. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.mkfs_features .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.info(device) Get BTRFS filesystem information. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.info /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.mkfs(*devices, **kwargs) Create a file system on the specified device. By default wipes out with force. .sp General options: .INDENT 7.0 .IP \(bu 2 \fBallocsize\fP: Specify the BTRFS offset from the start of the device. .IP \(bu 2 \fBbytecount\fP: Specify the size of the resultant filesystem. .IP \(bu 2 \fBnodesize\fP: Node size. .IP \(bu 2 \fBleafsize\fP: Specify the nodesize, the tree block size in which btrfs stores data. .IP \(bu 2 \fBnoforce\fP: Prevent force overwrite when an existing filesystem is detected on the device. .IP \(bu 2 \fBsectorsize\fP: Specify the sectorsize, the minimum data block allocation unit. .IP \(bu 2 \fBnodiscard\fP: Do not perform whole device TRIM operation by default. .IP \(bu 2 \fBuuid\fP: Pass UUID or pass True to generate one. .UNINDENT .sp Options: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP \fBdto\fP: (raid0|raid1|raid5|raid6|raid10|single|dup) Specify how the data must be spanned across the devices specified. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP \fBmto\fP: (raid0|raid1|raid5|raid6|raid10|single|dup) Specify how metadata must be spanned across the devices specified. .UNINDENT .IP \(bu 2 \fBfts\fP: Features (call \fBsalt <host> btrfs.features\fP for full list of available features) .UNINDENT .sp See the \fBmkfs.btrfs(8)\fP manpage for a more complete description of corresponding options description. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.mkfs /dev/sda1 salt \(aq*\(aq btrfs.mkfs /dev/sda1 noforce=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.properties(obj, type=None, set=None) List properties for given btrfs object. The object can be path of BTRFS device, mount point, or any directories/files inside the BTRFS filesystem. .sp General options: .INDENT 7.0 .IP \(bu 2 \fBtype\fP: Possible types are s[ubvol], f[ilesystem], i[node] and d[evice]. .IP \(bu 2 \fBforce\fP: Force overwrite existing filesystem on the disk .IP \(bu 2 \fBset\fP: <key=value,key1=value1...> Options for a filesystem properties. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.properties /mountpoint salt \(aq*\(aq btrfs.properties /dev/sda1 type=subvol set=\(aqro=false,label=\(dqMy Storage\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.resize(mountpoint, size) Resize filesystem. .sp General options: .INDENT 7.0 .IP \(bu 2 \fBmountpoint\fP: Specify the BTRFS mountpoint to resize. .IP \(bu 2 \fBsize\fP: ([+/\-]<newsize>[kKmMgGtTpPeE]|max) Specify the new size of the target. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.resize /mountpoint size=+1g salt \(aq*\(aq btrfs.resize /dev/sda1 size=max .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.subvolume_create(name, dest=None, qgroupids=None) Create subvolume \fIname\fP in \fIdest\fP\&. .sp Return True if the subvolume is created, False is the subvolume is already there. .INDENT 7.0 .TP .B name Name of the new subvolume .TP .B dest If not given, the subvolume will be created in the current directory, if given will be in /dest/name .TP .B qgroupids Add the newly created subcolume to a qgroup. This parameter is a list .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.subvolume_create var salt \(aq*\(aq btrfs.subvolume_create var dest=/mnt salt \(aq*\(aq btrfs.subvolume_create var qgroupids=\(aq[200]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.subvolume_delete(name=None, names=None, commit=None) Delete the subvolume(s) from the filesystem .sp The user can remove one single subvolume (name) or multiple of then at the same time (names). One of the two parameters needs to specified. .sp Please, refer to the documentation to understand the implication on the transactions, and when the subvolume is really deleted. .sp Return True if the subvolume is deleted, False is the subvolume was already missing. .INDENT 7.0 .TP .B name Name of the subvolume to remove .TP .B names List of names of subvolumes to remove .TP .B commit .INDENT 7.0 .IP \(bu 2 \(aqafter\(aq: Wait for transaction commit at the end .IP \(bu 2 \(aqeach\(aq: Wait for transaction commit after each delete .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.subvolume_delete /var/volumes/tmp salt \(aq*\(aq btrfs.subvolume_delete /var/volumes/tmp commit=after .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.subvolume_exists(path) Check if a subvolume is present in the filesystem. .INDENT 7.0 .TP .B path Mount point for the subvolume (full path) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.subvolume_exists /mnt/var .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.subvolume_find_new(name, last_gen) List the recently modified files in a subvolume .INDENT 7.0 .TP .B name Name of the subvolume .TP .B last_gen Last transid marker from where to compare .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.subvolume_find_new /var/volumes/tmp 1024 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.subvolume_get_default(path) Get the default subvolume of the filesystem path .INDENT 7.0 .TP .B path Mount point for the subvolume .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.subvolume_get_default /var/volumes/tmp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.subvolume_list(path, parent_id=False, absolute=False, ogeneration=False, generation=False, subvolumes=False, uuid=False, parent_uuid=False, sent_subvolume_uuid=False, snapshots=False, readonly=False, deleted=False, generation_cmp=None, ogeneration_cmp=None, sort=None) List the subvolumes present in the filesystem. .INDENT 7.0 .TP .B path Mount point for the subvolume .TP .B parent_id Print parent ID .TP .B absolute Print all the subvolumes in the filesystem and distinguish between absolute and relative path with respect to the given <path> .TP .B ogeneration Print the ogeneration of the subvolume .TP .B generation Print the generation of the subvolume .TP .B subvolumes Print only subvolumes below specified <path> .TP .B uuid Print the UUID of the subvolume .TP .B parent_uuid Print the parent uuid of subvolumes (and snapshots) .TP .B sent_subvolume_uuid Print the UUID of the sent subvolume, where the subvolume is the result of a receive operation .TP .B snapshots Only snapshot subvolumes in the filesystem will be listed .TP .B readonly Only readonly subvolumes in the filesystem will be listed .TP .B deleted Only deleted subvolumens that are ye not cleaned .TP .B generation_cmp List subvolumes in the filesystem that its generation is >=, <= or = value. \(aq+\(aq means >= value, \(aq\-\(aq means <= value, If there is neither \(aq+\(aq nor \(aq\-\(aq, it means = value .TP .B ogeneration_cmp List subvolumes in the filesystem that its ogeneration is >=, <= or = value .TP .B sort List subvolumes in order by specified items. Possible values: * rootid * gen * ogen * path You can add \(aq+\(aq or \(aq\-\(aq in front of each items, \(aq+\(aq means ascending, \(aq\-\(aq means descending. The default is ascending. You can combite it in a list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.subvolume_list /var/volumes/tmp salt \(aq*\(aq btrfs.subvolume_list /var/volumes/tmp path=True salt \(aq*\(aq btrfs.subvolume_list /var/volumes/tmp sort=\(aq[\-rootid]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.subvolume_set_default(subvolid, path) Set the subvolume as default .INDENT 7.0 .TP .B subvolid ID of the new default subvolume .TP .B path Mount point for the filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.subvolume_set_default 257 /var/volumes/tmp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.subvolume_show(path) Show information of a given subvolume .INDENT 7.0 .TP .B path Mount point for the filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.subvolume_show /var/volumes/tmp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.subvolume_snapshot(source, dest=None, name=None, read_only=False) Create a snapshot of a source subvolume .INDENT 7.0 .TP .B source Source subvolume from where to create the snapshot .TP .B dest If only dest is given, the subvolume will be named as the basename of the source .TP .B name Name of the snapshot .TP .B read_only Create a read only snapshot .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.subvolume_snapshot /var/volumes/tmp dest=/.snapshots salt \(aq*\(aq btrfs.subvolume_snapshot /var/volumes/tmp name=backup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.subvolume_sync(path, subvolids=None, sleep=None) Wait until given subvolume are completely removed from the filesystem after deletion. .INDENT 7.0 .TP .B path Mount point for the filesystem .TP .B subvolids List of IDs of subvolumes to wait for .TP .B sleep Sleep N seconds betwenn checks (default: 1) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.subvolume_sync /var/volumes/tmp salt \(aq*\(aq btrfs.subvolume_sync /var/volumes/tmp subvolids=\(aq[257]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.usage(path) Show in which disk the chunks are allocated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.usage /your/mountpoint .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.btrfs.version() Return BTRFS version. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq btrfs.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.cabal .SS Manage and query Cabal packages .sp New in version 2015.8.0. .INDENT 0.0 .TP .B salt.modules.cabal.install(pkg=None, pkgs=None, user=None, install_global=False, env=None) Install a cabal package. .INDENT 7.0 .TP .B pkg A package name in format accepted by cabal\-install. See: \fI\%https://wiki.haskell.org/Cabal\-Install\fP .TP .B pkgs A list of packages names in same format as \fBpkg\fP .TP .B user The user to run cabal install with .TP .B install_global Install package globally instead of locally .TP .B env Environment variables to set when invoking cabal. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cabal.install shellcheck salt \(aq*\(aq cabal.install shellcheck\-0.3.5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cabal.list_(pkg=None, user=None, installed=False, env=None) List packages matching a search string. .INDENT 7.0 .TP .B pkg Search string for matching package names .TP .B user The user to run cabal list with .TP .B installed If True, only return installed packages. .TP .B env Environment variables to set when invoking cabal. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cabal.list salt \(aq*\(aq cabal.list ShellCheck .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cabal.uninstall(pkg, user=None, env=None) Uninstall a cabal package. .INDENT 7.0 .TP .B pkg The package to uninstall .TP .B user The user to run ghc\-pkg unregister with .TP .B env Environment variables to set when invoking cabal. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cabal.uninstall ShellCheck .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cabal.update(user=None, env=None) Updates list of known packages. .INDENT 7.0 .TP .B user The user to run cabal update with .TP .B env Environment variables to set when invoking cabal. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cabal.update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.capirca_acl .SS Capirca ACL .sp Generate ACL (firewall) configuration for network devices. .sp New in version 2017.7.0. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> & Robert Ankeny <\fI\%robankeny@google.com\fP> .TP .B maturity new .TP .B depends capirca .TP .B platform unix .UNINDENT .SS Dependencies .sp The firewall configuration is generated by \fI\%Capirca\fP\&. .sp To install Capirca, execute: \fBpip install capirca\fP\&. .INDENT 0.0 .TP .B salt.modules.capirca_acl.get_filter_config(platform, filter_name, filter_options=None, terms=None, prepend=True, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None, merge_pillar=True, only_lower_merge=False, revision_id=None, revision_no=None, revision_date=True, revision_date_format=\(aq%Y/%m/%d\(aq) Return the configuration of a policy filter. .INDENT 7.0 .TP .B platform The name of the Capirca platform. .TP .B filter_name The name of the policy filter. .TP .B filter_options Additional filter options. These options are platform\-specific. See the complete list of \fI\%options\fP\&. .TP .B terms List of terms for this policy filter. If not specified or empty, will try to load the configuration from the pillar, unless \fBmerge_pillar\fP is set as \fBFalse\fP\&. .TP .B prepend: \fBTrue\fP When \fBmerge_pillar\fP is set as \fBTrue\fP, the final list of terms generated by merging the terms from \fBterms\fP with those defined in the pillar (if any): new terms are prepended at the beginning, while existing ones will preserve the position. To add the new terms at the end of the list, set this argument to \fBFalse\fP\&. .TP .B pillar_key: \fBacl\fP The key in the pillar containing the default attributes values. Default: \fBacl\fP\&. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .TP .B merge_pillar: \fBTrue\fP Merge the CLI variables with the pillar. Default: \fBTrue\fP\&. .TP .B only_lower_merge: \fBFalse\fP Specify if it should merge only the terms fields. Otherwise it will try to merge also filters fields. Default: \fBFalse\fP\&. .TP .B revision_id Add a comment in the filter config having the description for the changes applied. .TP .B revision_no The revision count. .TP .B revision_date: \fBTrue\fP Boolean flag: display the date when the filter configuration was generated. Default: \fBTrue\fP\&. .TP .B revision_date_format: \fB%Y/%m/%d\fP The date format to be used when generating the perforce data. Default: \fB%Y/%m/%d\fP (<year>/<month>/<day>). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq capirca.get_filter_config ciscoxr my\-filter pillar_key=netacl .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ! $Id:$ ! $Date:$ ! $Revision:$ no ipv4 access\-list my\-filter ipv4 access\-list my\-filter remark $Id:$ remark my\-term deny ipv4 any eq 1234 any deny ipv4 any eq 1235 any remark my\-other\-term permit tcp any range 5678 5680 any exit .ft P .fi .UNINDENT .UNINDENT .sp The filter configuration has been loaded from the pillar, having the following structure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C netacl: \- my\-filter: terms: \- my\-term: source_port: [1234, 1235] action: reject \- my\-other\-term: source_port: \- [5678, 5680] protocol: tcp action: accept .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.capirca_acl.get_filter_pillar(filter_name, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None) Helper that can be used inside a state SLS, in order to get the filter configuration given its name. .INDENT 7.0 .TP .B filter_name The name of the filter. .TP .B pillar_key The root key of the whole policy config. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.capirca_acl.get_policy_config(platform, filters=None, prepend=True, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None, merge_pillar=True, only_lower_merge=False, revision_id=None, revision_no=None, revision_date=True, revision_date_format=\(aq%Y/%m/%d\(aq) Return the configuration of the whole policy. .INDENT 7.0 .TP .B platform The name of the Capirca platform. .TP .B filters List of filters for this policy. If not specified or empty, will try to load the configuration from the pillar, unless \fBmerge_pillar\fP is set as \fBFalse\fP\&. .TP .B prepend: \fBTrue\fP When \fBmerge_pillar\fP is set as \fBTrue\fP, the final list of filters generated by merging the filters from \fBfilters\fP with those defined in the pillar (if any): new filters are prepended at the beginning, while existing ones will preserve the position. To add the new filters at the end of the list, set this argument to \fBFalse\fP\&. .TP .B pillar_key: \fBacl\fP The key in the pillar containing the default attributes values. Default: \fBacl\fP\&. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .TP .B merge_pillar: \fBTrue\fP Merge the CLI variables with the pillar. Default: \fBTrue\fP\&. .TP .B only_lower_merge: \fBFalse\fP Specify if it should merge only the filters and terms fields. Otherwise it will try to merge everything at the policy level. Default: \fBFalse\fP\&. .TP .B revision_id Add a comment in the policy config having the description for the changes applied. .TP .B revision_no The revision count. .TP .B revision_date: \fBTrue\fP Boolean flag: display the date when the policy configuration was generated. Default: \fBTrue\fP\&. .TP .B revision_date_format: \fB%Y/%m/%d\fP The date format to be used when generating the perforce data. Default: \fB%Y/%m/%d\fP (<year>/<month>/<day>). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq capirca.get_policy_config juniper pillar_key=netacl .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C firewall { family inet { replace: /* ** $Id:$ ** $Date:$ ** $Revision:$ ** */ filter my\-filter { term my\-term { from { source\-port [ 1234 1235 ]; } then { reject; } } term my\-other\-term { from { protocol tcp; source\-port 5678\-5680; } then accept; } } } } firewall { family inet { replace: /* ** $Id:$ ** $Date:$ ** $Revision:$ ** */ filter my\-other\-filter { interface\-specific; term dummy\-term { from { protocol [ tcp udp ]; } then { reject; } } } } } .ft P .fi .UNINDENT .UNINDENT .sp The policy configuration has been loaded from the pillar, having the following structure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C netacl: \- my\-filter: options: \- not\-interface\-specific terms: \- my\-term: source_port: [1234, 1235] action: reject \- my\-other\-term: source_port: \- [5678, 5680] protocol: tcp action: accept \- my\-other\-filter: terms: \- dummy\-term: protocol: \- tcp \- udp action: reject .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.capirca_acl.get_term_config(platform, filter_name, term_name, filter_options=None, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None, merge_pillar=True, revision_id=None, revision_no=None, revision_date=True, revision_date_format=\(aq%Y/%m/%d\(aq, source_service=None, destination_service=None, **term_fields) Return the configuration of a single policy term. .INDENT 7.0 .TP .B platform The name of the Capirca platform. .TP .B filter_name The name of the policy filter. .TP .B term_name The name of the term. .TP .B filter_options Additional filter options. These options are platform\-specific. E.g.: \fBinet6\fP, \fBbridge\fP, \fBobject\-group\fP, See the complete list of \fI\%options\fP\&. .TP .B pillar_key: \fBacl\fP The key in the pillar containing the default attributes values. Default: \fBacl\fP\&. If the pillar contains the following structure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C firewall: \- my\-filter: terms: \- my\-term: source_port: 1234 source_address: \- 1.2.3.4/32 \- 5.6.7.8/32 .ft P .fi .UNINDENT .UNINDENT .sp The \fBpillar_key\fP field would be specified as \fBfirewall\fP\&. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .TP .B merge_pillar: \fBTrue\fP Merge the CLI variables with the pillar. Default: \fBTrue\fP\&. .TP .B revision_id Add a comment in the term config having the description for the changes applied. .TP .B revision_no The revision count. .TP .B revision_date: \fBTrue\fP Boolean flag: display the date when the term configuration was generated. Default: \fBTrue\fP\&. .TP .B revision_date_format: \fB%Y/%m/%d\fP The date format to be used when generating the perforce data. Default: \fB%Y/%m/%d\fP (<year>/<month>/<day>). .TP .B source_service A special service to choose from. This is a helper so the user is able to select a source just using the name, instead of specifying a source_port and protocol. .sp As this module is available on Unix platforms only, it reads the \fI\%IANA\fP port assignment from \fB/etc/services\fP\&. .sp If the user requires additional shortcuts to be referenced, they can add entries under \fB/etc/services\fP, which can be managed using the \fI\%file state\fP\&. .TP .B destination_service A special service to choose from. This is a helper so the user is able to select a source just using the name, instead of specifying a destination_port and protocol. Allows the same options as \fBsource_service\fP\&. .TP .B term_fields Term attributes. To see what fields are supported, please consult the list of supported \fI\%keywords\fP\&. Some platforms have few other \fI\%optional\fP keywords. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The following fields are accepted: .INDENT 0.0 .IP \(bu 2 action .IP \(bu 2 address .IP \(bu 2 address_exclude .IP \(bu 2 comment .IP \(bu 2 counter .IP \(bu 2 expiration .IP \(bu 2 destination_address .IP \(bu 2 destination_address_exclude .IP \(bu 2 destination_port .IP \(bu 2 destination_prefix .IP \(bu 2 forwarding_class .IP \(bu 2 forwarding_class_except .IP \(bu 2 logging .IP \(bu 2 log_name .IP \(bu 2 loss_priority .IP \(bu 2 option .IP \(bu 2 policer .IP \(bu 2 port .IP \(bu 2 precedence .IP \(bu 2 principals .IP \(bu 2 protocol .IP \(bu 2 protocol_except .IP \(bu 2 qos .IP \(bu 2 pan_application .IP \(bu 2 routing_instance .IP \(bu 2 source_address .IP \(bu 2 source_address_exclude .IP \(bu 2 source_port .IP \(bu 2 source_prefix .IP \(bu 2 verbatim .IP \(bu 2 packet_length .IP \(bu 2 fragment_offset .IP \(bu 2 hop_limit .IP \(bu 2 icmp_type .IP \(bu 2 ether_type .IP \(bu 2 traffic_class_count .IP \(bu 2 traffic_type .IP \(bu 2 translated .IP \(bu 2 dscp_set .IP \(bu 2 dscp_match .IP \(bu 2 dscp_except .IP \(bu 2 next_ip .IP \(bu 2 flexible_match_range .IP \(bu 2 source_prefix_except .IP \(bu 2 destination_prefix_except .IP \(bu 2 vpn .IP \(bu 2 source_tag .IP \(bu 2 destination_tag .IP \(bu 2 source_interface .IP \(bu 2 destination_interface .IP \(bu 2 flattened .IP \(bu 2 flattened_addr .IP \(bu 2 flattened_saddr .IP \(bu 2 flattened_daddr .IP \(bu 2 priority .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The following fields can be also a single value and a list of values: .INDENT 0.0 .IP \(bu 2 action .IP \(bu 2 address .IP \(bu 2 address_exclude .IP \(bu 2 comment .IP \(bu 2 destination_address .IP \(bu 2 destination_address_exclude .IP \(bu 2 destination_port .IP \(bu 2 destination_prefix .IP \(bu 2 forwarding_class .IP \(bu 2 forwarding_class_except .IP \(bu 2 logging .IP \(bu 2 option .IP \(bu 2 port .IP \(bu 2 precedence .IP \(bu 2 principals .IP \(bu 2 protocol .IP \(bu 2 protocol_except .IP \(bu 2 pan_application .IP \(bu 2 source_address .IP \(bu 2 source_address_exclude .IP \(bu 2 source_port .IP \(bu 2 source_prefix .IP \(bu 2 verbatim .IP \(bu 2 icmp_type .IP \(bu 2 ether_type .IP \(bu 2 traffic_type .IP \(bu 2 dscp_match .IP \(bu 2 dscp_except .IP \(bu 2 flexible_match_range .IP \(bu 2 source_prefix_except .IP \(bu 2 destination_prefix_except .IP \(bu 2 source_tag .IP \(bu 2 destination_tag .IP \(bu 2 source_service .IP \(bu 2 destination_service .UNINDENT .sp Example: \fBdestination_address\fP can be either defined as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C destination_address: 172.17.17.1/24 .ft P .fi .UNINDENT .UNINDENT .sp or as a list of destination IP addresses: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C destination_address: \- 172.17.17.1/24 \- 172.17.19.1/24 .ft P .fi .UNINDENT .UNINDENT .sp or a list of services to be matched: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source_service: \- ntp \- snmp \- ldap \- bgpd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The port fields \fBsource_port\fP and \fBdestination_port\fP can be used as above to select either a single value, either a list of values, but also they can select port ranges. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source_port: \- [1000, 2000] \- [3000, 4000] .ft P .fi .UNINDENT .UNINDENT .sp With the configuration above, the user is able to select the 1000\-2000 and 3000\-4000 source port ranges. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq capirca.get_term_config arista filter\-name term\-name source_address=1.2.3.4 destination_address=5.6.7.8 action=accept .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ! $Date: 2017/03/22 $ no ip access\-list filter\-name ip access\-list filter\-name remark term\-name permit ip host 1.2.3.4 host 5.6.7.8 exit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.capirca_acl.get_term_pillar(filter_name, term_name, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None) Helper that can be used inside a state SLS, in order to get the term configuration given its name, under a certain filter uniquely identified by its name. .INDENT 7.0 .TP .B filter_name The name of the filter. .TP .B term_name The name of the term. .TP .B pillar_key: \fBacl\fP The root key of the whole policy config. Default: \fBacl\fP\&. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .UNINDENT .UNINDENT .SS salt.modules.cassandra_cql .sp Cassandra Database Module .sp New in version 2015.5.0. .sp This module works with Cassandra v2 and v3 and hence generates queries based on the internal schema of said version. .INDENT 0.0 .TP .B depends DataStax Python Driver for Apache Cassandra \fI\%https://github.com/datastax/python\-driver\fP pip install cassandra\-driver .TP .B referenced by Salt\(aqs cassandra_cql returner .TP .B configuration The Cassandra cluster members and connection port can either be specified in the master or minion config, the minion\(aqs pillar or be passed to the module. .sp Example configuration in the config for a single node: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cassandra: cluster: 192.168.50.10 port: 9000 .ft P .fi .UNINDENT .UNINDENT .sp Example configuration in the config for a cluster: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cassandra: cluster: \- 192.168.50.10 \- 192.168.50.11 \- 192.168.50.12 port: 9000 username: cas_admin .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2016.11.0. .sp Added support for \fBssl_options\fP and \fBprotocol_version\fP\&. .sp Example configuration with \fI\%ssl options\fP: .sp If \fBssl_options\fP are present in cassandra config the cassandra_cql returner will use SSL. SSL isn\(aqt used if \fBssl_options\fP isn\(aqt specified. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cassandra: cluster: \- 192.168.50.10 \- 192.168.50.11 \- 192.168.50.12 port: 9000 username: cas_admin ssl_options: ca_certs: /etc/ssl/certs/ca\-bundle.trust.crt # SSL version should be one from the ssl module # This is an optional parameter ssl_version: PROTOCOL_TLSv1 .ft P .fi .UNINDENT .UNINDENT .sp Additionally you can also specify the \fBprotocol_version\fP to \fI\%use\fP\&. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cassandra: cluster: \- 192.168.50.10 \- 192.168.50.11 \- 192.168.50.12 port: 9000 username: cas_admin # defaults to 4, if not set protocol_version: 3 .ft P .fi .UNINDENT .UNINDENT .sp Also all configuration could be passed directly to module as arguments. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .sp salt minion1 cassandra_cql.info contact_points=delme\-nextgen\-01 port=9042 cql_user=cassandra cql_pass=cassandra protocol_version=4 .sp salt minion1 cassandra_cql.info ssl_options=\(aq{\(dqca_certs\(dq: /path/to/\-ca.crt}\(aq .sp We can also provide the load balancing policy as arguments .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .sp salt minion1 cassandra_cql.cql_query \(dqalter user cassandra with password \(aqcassandra2\(aq ;\(dq contact_points=scylladb cql_user=user1 cql_pass=password port=9142 protocol_version=4 ssl_options=\(aq{\(dqca_certs\(dq: path\-to\-client\-ca.crt}\(aq load_balancing_policy=DCAwareRoundRobinPolicy load_balancing_policy_args=\(aq{\(dqlocal_dc\(dq: \(dqdatacenter1\(dq}\(aq .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.cql_query(query, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None) Run a query on a Cassandra cluster and return a dictionary. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBquery\fP (\fI\%str\fP) \-\- The query to execute. .IP \(bu 2 \fBcontact_points\fP (\fI\%str\fP\fI | \fP\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The Cassandra cluster addresses, can either be a string or a list of IPs. .IP \(bu 2 \fBcql_user\fP (\fI\%str\fP) \-\- The Cassandra user if authentication is turned on. .IP \(bu 2 \fBcql_pass\fP (\fI\%str\fP) \-\- The Cassandra user password if authentication is turned on. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The Cassandra cluster port, defaults to None. .IP \(bu 2 \fBparams\fP (\fI\%str\fP) \-\- The parameters for the query, optional. .IP \(bu 2 \fBprotocol_version\fP (\fI\%int\fP) \-\- Cassandra protocol version to use. .IP \(bu 2 \fBload_balancing_policy\fP (\fI\%str\fP) \-\- cassandra.policy class name to use .IP \(bu 2 \fBload_balancing_policy_args\fP (\fI\%dict\fP) \-\- cassandra.policy constructor args .IP \(bu 2 \fBssl_options\fP (\fI\%dict\fP) \-\- Cassandra protocol version to use. .UNINDENT .TP .B Returns A dictionary from the return values of the query .TP .B Return type \fI\%list\fP[\fI\%dict\fP] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqcassandra\-server\(aq cassandra_cql.cql_query \(dqSELECT * FROM users_by_name WHERE first_name = \(aqjane\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.cql_query_with_prepare(query, statement_name, statement_arguments, asynchronous=False, callback_errors=None, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None, **kwargs) Run a query on a Cassandra cluster and return a dictionary. .sp This function should not be used asynchronously for SELECTs \-\- it will not return anything and we don\(aqt currently have a mechanism for handling a future that will return results. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBquery\fP (\fI\%str\fP) \-\- The query to execute. .IP \(bu 2 \fBstatement_name\fP (\fI\%str\fP) \-\- Name to assign the prepared statement in the __context__ dictionary .IP \(bu 2 \fBstatement_arguments\fP (\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- Bind parameters for the SQL statement .IP \(bu 2 \fBasynchronous\fP (\fI\%bool\fP) \-\- Run this query in asynchronous mode .IP \(bu 2 \fBasync\fP (\fI\%bool\fP) \-\- Run this query in asynchronous mode (an alias to \(aqasynchronous\(aq) NOTE: currently it overrides \(aqasynchronous\(aq and it will be dropped in version 3001! .IP \(bu 2 \fBcallback_errors\fP (\fIFunction callable\fP) \-\- Function to call after query runs if there is an error .IP \(bu 2 \fBcontact_points\fP (\fI\%str\fP\fI | \fP\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The Cassandra cluster addresses, can either be a string or a list of IPs. .IP \(bu 2 \fBcql_user\fP (\fI\%str\fP) \-\- The Cassandra user if authentication is turned on. .IP \(bu 2 \fBcql_pass\fP (\fI\%str\fP) \-\- The Cassandra user password if authentication is turned on. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The Cassandra cluster port, defaults to None. .IP \(bu 2 \fBparams\fP (\fI\%str\fP) \-\- The parameters for the query, optional. .IP \(bu 2 \fBprotocol_version\fP \-\- Cassandra protocol version to use. .IP \(bu 2 \fBload_balancing_policy\fP (\fI\%str\fP) \-\- cassandra.policy class name to use .IP \(bu 2 \fBload_balancing_policy_args\fP (\fI\%dict\fP) \-\- cassandra.policy constructor args .IP \(bu 2 \fBssl_options\fP (\fI\%dict\fP) \-\- Cassandra protocol version to use. .UNINDENT .TP .B Returns A dictionary from the return values of the query .TP .B Return type \fI\%list\fP[\fI\%dict\fP] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Insert data asynchronously salt this\-node cassandra_cql.cql_query_with_prepare \(dqname_insert\(dq \(dqINSERT INTO USERS (first_name, last_name) VALUES (?, ?)\(dq statement_arguments=[\(aqJohn\(aq,\(aqDoe\(aq], asynchronous=True # Select data, should not be asynchronous because there is not currently a facility to return data from a future salt this\-node cassandra_cql.cql_query_with_prepare \(dqname_select\(dq \(dqSELECT * FROM USERS WHERE first_name=?\(dq statement_arguments=[\(aqJohn\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.create_keyspace(keyspace, replication_strategy=\(aqSimpleStrategy\(aq, replication_factor=1, replication_datacenters=None, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None) Create a new keyspace in Cassandra. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkeyspace\fP (\fI\%str\fP) \-\- The keyspace name .IP \(bu 2 \fBreplication_strategy\fP (\fI\%str\fP) \-\- either \fISimpleStrategy\fP or \fINetworkTopologyStrategy\fP .IP \(bu 2 \fBreplication_factor\fP (\fI\%int\fP) \-\- number of replicas of data on multiple nodes. not used if using NetworkTopologyStrategy .IP \(bu 2 \fBreplication_datacenters\fP (\fI\%str\fP\fI | \fP\fI\%dict\fP\fI[\fP\fI\%str\fP\fI, \fP\fI\%int\fP\fI]\fP) \-\- string or dict of datacenter names to replication factors, required if using NetworkTopologyStrategy (will be a dict if coming from state file). .IP \(bu 2 \fBcontact_points\fP (\fI\%str\fP\fI | \fP\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The Cassandra cluster addresses, can either be a string or a list of IPs. .IP \(bu 2 \fBcql_user\fP (\fI\%str\fP) \-\- The Cassandra user if authentication is turned on. .IP \(bu 2 \fBcql_pass\fP (\fI\%str\fP) \-\- The Cassandra user password if authentication is turned on. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The Cassandra cluster port, defaults to None. .IP \(bu 2 \fBprotocol_version\fP (\fI\%int\fP) \-\- Cassandra protocol version to use. .IP \(bu 2 \fBload_balancing_policy\fP (\fI\%str\fP) \-\- cassandra.policy class name to use .IP \(bu 2 \fBload_balancing_policy_args\fP (\fI\%dict\fP) \-\- cassandra.policy constructor args .IP \(bu 2 \fBssl_options\fP (\fI\%dict\fP) \-\- Cassandra protocol version to use. .UNINDENT .TP .B Returns The info for the keyspace or False if it does not exist. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # CLI Example: salt \(aqminion1\(aq cassandra_cql.create_keyspace keyspace=newkeyspace salt \(aqminion1\(aq cassandra_cql.create_keyspace keyspace=newkeyspace replication_strategy=NetworkTopologyStrategy replication_datacenters=\(aq{\(dqdatacenter_1\(dq: 3, \(dqdatacenter_2\(dq: 2}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.create_user(username, password, superuser=False, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None) Create a new cassandra user with credentials and superuser status. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- The name of the new user. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The password of the new user. .IP \(bu 2 \fBsuperuser\fP (\fI\%bool\fP) \-\- Is the new user going to be a superuser? default: False .IP \(bu 2 \fBcontact_points\fP (\fI\%str\fP\fI | \fP\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The Cassandra cluster addresses, can either be a string or a list of IPs. .IP \(bu 2 \fBcql_user\fP (\fI\%str\fP) \-\- The Cassandra user if authentication is turned on. .IP \(bu 2 \fBcql_pass\fP (\fI\%str\fP) \-\- The Cassandra user password if authentication is turned on. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The Cassandra cluster port, defaults to None. .IP \(bu 2 \fBprotocol_version\fP (\fI\%int\fP) \-\- Cassandra protocol version to use. .IP \(bu 2 \fBload_balancing_policy\fP (\fI\%str\fP) \-\- cassandra.policy class name to use .IP \(bu 2 \fBload_balancing_policy_args\fP (\fI\%dict\fP) \-\- cassandra.policy constructor args .IP \(bu 2 \fBssl_options\fP (\fI\%dict\fP) \-\- Cassandra protocol version to use. .UNINDENT .TP .B Returns .TP .B Return type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq cassandra_cql.create_user username=joe password=secret salt \(aqminion1\(aq cassandra_cql.create_user username=joe password=secret superuser=True salt \(aqminion1\(aq cassandra_cql.create_user username=joe password=secret superuser=True contact_points=minion1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.drop_keyspace(keyspace, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None) Drop a keyspace if it exists in a Cassandra cluster. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkeyspace\fP (\fI\%str\fP) \-\- The keyspace to drop. .IP \(bu 2 \fBcontact_points\fP (\fI\%str\fP\fI | \fP\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The Cassandra cluster addresses, can either be a string or a list of IPs. .IP \(bu 2 \fBcql_user\fP (\fI\%str\fP) \-\- The Cassandra user if authentication is turned on. .IP \(bu 2 \fBcql_pass\fP (\fI\%str\fP) \-\- The Cassandra user password if authentication is turned on. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The Cassandra cluster port, defaults to None. .IP \(bu 2 \fBprotocol_version\fP (\fI\%int\fP) \-\- Cassandra protocol version to use. .IP \(bu 2 \fBload_balancing_policy\fP (\fI\%str\fP) \-\- cassandra.policy class name to use .IP \(bu 2 \fBload_balancing_policy_args\fP (\fI\%dict\fP) \-\- cassandra.policy constructor args .IP \(bu 2 \fBssl_options\fP (\fI\%dict\fP) \-\- Cassandra protocol version to use. .UNINDENT .TP .B Returns The info for the keyspace or False if it does not exist. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq cassandra_cql.drop_keyspace keyspace=test salt \(aqminion1\(aq cassandra_cql.drop_keyspace keyspace=test contact_points=minion1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.grant_permission(username, resource=None, resource_type=\(aqkeyspace\(aq, permission=None, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None) Grant permissions to a user. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- The name of the user to grant permissions to. .IP \(bu 2 \fBresource\fP (\fI\%str\fP) \-\- The resource (keyspace or table), if None, permissions for all resources are granted. .IP \(bu 2 \fBresource_type\fP (\fI\%str\fP) \-\- The resource_type (keyspace or table), defaults to \(aqkeyspace\(aq. .IP \(bu 2 \fBpermission\fP (\fI\%str\fP) \-\- A permission name (e.g. select), if None, all permissions are granted. .IP \(bu 2 \fBcontact_points\fP (\fI\%str\fP\fI | \fP\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The Cassandra cluster addresses, can either be a string or a list of IPs. .IP \(bu 2 \fBcql_user\fP (\fI\%str\fP) \-\- The Cassandra user if authentication is turned on. .IP \(bu 2 \fBcql_pass\fP (\fI\%str\fP) \-\- The Cassandra user password if authentication is turned on. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The Cassandra cluster port, defaults to None. .IP \(bu 2 \fBprotocol_version\fP (\fI\%int\fP) \-\- Cassandra protocol version to use. .IP \(bu 2 \fBload_balancing_policy\fP (\fI\%str\fP) \-\- cassandra.policy class name to use .IP \(bu 2 \fBload_balancing_policy_args\fP (\fI\%dict\fP) \-\- cassandra.policy constructor args .IP \(bu 2 \fBssl_options\fP (\fI\%dict\fP) \-\- Cassandra protocol version to use. .UNINDENT .TP .B Returns .TP .B Return type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq cassandra_cql.grant_permission salt \(aqminion1\(aq cassandra_cql.grant_permission username=joe resource=test_keyspace permission=select salt \(aqminion1\(aq cassandra_cql.grant_permission username=joe resource=test_table resource_type=table permission=select contact_points=minion1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.info(contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None) Show the Cassandra information for this cluster. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontact_points\fP (\fI\%str\fP\fI | \fP\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The Cassandra cluster addresses, can either be a string or a list of IPs. .IP \(bu 2 \fBcql_user\fP (\fI\%str\fP) \-\- The Cassandra user if authentication is turned on. .IP \(bu 2 \fBcql_pass\fP (\fI\%str\fP) \-\- The Cassandra user password if authentication is turned on. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The Cassandra cluster port, defaults to None. .IP \(bu 2 \fBprotocol_version\fP (\fI\%int\fP) \-\- Cassandra protocol version to use. .IP \(bu 2 \fBload_balancing_policy\fP (\fI\%str\fP) \-\- cassandra.policy class name to use .IP \(bu 2 \fBload_balancing_policy_args\fP (\fI\%dict\fP) \-\- cassandra.policy constructor args .IP \(bu 2 \fBssl_options\fP (\fI\%dict\fP) \-\- Cassandra protocol version to use. .UNINDENT .TP .B Returns The information for this Cassandra cluster. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq cassandra_cql.info salt \(aqminion1\(aq cassandra_cql.info contact_points=minion1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.keyspace_exists(keyspace, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None) Check if a keyspace exists in a Cassandra cluster. .sp :param keyspace The keyspace name to check for. :type keyspace: str :param contact_points: The Cassandra cluster addresses, can either be a string or a list of IPs. :type contact_points: str | list[str] :param cql_user: The Cassandra user if authentication is turned on. :type cql_user: str :param cql_pass: The Cassandra user password if authentication is turned on. :type cql_pass: str :param port: The Cassandra cluster port, defaults to None. :type port: int :param protocol_version: Cassandra protocol version to use. :type protocol_version: int :param load_balancing_policy: cassandra.policy class name to use :type load_balancing_policy: str :param load_balancing_policy_args: cassandra.policy constructor args :type load_balancing_policy_args: dict :param ssl_options: Cassandra protocol version to use. :type ssl_options: dict :return: The info for the keyspace or False if it does not exist. :rtype: dict .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq cassandra_cql.keyspace_exists keyspace=system .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.list_column_families(keyspace=None, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None) List column families in a Cassandra cluster for all keyspaces or just the provided one. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkeyspace\fP (\fI\%str\fP) \-\- The keyspace to provide the column families for, optional. .IP \(bu 2 \fBcontact_points\fP (\fI\%str\fP\fI | \fP\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The Cassandra cluster addresses, can either be a string or a list of IPs. .IP \(bu 2 \fBcql_user\fP (\fI\%str\fP) \-\- The Cassandra user if authentication is turned on. .IP \(bu 2 \fBcql_pass\fP (\fI\%str\fP) \-\- The Cassandra user password if authentication is turned on. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The Cassandra cluster port, defaults to None. .IP \(bu 2 \fBprotocol_version\fP (\fI\%int\fP) \-\- Cassandra protocol version to use. .IP \(bu 2 \fBload_balancing_policy\fP (\fI\%str\fP) \-\- cassandra.policy class name to use .IP \(bu 2 \fBload_balancing_policy_args\fP (\fI\%dict\fP) \-\- cassandra.policy constructor args .IP \(bu 2 \fBssl_options\fP (\fI\%dict\fP) \-\- Cassandra protocol version to use. .UNINDENT .TP .B Returns The column families in this Cassandra cluster. .TP .B Return type \fI\%list\fP[\fI\%dict\fP] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq cassandra_cql.list_column_families salt \(aqminion1\(aq cassandra_cql.list_column_families contact_points=minion1 salt \(aqminion1\(aq cassandra_cql.list_column_families keyspace=system .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.list_keyspaces(contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None) List keyspaces in a Cassandra cluster. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontact_points\fP (\fI\%str\fP\fI | \fP\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The Cassandra cluster addresses, can either be a string or a list of IPs. .IP \(bu 2 \fBcql_user\fP (\fI\%str\fP) \-\- The Cassandra user if authentication is turned on. .IP \(bu 2 \fBcql_pass\fP (\fI\%str\fP) \-\- The Cassandra user password if authentication is turned on. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The Cassandra cluster port, defaults to None. .IP \(bu 2 \fBprotocol_version\fP (\fI\%int\fP) \-\- Cassandra protocol version to use. .IP \(bu 2 \fBload_balancing_policy\fP (\fI\%str\fP) \-\- cassandra.policy class name to use .IP \(bu 2 \fBload_balancing_policy_args\fP (\fI\%dict\fP) \-\- cassandra.policy constructor args .IP \(bu 2 \fBssl_options\fP (\fI\%dict\fP) \-\- Cassandra protocol version to use. .UNINDENT .TP .B Returns The keyspaces in this Cassandra cluster. .TP .B Return type \fI\%list\fP[\fI\%dict\fP] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq cassandra_cql.list_keyspaces salt \(aqminion1\(aq cassandra_cql.list_keyspaces contact_points=minion1 port=9000 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.list_permissions(username=None, resource=None, resource_type=\(aqkeyspace\(aq, permission=None, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None) List permissions. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- The name of the user to list permissions for. .IP \(bu 2 \fBresource\fP (\fI\%str\fP) \-\- The resource (keyspace or table), if None, permissions for all resources are listed. .IP \(bu 2 \fBresource_type\fP (\fI\%str\fP) \-\- The resource_type (keyspace or table), defaults to \(aqkeyspace\(aq. .IP \(bu 2 \fBpermission\fP (\fI\%str\fP) \-\- A permission name (e.g. select), if None, all permissions are listed. .IP \(bu 2 \fBcontact_points\fP (\fI\%str\fP\fI | \fP\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The Cassandra cluster addresses, can either be a string or a list of IPs. .IP \(bu 2 \fBcql_user\fP (\fI\%str\fP) \-\- The Cassandra user if authentication is turned on. .IP \(bu 2 \fBcql_pass\fP (\fI\%str\fP) \-\- The Cassandra user password if authentication is turned on. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The Cassandra cluster port, defaults to None. .IP \(bu 2 \fBprotocol_version\fP (\fI\%int\fP) \-\- Cassandra protocol version to use. .IP \(bu 2 \fBload_balancing_policy\fP (\fI\%str\fP) \-\- cassandra.policy class name to use .IP \(bu 2 \fBload_balancing_policy_args\fP (\fI\%dict\fP) \-\- cassandra.policy constructor args .IP \(bu 2 \fBssl_options\fP (\fI\%dict\fP) \-\- Cassandra protocol version to use. .UNINDENT .TP .B Returns Dictionary of permissions. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq cassandra_cql.list_permissions salt \(aqminion1\(aq cassandra_cql.list_permissions username=joe resource=test_keyspace permission=select salt \(aqminion1\(aq cassandra_cql.list_permissions username=joe resource=test_table resource_type=table permission=select contact_points=minion1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.list_users(contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None) List existing users in this Cassandra cluster. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontact_points\fP (\fI\%str\fP\fI | \fP\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The Cassandra cluster addresses, can either be a string or a list of IPs. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The Cassandra cluster port, defaults to None. .IP \(bu 2 \fBcql_user\fP (\fI\%str\fP) \-\- The Cassandra user if authentication is turned on. .IP \(bu 2 \fBcql_pass\fP (\fI\%str\fP) \-\- The Cassandra user password if authentication is turned on. .IP \(bu 2 \fBprotocol_version\fP (\fI\%int\fP) \-\- Cassandra protocol version to use. .IP \(bu 2 \fBload_balancing_policy\fP (\fI\%str\fP) \-\- cassandra.policy class name to use .IP \(bu 2 \fBload_balancing_policy_args\fP (\fI\%dict\fP) \-\- cassandra.policy constructor args .IP \(bu 2 \fBssl_options\fP (\fI\%dict\fP) \-\- Cassandra protocol version to use. .UNINDENT .TP .B Returns The list of existing users. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq cassandra_cql.list_users salt \(aqminion1\(aq cassandra_cql.list_users contact_points=minion1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra_cql.version(contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None) Show the Cassandra version. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontact_points\fP (\fI\%str\fP\fI | \fP\fI\%list\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The Cassandra cluster addresses, can either be a string or a list of IPs. .IP \(bu 2 \fBcql_user\fP (\fI\%str\fP) \-\- The Cassandra user if authentication is turned on. .IP \(bu 2 \fBcql_pass\fP (\fI\%str\fP) \-\- The Cassandra user password if authentication is turned on. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The Cassandra cluster port, defaults to None. .IP \(bu 2 \fBprotocol_version\fP (\fI\%int\fP) \-\- Cassandra protocol version to use. .IP \(bu 2 \fBload_balancing_policy\fP (\fI\%str\fP) \-\- cassandra.policy class name to use .IP \(bu 2 \fBload_balancing_policy_args\fP (\fI\%dict\fP) \-\- cassandra.policy constructor args .IP \(bu 2 \fBssl_options\fP (\fI\%dict\fP) \-\- Cassandra protocol version to use. .UNINDENT .TP .B Returns The version for this Cassandra cluster. .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq cassandra_cql.version salt \(aqminion1\(aq cassandra_cql.version contact_points=minion1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.celery .sp Support for scheduling celery tasks. The worker is independent of salt and thus can run in a different virtualenv or on a different python version, as long as broker, backend and serializer configurations match. Also note that celery and packages required by the celery broker, e.g. redis must be installed to load the salt celery execution module. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 A new app (and thus new connections) is created for each task execution .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.celery.run_task(task_name, args=None, kwargs=None, broker=None, backend=None, wait_for_result=False, timeout=None, propagate=True, interval=0.5, no_ack=True, raise_timeout=True, config=None) Execute celery tasks. For celery specific parameters see celery documentation. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq celery.run_task tasks.sleep args=[4] broker=redis://localhost \e backend=redis://localhost wait_for_result=true .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B task_name The task name, e.g. tasks.sleep .TP .B args Task arguments as a list .TP .B kwargs Task keyword arguments .TP .B broker Broker for celeryapp, see celery documentation .TP .B backend Result backend for celeryapp, see celery documentation .TP .B wait_for_result Wait until task result is read from result backend and return result, Default: False .TP .B timeout Timeout waiting for result from celery, see celery AsyncResult.get documentation .TP .B propagate Propagate exceptions from celery task, see celery AsyncResult.get documentation, Default: True .TP .B interval Interval to check for task result, see celery AsyncResult.get documentation, Default: 0.5 .TP .B no_ack see celery AsyncResult.get documentation. Default: True .TP .B raise_timeout Raise timeout exception if waiting for task result times out. Default: False .TP .B config Config dict for celery app, See celery documentation .UNINDENT .UNINDENT .SS salt.modules.ceph .sp Module to provide ceph control with salt. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 ceph_cfg Python module .UNINDENT .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.modules.ceph.ceph_version() Get the version of ceph installed .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.ceph_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.cluster_quorum(**kwargs) Get the cluster\(aqs quorum status .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.cluster_quorum \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.cluster_status(**kwargs) Get the cluster status, including health if in quorum .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.cluster_status \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.keyring_auth_add(**kwargs) Add keyring to authorized list .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.keyring_auth_add \e \(aqkeyring_type\(aq=\(aqadmin\(aq \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B keyring_type (required) One of \fBadmin\fP, \fBmon\fP, \fBosd\fP, \fBrgw\fP, \fBmds\fP .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.keyring_auth_del(**kwargs) Remove keyring from authorised list .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.keyring_osd_auth_del \e \(aqkeyring_type\(aq=\(aqadmin\(aq \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B keyring_type (required) One of \fBadmin\fP, \fBmon\fP, \fBosd\fP, \fBrgw\fP, \fBmds\fP .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.keyring_auth_list(**kwargs) List all cephx authorization keys .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.keyring_auth_list \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.keyring_create(**kwargs) Create keyring for cluster .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.keyring_create \e \(aqkeyring_type\(aq=\(aqadmin\(aq \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B keyring_type (required) One of \fBadmin\fP, \fBmon\fP, \fBosd\fP, \fBrgw\fP, \fBmds\fP .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.keyring_present(**kwargs) Returns \fBTrue\fP if the keyring is present on disk, otherwise \fBFalse\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.keyring_present \e \(aqkeyring_type\(aq=\(aqadmin\(aq \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B keyring_type (required) One of \fBadmin\fP, \fBmon\fP, \fBosd\fP, \fBrgw\fP, \fBmds\fP .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.keyring_purge(**kwargs) Delete keyring for cluster .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.keyring_purge \e \(aqkeyring_type\(aq=\(aqadmin\(aq \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B keyring_type (required) One of \fBadmin\fP, \fBmon\fP, \fBosd\fP, \fBrgw\fP, \fBmds\fP .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .sp If no ceph config file is found, this command will fail. .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.keyring_save(**kwargs) Create save keyring locally .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.keyring_save \e \(aqkeyring_type\(aq=\(aqadmin\(aq \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B keyring_type (required) One of \fBadmin\fP, \fBmon\fP, \fBosd\fP, \fBrgw\fP, \fBmds\fP .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.mds_create(**kwargs) Create a mds .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.mds_create \e \(aqname\(aq = \(aqmds.name\(aq \e \(aqport\(aq = 1000, \e \(aqaddr\(aq = \(aqfqdn.example.org\(aq \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name (required) The MDS name (must start with \fBmds.\fP) .TP .B port (required) Port to which the MDS will listen .TP .B addr (required) Address or IP address for the MDS to listen .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.mds_destroy(**kwargs) Remove a mds .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.mds_destroy \e \(aqname\(aq = \(aqmds.name\(aq \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name (required) The MDS name (must start with \fBmds.\fP) .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.mon_active(**kwargs) Returns \fBTrue\fP if the mon daemon is running, otherwise \fBFalse\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.mon_active \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.mon_create(**kwargs) Create a mon node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.mon_create \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.mon_is(**kwargs) Returns \fBTrue\fP if the target is a mon node, otherwise \fBFalse\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.mon_is \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.mon_quorum(**kwargs) Returns \fBTrue\fP if the mon daemon is in the quorum, otherwise \fBFalse\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.mon_quorum \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.mon_status(**kwargs) Get status from mon daemon .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.mon_status \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.osd_activate(**kwargs) Activate an OSD .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.osd_activate \(aqosd_dev\(aq=\(aq/dev/vdc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.osd_discover() List all OSD by cluster .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.osd_discover .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.osd_prepare(**kwargs) Prepare an OSD .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.osd_prepare \(aqosd_dev\(aq=\(aq/dev/vdc\(aq \e \(aqjournal_dev\(aq=\(aqdevice\(aq \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq \e \(aqosd_fs_type\(aq=\(aqxfs\(aq \e \(aqosd_uuid\(aq=\(aq2a143b73\-6d85\-4389\-a9e9\-b8a78d9e1e07\(aq \e \(aqjournal_uuid\(aq=\(aq4562a5db\-ff6f\-4268\-811d\-12fd4a09ae98\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_uuid The device to store the osd data on. .TP .B journal_dev The journal device. defaults to osd_dev. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .TP .B cluster_uuid The cluster date will be added too. Defaults to the value found in local config. .TP .B osd_fs_type set the file system to store OSD data with. Defaults to \(dqxfs\(dq. .TP .B osd_uuid set the OSD data UUID. If set will return if OSD with data UUID already exists. .TP .B journal_uuid set the OSD journal UUID. If set will return if OSD with journal UUID already exists. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.partition_is(dev) Check whether a given device path is a partition or a full disk. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.partition_is /dev/sdc1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.partition_list() List partitions by disk .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.partition_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.partition_list_journal() List all OSD journal partitions by partition .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.partition_list_journal .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.partition_list_osd() List all OSD data partitions by partition .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.partition_list_osd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.pool_add(pool_name, **kwargs) Create a pool .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.pool_add pool_name \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B pg_num Default to 8 .TP .B pgp_num Default to pg_num .TP .B pool_type can take values \(dqreplicated\(dq or \(dqerasure\(dq .TP .B erasure_code_profile The \(dqerasure_code_profile\(dq .TP .B crush_ruleset The crush map rule set .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.pool_del(pool_name, **kwargs) Delete a pool .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.pool_del pool_name \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.pool_list(**kwargs) List all pools .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.pool_list \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.purge(**kwargs) purge ceph configuration on the node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.purge \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.rgw_create(**kwargs) Create a rgw .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.rgw_create \e \(aqname\(aq = \(aqrgw.name\(aq \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name (required) The RGW client name. Must start with \fBrgw.\fP .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.rgw_destroy(**kwargs) Remove a rgw .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.rgw_destroy \e \(aqname\(aq = \(aqrgw.name\(aq \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name (required) The RGW client name (must start with \fBrgw.\fP) .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.rgw_pools_create(**kwargs) Create pools for rgw .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.rgw_pools_create .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.rgw_pools_missing(**kwargs) Show pools missing for rgw .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.rgw_pools_missing .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ceph.zap(target=None, **kwargs) Destroy the partition table and content of a given disk. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ceph.osd_prepare \(aqdev\(aq=\(aq/dev/vdc\(aq \e \(aqcluster_name\(aq=\(aqceph\(aq \e \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B dev The block device to format. .TP .B cluster_name The cluster name. Defaults to \fBceph\fP\&. .TP .B cluster_uuid The cluster UUID. Defaults to value found in ceph config file. .UNINDENT .UNINDENT .SS salt.modules.chassis .sp Glue execution module to link to the \fI\%fx2 proxymodule\fP\&. .sp Depends: \fI\%iDRAC Remote execution module (salt.modules.dracr)\fP .sp For documentation on commands that you can direct to a Dell chassis via proxy, look in the documentation for \fI\%salt.modules.dracr\fP\&. .sp This execution module calls through to a function in the fx2 proxy module called \fBchconfig\fP\&. That function looks up the function passed in the \fBcmd\fP parameter in \fI\%salt.modules.dracr\fP and calls it. .sp New in version 2015.8.2. .INDENT 0.0 .TP .B salt.modules.chassis.chassis_credentials() .UNINDENT .INDENT 0.0 .TP .B salt.modules.chassis.cmd(cmd, *args, **kwargs) .UNINDENT .SS salt.modules.chef .sp Execute chef in server or solo mode .INDENT 0.0 .TP .B salt.modules.chef.client(whyrun=False, localmode=False, logfile=None, **kwargs) Execute a chef client run and return a dict with the stderr, stdout, return code, and pid. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chef.client server=https://localhost .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B server The chef server URL .TP .B client_key Set the client key file location .TP .B config The configuration file to use .TP .B config\-file\-jail Directory under which config files are allowed to be loaded (no client.rb or knife.rb outside this path will be loaded). .TP .B environment Set the Chef Environment on the node .TP .B group Group to set privilege to .TP .B json\-attributes Load attributes from a JSON file or URL .TP .B localmode Point chef\-client at local repository if True .TP .B log_level Set the log level (debug, info, warn, error, fatal) .TP .B logfile Set the log file location .TP .B node\-name The node name for this client .TP .B override\-runlist Replace current run list with specified items for a single run .TP .B pid Set the PID file location, defaults to /tmp/chef\-client.pid .TP .B run\-lock\-timeout Set maximum duration to wait for another client run to finish, default is indefinitely. .TP .B runlist Permanently replace current run list with specified items .TP .B user User to set privilege to .TP .B validation_key Set the validation key file location, used for registering new clients .TP .B whyrun Enable whyrun mode when set to True .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chef.solo(whyrun=False, logfile=None, **kwargs) Execute a chef solo run and return a dict with the stderr, stdout, return code, and pid. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chef.solo override\-runlist=test .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B config The configuration file to use .TP .B environment Set the Chef Environment on the node .TP .B group Group to set privilege to .TP .B json\-attributes Load attributes from a JSON file or URL .TP .B log_level Set the log level (debug, info, warn, error, fatal) .TP .B logfile Set the log file location .TP .B node\-name The node name for this client .TP .B override\-runlist Replace current run list with specified items for a single run .TP .B recipe\-url Pull down a remote gzipped tarball of recipes and untar it to the cookbook cache .TP .B run\-lock\-timeout Set maximum duration to wait for another client run to finish, default is indefinitely. .TP .B user User to set privilege to .TP .B whyrun Enable whyrun mode when set to True .UNINDENT .UNINDENT .SS salt.modules.chocolatey .sp A module that wraps calls to the Chocolatey package manager (\fI\%http://chocolatey.org\fP) .sp New in version 2014.1.0. .INDENT 0.0 .TP .B salt.modules.chocolatey.add_source(name, source_location, username=None, password=None, priority=None) Instructs Chocolatey to add a source. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the source to be added as a chocolatey repository. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- Location of the source you want to work with. .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- Provide username for chocolatey sources that need authentication credentials. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- Provide password for chocolatey sources that need authentication credentials. .IP \(bu 2 \fBpriority\fP (\fI\%int\fP) \-\- The priority order of this source as compared to other sources, lower is better. Defaults to 0 (no priority). All priorities above 0 will be evaluated first, then zero\-based values will be evaluated in config file order. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.add_source <source name> <source_location> salt \(aq*\(aq chocolatey.add_source <source name> <source_location> priority=100 salt \(aq*\(aq chocolatey.add_source <source name> <source_location> user=<user> password=<password> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.bootstrap(force=False, source=None, version=None) Download and install the latest version of the Chocolatey package manager via the official bootstrap. .sp Chocolatey requires Windows PowerShell and the .NET v4.0 runtime. Depending on the host\(aqs version of Windows, chocolatey.bootstrap will attempt to ensure these prerequisites are met by downloading and executing the appropriate installers from Microsoft. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If PowerShell is installed, you may have to restart the host machine for Chocolatey to work. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you\(aqre installing offline using the source parameter, the PowerShell and .NET requirements must already be met on the target. This shouldn\(aqt be a problem on Windows versions 2012/8 and later .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you\(aqre installing chocolatey version 2.0+ the system requires .NET 4.8. Installing this requires a reboot, therefore this module will not automatically install .NET 4.8. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBforce\fP (\fI\%bool\fP) \-\- Run the bootstrap process even if Chocolatey is found in the path. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- .sp The location of the \fB\&.nupkg\fP file or \fB\&.ps1\fP file to run from an alternate location. This can be one of the following types of URLs: .INDENT 2.0 .IP \(bu 2 salt:// .IP \(bu 2 http(s):// .IP \(bu 2 \fI\%ftp://\fP .IP \(bu 2 \fI\%file://\fP \- A local file on the system .UNINDENT .sp New in version 3001. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- .sp The version of chocolatey to install. The latest version is installed if this value is \fBNone\fP\&. Default is \fBNone\fP .sp New in version 3007.1. .UNINDENT .TP .B Returns The stdout of the Chocolatey installation script .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # To bootstrap Chocolatey salt \(aq*\(aq chocolatey.bootstrap salt \(aq*\(aq chocolatey.bootstrap force=True # To bootstrap Chocolatey offline from a file on the salt master salt \(aq*\(aq chocolatey.bootstrap source=salt://files/chocolatey.nupkg # To bootstrap Chocolatey from a file on C:\eTemp salt \(aq*\(aq chocolatey.bootstrap source=C:\eTemp\echocolatey.nupkg # To bootstrap Chocolatey version 1.4.0 salt \(aq*\(aq chocolatey.bootstrap version=1.4.0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.chocolatey_version(refresh=False) Returns the version of Chocolatey installed on the minion. .INDENT 7.0 .TP .B Parameters \fBrefresh\fP (\fI\%bool\fP) \-\- .sp Refresh the cached version of chocolatey .sp New in version 3007.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.chocolatey_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.disable_source(name) Instructs Chocolatey to disable a source. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- Name of the source repository to disable. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.disable_source <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.enable_source(name) Instructs Chocolatey to enable a source. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- Name of the source repository to enable. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.enable_source <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install(name, version=None, source=None, force=False, pre_versions=False, install_args=None, override_args=False, force_x86=False, package_args=None, allow_multiple=False, execution_timeout=None) Instructs Chocolatey to install a package. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be installed. Only accepts a single argument. Required. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- Install a specific version of the package. Defaults to latest version. Default is \fBNone\fP\&. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- .sp Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed. Default is \fBNone\fP\&. .sp Alternate Sources: .INDENT 2.0 .IP \(bu 2 cygwin .IP \(bu 2 python .IP \(bu 2 ruby .IP \(bu 2 webpi .IP \(bu 2 windowsfeatures .UNINDENT .IP \(bu 2 \fBforce\fP (\fI\%bool\fP) \-\- Reinstall the current version of an existing package. Do not use with \fBallow_multiple\fP\&. Default is \fBFalse\fP\&. .IP \(bu 2 \fBpre_versions\fP (\fI\%bool\fP) \-\- Include pre\-release packages. Default is \fBFalse\fP\&. .IP \(bu 2 \fBinstall_args\fP (\fI\%str\fP) \-\- A list of install arguments you want to pass to the installation process, i.e. product key or feature list. Default is \fBNone\fP\&. .IP \(bu 2 \fBoverride_args\fP (\fI\%bool\fP) \-\- Set to true if you want to override the original install arguments (for the native installer) in the package and use your own. When this is set to \fBFalse\fP install_args will be appended to the end of the default arguments. Default is \fBNone\fP\&. .IP \(bu 2 \fBforce_x86\fP (\fI\%bool\fP) \-\- Force x86 (32bit) installation on 64bit systems. Default is \fBFalse\fP\&. .IP \(bu 2 \fBpackage_args\fP (\fI\%str\fP) \-\- Arguments you want to pass to the package. Default is \fBNone\fP\&. .IP \(bu 2 \fBallow_multiple\fP (\fI\%bool\fP) \-\- .sp Allow multiple versions of the package to be installed. Do not use with \fBforce\fP\&. Does not work with all packages. Default is \fBFalse\fP\&. .sp New in version 2017.7.0. .IP \(bu 2 \fBexecution_timeout\fP (\fI\%str\fP) \-\- .sp Chocolatey execution timeout value you want to pass to the installation process. Default is \fBNone\fP\&. .sp New in version 2018.3.0. .UNINDENT .TP .B Returns The output of the \fBchocolatey\fP command .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install <package name> salt \(aq*\(aq chocolatey.install <package name> version=<package version> salt \(aq*\(aq chocolatey.install <package name> install_args=<args> override_args=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install_cygwin(name, install_args=None, override_args=False) Instructs Chocolatey to install a package via Cygwin. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be installed. Only accepts a single argument. .IP \(bu 2 \fBinstall_args\fP (\fI\%str\fP) \-\- A list of install arguments you want to pass to the installation process, i.e. product key or feature list .IP \(bu 2 \fBoverride_args\fP (\fI\%bool\fP) \-\- Set to \fBTrue\fP if you want to override the original install arguments (for the native installer) in the package and use your own. When this is set to \fBFalse\fP install_args will be appended to the end of the default arguments .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install_cygwin <package name> salt \(aq*\(aq chocolatey.install_cygwin <package name> install_args=<args> override_args=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install_gem(name, version=None, install_args=None, override_args=False) Instructs Chocolatey to install a package via Ruby\(aqs Gems. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be installed. Only accepts a single argument. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- Install a specific version of the package. Defaults to the latest version available. .IP \(bu 2 \fBinstall_args\fP (\fI\%str\fP) \-\- A list of install arguments you want to pass to the installation process, i.e. product key or feature list .IP \(bu 2 \fBoverride_args\fP (\fI\%bool\fP) \-\- Set to \fBTrue\fP if you want to override the original install arguments (for the native installer) in the package and use your own. When this is set to \fBFalse\fP install_args will be appended to the end of the default arguments .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install_gem <package name> salt \(aq*\(aq chocolatey.install_gem <package name> version=<package version> salt \(aq*\(aq chocolatey.install_gem <package name> install_args=<args> override_args=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install_missing(name, version=None, source=None) Instructs Chocolatey to install a package if it doesn\(aqt already exist. .sp Changed in version 2014.7.0: If the minion has Chocolatey >= 0.9.8.24 installed, this function calls \fI\%chocolatey.install\fP instead, as \fBinstallmissing\fP is deprecated as of that version and will be removed in Chocolatey 1.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be installed. Only accepts a single argument. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- Install a specific version of the package. Defaults to the latest version available. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install_missing <package name> salt \(aq*\(aq chocolatey.install_missing <package name> version=<package version> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install_python(name, version=None, install_args=None, override_args=False) Instructs Chocolatey to install a package via Python\(aqs easy_install. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be installed. Only accepts a single argument. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- Install a specific version of the package. Defaults to the latest version available. .IP \(bu 2 \fBinstall_args\fP (\fI\%str\fP) \-\- A list of install arguments you want to pass to the installation process, i.e. product key or feature list. .IP \(bu 2 \fBoverride_args\fP (\fI\%bool\fP) \-\- Set to \fBTrue\fP if you want to override the original install arguments (for the native installer) in the package and use your own. When this is set to \fBFalse\fP install_args will be appended to the end of the default arguments. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install_python <package name> salt \(aq*\(aq chocolatey.install_python <package name> version=<package version> salt \(aq*\(aq chocolatey.install_python <package name> install_args=<args> override_args=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install_webpi(name, install_args=None, override_args=False) Instructs Chocolatey to install a package via the Microsoft Web PI service. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be installed. Only accepts a single argument. .IP \(bu 2 \fBinstall_args\fP (\fI\%str\fP) \-\- A list of install arguments you want to pass to the installation process, i.e. product key or feature list. .IP \(bu 2 \fBoverride_args\fP (\fI\%bool\fP) \-\- Set to \fBTrue\fP if you want to override the original install arguments (for the native installer) in the package and use your own. When this is set to \fBFalse\fP install_args will be appended to the end of the default arguments. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install_webpi <package name> salt \(aq*\(aq chocolatey.install_webpi <package name> install_args=<args> override_args=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install_windowsfeatures(name) Instructs Chocolatey to install a Windows Feature via the Deployment Image Servicing and Management tool. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the feature to be installed. Only accepts a single argument. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install_windowsfeatures <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.list_(narrow=None, all_versions=False, pre_versions=False, source=None, local_only=False, exact=False) Instructs Chocolatey to pull a vague package list from the repository. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnarrow\fP (\fI\%str\fP) \-\- Term used to narrow down results. Searches against name/description/tag. Default is None. .IP \(bu 2 \fBall_versions\fP (\fI\%bool\fP) \-\- Display all available package versions in results. Default is False. .IP \(bu 2 \fBpre_versions\fP (\fI\%bool\fP) \-\- Display pre\-release packages in results. Default is False. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed if None is passed. Default is None. .IP \(bu 2 \fBlocal_only\fP (\fI\%bool\fP) \-\- Only display packages that are installed locally. Default is False. .IP \(bu 2 \fBexact\fP (\fI\%bool\fP) \-\- .sp Only display packages that match \fBnarrow\fP exactly. Default is False. .sp New in version 2017.7.0. .UNINDENT .TP .B Returns A dictionary of results. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.list <narrow> salt \(aq*\(aq chocolatey.list <narrow> all_versions=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.list_sources() Returns the list of installed sources. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.list_sources .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.list_webpi() Instructs Chocolatey to pull a full package list from the Microsoft Web PI repository. .INDENT 7.0 .TP .B Returns List of webpi packages .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.list_webpi .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.list_windowsfeatures() Instructs Chocolatey to pull a full package list from the Windows Features list, via the Deployment Image Servicing and Management tool. .INDENT 7.0 .TP .B Returns List of Windows Features .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.list_windowsfeatures .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.unbootstrap() Uninstall chocolatey from the system by doing the following: .INDENT 7.0 .IP \(bu 2 Delete the Chocolatey Directory .IP \(bu 2 Remove Chocolatey from the path .IP \(bu 2 Remove Chocolatey environment variables .UNINDENT .sp New in version 3001. .INDENT 7.0 .TP .B Returns A list of items that were removed, otherwise an empty list .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt * chocolatey.unbootstrap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.uninstall(name, version=None, uninstall_args=None, override_args=False, force=False) Instructs Chocolatey to uninstall a package. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be uninstalled. Only accepts a single argument. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- Uninstalls a specific version of the package. Defaults to the latest version installed. .IP \(bu 2 \fBuninstall_args\fP (\fI\%str\fP) \-\- A list of uninstall arguments you want to pass to the uninstallation process, i.e. product key or feature list. .IP \(bu 2 \fBoverride_args\fP \-\- Set to \fBTrue\fP if you want to override the original uninstall arguments (for the native uninstaller) in the package and use your own. When this is set to \fBFalse\fP uninstall_args will be appended to the end of the default arguments. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.uninstall <package name> salt \(aq*\(aq chocolatey.uninstall <package name> version=<package version> salt \(aq*\(aq chocolatey.uninstall <package name> version=<package version> uninstall_args=<args> override_args=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.update(name, source=None, pre_versions=False) Instructs Chocolatey to update packages on the system. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to update, or \(dqall\(dq to update everything installed on the system. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed. .IP \(bu 2 \fBpre_versions\fP (\fI\%bool\fP) \-\- Include pre\-release packages in comparison. Defaults to \fBFalse\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq chocolatey.update all salt \(dq*\(dq chocolatey.update <package name> pre_versions=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.upgrade(name, version=None, source=None, force=False, pre_versions=False, install_args=None, override_args=False, force_x86=False, package_args=None) New in version 2016.3.4. .sp Instructs Chocolatey to upgrade packages on the system. (update is being deprecated). This command will install the package if not installed. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to update, or \(dqall\(dq to update everything installed on the system. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- Install a specific version of the package. Defaults to latest version. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed. .IP \(bu 2 \fBforce\fP (\fI\%bool\fP) \-\- Reinstall the \fBsame\fP version already installed. .IP \(bu 2 \fBpre_versions\fP (\fI\%bool\fP) \-\- Include pre\-release packages in comparison. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBinstall_args\fP (\fI\%str\fP) \-\- A list of install arguments you want to pass to the installation process, i.e. product key or feature list. .IP \(bu 2 \fBoverride_args\fP (\fI\%bool\fP) \-\- Set to \fBTrue\fP if you want to override the original install arguments (for the native installer) in the package and use your own. When this is set to \fBFalse\fP install_args will be appended to the end of the default arguments. .IP \(bu 2 \fBforce_x86\fP (\fI\%bool\fP) \-\- Force x86 (32bit) installation on 64bit systems. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBpackage_args\fP (\fI\%str\fP) \-\- A list of arguments you want to pass to the package. .UNINDENT .TP .B Returns Results of the \fBchocolatey\fP command .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq chocolatey.upgrade all salt \(dq*\(dq chocolatey.upgrade <package name> pre_versions=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.version(name, check_remote=False, source=None, pre_versions=False) Instructs Chocolatey to check an installed package version, and optionally compare it to one available from a remote feed. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to check. Required. .IP \(bu 2 \fBcheck_remote\fP (\fI\%bool\fP) \-\- Get the version number of the latest package from the remote feed. Default is \fBFalse\fP\&. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed. Default is \fBNone\fP\&. .IP \(bu 2 \fBpre_versions\fP (\fI\%bool\fP) \-\- Include pre\-release packages in comparison. Default is \fBFalse\fP\&. .UNINDENT .TP .B Returns A dictionary of currently installed software and versions .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq chocolatey.version <package name> salt \(dq*\(dq chocolatey.version <package name> check_remote=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.chronos .sp Module providing a simple management interface to a chronos cluster. .sp Currently this only works when run through a proxy minion. .sp New in version 2015.8.2. .INDENT 0.0 .TP .B salt.modules.chronos.has_job(name) Return whether the given job is currently configured. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt chronos\-minion\-id chronos.has_job my\-job .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chronos.job(name) Return the current server configuration for the specified job. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt chronos\-minion\-id chronos.job my\-job .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chronos.jobs() Return a list of the currently installed job names. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt chronos\-minion\-id chronos.jobs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chronos.rm_job(name) Remove the specified job from the server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt chronos\-minion\-id chronos.rm_job my\-job .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chronos.update_job(name, config) Update the specified job with the given configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt chronos\-minion\-id chronos.update_job my\-job \(aq<config yaml>\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.chroot .sp Module for chroot :maintainer: Alberto Planas <\fI\%aplanas@suse.com\fP> :maturity: new :depends: None :platform: Linux .INDENT 0.0 .TP .B salt.modules.chroot.apply_(root, mods=None, **kwargs) Apply an state inside a chroot. .sp This function will call \fIchroot.highstate\fP or \fIchroot.sls\fP based on the arguments passed to this function. It exists as a more intuitive way of applying states. .INDENT 7.0 .TP .B root Path to the chroot environment .UNINDENT .sp For a formal description of the possible parameters accepted in this function, check \fIstate.apply_\fP documentation. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion chroot.apply /chroot salt myminion chroot.apply /chroot stuff salt myminion chroot.apply /chroot stuff pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chroot.call(root, function, *args, **kwargs) Executes a Salt function inside a chroot environment. .sp The chroot does not need to have Salt installed, but Python is required. .INDENT 7.0 .TP .B root Path to the chroot environment .TP .B function Salt execution module function .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion chroot.call /chroot test.ping salt myminion chroot.call /chroot ssh.set_auth_key user key=mykey .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chroot.create(root) Create a basic chroot environment. .sp Note that this environment is not functional. The caller needs to install the minimal required binaries, including Python if chroot.call is called. .INDENT 7.0 .TP .B root Path to the chroot environment .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion chroot.create /chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chroot.exist(root) Return True if the chroot environment is present. .INDENT 7.0 .TP .B root Path to the chroot environment .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion chroot.exist /chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chroot.highstate(root, **kwargs) Retrieve the state data from the salt master for this minion and execute it inside the chroot. .INDENT 7.0 .TP .B root Path to the chroot environment .UNINDENT .sp For a formal description of the possible parameters accepted in this function, check \fIstate.highstate\fP documentation. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion chroot.highstate /chroot salt myminion chroot.highstate /chroot pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chroot.in_chroot() Return True if the process is inside a chroot jail .sp New in version 3004. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion chroot.in_chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chroot.sls(root, mods, saltenv=\(aqbase\(aq, test=None, exclude=None, **kwargs) Execute the states in one or more SLS files inside the chroot. .INDENT 7.0 .TP .B root Path to the chroot environment .TP .B saltenv Specify a salt fileserver environment to be used when applying states .TP .B mods List of states to execute .TP .B test Run states in test\-only (dry\-run) mode .TP .B exclude Exclude specific states from execution. Accepts a list of sls names, a comma\-separated string of sls names, or a list of dictionaries containing \fBsls\fP or \fBid\fP keys. Glob\-patterns may be used to match multiple states. .UNINDENT .sp For a formal description of the possible parameters accepted in this function, check \fIstate.sls\fP documentation. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chroot.sls /chroot stuff pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.cimc .sp Module to provide Cisco UCS compatibility to Salt .INDENT 0.0 .TP .B codeauthor \fBSpencer Ervin <spencer_ervin@hotmail.com>\fP .TP .B maturity new .TP .B depends none .TP .B platform unix .UNINDENT .SS Configuration .sp This module accepts connection configuration details either as parameters, or as configuration settings in pillar as a Salt proxy. Options passed into opts will be ignored if options are passed into pillar. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Cisco UCS Proxy Module\fP .UNINDENT .UNINDENT .SS About .sp This execution module was designed to handle connections to a Cisco UCS server. This module adds support to send connections directly to the device through the rest API. .INDENT 0.0 .TP .B salt.modules.cimc.activate_backup_image(reset=False) Activates the firmware backup image. .sp CLI Example: .INDENT 7.0 .TP .B Parameters \fBreset\fP (\fI\%bool\fP) \-\- Reset the CIMC device on activate. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.activate_backup_image salt \(aq*\(aq cimc.activate_backup_image reset=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.create_user(uid=None, username=None, password=None, priv=None) Create a CIMC user with username and password. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuid\fP (\fI\%int\fP) \-\- The user ID slot to create the user account in. .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- The name of the user. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The clear text password of the user. .IP \(bu 2 \fBpriv\fP (\fI\%str\fP) \-\- The privilege level of the user. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.create_user 11 username=admin password=foobar priv=admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_bios_defaults() Get the default values of BIOS tokens. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_bios_defaults .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_bios_settings() Get the C240 server BIOS token values. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_bios_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_boot_order() Retrieves the configured boot order table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_boot_order .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_cpu_details() Get the CPU product ID details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_cpu_details .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_disks() Get the HDD product ID details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_disks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_ethernet_interfaces() Get the adapter Ethernet interface details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_ethernet_interfaces .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_fibre_channel_interfaces() Get the adapter fibre channel interface details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_fibre_channel_interfaces .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_firmware() Retrieves the current running firmware versions of server components. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_firmware .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_hostname() Retrieves the hostname from the device. .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_hostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_ldap() Retrieves LDAP server details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_ldap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_management_interface() Retrieve the management interface details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_management_interface .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_memory_token() Get the memory RAS BIOS token. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_memory_token .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_memory_unit() Get the IMM/Memory unit product ID details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_memory_unit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_network_adapters() Get the list of network adapters and configuration details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_network_adapters .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_ntp() Retrieves the current running NTP configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_ntp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_pci_adapters() Get the PCI adapter product ID details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_disks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_power_configuration() Get the configuration of the power settings from the device. This is only available on some C\-Series servers. .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_power_configuration .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_power_supplies() Retrieves the power supply unit details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_power_supplies .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_snmp_config() Get the snmp configuration details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_snmp_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_syslog() Get the Syslog client\-server details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_syslog .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_syslog_settings() Get the Syslog configuration settings from the system. .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_syslog_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_system_info() Get the system information. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_system_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_users() Get the CIMC users. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_vic_adapters() Get the VIC adapter general profile details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_vic_adapters .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.get_vic_uplinks() Get the VIC adapter uplink port details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.get_vic_uplinks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.mount_share(name=None, remote_share=None, remote_file=None, mount_type=\(aqnfs\(aq, username=None, password=None) Mounts a remote file through a remote share. Currently, this feature is supported in version 1.5 or greater. The remote share can be either NFS, CIFS, or WWW. .INDENT 7.0 .TP .B Some of the advantages of CIMC Mounted vMedia include: Communication between mounted media and target stays local (inside datacenter) Media mounts can be scripted/automated No vKVM requirements for media connection Multiple share types supported Connections supported through all CIMC interfaces .sp Note: CIMC Mounted vMedia is enabled through BIOS configuration. .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the volume on the CIMC device. .IP \(bu 2 \fBremote_share\fP (\fI\%str\fP) \-\- The file share link that will be used to mount the share. This can be NFS, CIFS, or WWW. This .IP \(bu 2 \fBfile.\fP (\fImust be the directory path and not the full path to the remote\fP) \-\- .IP \(bu 2 \fBremote_file\fP (\fI\%str\fP) \-\- The name of the remote file to mount. It must reside within remote_share. .IP \(bu 2 \fBmount_type\fP (\fI\%str\fP) \-\- The type of share to mount. Valid options are nfs, cifs, and www. .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- An optional requirement to pass credentials to the remote share. If not provided, an .IP \(bu 2 \fBmade.\fP (\fIunauthenticated connection attempt will be\fP) \-\- .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- An optional requirement to pass a password to the remote share. If not provided, an .IP \(bu 2 \fBmade.\fP \-\- .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.mount_share name=WIN7 remote_share=10.xxx.27.xxx:/nfs remote_file=sl1huu.iso salt \(aq*\(aq cimc.mount_share name=WIN7 remote_share=10.xxx.27.xxx:/nfs remote_file=sl1huu.iso username=bob password=badpassword .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.reboot() Power cycling the server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.reboot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.set_hostname(hostname=None) Sets the hostname on the server. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters \fBhostname\fP (\fI\%str\fP) \-\- The new hostname to set. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.set_hostname foobar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.set_logging_levels(remote=None, local=None) Sets the logging levels of the CIMC devices. The logging levels must match the following options: emergency, alert, critical, error, warning, notice, informational, debug. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBremote\fP (\fI\%str\fP) \-\- The logging level for SYSLOG logs. .IP \(bu 2 \fBlocal\fP (\fI\%str\fP) \-\- The logging level for the local device. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.set_logging_levels remote=error local=notice .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.set_ntp_server(server1=\(aq\(aq, server2=\(aq\(aq, server3=\(aq\(aq, server4=\(aq\(aq) Sets the NTP servers configuration. This will also enable the client NTP service. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBserver1\fP (\fI\%str\fP) \-\- The first IP address or FQDN of the NTP servers. .IP \(bu 2 \fBserver2\fP (\fI\%str\fP) \-\- The second IP address or FQDN of the NTP servers. .IP \(bu 2 \fBserver3\fP (\fI\%str\fP) \-\- The third IP address or FQDN of the NTP servers. .IP \(bu 2 \fBserver4\fP (\fI\%str\fP) \-\- The fourth IP address or FQDN of the NTP servers. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.set_ntp_server 10.10.10.1 salt \(aq*\(aq cimc.set_ntp_server 10.10.10.1 foo.bar.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.set_power_configuration(policy=None, delayType=None, delayValue=None) Sets the power configuration on the device. This is only available for some C\-Series servers. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpolicy\fP (\fI\%str\fP) \-\- The action to be taken when chassis power is restored after .IP \(bu 2 \fBfollowing\fP (\fIdelayed with this option. This can be one\fP\fI of \fP\fIthe\fP) \-\- .sp reset: The server is allowed to boot up normally when power is restored. The server can restart immediately or, optionally, after a fixed or random delay. .sp stay\-off: The server remains off until it is manually restarted. .sp last\-state: The server restarts and the system attempts to restore any processes that were running before power was lost. .IP \(bu 2 \fBdelayType\fP (\fI\%str\fP) \-\- If the selected policy is reset, the restart can be .IP \(bu 2 \fBfollowing\fP \-\- .sp fixed: The server restarts after a fixed delay. .sp random: The server restarts after a random delay. .IP \(bu 2 \fBdelayValue\fP (\fI\%int\fP) \-\- If a fixed delay is selected, once chassis power is .IP \(bu 2 \fBrebooting\fP (\fIrestored and the Cisco IMC has finished\fP) \-\- .IP \(bu 2 \fBfor\fP (\fIthe system waits\fP) \-\- .IP \(bu 2 \fBan\fP (\fIthe specified number\fP\fI of \fP\fIseconds before restarting the server. Enter\fP) \-\- .IP \(bu 2 \fB240.\fP (\fIinteger between 0 and\fP) \-\- .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.set_power_configuration stay\-off salt \(aq*\(aq cimc.set_power_configuration reset fixed 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.set_syslog_server(server=None, type=\(aqprimary\(aq) Set the SYSLOG server on the host. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBserver\fP (\fI\%str\fP) \-\- The hostname or IP address of the SYSLOG server. .IP \(bu 2 \fBtype\fP (\fI\%str\fP) \-\- Specifies the type of SYSLOG server. This can either be primary (default) or secondary. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.set_syslog_server foo.bar.com salt \(aq*\(aq cimc.set_syslog_server foo.bar.com primary salt \(aq*\(aq cimc.set_syslog_server foo.bar.com secondary .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.set_user(uid=None, username=None, password=None, priv=None, status=None) Sets a CIMC user with specified configurations. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuid\fP (\fI\%int\fP) \-\- The user ID slot to create the user account in. .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- The name of the user. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The clear text password of the user. .IP \(bu 2 \fBpriv\fP (\fI\%str\fP) \-\- The privilege level of the user. .IP \(bu 2 \fBstatus\fP (\fI\%str\fP) \-\- The account status of the user. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.set_user 11 username=admin password=foobar priv=admin active .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.tftp_update_bios(server=None, path=None) Update the BIOS firmware through TFTP. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBserver\fP (\fI\%str\fP) \-\- The IP address or hostname of the TFTP server. .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The TFTP path and filename for the BIOS image. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.tftp_update_bios foo.bar.com HP\-SL2.cap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cimc.tftp_update_cimc(server=None, path=None) Update the CIMC firmware through TFTP. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBserver\fP (\fI\%str\fP) \-\- The IP address or hostname of the TFTP server. .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The TFTP path and filename for the CIMC image. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cimc.tftp_update_cimc foo.bar.com HP\-SL2.bin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ciscoconfparse_mod .sp Execution module for \fI\%ciscoconfparse\fP .sp New in version 2019.2.0. .sp This module can be used for basic configuration parsing, audit or validation for a variety of network platforms having Cisco IOS style configuration (one space indentation), including: Cisco IOS, Cisco Nexus, Cisco IOS\-XR, Cisco IOS\-XR, Cisco ASA, Arista EOS, Brocade, HP Switches, Dell PowerConnect Switches, or Extreme Networks devices. In newer versions, \fBciscoconfparse\fP provides support for brace\-delimited configuration style as well, for platforms such as: Juniper Junos, Palo Alto, or F5 Networks. .sp See \fI\%http://www.pennington.net/py/ciscoconfparse/index.html\fP for further details. .INDENT 0.0 .TP .B depends ciscoconfparse .UNINDENT .sp This module depends on the Python library with the same name, \fBciscoconfparse\fP \- to install execute: \fBpip install ciscoconfparse\fP\&. .INDENT 0.0 .TP .B salt.modules.ciscoconfparse_mod.filter_lines(config=None, config_path=None, parent_regex=None, child_regex=None, saltenv=\(aqbase\(aq) Return a list of detailed matches, for the configuration blocks (parent\-child relationship) whose parent respects the regular expressions configured via the \fBparent_regex\fP argument, and the child matches the \fBchild_regex\fP regular expression. The result is a list of dictionaries with the following keys: .INDENT 7.0 .IP \(bu 2 \fBmatch\fP: a boolean value that tells whether \fBchild_regex\fP matched any children lines. .IP \(bu 2 \fBparent\fP: the parent line (as text). .IP \(bu 2 \fBchild\fP: the child line (as text). If no child line matched, this field will be \fBNone\fP\&. .UNINDENT .sp Note that the return list contains the elements that matched the parent condition, the \fBparent_regex\fP regular expression. Therefore, the \fBparent\fP field will always have a valid value, while \fBmatch\fP and \fBchild\fP may default to \fBFalse\fP and \fBNone\fP respectively when there is not child match. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ciscoconfparse.filter_lines config_path=https://bit.ly/2mAdq7z parent_regex=\(aqGigabit\(aq child_regex=\(aqshutdown\(aq .ft P .fi .UNINDENT .UNINDENT .sp Example output (for the example above): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ { \(aqparent\(aq: \(aqinterface GigabitEthernet1\(aq, \(aqmatch\(aq: False, \(aqchild\(aq: None }, { \(aqparent\(aq: \(aqinterface GigabitEthernet2\(aq, \(aqmatch\(aq: True, \(aqchild\(aq: \(aq shutdown\(aq }, { \(aqparent\(aq: \(aqinterface GigabitEthernet3\(aq, \(aqmatch\(aq: True, \(aqchild\(aq: \(aq shutdown\(aq } ] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ciscoconfparse_mod.find_lines(config=None, config_path=None, regex=None, saltenv=\(aqbase\(aq) Return all the lines (as text) that match the expression in the \fBregex\fP argument. .INDENT 7.0 .TP .B config The configuration sent as text. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument is ignored when \fBconfig_path\fP is specified. .UNINDENT .UNINDENT .TP .B config_path The absolute or remote path to the file with the configuration to be parsed. This argument supports the usual Salt filesystem URIs, e.g., \fBsalt://\fP, \fBhttps://\fP, \fBftp://\fP, \fBs3://\fP, etc. .TP .B regex The regular expression to match the lines against. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. This argument is ignored when \fBconfig_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ciscoconfparse.find_lines config_path=https://bit.ly/2mAdq7z regex=\(aqip address\(aq .ft P .fi .UNINDENT .UNINDENT .sp Output example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cisco\-ios\-router: \- ip address dhcp \- ip address 172.20.0.1 255.255.255.0 \- no ip address .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ciscoconfparse_mod.find_lines_w_child(config=None, config_path=None, parent_regex=None, child_regex=None, ignore_ws=False, saltenv=\(aqbase\(aq) Return a list of parent lines (as text) matching the regular expression \fBparent_regex\fP that have children lines matching \fBchild_regex\fP\&. .INDENT 7.0 .TP .B config The configuration sent as text. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument is ignored when \fBconfig_path\fP is specified. .UNINDENT .UNINDENT .TP .B config_path The absolute or remote path to the file with the configuration to be parsed. This argument supports the usual Salt filesystem URIs, e.g., \fBsalt://\fP, \fBhttps://\fP, \fBftp://\fP, \fBs3://\fP, etc. .TP .B parent_regex The regular expression to match the parent lines against. .TP .B child_regex The regular expression to match the child lines against. .TP .B ignore_ws: \fBFalse\fP Whether to ignore the white spaces. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. This argument is ignored when \fBconfig_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ciscoconfparse.find_lines_w_child config_path=https://bit.ly/2mAdq7z parent_line=\(aqline con\(aq child_line=\(aqstopbits\(aq salt \(aq*\(aq ciscoconfparse.find_lines_w_child config_path=https://bit.ly/2uIRxau parent_regex=\(aqge\-(.*)\(aq child_regex=\(aqunit \ed+\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ciscoconfparse_mod.find_lines_wo_child(config=None, config_path=None, parent_regex=None, child_regex=None, ignore_ws=False, saltenv=\(aqbase\(aq) Return a list of parent \fBciscoconfparse.IOSCfgLine\fP lines as text, which matched the \fBparent_regex\fP and whose children did \fInot\fP match \fBchild_regex\fP\&. Only the parent \fBciscoconfparse.IOSCfgLine\fP text lines will be returned. For simplicity, this method only finds oldest ancestors without immediate children that match. .INDENT 7.0 .TP .B config The configuration sent as text. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument is ignored when \fBconfig_path\fP is specified. .UNINDENT .UNINDENT .TP .B config_path The absolute or remote path to the file with the configuration to be parsed. This argument supports the usual Salt filesystem URIs, e.g., \fBsalt://\fP, \fBhttps://\fP, \fBftp://\fP, \fBs3://\fP, etc. .TP .B parent_regex The regular expression to match the parent lines against. .TP .B child_regex The regular expression to match the child lines against. .TP .B ignore_ws: \fBFalse\fP Whether to ignore the white spaces. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. This argument is ignored when \fBconfig_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ciscoconfparse.find_lines_wo_child config_path=https://bit.ly/2mAdq7z parent_line=\(aqline con\(aq child_line=\(aqstopbits\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ciscoconfparse_mod.find_objects(config=None, config_path=None, regex=None, saltenv=\(aqbase\(aq) Return all the line objects that match the expression in the \fBregex\fP argument. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This function is mostly valuable when invoked from other Salt components (i.e., execution modules, states, templates etc.). For CLI usage, please consider using \fBciscoconfparse.find_lines\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B config The configuration sent as text. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument is ignored when \fBconfig_path\fP is specified. .UNINDENT .UNINDENT .TP .B config_path The absolute or remote path to the file with the configuration to be parsed. This argument supports the usual Salt filesystem URIs, e.g., \fBsalt://\fP, \fBhttps://\fP, \fBftp://\fP, \fBs3://\fP, etc. .TP .B regex The regular expression to match the lines against. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. This argument is ignored when \fBconfig_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp Usage example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C objects = __salt__[\(aqciscoconfparse.find_objects\(aq](config_path=\(aqsalt://path/to/config.txt\(aq, regex=\(aqGigabit\(aq) for obj in objects: print(obj.text) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ciscoconfparse_mod.find_objects_w_child(config=None, config_path=None, parent_regex=None, child_regex=None, ignore_ws=False, saltenv=\(aqbase\(aq) Parse through the children of all parent lines matching \fBparent_regex\fP, and return a list of child objects, which matched the \fBchild_regex\fP\&. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This function is mostly valuable when invoked from other Salt components (i.e., execution modules, states, templates etc.). For CLI usage, please consider using \fBciscoconfparse.find_lines_w_child\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B config The configuration sent as text. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument is ignored when \fBconfig_path\fP is specified. .UNINDENT .UNINDENT .TP .B config_path The absolute or remote path to the file with the configuration to be parsed. This argument supports the usual Salt filesystem URIs, e.g., \fBsalt://\fP, \fBhttps://\fP, \fBftp://\fP, \fBs3://\fP, etc. .TP .B parent_regex The regular expression to match the parent lines against. .TP .B child_regex The regular expression to match the child lines against. .TP .B ignore_ws: \fBFalse\fP Whether to ignore the white spaces. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. This argument is ignored when \fBconfig_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp Usage example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C objects = __salt__[\(aqciscoconfparse.find_objects_w_child\(aq](config_path=\(aqhttps://bit.ly/2mAdq7z\(aq, parent_regex=\(aqline con\(aq, child_regex=\(aqstopbits\(aq) for obj in objects: print(obj.text) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ciscoconfparse_mod.find_objects_wo_child(config=None, config_path=None, parent_regex=None, child_regex=None, ignore_ws=False, saltenv=\(aqbase\(aq) Return a list of parent \fBciscoconfparse.IOSCfgLine\fP objects, which matched the \fBparent_regex\fP and whose children did \fInot\fP match \fBchild_regex\fP\&. Only the parent \fBciscoconfparse.IOSCfgLine\fP objects will be returned. For simplicity, this method only finds oldest ancestors without immediate children that match. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This function is mostly valuable when invoked from other Salt components (i.e., execution modules, states, templates etc.). For CLI usage, please consider using \fBciscoconfparse.find_lines_wo_child\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B config The configuration sent as text. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument is ignored when \fBconfig_path\fP is specified. .UNINDENT .UNINDENT .TP .B config_path The absolute or remote path to the file with the configuration to be parsed. This argument supports the usual Salt filesystem URIs, e.g., \fBsalt://\fP, \fBhttps://\fP, \fBftp://\fP, \fBs3://\fP, etc. .TP .B parent_regex The regular expression to match the parent lines against. .TP .B child_regex The regular expression to match the child lines against. .TP .B ignore_ws: \fBFalse\fP Whether to ignore the white spaces. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. This argument is ignored when \fBconfig_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp Usage example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C objects = __salt__[\(aqciscoconfparse.find_objects_wo_child\(aq](config_path=\(aqhttps://bit.ly/2mAdq7z\(aq, parent_regex=\(aqline con\(aq, child_regex=\(aqstopbits\(aq) for obj in objects: print(obj.text) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.cisconso .sp Execution module for Cisco Network Services Orchestrator Proxy minions .sp New in version 2016.11.0. .sp For documentation on setting up the cisconso proxy minion look in the documentation for \fI\%salt.proxy.cisconso\fP\&. .INDENT 0.0 .TP .B salt.modules.cisconso.apply_rollback(datastore, name) Apply a system rollback .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdatastore\fP (\fBDatastoreType\fP (\fBstr\fP enum).) \-\- The datastore, e.g. running, operational. One of the NETCONF store IETF types .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- an ID of the rollback to restore .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt cisco\-nso cisconso.apply_rollback 52 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cisconso.get_data(datastore, path) Get the configuration of the device tree at the given path .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdatastore\fP (\fBDatastoreType\fP (\fBstr\fP enum).) \-\- The datastore, e.g. running, operational. One of the NETCONF store IETF types .IP \(bu 2 \fBpath\fP (\fBlist\fP, \fBstr\fP OR \fBtuple\fP) \-\- The device path to set the value at, a list of element names in order, / separated .UNINDENT .TP .B Returns The network configuration at that tree .TP .B Return type \fBdict\fP .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt cisco\-nso cisconso.get_data running \(aqdevices/ex0\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cisconso.get_rollback(name) Get the backup of stored a configuration rollback .INDENT 7.0 .TP .B Parameters \fBname\fP (\fBstr\fP) \-\- Typically an ID of the backup .TP .B Return type \fBstr\fP .TP .B Returns the contents of the rollback snapshot .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt cisco\-nso cisconso.get_rollback 52 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cisconso.get_rollbacks() Get a list of stored configuration rollbacks .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt cisco\-nso cisconso.get_rollbacks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cisconso.info() Return system information for grains of the NSO proxy minion .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cisconso.info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cisconso.set_data_value(datastore, path, data) Set a data entry in a datastore .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdatastore\fP (\fBDatastoreType\fP (\fBstr\fP enum).) \-\- The datastore, e.g. running, operational. One of the NETCONF store IETF types .IP \(bu 2 \fBpath\fP (\fBlist\fP, \fBstr\fP OR \fBtuple\fP) \-\- The device path to set the value at, a list of element names in order, / separated .IP \(bu 2 \fBdata\fP (\fBdict\fP) \-\- The new value at the given path .UNINDENT .TP .B Return type \fBbool\fP .TP .B Returns \fBTrue\fP if successful, otherwise error. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt cisco\-nso cisconso.set_data_value running \(aqdevices/ex0/routes\(aq 10.0.0.20/24 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.cloud .sp Salt\-specific interface for calling Salt Cloud directly .INDENT 0.0 .TP .B salt.modules.cloud.action(fun=None, cloudmap=None, names=None, provider=None, instance=None, **kwargs) Execute a single action on the given provider/instance .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.action start instance=myinstance salt minionname cloud.action stop instance=myinstance salt minionname cloud.action show_image provider=my\-ec2\-config image=ami\-1624987f .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.create(provider, names, opts=None, **kwargs) Create an instance using Salt Cloud .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.create my\-ec2\-config myinstance image=ami\-1624987f size=\(aqt1.micro\(aq ssh_username=ec2\-user securitygroup=default delvol_on_destroy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.destroy(names) Destroy the named VM(s) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.destroy myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.full_query(query_type=\(aqlist_nodes_full\(aq) List all available cloud provider data .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.full_query .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.get_instance(name, provider=None) Return details on an instance. .sp Similar to the cloud action show_instance but returns only the instance details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.get_instance myinstance .ft P .fi .UNINDENT .UNINDENT .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {{ salt[\(aqcloud.get_instance\(aq](\(aqmyinstance\(aq)[\(aqmac_address\(aq] }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.has_instance(name, provider=None) Return true if the instance is found on a provider .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.has_instance myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.list_images(provider=\(aqall\(aq) List cloud provider images for the given providers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.list_images my\-gce\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.list_locations(provider=\(aqall\(aq) List cloud provider locations for the given providers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.list_locations my\-gce\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.list_sizes(provider=\(aqall\(aq) List cloud provider sizes for the given providers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.list_sizes my\-gce\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.map_run(path=None, **kwargs) Execute a salt cloud map file .sp Cloud Map data can be retrieved from several sources: .INDENT 7.0 .IP \(bu 2 a local file (provide the path to the file to the \(aqpath\(aq argument) .IP \(bu 2 a JSON\-formatted map directly (provide the appropriately formatted to using the \(aqmap_data\(aq argument) .IP \(bu 2 the Salt Pillar (provide the map name of under \(aqpillar:cloud:maps\(aq to the \(aqmap_pillar\(aq argument) .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Only one of these sources can be read at a time. The options are listed in their order of precedence. .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.map_run /path/to/cloud.map salt minionname cloud.map_run path=/path/to/cloud.map salt minionname cloud.map_run map_pillar=\(aq<map_pillar>\(aq .. versionchanged:: 2018.3.1 salt minionname cloud.map_run map_data=\(aq<actual map data>\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.network_create(provider, names, **kwargs) Create private network .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.network_create my\-nova names=[\(aqsalt\(aq] cidr=\(aq192.168.100.0/24\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.network_list(provider) List private networks .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.network_list my\-nova .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.profile_(profile, names, vm_overrides=None, opts=None, **kwargs) Spin up an instance using Salt Cloud .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.profile my\-gce\-config myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.query(query_type=\(aqlist_nodes\(aq) List cloud provider data for all providers .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.query salt minionname cloud.query list_nodes_full salt minionname cloud.query list_nodes_select .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.select_query(query_type=\(aqlist_nodes_select\(aq) List selected nodes .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.select_query .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.virtual_interface_create(provider, names, **kwargs) Attach private interfaces to a server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.virtual_interface_create my\-nova names=[\(aqsalt\-master\(aq] net_name=\(aqsalt\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.virtual_interface_list(provider, names, **kwargs) List virtual interfaces on a server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.virtual_interface_list my\-nova names=[\(aqsalt\-master\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.volume_attach(provider, names, **kwargs) Attach volume to a server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.volume_attach my\-nova myblock server_name=myserver device=\(aq/dev/xvdf\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.volume_create(provider, names, **kwargs) Create volume .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.volume_create my\-nova myblock size=100 voltype=SSD .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.volume_delete(provider, names, **kwargs) Delete volume .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.volume_delete my\-nova myblock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.volume_detach(provider, names, **kwargs) Detach volume from a server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.volume_detach my\-nova myblock server_name=myserver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.volume_list(provider) List block storage volumes .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.volume_list my\-nova .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.cmdmod .sp A module for shelling out. .sp Keep in mind that this module is insecure, in that it can give whomever has access to the master root execution access to all salt minions. .INDENT 0.0 .TP .B salt.modules.cmdmod.exec_code(lang, code, cwd=None, args=None, **kwargs) Pass in two strings, the first naming the executable language, aka \- python2, python3, ruby, perl, lua, etc. the second string containing the code you wish to execute. The stdout will be returned. .sp All parameters from \fI\%cmd.run_all\fP except python_shell can be used. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.exec_code ruby \(aqputs \(dqcheese\(dq\(aq salt \(aq*\(aq cmd.exec_code ruby \(aqputs \(dqcheese\(dq\(aq args=\(aq[\(dqarg1\(dq, \(dqarg2\(dq]\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.exec_code_all(lang, code, cwd=None, args=None, **kwargs) Pass in two strings, the first naming the executable language, aka \- python2, python3, ruby, perl, lua, etc. the second string containing the code you wish to execute. All cmd artifacts (stdout, stderr, retcode, pid) will be returned. .sp All parameters from \fI\%cmd.run_all\fP except python_shell can be used. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.exec_code_all ruby \(aqputs \(dqcheese\(dq\(aq salt \(aq*\(aq cmd.exec_code_all ruby \(aqputs \(dqcheese\(dq\(aq args=\(aq[\(dqarg1\(dq, \(dqarg2\(dq]\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.has_exec(cmd) Returns true if the executable is available on the minion, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.has_exec cat .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.powershell(cmd, cwd=None, stdin=None, runas=None, shell=\(aqpowershell\(aq, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel=\(aqdebug\(aq, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, password=None, depth=None, encode_cmd=False, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Execute the passed PowerShell command and return the output as a dictionary. .sp Other \fBcmd.*\fP functions (besides \fBcmd.powershell_all\fP) return the raw text output of the command. This function appends \fB| ConvertTo\-JSON\fP to the command and then parses the JSON into a Python dictionary. If you want the raw textual result of your PowerShell command you should use \fBcmd.run\fP with the \fBshell=powershell\fP option. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run \(aq$PSVersionTable.CLRVersion\(aq shell=powershell salt \(aq*\(aq cmd.run \(aqGet\-NetTCPConnection\(aq shell=powershell .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This passes the cmd argument directly to PowerShell without any further processing! Be absolutely sure that you have properly sanitized the command passed to this function and do not use untrusted inputs. .UNINDENT .UNINDENT .sp In addition to the normal \fBcmd.run\fP parameters, this command offers the \fBdepth\fP parameter to change the Windows default depth for the \fBConvertTo\-JSON\fP powershell command. The Windows default is 2. If you need more depth, set that here. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For some commands, setting the depth to a value greater than 4 greatly increases the time it takes for the command to return and in many cases returns useless data. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcmd\fP (\fI\%str\fP) \-\- The powershell command to run. .IP \(bu 2 \fBcwd\fP (\fI\%str\fP) \-\- The directory from which to execute the command. Defaults to the home directory of the user specified by \fBrunas\fP (or the user under which Salt is running if \fBrunas\fP is not specified). .IP \(bu 2 \fBstdin\fP (\fI\%str\fP) \-\- A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. If running on a Windows minion you must also use the \fBpassword\fP argument, and the target user account must be in the Administrators group. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- .sp Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .sp New in version 2016.3.0. .IP \(bu 2 \fBshell\fP (\fI\%str\fP) \-\- Specify an alternate shell. Defaults to \(dqpowershell\(dq. Can also use \(dqpwsh\(dq for powershell core if present on the system .IP \(bu 2 \fBpython_shell\fP (\fI\%bool\fP) \-\- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection. .IP \(bu 2 \fBenv\fP (\fI\%dict\fP) \-\- .sp Environment variables to be set prior to execution. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When passing environment variables on the CLI, they should be passed as the string representation of a dictionary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.powershell \(aqsome command\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When using environment variables on Window\(aqs, case\-sensitivity matters, i.e. Window\(aqs uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .IP \(bu 2 \fBclean_env\fP (\fI\%bool\fP) \-\- Attempt to clean out all other shell environment variables and set only those provided in the \(aqenv\(aq argument to this function. .IP \(bu 2 \fBtemplate\fP (\fI\%str\fP) \-\- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported. .IP \(bu 2 \fBrstrip\fP (\fI\%bool\fP) \-\- Strip all whitespace off the end of output before it is returned. .IP \(bu 2 \fBumask\fP (\fI\%str\fP) \-\- The umask (in octal) to use when running the command. .IP \(bu 2 \fBoutput_encoding\fP (\fI\%str\fP) \-\- .sp Control the encoding used to decode the command\(aqs output. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This should not need to be used in most cases. By default, Salt will try to use the encoding detected from the system locale, and will fall back to UTF\-8 if this fails. This should only need to be used in cases where the output of the command is encoded in something other than the system locale or UTF\-8. .sp To see the encoding Salt has detected from the system locale, check the \fIlocale\fP line in the output of \fI\%test.versions_report\fP\&. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBoutput_loglevel\fP (\fI\%str\fP) \-\- .sp Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_retcode\fP (\fI\%bool\fP) \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBhide_output\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP, suppress stdout and stderr in the return data. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- A timeout in seconds for the executed process to return. .IP \(bu 2 \fBuse_vt\fP (\fI\%bool\fP) \-\- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .IP \(bu 2 \fBreset_system_locale\fP (\fI\%bool\fP) \-\- Resets the system locale .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- The salt environment to use. Default is \(aqbase\(aq .IP \(bu 2 \fBdepth\fP (\fI\%int\fP) \-\- .sp The number of levels of contained objects to be included. Default is 2. Values greater than 4 seem to greatly increase the time it takes for the command to complete for some commands. eg: \fBdir\fP .sp New in version 2016.3.4. .IP \(bu 2 \fBencode_cmd\fP (\fI\%bool\fP) \-\- Encode the command before executing. Use in cases where characters may be dropped or incorrectly converted when executed. Default is False. .IP \(bu 2 \fBsuccess_retcodes\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of non\-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBsuccess_stdout\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBsuccess_stderr\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBstdin_raw_newlines\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B False If \fBTrue\fP, Salt will not automatically convert the characters \fB\en\fP present in the \fBstdin\fP value to newlines. .UNINDENT .sp New in version 2019.2.0. .UNINDENT .TP .B Returns .INDENT 7.0 .TP .B dict A dictionary of data returned by the powershell command. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.powershell \(dq$PSVersionTable.CLRVersion\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.powershell_all(cmd, cwd=None, stdin=None, runas=None, shell=\(aqpowershell\(aq, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel=\(aqdebug\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, password=None, depth=None, encode_cmd=False, force_list=False, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Execute the passed PowerShell command and return a dictionary with a result field representing the output of the command, as well as other fields showing us what the PowerShell invocation wrote to \fBstderr\fP, the process id, and the exit code of the invocation. .sp This function appends \fB| ConvertTo\-JSON\fP to the command before actually invoking powershell. .sp An unquoted empty string is not valid JSON, but it\(aqs very normal for the Powershell output to be exactly that. Therefore, we do not attempt to parse empty Powershell output (which would result in an exception). Instead we treat this as a special case and one of two things will happen: .INDENT 7.0 .IP \(bu 2 If the value of the \fBforce_list\fP parameter is \fBTrue\fP, then the \fBresult\fP field of the return dictionary will be an empty list. .IP \(bu 2 If the value of the \fBforce_list\fP parameter is \fBFalse\fP, then the return dictionary \fBwill not have a result key added to it\fP\&. We aren\(aqt setting \fBresult\fP to \fBNone\fP in this case, because \fBNone\fP is the Python representation of \(dqnull\(dq in JSON. (We likewise can\(aqt use \fBFalse\fP for the equivalent reason.) .UNINDENT .sp If Powershell\(aqs output is not an empty string and Python cannot parse its content, then a \fBCommandExecutionError\fP exception will be raised. .sp If Powershell\(aqs output is not an empty string, Python is able to parse its content, and the type of the resulting Python object is other than \fBlist\fP then one of two things will happen: .INDENT 7.0 .IP \(bu 2 If the value of the \fBforce_list\fP parameter is \fBTrue\fP, then the \fBresult\fP field will be a singleton list with the Python object as its sole member. .IP \(bu 2 If the value of the \fBforce_list\fP parameter is \fBFalse\fP, then the value of \fBresult\fP will be the unmodified Python object. .UNINDENT .sp If Powershell\(aqs output is not an empty string, Python is able to parse its content, and the type of the resulting Python object is \fBlist\fP, then the value of \fBresult\fP will be the unmodified Python object. The \fBforce_list\fP parameter has no effect in this case. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 An example of why the \fBforce_list\fP parameter is useful is as follows: The Powershell command \fBdir x | Convert\-ToJson\fP results in .INDENT 0.0 .IP \(bu 2 no output when x is an empty directory. .IP \(bu 2 a dictionary object when x contains just one item. .IP \(bu 2 a list of dictionary objects when x contains multiple items. .UNINDENT .sp By setting \fBforce_list\fP to \fBTrue\fP we will always end up with a list of dictionary items, representing files, no matter how many files x contains. Conversely, if \fBforce_list\fP is \fBFalse\fP, we will end up with no \fBresult\fP key in our return dictionary when x is an empty directory, and a dictionary object when x contains just one file. .UNINDENT .UNINDENT .sp If you want a similar function but with a raw textual result instead of a Python dictionary, you should use \fBcmd.run_all\fP in combination with \fBshell=powershell\fP\&. .sp The remaining fields in the return dictionary are described in more detail in the \fBReturns\fP section. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_all \(aq$PSVersionTable.CLRVersion\(aq shell=powershell salt \(aq*\(aq cmd.run_all \(aqGet\-NetTCPConnection\(aq shell=powershell .ft P .fi .UNINDENT .UNINDENT .sp New in version 2018.3.0. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This passes the cmd argument directly to PowerShell without any further processing! Be absolutely sure that you have properly sanitized the command passed to this function and do not use untrusted inputs. .UNINDENT .UNINDENT .sp In addition to the normal \fBcmd.run\fP parameters, this command offers the \fBdepth\fP parameter to change the Windows default depth for the \fBConvertTo\-JSON\fP powershell command. The Windows default is 2. If you need more depth, set that here. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For some commands, setting the depth to a value greater than 4 greatly increases the time it takes for the command to return and in many cases returns useless data. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcmd\fP (\fI\%str\fP) \-\- The powershell command to run. .IP \(bu 2 \fBcwd\fP (\fI\%str\fP) \-\- The directory from which to execute the command. Defaults to the home directory of the user specified by \fBrunas\fP (or the user under which Salt is running if \fBrunas\fP is not specified). .IP \(bu 2 \fBstdin\fP (\fI\%str\fP) \-\- A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. If running on a Windows minion you must also use the \fBpassword\fP argument, and the target user account must be in the Administrators group. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .IP \(bu 2 \fBshell\fP (\fI\%str\fP) \-\- Specify an alternate shell. Defaults to \(dqpowershell\(dq. Can also use \(dqpwsh\(dq for powershell core if present on the system .IP \(bu 2 \fBpython_shell\fP (\fI\%bool\fP) \-\- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection. .IP \(bu 2 \fBenv\fP (\fI\%dict\fP) \-\- .sp Environment variables to be set prior to execution. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When passing environment variables on the CLI, they should be passed as the string representation of a dictionary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.powershell_all \(aqsome command\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When using environment variables on Window\(aqs, case\-sensitivity matters, i.e. Window\(aqs uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .IP \(bu 2 \fBclean_env\fP (\fI\%bool\fP) \-\- Attempt to clean out all other shell environment variables and set only those provided in the \(aqenv\(aq argument to this function. .IP \(bu 2 \fBtemplate\fP (\fI\%str\fP) \-\- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported. .IP \(bu 2 \fBrstrip\fP (\fI\%bool\fP) \-\- Strip all whitespace off the end of output before it is returned. .IP \(bu 2 \fBumask\fP (\fI\%str\fP) \-\- The umask (in octal) to use when running the command. .IP \(bu 2 \fBoutput_encoding\fP (\fI\%str\fP) \-\- .sp Control the encoding used to decode the command\(aqs output. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This should not need to be used in most cases. By default, Salt will try to use the encoding detected from the system locale, and will fall back to UTF\-8 if this fails. This should only need to be used in cases where the output of the command is encoded in something other than the system locale or UTF\-8. .sp To see the encoding Salt has detected from the system locale, check the \fIlocale\fP line in the output of \fI\%test.versions_report\fP\&. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBoutput_loglevel\fP (\fI\%str\fP) \-\- .sp Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_retcode\fP (\fI\%bool\fP) \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- A timeout in seconds for the executed process to return. .IP \(bu 2 \fBuse_vt\fP (\fI\%bool\fP) \-\- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .IP \(bu 2 \fBreset_system_locale\fP (\fI\%bool\fP) \-\- Resets the system locale .IP \(bu 2 \fBignore_retcode\fP \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- The salt environment to use. Default is \(aqbase\(aq .IP \(bu 2 \fBdepth\fP (\fI\%int\fP) \-\- The number of levels of contained objects to be included. Default is 2. Values greater than 4 seem to greatly increase the time it takes for the command to complete for some commands. eg: \fBdir\fP .IP \(bu 2 \fBencode_cmd\fP (\fI\%bool\fP) \-\- Encode the command before executing. Use in cases where characters may be dropped or incorrectly converted when executed. Default is False. .IP \(bu 2 \fBforce_list\fP (\fI\%bool\fP) \-\- The purpose of this parameter is described in the preamble of this function\(aqs documentation. Default value is False. .IP \(bu 2 \fBsuccess_retcodes\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of non\-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBsuccess_stdout\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBsuccess_stderr\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBstdin_raw_newlines\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B False If \fBTrue\fP, Salt will not automatically convert the characters \fB\en\fP present in the \fBstdin\fP value to newlines. .UNINDENT .sp New in version 2019.2.0. .UNINDENT .TP .B Returns A dictionary with the following entries: .INDENT 7.0 .TP .B result For a complete description of this field, please refer to this function\(aqs preamble. \fBThis key will not be added to the dictionary when force_list is False and Powershell\(aqs output is the empty string.\fP .TP .B stderr What the PowerShell invocation wrote to \fBstderr\fP\&. .TP .B pid The process id of the PowerShell invocation .TP .B retcode This is the exit code of the invocation of PowerShell. If the final execution status (in PowerShell) of our command (with \fB| ConvertTo\-JSON\fP appended) is \fBFalse\fP this should be non\-0. Likewise if PowerShell exited with \fB$LASTEXITCODE\fP set to some non\-0 value, then \fBretcode\fP will end up with this value. .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.powershell_all \(dq$PSVersionTable.CLRVersion\(dq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.powershell_all \(dqdir mydirectory\(dq force_list=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.retcode(cmd, cwd=None, stdin=None, runas=None, group=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, umask=None, output_encoding=None, output_loglevel=\(aqdebug\(aq, log_callback=None, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, password=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Execute a shell command and return the command\(aqs return code. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcmd\fP (\fI\%str\fP) \-\- The command to run. ex: \fBls \-lart /home\fP .IP \(bu 2 \fBcwd\fP (\fI\%str\fP) \-\- The directory from which to execute the command. Defaults to the home directory of the user specified by \fBrunas\fP (or the user under which Salt is running if \fBrunas\fP is not specified). .IP \(bu 2 \fBstdin\fP (\fI\%str\fP) \-\- A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- .sp Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. If running on a Windows minion you must also use the \fBpassword\fP argument, and the target user account must be in the Administrators group. .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 For versions 2018.3.3 and above on macosx while using runas, to pass special characters to the command you need to escape the characters on the shell. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmd.retcode \(aqecho \(aq\e\(aq\(aqh=\e\(dqbaz\e\(dq\(aq\e\(aq\(aq\(aq runas=macuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- .sp Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .sp New in version 2016.3.0. .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- Group to run command as. Not currently supported on Windows. .IP \(bu 2 \fBshell\fP (\fI\%str\fP) \-\- Specify an alternate shell. Defaults to the system\(aqs default shell. .IP \(bu 2 \fBpython_shell\fP (\fI\%bool\fP) \-\- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection. .IP \(bu 2 \fBenv\fP (\fI\%dict\fP) \-\- .sp Environment variables to be set prior to execution. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When passing environment variables on the CLI, they should be passed as the string representation of a dictionary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.retcode \(aqsome command\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When using environment variables on Window\(aqs, case\-sensitivity matters, i.e. Window\(aqs uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .IP \(bu 2 \fBclean_env\fP (\fI\%bool\fP) \-\- Attempt to clean out all other shell environment variables and set only those provided in the \(aqenv\(aq argument to this function. .IP \(bu 2 \fBtemplate\fP (\fI\%str\fP) \-\- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported. .IP \(bu 2 \fBrstrip\fP (\fI\%bool\fP) \-\- Strip all whitespace off the end of output before it is returned. .IP \(bu 2 \fBumask\fP (\fI\%str\fP) \-\- The umask (in octal) to use when running the command. .IP \(bu 2 \fBoutput_encoding\fP (\fI\%str\fP) \-\- .sp Control the encoding used to decode the command\(aqs output. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This should not need to be used in most cases. By default, Salt will try to use the encoding detected from the system locale, and will fall back to UTF\-8 if this fails. This should only need to be used in cases where the output of the command is encoded in something other than the system locale or UTF\-8. .sp To see the encoding Salt has detected from the system locale, check the \fIlocale\fP line in the output of \fI\%test.versions_report\fP\&. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBoutput_loglevel\fP (\fI\%str\fP) \-\- .sp Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_retcode\fP (\fI\%bool\fP) \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- A timeout in seconds for the executed process to return. .IP \(bu 2 \fBuse_vt\fP (\fI\%bool\fP) \-\- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .IP \(bu 2 \fBsuccess_retcodes\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of non\-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBsuccess_stdout\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBsuccess_stderr\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBstdin_raw_newlines\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B False If \fBTrue\fP, Salt will not automatically convert the characters \fB\en\fP present in the \fBstdin\fP value to newlines. .UNINDENT .sp New in version 2019.2.0. .UNINDENT .TP .B Return type \fI\%int\fP .TP .B Return type None .TP .B Returns Return Code as an int or None if there was an exception. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.retcode \(dqfile /bin/bash\(dq .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.retcode template=jinja \(dqfile {{grains.pythonpath[0]}}/python\(dq .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.retcode \(dqgrep f\(dq stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run(cmd, cwd=None, stdin=None, runas=None, group=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel=\(aqdebug\(aq, log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, redirect_stderr=True, bg=False, password=None, encoded_cmd=False, raise_err=False, prepend_path=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Execute the passed command and return the output as a string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcmd\fP (\fI\%str\fP) \-\- The command to run. ex: \fBls \-lart /home\fP .IP \(bu 2 \fBcwd\fP (\fI\%str\fP) \-\- The directory from which to execute the command. Defaults to the home directory of the user specified by \fBrunas\fP (or the user under which Salt is running if \fBrunas\fP is not specified). .IP \(bu 2 \fBstdin\fP (\fI\%str\fP) \-\- A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- .sp Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 For versions 2018.3.3 and above on macosx while using runas, on linux while using run, to pass special characters to the command you need to escape the characters on the shell. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmd.run \(aqecho \(aq\e\(aq\(aqh=\e\(dqbaz\e\(dq\(aq\e\(aq\(aq\(aq runas=macuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- Group to run command as. Not currently supported on Windows. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- .sp Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .sp New in version 2016.3.0. .IP \(bu 2 \fBshell\fP (\fI\%str\fP) \-\- Specify an alternate shell. Defaults to the system\(aqs default shell. .IP \(bu 2 \fBpython_shell\fP (\fI\%bool\fP) \-\- If \fBFalse\fP, let python handle the positional arguments. Set to \fBTrue\fP to use shell features, such as pipes or redirection. .IP \(bu 2 \fBbg\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP, run command in background and do not await or deliver its results .sp New in version 2016.3.0. .IP \(bu 2 \fBenv\fP (\fI\%dict\fP) \-\- .sp Environment variables to be set prior to execution. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When passing environment variables on the CLI, they should be passed as the string representation of a dictionary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.run \(aqsome command\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When using environment variables on Window\(aqs, case\-sensitivity matters, i.e. Window\(aqs uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .IP \(bu 2 \fBclean_env\fP (\fI\%bool\fP) \-\- Attempt to clean out all other shell environment variables and set only those provided in the \(aqenv\(aq argument to this function. .IP \(bu 2 \fBprepend_path\fP (\fI\%str\fP) \-\- .sp $PATH segment to prepend (trailing \(aq:\(aq not necessary) to $PATH .sp New in version 2018.3.0. .IP \(bu 2 \fBtemplate\fP (\fI\%str\fP) \-\- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported. .IP \(bu 2 \fBrstrip\fP (\fI\%bool\fP) \-\- Strip all whitespace off the end of output before it is returned. .IP \(bu 2 \fBumask\fP (\fI\%str\fP) \-\- The umask (in octal) to use when running the command. .IP \(bu 2 \fBoutput_encoding\fP (\fI\%str\fP) \-\- .sp Control the encoding used to decode the command\(aqs output. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This should not need to be used in most cases. By default, Salt will try to use the encoding detected from the system locale, and will fall back to UTF\-8 if this fails. This should only need to be used in cases where the output of the command is encoded in something other than the system locale or UTF\-8. .sp To see the encoding Salt has detected from the system locale, check the \fIlocale\fP line in the output of \fI\%test.versions_report\fP\&. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBoutput_loglevel\fP (\fI\%str\fP) \-\- .sp Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_retcode\fP (\fI\%bool\fP) \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBhide_output\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP, suppress stdout and stderr in the return data. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- A timeout in seconds for the executed process to return. .IP \(bu 2 \fBuse_vt\fP (\fI\%bool\fP) \-\- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .IP \(bu 2 \fBredirect_stderr\fP (\fI\%bool\fP) \-\- .sp If set to \fBTrue\fP, then stderr will be redirected to stdout. This is helpful for cases where obtaining both the retcode and output is desired. Default is \fBTrue\fP .sp New in version 3006.9. .IP \(bu 2 \fBencoded_cmd\fP (\fI\%bool\fP) \-\- .sp Specify if the supplied command is encoded. Only applies to shell \(aqpowershell\(aq and \(aqpwsh\(aq. .sp New in version 2018.3.0. .sp Older versions of powershell seem to return raw xml data in the return. To avoid raw xml data in the return, prepend your command with the following before encoding: .sp \fI$ProgressPreference=\(aqSilentlyContinue\(aq; <your command>\fP .sp The following powershell code block will encode the \fIWrite\-Output\fP command so that it will not have the raw xml data in the return: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C # target string $Command = \(aq$ProgressPreference=\(dqSilentlyContinue\(dq; Write\-Output \(dqhello\(dq\(aq # Convert to Base64 encoded string $Encoded = [convert]::ToBase64String([System.Text.encoding]::Unicode.GetBytes($command)) Write\-Output $Encoded .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBraise_err\fP (\fI\%bool\fP) \-\- If \fBTrue\fP and the command has a nonzero exit code, a CommandExecutionError exception will be raised. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This function does not process commands through a shell unless the python_shell flag is set to True. This means that any shell\-specific functionality such as \(aqecho\(aq or the use of pipes, redirection or &&, should either be migrated to cmd.shell or have the python_shell=True flag set here. .sp The use of python_shell=True means that the shell will accept _any_ input including potentially malicious commands such as \(aqgood_command;rm \-rf /\(aq. Be absolutely certain that you have sanitized your input prior to using python_shell=True .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsuccess_retcodes\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of non\-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBsuccess_stdout\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBsuccess_stderr\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBstdin_raw_newlines\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B False If \fBTrue\fP, Salt will not automatically convert the characters \fB\e\en\fP present in the \fBstdin\fP value to newlines. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBwindows_codepage\fP (\fI\%int\fP) \-\- .INDENT 2.0 .TP .B 65001 Only applies to Windows: the minion uses \fIC:WindowsSystem32chcp.com\fP to verify or set the code page before the command \fIcmd\fP is executed. Code page 65001 corresponds with UTF\-8 and allows international localization of Windows. .UNINDENT .sp New in version 3002. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run \(dqls \-l | awk \(aq/foo/{print \e\e$2}\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run template=jinja \(dqls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e\e$2}\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .sp Specify an alternate shell with the shell parameter: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run \(dqGet\-ChildItem C:\e\e \(dq shell=\(aqpowershell\(aq .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run \(dqgrep f\(dq stdin=\(aqone\e\entwo\e\enthree\e\enfour\e\enfive\e\en\(aq .ft P .fi .UNINDENT .UNINDENT .sp If an equal sign (\fB=\fP) appears in an argument to a Salt command it is interpreted as a keyword argument in the format \fBkey=val\fP\&. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run cmd=\(aqsed \-e s/=/:/g\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_all(cmd, cwd=None, stdin=None, runas=None, group=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel=\(aqdebug\(aq, log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, redirect_stderr=False, password=None, encoded_cmd=False, prepend_path=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Execute the passed command and return a dict of return data .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcmd\fP (\fI\%str\fP) \-\- The command to run. ex: \fBls \-lart /home\fP .IP \(bu 2 \fBcwd\fP (\fI\%str\fP) \-\- The directory from which to execute the command. Defaults to the home directory of the user specified by \fBrunas\fP (or the user under which Salt is running if \fBrunas\fP is not specified). .IP \(bu 2 \fBstdin\fP (\fI\%str\fP) \-\- A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- .sp Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. If running on a Windows minion you must also use the \fBpassword\fP argument, and the target user account must be in the Administrators group. .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 For versions 2018.3.3 and above on macosx while using runas, to pass special characters to the command you need to escape the characters on the shell. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmd.run_all \(aqecho \(aq\e\(aq\(aqh=\e\(dqbaz\e\(dq\(aq\e\(aq\(aq\(aq runas=macuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- .sp Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .sp New in version 2016.3.0. .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- Group to run command as. Not currently supported on Windows. .IP \(bu 2 \fBshell\fP (\fI\%str\fP) \-\- Specify an alternate shell. Defaults to the system\(aqs default shell. .IP \(bu 2 \fBpython_shell\fP (\fI\%bool\fP) \-\- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection. .IP \(bu 2 \fBenv\fP (\fI\%dict\fP) \-\- .sp Environment variables to be set prior to execution. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When passing environment variables on the CLI, they should be passed as the string representation of a dictionary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.run_all \(aqsome command\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When using environment variables on Window\(aqs, case\-sensitivity matters, i.e. Window\(aqs uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .IP \(bu 2 \fBclean_env\fP (\fI\%bool\fP) \-\- Attempt to clean out all other shell environment variables and set only those provided in the \(aqenv\(aq argument to this function. .IP \(bu 2 \fBprepend_path\fP (\fI\%str\fP) \-\- .sp $PATH segment to prepend (trailing \(aq:\(aq not necessary) to $PATH .sp New in version 2018.3.0. .IP \(bu 2 \fBtemplate\fP (\fI\%str\fP) \-\- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported. .IP \(bu 2 \fBrstrip\fP (\fI\%bool\fP) \-\- Strip all whitespace off the end of output before it is returned. .IP \(bu 2 \fBumask\fP (\fI\%str\fP) \-\- The umask (in octal) to use when running the command. .IP \(bu 2 \fBoutput_encoding\fP (\fI\%str\fP) \-\- .sp Control the encoding used to decode the command\(aqs output. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This should not need to be used in most cases. By default, Salt will try to use the encoding detected from the system locale, and will fall back to UTF\-8 if this fails. This should only need to be used in cases where the output of the command is encoded in something other than the system locale or UTF\-8. .sp To see the encoding Salt has detected from the system locale, check the \fIlocale\fP line in the output of \fI\%test.versions_report\fP\&. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBoutput_loglevel\fP (\fI\%str\fP) \-\- .sp Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_retcode\fP (\fI\%bool\fP) \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBhide_output\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP, suppress stdout and stderr in the return data. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- A timeout in seconds for the executed process to return. .IP \(bu 2 \fBuse_vt\fP (\fI\%bool\fP) \-\- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .IP \(bu 2 \fBencoded_cmd\fP (\fI\%bool\fP) \-\- .sp Specify if the supplied command is encoded. Only applies to shell \(aqpowershell\(aq and \(aqpwsh\(aq. .sp New in version 2018.3.0. .sp Older versions of powershell seem to return raw xml data in the return. To avoid raw xml data in the return, prepend your command with the following before encoding: .sp \fI$ProgressPreference=\(aqSilentlyContinue\(aq; <your command>\fP .sp The following powershell code block will encode the \fIWrite\-Output\fP command so that it will not have the raw xml data in the return: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C # target string $Command = \(aq$ProgressPreference=\(dqSilentlyContinue\(dq; Write\-Output \(dqhello\(dq\(aq # Convert to Base64 encoded string $Encoded = [convert]::ToBase64String([System.Text.encoding]::Unicode.GetBytes($command)) Write\-Output $Encoded .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBredirect_stderr\fP (\fI\%bool\fP) \-\- .sp If set to \fBTrue\fP, then stderr will be redirected to stdout. This is helpful for cases where obtaining both the retcode and output is desired, but it is not desired to have the output separated into both stdout and stderr. .sp New in version 2015.8.2. .IP \(bu 2 \fBpassword\fP \-\- .sp Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .INDENT 2.0 .INDENT 3.5 New in version 2016.3.0. .UNINDENT .UNINDENT .IP \(bu 2 \fBbg\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP, run command in background and do not await or deliver its results .sp New in version 2016.3.6. .IP \(bu 2 \fBsuccess_retcodes\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of non\-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBsuccess_stdout\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBsuccess_stderr\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBstdin_raw_newlines\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B False If \fBTrue\fP, Salt will not automatically convert the characters \fB\en\fP present in the \fBstdin\fP value to newlines. .UNINDENT .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_all \(dqls \-l | awk \(aq/foo/{print \e$2}\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_all template=jinja \(dqls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e$2}\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_all \(dqgrep f\(dq stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_bg(cmd, cwd=None, runas=None, group=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, umask=None, timeout=None, output_encoding=None, output_loglevel=\(aqdebug\(aq, log_callback=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, password=None, prepend_path=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) New in version 2016.3.0. .sp Execute the passed command in the background and return its PID .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the init system is systemd and the backgrounded task should run even if the salt\-minion process is restarted, prepend \fBsystemd\-run \-\-scope\fP to the command. This will reparent the process in its own scope separate from salt\-minion, and will not be affected by restarting the minion service. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcmd\fP (\fI\%str\fP) \-\- The command to run. ex: \fBls \-lart /home\fP .IP \(bu 2 \fBcwd\fP (\fI\%str\fP) \-\- The directory from which to execute the command. Defaults to the home directory of the user specified by \fBrunas\fP (or the user under which Salt is running if \fBrunas\fP is not specified). .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- Group to run command as. Not currently supported on Windows. .IP \(bu 2 \fBshell\fP (\fI\%str\fP) \-\- Shell to execute under. Defaults to the system default shell. .IP \(bu 2 \fBoutput_encoding\fP (\fI\%str\fP) \-\- .sp Control the encoding used to decode the command\(aqs output. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This should not need to be used in most cases. By default, Salt will try to use the encoding detected from the system locale, and will fall back to UTF\-8 if this fails. This should only need to be used in cases where the output of the command is encoded in something other than the system locale or UTF\-8. .sp To see the encoding Salt has detected from the system locale, check the \fIlocale\fP line in the output of \fI\%test.versions_report\fP\&. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBoutput_loglevel\fP (\fI\%str\fP) \-\- .sp Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_retcode\fP (\fI\%bool\fP) \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- .sp Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. If running on a Windows minion you must also use the \fBpassword\fP argument, and the target user account must be in the Administrators group. .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 For versions 2018.3.3 and above on macosx while using runas, to pass special characters to the command you need to escape the characters on the shell. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmd.run_bg \(aqecho \(aq\e\(aq\(aqh=\e\(dqbaz\e\(dq\(aq\e\(aq\(aq\(aq runas=macuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- .sp Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .sp New in version 2016.3.0. .IP \(bu 2 \fBshell\fP \-\- Specify an alternate shell. Defaults to the system\(aqs default shell. .IP \(bu 2 \fBpython_shell\fP (\fI\%bool\fP) \-\- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection. .IP \(bu 2 \fBenv\fP (\fI\%dict\fP) \-\- .sp Environment variables to be set prior to execution. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When passing environment variables on the CLI, they should be passed as the string representation of a dictionary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.run_bg \(aqsome command\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When using environment variables on Window\(aqs, case\-sensitivity matters, i.e. Window\(aqs uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .IP \(bu 2 \fBclean_env\fP (\fI\%bool\fP) \-\- Attempt to clean out all other shell environment variables and set only those provided in the \(aqenv\(aq argument to this function. .IP \(bu 2 \fBprepend_path\fP (\fI\%str\fP) \-\- .sp $PATH segment to prepend (trailing \(aq:\(aq not necessary) to $PATH .sp New in version 2018.3.0. .IP \(bu 2 \fBtemplate\fP (\fI\%str\fP) \-\- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported. .IP \(bu 2 \fBumask\fP (\fI\%str\fP) \-\- The umask (in octal) to use when running the command. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- A timeout in seconds for the executed process to return. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This function does not process commands through a shell unless the \fBpython_shell\fP argument is set to \fBTrue\fP\&. This means that any shell\-specific functionality such as \(aqecho\(aq or the use of pipes, redirection or &&, should either be migrated to cmd.shell or have the python_shell=True flag set here. .sp The use of \fBpython_shell=True\fP means that the shell will accept _any_ input including potentially malicious commands such as \(aqgood_command;rm \-rf /\(aq. Be absolutely certain that you have sanitized your input prior to using \fBpython_shell=True\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsuccess_retcodes\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of non\-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBsuccess_stdout\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBsuccess_stderr\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBstdin_raw_newlines\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B False If \fBTrue\fP, Salt will not automatically convert the characters \fB\e\en\fP present in the \fBstdin\fP value to newlines. .UNINDENT .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_bg \(dqfstrim\-all\(dq .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_bg template=jinja \(dqls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e\e$2}\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .sp Specify an alternate shell with the shell parameter: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_bg \(dqGet\-ChildItem C:\e\e \(dq shell=\(aqpowershell\(aq .ft P .fi .UNINDENT .UNINDENT .sp If an equal sign (\fB=\fP) appears in an argument to a Salt command it is interpreted as a keyword argument in the format \fBkey=val\fP\&. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_bg cmd=\(aqls \-lR / | sed \-e s/=/:/g > /tmp/dontwait\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_chroot(root, cmd, cwd=None, stdin=None, runas=None, group=None, shell=\(aq/bin/bash\(aq, python_shell=True, binds=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel=\(aqquiet\(aq, log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, bg=False, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) New in version 2014.7.0. .sp This function runs \fI\%cmd.run_all\fP wrapped within a chroot, with dev and proc mounted in the chroot .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBroot\fP (\fI\%str\fP) \-\- Path to the root of the jail to use. .IP \(bu 2 \fBstdin\fP (\fI\%str\fP) \-\- A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input.: .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run script as. .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- Group to run script as. .IP \(bu 2 \fBshell\fP (\fI\%str\fP) \-\- Shell to execute under. Defaults to the system default shell. .IP \(bu 2 \fBcmd\fP (\fI\%str\fP) \-\- The command to run. ex: \fBls \-lart /home\fP .IP \(bu 2 \fBcwd\fP (\fI\%str\fP) \-\- The directory from which to execute the command. Defaults to the home directory of the user specified by \fBrunas\fP (or the user under which Salt is running if \fBrunas\fP is not specified). .IP \(bu 2 \fBrunas\fP \-\- Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. If running on a Windows minion you must also use the \fBpassword\fP argument, and the target user account must be in the Administrators group. .IP \(bu 2 \fBshell\fP \-\- Specify an alternate shell. Defaults to the system\(aqs default shell. .IP \(bu 2 \fBpython_shell\fP (\fI\%bool\fP) \-\- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection. .IP \(bu 2 \fBbinds\fP (\fI\%list\fP) \-\- .sp List of directories that will be exported inside the chroot with the bind option. .sp New in version 3000. .IP \(bu 2 \fBenv\fP (\fI\%dict\fP) \-\- .sp Environment variables to be set prior to execution. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When passing environment variables on the CLI, they should be passed as the string representation of a dictionary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.run_chroot \(aqsome command\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When using environment variables on Window\(aqs, case\-sensitivity matters, i.e. Window\(aqs uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .IP \(bu 2 \fBclean_env\fP (\fI\%dict\fP) \-\- Attempt to clean out all other shell environment variables and set only those provided in the \(aqenv\(aq argument to this function. .IP \(bu 2 \fBtemplate\fP (\fI\%str\fP) \-\- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported. .IP \(bu 2 \fBrstrip\fP (\fI\%bool\fP) \-\- Strip all whitespace off the end of output before it is returned. .IP \(bu 2 \fBumask\fP (\fI\%str\fP) \-\- The umask (in octal) to use when running the command. .IP \(bu 2 \fBoutput_encoding\fP (\fI\%str\fP) \-\- .sp Control the encoding used to decode the command\(aqs output. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This should not need to be used in most cases. By default, Salt will try to use the encoding detected from the system locale, and will fall back to UTF\-8 if this fails. This should only need to be used in cases where the output of the command is encoded in something other than the system locale or UTF\-8. .sp To see the encoding Salt has detected from the system locale, check the \fIlocale\fP line in the output of \fI\%test.versions_report\fP\&. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBoutput_loglevel\fP (\fI\%str\fP) \-\- .sp Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_retcode\fP (\fI\%bool\fP) \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBhide_output\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP, suppress stdout and stderr in the return data. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- A timeout in seconds for the executed process to return. .IP \(bu 2 \fBuse_vt\fP (\fI\%bool\fP) \-\- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .IP \(bu 2 \fBsuccess_retcodes\fP \-\- .INDENT 2.0 .TP .B This parameter will allow a list of non\-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBsuccess_stdout\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBsuccess_stderr\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .UNINDENT .TP .B Parar str stdin A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_chroot /var/lib/lxc/container_name/rootfs \(aqsh /tmp/bootstrap.sh\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_stderr(cmd, cwd=None, stdin=None, runas=None, group=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel=\(aqdebug\(aq, log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, password=None, prepend_path=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Execute a command and only return the standard error .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcmd\fP (\fI\%str\fP) \-\- The command to run. ex: \fBls \-lart /home\fP .IP \(bu 2 \fBcwd\fP (\fI\%str\fP) \-\- The directory from which to execute the command. Defaults to the home directory of the user specified by \fBrunas\fP (or the user under which Salt is running if \fBrunas\fP is not specified). .IP \(bu 2 \fBstdin\fP (\fI\%str\fP) \-\- A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- .sp Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. If running on a Windows minion you must also use the \fBpassword\fP argument, and the target user account must be in the Administrators group. .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 For versions 2018.3.3 and above on macosx while using runas, to pass special characters to the command you need to escape the characters on the shell. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmd.run_stderr \(aqecho \(aq\e\(aq\(aqh=\e\(dqbaz\e\(dq\(aq\e\(aq\(aq\(aq runas=macuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- .sp Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .sp New in version 2016.3.0. .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- Group to run command as. Not currently supported on Windows. .IP \(bu 2 \fBshell\fP (\fI\%str\fP) \-\- Specify an alternate shell. Defaults to the system\(aqs default shell. .IP \(bu 2 \fBpython_shell\fP (\fI\%bool\fP) \-\- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection. .IP \(bu 2 \fBenv\fP (\fI\%dict\fP) \-\- .sp Environment variables to be set prior to execution. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When passing environment variables on the CLI, they should be passed as the string representation of a dictionary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.run_stderr \(aqsome command\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When using environment variables on Window\(aqs, case\-sensitivity matters, i.e. Window\(aqs uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .IP \(bu 2 \fBclean_env\fP (\fI\%bool\fP) \-\- Attempt to clean out all other shell environment variables and set only those provided in the \(aqenv\(aq argument to this function. .IP \(bu 2 \fBprepend_path\fP (\fI\%str\fP) \-\- .sp $PATH segment to prepend (trailing \(aq:\(aq not necessary) to $PATH .sp New in version 2018.3.0. .IP \(bu 2 \fBtemplate\fP (\fI\%str\fP) \-\- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported. .IP \(bu 2 \fBrstrip\fP (\fI\%bool\fP) \-\- Strip all whitespace off the end of output before it is returned. .IP \(bu 2 \fBumask\fP (\fI\%str\fP) \-\- The umask (in octal) to use when running the command. .IP \(bu 2 \fBoutput_encoding\fP (\fI\%str\fP) \-\- .sp Control the encoding used to decode the command\(aqs output. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This should not need to be used in most cases. By default, Salt will try to use the encoding detected from the system locale, and will fall back to UTF\-8 if this fails. This should only need to be used in cases where the output of the command is encoded in something other than the system locale or UTF\-8. .sp To see the encoding Salt has detected from the system locale, check the \fIlocale\fP line in the output of \fI\%test.versions_report\fP\&. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBoutput_loglevel\fP (\fI\%str\fP) \-\- .sp Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_retcode\fP (\fI\%bool\fP) \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBhide_output\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP, suppress stdout and stderr in the return data. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- A timeout in seconds for the executed process to return. .IP \(bu 2 \fBuse_vt\fP (\fI\%bool\fP) \-\- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .IP \(bu 2 \fBsuccess_retcodes\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of non\-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBsuccess_stdout\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBsuccess_stderr\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBstdin_raw_newlines\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B False If \fBTrue\fP, Salt will not automatically convert the characters \fB\en\fP present in the \fBstdin\fP value to newlines. .UNINDENT .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_stderr \(dqls \-l | awk \(aq/foo/{print \e$2}\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_stderr template=jinja \(dqls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e$2}\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_stderr \(dqgrep f\(dq stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_stdout(cmd, cwd=None, stdin=None, runas=None, group=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel=\(aqdebug\(aq, log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, password=None, prepend_path=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Execute a command, and only return the standard out .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcmd\fP (\fI\%str\fP) \-\- The command to run. ex: \fBls \-lart /home\fP .IP \(bu 2 \fBcwd\fP (\fI\%str\fP) \-\- The directory from which to execute the command. Defaults to the home directory of the user specified by \fBrunas\fP (or the user under which Salt is running if \fBrunas\fP is not specified). .IP \(bu 2 \fBstdin\fP (\fI\%str\fP) \-\- A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- .sp Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. If running on a Windows minion you must also use the \fBpassword\fP argument, and the target user account must be in the Administrators group. .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 For versions 2018.3.3 and above on macosx while using runas, to pass special characters to the command you need to escape the characters on the shell. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmd.run_stdout \(aqecho \(aq\e\(aq\(aqh=\e\(dqbaz\e\(dq\(aq\e\(aq\(aq\(aq runas=macuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- .sp Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .sp New in version 2016.3.0. .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- Group to run command as. Not currently supported on Windows. .IP \(bu 2 \fBshell\fP (\fI\%str\fP) \-\- Specify an alternate shell. Defaults to the system\(aqs default shell. .IP \(bu 2 \fBpython_shell\fP (\fI\%bool\fP) \-\- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection. .IP \(bu 2 \fBenv\fP (\fI\%dict\fP) \-\- .sp Environment variables to be set prior to execution. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When passing environment variables on the CLI, they should be passed as the string representation of a dictionary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.run_stdout \(aqsome command\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When using environment variables on Window\(aqs, case\-sensitivity matters, i.e. Window\(aqs uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .IP \(bu 2 \fBclean_env\fP (\fI\%bool\fP) \-\- Attempt to clean out all other shell environment variables and set only those provided in the \(aqenv\(aq argument to this function. .IP \(bu 2 \fBprepend_path\fP (\fI\%str\fP) \-\- .sp $PATH segment to prepend (trailing \(aq:\(aq not necessary) to $PATH .sp New in version 2018.3.0. .IP \(bu 2 \fBtemplate\fP (\fI\%str\fP) \-\- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported. .IP \(bu 2 \fBrstrip\fP (\fI\%bool\fP) \-\- Strip all whitespace off the end of output before it is returned. .IP \(bu 2 \fBumask\fP (\fI\%str\fP) \-\- The umask (in octal) to use when running the command. .IP \(bu 2 \fBoutput_encoding\fP (\fI\%str\fP) \-\- .sp Control the encoding used to decode the command\(aqs output. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This should not need to be used in most cases. By default, Salt will try to use the encoding detected from the system locale, and will fall back to UTF\-8 if this fails. This should only need to be used in cases where the output of the command is encoded in something other than the system locale or UTF\-8. .sp To see the encoding Salt has detected from the system locale, check the \fIlocale\fP line in the output of \fI\%test.versions_report\fP\&. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBoutput_loglevel\fP (\fI\%str\fP) \-\- .sp Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_retcode\fP (\fI\%bool\fP) \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBhide_output\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP, suppress stdout and stderr in the return data. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- A timeout in seconds for the executed process to return. .IP \(bu 2 \fBuse_vt\fP (\fI\%bool\fP) \-\- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .IP \(bu 2 \fBsuccess_retcodes\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of non\-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBsuccess_stdout\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBsuccess_stderr\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBstdin_raw_newlines\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B False If \fBTrue\fP, Salt will not automatically convert the characters \fB\en\fP present in the \fBstdin\fP value to newlines. .UNINDENT .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_stdout \(dqls \-l | awk \(aq/foo/{print \e$2}\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_stdout template=jinja \(dqls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e$2}\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_stdout \(dqgrep f\(dq stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.script(source, args=None, cwd=None, stdin=None, runas=None, group=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, template=None, umask=None, output_encoding=None, output_loglevel=\(aqdebug\(aq, log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, saltenv=None, use_vt=False, bg=False, password=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Download a script from a remote location and execute the script locally. The script can be located on the salt master file server or on an HTTP/FTP server. .sp The script will be executed directly, so it can be written in any available programming language. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- The location of the script to download. If the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs .IP \(bu 2 \fBargs\fP (\fI\%str\fP) \-\- .sp String of command line args to pass to the script. Only used if no args are specified as part of the \fIname\fP argument. To pass a string containing spaces in YAML, you will need to doubly\-quote it: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.script salt://foo.sh \(dqarg1 \(aqarg two\(aq arg3\(dq .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBcwd\fP (\fI\%str\fP) \-\- The directory from which to execute the command. Defaults to the directory returned from Python\(aqs tempfile.mkstemp. .IP \(bu 2 \fBstdin\fP (\fI\%str\fP) \-\- A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- .sp Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. If running on a Windows minion you must also use the \fBpassword\fP argument, and the target user account must be in the Administrators group. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 For Window\(aqs users, specifically Server users, it may be necessary to specify your runas user using the User Logon Name instead of the legacy logon name. Traditionally, logons would be in the following format. .INDENT 0.0 .INDENT 3.5 \fBDomain/user\fP .UNINDENT .UNINDENT .sp In the event this causes issues when executing scripts, use the UPN format which looks like the following. .INDENT 0.0 .INDENT 3.5 \fBuser@domain.local\fP .UNINDENT .UNINDENT .sp More information <\fI\%https://github.com/saltstack/salt/issues/55080\fP> .UNINDENT .UNINDENT .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- .sp Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .sp New in version 2016.3.0. .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- Group to run script as. Not currently supported on Windows. .IP \(bu 2 \fBshell\fP (\fI\%str\fP) \-\- Specify an alternate shell. Defaults to the system\(aqs default shell. .IP \(bu 2 \fBpython_shell\fP (\fI\%bool\fP) \-\- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection. .IP \(bu 2 \fBbg\fP (\fI\%bool\fP) \-\- If True, run script in background and do not await or deliver its results .IP \(bu 2 \fBenv\fP (\fI\%dict\fP) \-\- .sp Environment variables to be set prior to execution. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When passing environment variables on the CLI, they should be passed as the string representation of a dictionary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.script \(aqsome command\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When using environment variables on Window\(aqs, case\-sensitivity matters, i.e. Window\(aqs uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .IP \(bu 2 \fBtemplate\fP (\fI\%str\fP) \-\- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported. .IP \(bu 2 \fBumask\fP (\fI\%str\fP) \-\- The umask (in octal) to use when running the command. .IP \(bu 2 \fBoutput_encoding\fP (\fI\%str\fP) \-\- .sp Control the encoding used to decode the command\(aqs output. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This should not need to be used in most cases. By default, Salt will try to use the encoding detected from the system locale, and will fall back to UTF\-8 if this fails. This should only need to be used in cases where the output of the command is encoded in something other than the system locale or UTF\-8. .sp To see the encoding Salt has detected from the system locale, check the \fIlocale\fP line in the output of \fI\%test.versions_report\fP\&. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBoutput_loglevel\fP (\fI\%str\fP) \-\- .sp Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_retcode\fP (\fI\%bool\fP) \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBhide_output\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP, suppress stdout and stderr in the return data. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- If the command has not terminated after timeout seconds, send the subprocess sigterm, and if sigterm is ignored, follow up with sigkill .IP \(bu 2 \fBuse_vt\fP (\fI\%bool\fP) \-\- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .IP \(bu 2 \fBsuccess_retcodes\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of non\-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBsuccess_stdout\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBsuccess_stderr\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBstdin_raw_newlines\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B False If \fBTrue\fP, Salt will not automatically convert the characters \fB\en\fP present in the \fBstdin\fP value to newlines. .UNINDENT .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.script salt://scripts/runme.sh salt \(aq*\(aq cmd.script salt://scripts/runme.sh \(aqarg1 arg2 \(dqarg 3\(dq\(aq salt \(aq*\(aq cmd.script salt://scripts/windows_task.ps1 args=\(aq \-Input c:\etmp\einfile.txt\(aq shell=\(aqpowershell\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.script salt://scripts/runme.sh stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.script_retcode(source, args=None, cwd=None, stdin=None, runas=None, group=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, template=\(aqjinja\(aq, umask=None, timeout=None, reset_system_locale=True, saltenv=None, output_encoding=None, output_loglevel=\(aqdebug\(aq, log_callback=None, use_vt=False, password=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Download a script from a remote location and execute the script locally. The script can be located on the salt master file server or on an HTTP/FTP server. .sp The script will be executed directly, so it can be written in any available programming language. .sp The script can also be formatted as a template, the default is jinja. .sp Only evaluate the script return code and do not block for terminal output .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- The location of the script to download. If the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs .IP \(bu 2 \fBargs\fP (\fI\%str\fP) \-\- String of command line args to pass to the script. Only used if no args are specified as part of the \fIname\fP argument. To pass a string containing spaces in YAML, you will need to doubly\-quote it: \(dqarg1 \(aqarg two\(aq arg3\(dq .IP \(bu 2 \fBcwd\fP (\fI\%str\fP) \-\- The directory from which to execute the command. Defaults to the home directory of the user specified by \fBrunas\fP (or the user under which Salt is running if \fBrunas\fP is not specified). .IP \(bu 2 \fBstdin\fP (\fI\%str\fP) \-\- A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. If running on a Windows minion you must also use the \fBpassword\fP argument, and the target user account must be in the Administrators group. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- .sp Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .sp New in version 2016.3.0. .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- Group to run script as. Not currently supported on Windows. .IP \(bu 2 \fBshell\fP (\fI\%str\fP) \-\- Specify an alternate shell. Defaults to the system\(aqs default shell. .IP \(bu 2 \fBpython_shell\fP (\fI\%bool\fP) \-\- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection. .IP \(bu 2 \fBenv\fP (\fI\%dict\fP) \-\- .sp Environment variables to be set prior to execution. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When passing environment variables on the CLI, they should be passed as the string representation of a dictionary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.script_retcode \(aqsome command\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When using environment variables on Window\(aqs, case\-sensitivity matters, i.e. Window\(aqs uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .IP \(bu 2 \fBtemplate\fP (\fI\%str\fP) \-\- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported. .IP \(bu 2 \fBumask\fP (\fI\%str\fP) \-\- The umask (in octal) to use when running the command. .IP \(bu 2 \fBoutput_encoding\fP (\fI\%str\fP) \-\- .sp Control the encoding used to decode the command\(aqs output. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This should not need to be used in most cases. By default, Salt will try to use the encoding detected from the system locale, and will fall back to UTF\-8 if this fails. This should only need to be used in cases where the output of the command is encoded in something other than the system locale or UTF\-8. .sp To see the encoding Salt has detected from the system locale, check the \fIlocale\fP line in the output of \fI\%test.versions_report\fP\&. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBoutput_loglevel\fP (\fI\%str\fP) \-\- .sp Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_retcode\fP (\fI\%bool\fP) \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- If the command has not terminated after timeout seconds, send the subprocess sigterm, and if sigterm is ignored, follow up with sigkill .IP \(bu 2 \fBuse_vt\fP (\fI\%bool\fP) \-\- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .IP \(bu 2 \fBsuccess_retcodes\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of non\-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBsuccess_stdout\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBsuccess_stderr\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBstdin_raw_newlines\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B False If \fBTrue\fP, Salt will not automatically convert the characters \fB\en\fP present in the \fBstdin\fP value to newlines. .UNINDENT .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.script_retcode salt://scripts/runme.sh salt \(aq*\(aq cmd.script_retcode salt://scripts/runme.sh \(aqarg1 arg2 \(dqarg 3\(dq\(aq salt \(aq*\(aq cmd.script_retcode salt://scripts/windows_task.ps1 args=\(aq \-Input c:\etmp\einfile.txt\(aq shell=\(aqpowershell\(aq .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.script_retcode salt://scripts/runme.sh stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.shell(cmd, cwd=None, stdin=None, runas=None, group=None, shell=\(aq/bin/bash\(aq, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel=\(aqdebug\(aq, log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, bg=False, password=None, prepend_path=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Execute the passed command and return the output as a string. .sp New in version 2015.5.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcmd\fP (\fI\%str\fP) \-\- The command to run. ex: \fBls \-lart /home\fP .IP \(bu 2 \fBcwd\fP (\fI\%str\fP) \-\- The directory from which to execute the command. Defaults to the home directory of the user specified by \fBrunas\fP (or the user under which Salt is running if \fBrunas\fP is not specified). .IP \(bu 2 \fBstdin\fP (\fI\%str\fP) \-\- A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- .sp Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. If running on a Windows minion you must also use the \fBpassword\fP argument, and the target user account must be in the Administrators group. .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 For versions 2018.3.3 and above on macosx while using runas, to pass special characters to the command you need to escape the characters on the shell. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmd.shell \(aqecho \(aq\e\(aq\(aqh=\e\(dqbaz\e\(dq\(aq\e\(aq\(aq\(aq runas=macuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- Group to run command as. Not currently supported on Windows. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- .sp Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .sp New in version 2016.3.0. .IP \(bu 2 \fBshell\fP (\fI\%int\fP) \-\- Shell to execute under. Defaults to the system default shell. .IP \(bu 2 \fBbg\fP (\fI\%bool\fP) \-\- If True, run command in background and do not await or deliver its results .IP \(bu 2 \fBenv\fP (\fI\%dict\fP) \-\- .sp Environment variables to be set prior to execution. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When passing environment variables on the CLI, they should be passed as the string representation of a dictionary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cmd.shell \(aqsome command\(aq env=\(aq{\(dqFOO\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When using environment variables on Window\(aqs, case\-sensitivity matters, i.e. Window\(aqs uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .IP \(bu 2 \fBclean_env\fP (\fI\%bool\fP) \-\- Attempt to clean out all other shell environment variables and set only those provided in the \(aqenv\(aq argument to this function. .IP \(bu 2 \fBprepend_path\fP (\fI\%str\fP) \-\- .sp $PATH segment to prepend (trailing \(aq:\(aq not necessary) to $PATH .sp New in version 2018.3.0. .IP \(bu 2 \fBtemplate\fP (\fI\%str\fP) \-\- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported. .IP \(bu 2 \fBrstrip\fP (\fI\%bool\fP) \-\- Strip all whitespace off the end of output before it is returned. .IP \(bu 2 \fBumask\fP (\fI\%str\fP) \-\- The umask (in octal) to use when running the command. .IP \(bu 2 \fBoutput_encoding\fP (\fI\%str\fP) \-\- .sp Control the encoding used to decode the command\(aqs output. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This should not need to be used in most cases. By default, Salt will try to use the encoding detected from the system locale, and will fall back to UTF\-8 if this fails. This should only need to be used in cases where the output of the command is encoded in something other than the system locale or UTF\-8. .sp To see the encoding Salt has detected from the system locale, check the \fIlocale\fP line in the output of \fI\%test.versions_report\fP\&. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBoutput_loglevel\fP (\fI\%str\fP) \-\- .sp Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_retcode\fP (\fI\%bool\fP) \-\- If the exit code of the command is nonzero, this is treated as an error condition, and the output from the command will be logged to the minion log. However, there are some cases where programs use the return code for signaling and a nonzero exit code doesn\(aqt necessarily mean failure. Pass this argument as \fBTrue\fP to skip logging the output if the command has a nonzero exit code. .IP \(bu 2 \fBhide_output\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP, suppress stdout and stderr in the return data. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- A timeout in seconds for the executed process to return. .IP \(bu 2 \fBuse_vt\fP (\fI\%bool\fP) \-\- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This passes the cmd argument directly to the shell without any further processing! Be absolutely sure that you have properly sanitized the command passed to this function and do not use untrusted inputs. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsuccess_retcodes\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of non\-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBsuccess_stdout\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBsuccess_stderr\fP (\fI\%list\fP) \-\- .INDENT 2.0 .TP .B This parameter will allow a list of strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .sp New in version 3004. .IP \(bu 2 \fBstdin_raw_newlines\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B False If \fBTrue\fP, Salt will not automatically convert the characters \fB\en\fP present in the \fBstdin\fP value to newlines. .UNINDENT .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.shell \(dqls \-l | awk \(aq/foo/{print \e$2}\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.shell template=jinja \(dqls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e$2}\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .sp Specify an alternate shell with the shell parameter: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.shell \(dqGet\-ChildItem C:\e \(dq shell=\(aqpowershell\(aq .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.shell \(dqgrep f\(dq stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .sp If an equal sign (\fB=\fP) appears in an argument to a Salt command it is interpreted as a keyword argument in the format \fBkey=val\fP\&. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.shell cmd=\(aqsed \-e s/=/:/g\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.shell_info(shell, list_modules=False) New in version 2016.11.0. .sp Provides information about a shell or script languages which often use \fB#!\fP\&. The values returned are dependent on the shell or scripting languages all return the \fBinstalled\fP, \fBpath\fP, \fBversion\fP, \fBversion_raw\fP .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBshell\fP (\fI\%str\fP) \-\- Name of the shell. Support shells/script languages include .IP \(bu 2 \fBbash\fP \-\- .IP \(bu 2 \fBcmd\fP \-\- .IP \(bu 2 \fBperl\fP \-\- .IP \(bu 2 \fBphp\fP \-\- .IP \(bu 2 \fBpowershell\fP \-\- .IP \(bu 2 \fBpython\fP \-\- .IP \(bu 2 \fBzsh\fP (\fIruby and\fP) \-\- .IP \(bu 2 \fBlist_modules\fP (\fI\%bool\fP) \-\- True to list modules available to the shell. .IP \(bu 2 \fBmodules.\fP (\fICurrently only lists powershell\fP) \-\- .UNINDENT .TP .B Returns A dictionary of information about the shell .TP .B Return type \fI\%dict\fP .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqversion\(aq: \(aq<2 or 3 numeric components dot\-separated>\(aq, \(aqversion_raw\(aq: \(aq<full version string>\(aq, \(aqpath\(aq: \(aq<full path to binary>\(aq, \(aqinstalled\(aq: <True, False or None>, \(aq<attribute>\(aq: \(aq<attribute value>\(aq} .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBinstalled\fP is always returned, if \fBNone\fP or \fBFalse\fP also returns error and may also return \fBstdout\fP for diagnostics. .IP \(bu 2 \fBversion\fP is for use in determine if a shell/script language has a particular feature set, not for package management. .IP \(bu 2 The shell must be within the executable search path. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.shell_info bash salt \(aq*\(aq cmd.shell_info powershell .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Codeauthor Damon Atkins <\fI\%https://github.com/damon\-atkins\fP> .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.shells() Lists the valid shells on this system via the /etc/shells file .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.shells .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.tty(device, echo=\(aq\(aq) Echo a string to a specific tty .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.tty tty0 \(aqThis is a test\(aq salt \(aq*\(aq cmd.tty pts3 \(aqThis is a test\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.which(cmd) Returns the path of an executable available on the minion, None otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.which cat .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.which_bin(cmds) Returns the first command found in a list of commands .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.which_bin \(aq[pip2, pip, pip\-python]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.composer .sp Use composer to install PHP dependencies for a directory .INDENT 0.0 .TP .B salt.modules.composer.did_composer_install(dir) Test to see if the vendor directory exists in this directory .INDENT 7.0 .TP .B dir Directory location of the composer.json file .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq composer.did_composer_install /var/www/application .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.composer.install(directory, composer=None, php=None, runas=None, prefer_source=None, prefer_dist=None, no_scripts=None, no_plugins=None, optimize=None, no_dev=None, quiet=False, composer_home=\(aq/root\(aq, env=None) Install composer dependencies for a directory. .sp If composer has not been installed globally making it available in the system PATH & making it executable, the \fBcomposer\fP and \fBphp\fP parameters will need to be set to the location of the executables. .INDENT 7.0 .TP .B directory Directory location of the composer.json file. .TP .B composer Location of the composer.phar file. If not set composer will just execute \(dqcomposer\(dq as if it is installed globally. (i.e. /path/to/composer.phar) .TP .B php Location of the php executable to use with composer. (i.e. /usr/bin/php) .TP .B runas Which system user to run composer as. .TP .B prefer_source \-\-prefer\-source option of composer. .TP .B prefer_dist \-\-prefer\-dist option of composer. .TP .B no_scripts \-\-no\-scripts option of composer. .TP .B no_plugins \-\-no\-plugins option of composer. .TP .B optimize \-\-optimize\-autoloader option of composer. Recommended for production. .TP .B no_dev \-\-no\-dev option for composer. Recommended for production. .TP .B quiet \-\-quiet option for composer. Whether or not to return output from composer. .TP .B composer_home $COMPOSER_HOME environment variable .TP .B env A list of environment variables to be set prior to execution. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq composer.install /var/www/application salt \(aq*\(aq composer.install /var/www/application no_dev=True optimize=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.composer.selfupdate(composer=None, php=None, runas=None, quiet=False, composer_home=\(aq/root\(aq) Update composer itself. .sp If composer has not been installed globally making it available in the system PATH & making it executable, the \fBcomposer\fP and \fBphp\fP parameters will need to be set to the location of the executables. .INDENT 7.0 .TP .B composer Location of the composer.phar file. If not set composer will just execute \(dqcomposer\(dq as if it is installed globally. (i.e. /path/to/composer.phar) .TP .B php Location of the php executable to use with composer. (i.e. /usr/bin/php) .TP .B runas Which system user to run composer as. .TP .B quiet \-\-quiet option for composer. Whether or not to return output from composer. .TP .B composer_home $COMPOSER_HOME environment variable .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq composer.selfupdate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.composer.update(directory, composer=None, php=None, runas=None, prefer_source=None, prefer_dist=None, no_scripts=None, no_plugins=None, optimize=None, no_dev=None, quiet=False, composer_home=\(aq/root\(aq, env=None) Update composer dependencies for a directory. .sp If \fIcomposer install\fP has not yet been run, this runs \fIcomposer install\fP instead. .sp If composer has not been installed globally making it available in the system PATH & making it executable, the \fBcomposer\fP and \fBphp\fP parameters will need to be set to the location of the executables. .INDENT 7.0 .TP .B directory Directory location of the composer.json file. .TP .B composer Location of the composer.phar file. If not set composer will just execute \(dqcomposer\(dq as if it is installed globally. (i.e. /path/to/composer.phar) .TP .B php Location of the php executable to use with composer. (i.e. /usr/bin/php) .TP .B runas Which system user to run composer as. .TP .B prefer_source \-\-prefer\-source option of composer. .TP .B prefer_dist \-\-prefer\-dist option of composer. .TP .B no_scripts \-\-no\-scripts option of composer. .TP .B no_plugins \-\-no\-plugins option of composer. .TP .B optimize \-\-optimize\-autoloader option of composer. Recommended for production. .TP .B no_dev \-\-no\-dev option for composer. Recommended for production. .TP .B quiet \-\-quiet option for composer. Whether or not to return output from composer. .TP .B composer_home $COMPOSER_HOME environment variable .TP .B env A list of environment variables to be set prior to execution. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq composer.update /var/www/application salt \(aq*\(aq composer.update /var/www/application no_dev=True optimize=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.config .sp Return config information .INDENT 0.0 .TP .B salt.modules.config.backup_mode(backup=\(aq\(aq) Return the backup mode .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.backup_mode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.dot_vals(value) Pass in a configuration value that should be preceded by the module name and a dot, this will return a list of all read key/value pairs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.dot_vals host .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.gather_bootstrap_script(bootstrap=None) Download the salt\-bootstrap script, and return its location .INDENT 7.0 .TP .B bootstrap URL of alternate bootstrap script .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.gather_bootstrap_script .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.get(key, default=\(aq\(aq, delimiter=\(aq:\(aq, merge=None, omit_opts=False, omit_pillar=False, omit_master=False, omit_grains=False) New in version 0.14.0. .sp Attempt to retrieve the named value from the minion config file, pillar, grains or the master config. If the named value is not available, return the value specified by the \fBdefault\fP argument. If this argument is not specified, \fBdefault\fP falls back to an empty string. .sp Values can also be retrieved from nested dictionaries. Assume the below data structure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqpkg\(aq: {\(aqapache\(aq: \(aqhttpd\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp To retrieve the value associated with the \fBapache\fP key, in the sub\-dictionary corresponding to the \fBpkg\fP key, the following command can be used: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion config.get pkg:apache .ft P .fi .UNINDENT .UNINDENT .sp The \fB:\fP (colon) is used to represent a nested dictionary level. .sp Changed in version 2015.5.0: The \fBdelimiter\fP argument was added, to allow delimiters other than \fB:\fP to be used. .sp This function traverses these data stores in this order, returning the first match found: .INDENT 7.0 .IP \(bu 2 Minion configuration .IP \(bu 2 Minion\(aqs grains .IP \(bu 2 Minion\(aqs pillar data .IP \(bu 2 Master configuration (requires \fBpillar_opts\fP to be set to \fBTrue\fP in Minion config file in order to work) .UNINDENT .sp This means that if there is a value that is going to be the same for the majority of minions, it can be configured in the Master config file, and then overridden using the grains, pillar, or Minion config file. .sp Adding config options to the Master or Minion configuration file is easy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my\-config\-option: value cafe\-menu: \- egg and bacon \- egg sausage and bacon \- egg and spam \- egg bacon and spam \- egg bacon sausage and spam \- spam bacon sausage and spam \- spam egg spam spam bacon and spam \- spam sausage spam spam bacon spam tomato and spam .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Minion configuration options built into Salt (like those defined \fI\%here\fP) will \fIalways\fP be defined in the Minion configuration and thus \fIcannot be overridden by grains or pillar data\fP\&. However, additional (user\-defined) configuration options (as in the above example) will not be in the Minion configuration by default and thus can be overridden using grains/pillar data by leaving the option out of the minion config file. .UNINDENT .UNINDENT .sp \fBArguments\fP .INDENT 7.0 .TP .B delimiter New in version 2015.5.0. .sp Override the delimiter used to separate nested levels of a data structure. .TP .B merge New in version 2015.5.0. .sp If passed, this parameter will change the behavior of the function so that, instead of traversing each data store above in order and returning the first match, the data stores are first merged together and then searched. The pillar data is merged into the master config data, then the grains are merged, followed by the Minion config data. The resulting data structure is then searched for a match. This allows for configurations to be more flexible. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The merging described above does not mean that grain data will end up in the Minion\(aqs pillar data, or pillar data will end up in the master config data, etc. The data is just combined for the purposes of searching an amalgam of the different data stores. .UNINDENT .UNINDENT .sp The supported merge strategies are as follows: .INDENT 7.0 .IP \(bu 2 \fBrecurse\fP \- If a key exists in both dictionaries, and the new value is not a dictionary, it is replaced. Otherwise, the sub\-dictionaries are merged together into a single dictionary, recursively on down, following the same criteria. For example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C >>> dict1 = {\(aqfoo\(aq: {\(aqbar\(aq: 1, \(aqqux\(aq: True}, \(aqhosts\(aq: [\(aqa\(aq, \(aqb\(aq, \(aqc\(aq], \(aqonly_x\(aq: None} >>> dict2 = {\(aqfoo\(aq: {\(aqbaz\(aq: 2, \(aqqux\(aq: False}, \(aqhosts\(aq: [\(aqd\(aq, \(aqe\(aq, \(aqf\(aq], \(aqonly_y\(aq: None} >>> merged {\(aqfoo\(aq: {\(aqbar\(aq: 1, \(aqbaz\(aq: 2, \(aqqux\(aq: False}, \(aqhosts\(aq: [\(aqd\(aq, \(aqe\(aq, \(aqf\(aq], \(aqonly_dict1\(aq: None, \(aqonly_dict2\(aq: None} .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBoverwrite\fP \- If a key exists in the top level of both dictionaries, the new value completely overwrites the old. For example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C >>> dict1 = {\(aqfoo\(aq: {\(aqbar\(aq: 1, \(aqqux\(aq: True}, \(aqhosts\(aq: [\(aqa\(aq, \(aqb\(aq, \(aqc\(aq], \(aqonly_x\(aq: None} >>> dict2 = {\(aqfoo\(aq: {\(aqbaz\(aq: 2, \(aqqux\(aq: False}, \(aqhosts\(aq: [\(aqd\(aq, \(aqe\(aq, \(aqf\(aq], \(aqonly_y\(aq: None} >>> merged {\(aqfoo\(aq: {\(aqbaz\(aq: 2, \(aqqux\(aq: False}, \(aqhosts\(aq: [\(aqd\(aq, \(aqe\(aq, \(aqf\(aq], \(aqonly_dict1\(aq: None, \(aqonly_dict2\(aq: None} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.get pkg:apache salt \(aq*\(aq config.get lxc.container_profile:centos merge=recurse .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.items() Return the complete config from the currently running minion process. This includes defaults for values not set in the config file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.items .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.manage_mode(mode) Return a mode value, normalized to a string .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.manage_mode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.merge(value, default=\(aq\(aq, omit_opts=False, omit_master=False, omit_pillar=False) Retrieves an option based on key, merging all matches. .sp Same as \fBoption()\fP except that it merges all matches, rather than taking the first match. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.merge schedule .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.option(value, default=None, omit_opts=False, omit_grains=False, omit_pillar=False, omit_master=False, omit_all=False, wildcard=False) Returns the setting for the specified config value. The priority for matches is the same as in \fI\%config.get\fP, only this function does not recurse into nested data structures. Another difference between this function and \fI\%config.get\fP is that it comes with a set of \(dqsane defaults\(dq. To view these, you can run the following command: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.option \(aq*\(aq omit_all=True wildcard=True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B default The default value if no match is found. If not specified, then the fallback default will be an empty string, unless \fBwildcard=True\fP, in which case the return will be an empty dictionary. .TP .B omit_opts False Pass as \fBTrue\fP to exclude matches from the minion configuration file .TP .B omit_grains False Pass as \fBTrue\fP to exclude matches from the grains .TP .B omit_pillar False Pass as \fBTrue\fP to exclude matches from the pillar data .TP .B omit_master False Pass as \fBTrue\fP to exclude matches from the master configuration file .TP .B omit_all True Shorthand to omit all of the above and return matches only from the \(dqsane defaults\(dq. .sp New in version 3000. .TP .B wildcard False If used, this will perform pattern matching on keys. Note that this will also significantly change the return data. Instead of only a value being returned, a dictionary mapping the matched keys to their values is returned. For example, using \fBwildcard=True\fP with a \fBkey\fP of \fB\(aqfoo.ba*\fP could return a dictionary like so: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqfoo.bar\(aq: True, \(aqfoo.baz\(aq: False} .ft P .fi .UNINDENT .UNINDENT .sp New in version 3000. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.option redis.host .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.valid_fileproto(uri) Returns a boolean value based on whether or not the URI passed has a valid remote file protocol designation .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.valid_fileproto salt://path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.consul .sp Interact with Consul .sp \fI\%https://www.consul.io\fP .INDENT 0.0 .TP .B salt.modules.consul.acl_clone(consul_url=None, token=None, **kwargs) Information about an ACL token. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBid\fP \-\- Unique identifier for the ACL to update. .UNINDENT .TP .B Returns Boolean, message of success or failure, and new ID of cloned ACL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.acl_info id=\(aqc1c4d223\-91cb\-3d1f\-1ee8\-f2af9e7b6716\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.acl_create(consul_url=None, token=None, **kwargs) Create a new ACL token. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBname\fP \-\- Meaningful indicator of the ACL\(aqs purpose. .IP \(bu 2 \fBtype\fP \-\- Type is either client or management. A management token is comparable to a root user and has the ability to perform any action including creating, modifying, and deleting ACLs. .IP \(bu 2 \fBrules\fP \-\- The Consul server URL. .UNINDENT .TP .B Returns Boolean & message of success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.acl_create .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.acl_delete(consul_url=None, token=None, **kwargs) Delete an ACL token. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBid\fP \-\- Unique identifier for the ACL to update. .UNINDENT .TP .B Returns Boolean & message of success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.acl_delete id=\(aqc1c4d223\-91cb\-3d1f\-1ee8\-f2af9e7b6716\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.acl_info(consul_url=None, **kwargs) Information about an ACL token. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBid\fP \-\- Unique identifier for the ACL to update. .UNINDENT .TP .B Returns Information about the ACL requested. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.acl_info id=\(aqc1c4d223\-91cb\-3d1f\-1ee8\-f2af9e7b6716\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.acl_list(consul_url=None, token=None, **kwargs) List the ACL tokens. .INDENT 7.0 .TP .B Parameters \fBconsul_url\fP \-\- The Consul server URL. .TP .B Returns List of ACLs .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.acl_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.acl_update(consul_url=None, token=None, **kwargs) Update an ACL token. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBname\fP \-\- Meaningful indicator of the ACL\(aqs purpose. .IP \(bu 2 \fBid\fP \-\- Unique identifier for the ACL to update. .IP \(bu 2 \fBtype\fP \-\- Type is either client or management. A management token is comparable to a root user and has the ability to perform any action including creating, modifying, and deleting ACLs. .IP \(bu 2 \fBrules\fP \-\- The Consul server URL. .UNINDENT .TP .B Returns Boolean & message of success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.acl_update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_check_deregister(consul_url=None, token=None, checkid=None) The agent will take care of deregistering the check from the Catalog. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBcheckid\fP \-\- The ID of the check to deregister from Consul. .UNINDENT .TP .B Returns Boolean and message indicating success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_check_deregister checkid=\(aqMemory Utilization\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_check_fail(consul_url=None, token=None, checkid=None, **kwargs) This endpoint is used with a check that is of the TTL type. When this is called, the status of the check is set to critical and the TTL clock is reset. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBcheckid\fP \-\- The ID of the check to deregister from Consul. .IP \(bu 2 \fBnote\fP \-\- A human\-readable message with the status of the check. .UNINDENT .TP .B Returns Boolean and message indicating success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_check_fail checkid=\(aqredis_check1\(aq note=\(aqForcing check into critical state.\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_check_pass(consul_url=None, token=None, checkid=None, **kwargs) This endpoint is used with a check that is of the TTL type. When this is called, the status of the check is set to passing and the TTL clock is reset. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBcheckid\fP \-\- The ID of the check to mark as passing. .IP \(bu 2 \fBnote\fP \-\- A human\-readable message with the status of the check. .UNINDENT .TP .B Returns Boolean and message indicating success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_check_pass checkid=\(aqredis_check1\(aq note=\(aqForcing check into passing state.\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_check_register(consul_url=None, token=None, **kwargs) The register endpoint is used to add a new check to the local agent. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBname\fP \-\- The description of what the check is for. .IP \(bu 2 \fBid\fP \-\- The unique name to use for the check, if not provided \(aqname\(aq is used. .IP \(bu 2 \fBnotes\fP \-\- Human readable description of the check. .IP \(bu 2 \fBscript\fP \-\- If script is provided, the check type is a script, and Consul will evaluate that script based on the interval parameter. .IP \(bu 2 \fBhttp\fP \-\- Check will perform an HTTP GET request against the value of HTTP (expected to be a URL) based on the interval parameter. .IP \(bu 2 \fBttl\fP \-\- If a TTL type is used, then the TTL update endpoint must be used periodically to update the state of the check. .IP \(bu 2 \fBinterval\fP \-\- Interval at which the check should run. .UNINDENT .TP .B Returns Boolean and message indicating success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_check_register name=\(aqMemory Utilization\(aq script=\(aq/usr/local/bin/check_mem.py\(aq interval=\(aq15s\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_check_warn(consul_url=None, token=None, checkid=None, **kwargs) This endpoint is used with a check that is of the TTL type. When this is called, the status of the check is set to warning and the TTL clock is reset. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBcheckid\fP \-\- The ID of the check to deregister from Consul. .IP \(bu 2 \fBnote\fP \-\- A human\-readable message with the status of the check. .UNINDENT .TP .B Returns Boolean and message indicating success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_check_warn checkid=\(aqredis_check1\(aq note=\(aqForcing check into warning state.\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_checks(consul_url=None, token=None) Returns the checks the local agent is managing .INDENT 7.0 .TP .B Parameters \fBconsul_url\fP \-\- The Consul server URL. .TP .B Returns Returns the checks the local agent is managing .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_checks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_join(consul_url=None, token=None, address=None, **kwargs) Triggers the local agent to join a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBaddress\fP \-\- The address for the agent to connect to. .IP \(bu 2 \fBwan\fP \-\- Causes the agent to attempt to join using the WAN pool. .UNINDENT .TP .B Returns Boolean and message indicating success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_join address=\(aq192.168.1.1\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_leave(consul_url=None, token=None, node=None) Used to instruct the agent to force a node into the left state. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBnode\fP \-\- The node the agent will force into left state .UNINDENT .TP .B Returns Boolean and message indicating success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_leave node=\(aqweb1.example.com\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_maintenance(consul_url=None, token=None, **kwargs) Manages node maintenance mode .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBenable\fP \-\- The enable flag is required. Acceptable values are either true (to enter maintenance mode) or false (to resume normal operation). .IP \(bu 2 \fBreason\fP \-\- If provided, its value should be a text string explaining the reason for placing the node into maintenance mode. .UNINDENT .TP .B Returns Boolean and message indicating success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_maintenance enable=\(aqFalse\(aq reason=\(aqUpgrade in progress\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_members(consul_url=None, token=None, **kwargs) Returns the members as seen by the local serf agent .INDENT 7.0 .TP .B Parameters \fBconsul_url\fP \-\- The Consul server URL. .TP .B Returns Returns the members as seen by the local serf agent .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_members .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_self(consul_url=None, token=None) Returns the local node configuration .INDENT 7.0 .TP .B Parameters \fBconsul_url\fP \-\- The Consul server URL. .TP .B Returns Returns the local node configuration .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_self .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_service_deregister(consul_url=None, token=None, serviceid=None) Used to remove a service. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBserviceid\fP \-\- A serviceid describing the service. .UNINDENT .TP .B Returns Boolean and message indicating success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_service_deregister serviceid=\(aqredis\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_service_maintenance(consul_url=None, token=None, serviceid=None, **kwargs) Used to place a service into maintenance mode. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBserviceid\fP \-\- A name of the service. .IP \(bu 2 \fBenable\fP \-\- Whether the service should be enabled or disabled. .IP \(bu 2 \fBreason\fP \-\- A human readable message of why the service was enabled or disabled. .UNINDENT .TP .B Returns Boolean and message indicating success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_service_deregister serviceid=\(aqredis\(aq enable=\(aqTrue\(aq reason=\(aqDown for upgrade\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_service_register(consul_url=None, token=None, **kwargs) The used to add a new service, with an optional health check, to the local agent. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBname\fP \-\- A name describing the service. .IP \(bu 2 \fBaddress\fP \-\- The address used by the service, defaults to the address of the agent. .IP \(bu 2 \fBport\fP \-\- The port used by the service. .IP \(bu 2 \fBid\fP \-\- Unique ID to identify the service, if not provided the value of the name parameter is used. .IP \(bu 2 \fBtags\fP \-\- Identifying tags for service, string or list. .IP \(bu 2 \fBscript\fP \-\- If script is provided, the check type is a script, and Consul will evaluate that script based on the interval parameter. .IP \(bu 2 \fBhttp\fP \-\- Check will perform an HTTP GET request against the value of HTTP (expected to be a URL) based on the interval parameter. .IP \(bu 2 \fBcheck_ttl\fP \-\- If a TTL type is used, then the TTL update endpoint must be used periodically to update the state of the check. .IP \(bu 2 \fBcheck_interval\fP \-\- Interval at which the check should run. .UNINDENT .TP .B Returns Boolean and message indicating success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_service_register name=\(aqredis\(aq tags=\(aq[\(dqmaster\(dq, \(dqv1\(dq]\(aq address=\(dq127.0.0.1\(dq port=\(dq8080\(dq check_script=\(dq/usr/local/bin/check_redis.py\(dq interval=\(dq10s\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.agent_services(consul_url=None, token=None) Returns the services the local agent is managing .INDENT 7.0 .TP .B Parameters \fBconsul_url\fP \-\- The Consul server URL. .TP .B Returns Returns the services the local agent is managing .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.agent_services .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.catalog_datacenters(consul_url=None, token=None) Return list of available datacenters from catalog. .INDENT 7.0 .TP .B Parameters \fBconsul_url\fP \-\- The Consul server URL. .TP .B Returns The list of available datacenters. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.catalog_datacenters .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.catalog_deregister(consul_url=None, token=None, **kwargs) Deregisters a node, service, or check .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBnode\fP \-\- The node to deregister. .IP \(bu 2 \fBdatacenter\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .IP \(bu 2 \fBcheckid\fP \-\- The ID of the health check to deregister. .IP \(bu 2 \fBserviceid\fP \-\- The ID of the service to deregister. .UNINDENT .TP .B Returns Boolean & message of success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.catalog_register node=\(aqnode1\(aq serviceid=\(aqredis_server1\(aq checkid=\(aqredis_check1\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.catalog_node(consul_url=None, token=None, node=None, **kwargs) Information about the registered node. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBnode\fP \-\- The node to request information about. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .UNINDENT .TP .B Returns Information about the requested node. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.catalog_service service=\(aqredis\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.catalog_nodes(consul_url=None, token=None, **kwargs) Return list of available nodes from catalog. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .UNINDENT .TP .B Returns The list of available nodes. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.catalog_nodes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.catalog_register(consul_url=None, token=None, **kwargs) Registers a new node, service, or check .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .IP \(bu 2 \fBnode\fP \-\- The node to register. .IP \(bu 2 \fBaddress\fP \-\- The address of the node. .IP \(bu 2 \fBservice\fP \-\- The service that will be registered. .IP \(bu 2 \fBservice_address\fP \-\- The address that the service listens on. .IP \(bu 2 \fBservice_port\fP \-\- The port for the service. .IP \(bu 2 \fBservice_id\fP \-\- A unique identifier for the service, if this is not provided \(dqname\(dq will be used. .IP \(bu 2 \fBservice_tags\fP \-\- Any tags associated with the service. .IP \(bu 2 \fBcheck\fP \-\- The name of the health check to register .IP \(bu 2 \fBcheck_status\fP \-\- The initial status of the check, must be one of unknown, passing, warning, or critical. .IP \(bu 2 \fBcheck_service\fP \-\- The service that the check is performed against. .IP \(bu 2 \fBcheck_id\fP \-\- Unique identifier for the service. .IP \(bu 2 \fBcheck_notes\fP \-\- An opaque field that is meant to hold human\-readable text. .UNINDENT .TP .B Returns Boolean & message of success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.catalog_register node=\(aqnode1\(aq address=\(aq192.168.1.1\(aq service=\(aqredis\(aq service_address=\(aq127.0.0.1\(aq service_port=\(aq8080\(aq service_id=\(aqredis_server1\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.catalog_service(consul_url=None, token=None, service=None, **kwargs) Information about the registered service. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .IP \(bu 2 \fBtag\fP \-\- Filter returned services with tag parameter. .UNINDENT .TP .B Returns Information about the requested service. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.catalog_service service=\(aqredis\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.catalog_services(consul_url=None, token=None, **kwargs) Return list of available services rom catalog. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .UNINDENT .TP .B Returns The list of available services. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.catalog_services .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.delete(consul_url=None, token=None, key=None, **kwargs) Delete values from Consul .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBkey\fP \-\- The key to use as the starting point for the list. .IP \(bu 2 \fBrecurse\fP \-\- Delete values recursively beginning at the value of key. .IP \(bu 2 \fBcas\fP \-\- This flag is used to turn the DELETE into a Check\-And\-Set operation. .UNINDENT .TP .B Returns Boolean & message of success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.delete key=\(aqweb\(aq salt \(aq*\(aq consul.delete key=\(aqweb\(aq recurse=\(aqTrue\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.event_fire(consul_url=None, token=None, name=None, **kwargs) List the ACL tokens. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBname\fP \-\- The name of the event to fire. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .IP \(bu 2 \fBnode\fP \-\- Filter by node name. .IP \(bu 2 \fBservice\fP \-\- Filter by service name. .IP \(bu 2 \fBtag\fP \-\- Filter by tag name. .UNINDENT .TP .B Returns List of ACLs .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.event_fire name=\(aqdeploy\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.event_list(consul_url=None, token=None, **kwargs) List the recent events. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBname\fP \-\- The name of the event to fire. .UNINDENT .TP .B Returns List of ACLs .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.event_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.get(consul_url=None, key=None, token=None, recurse=False, decode=False, raw=False) Get key from Consul .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBkey\fP \-\- The key to use as the starting point for the list. .IP \(bu 2 \fBrecurse\fP \-\- Return values recursively beginning at the value of key. .IP \(bu 2 \fBdecode\fP \-\- By default values are stored as Base64 encoded values, decode will return the whole key with the value decoded. .IP \(bu 2 \fBraw\fP \-\- Simply return the decoded value of the key. .UNINDENT .TP .B Returns The keys in Consul. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.get key=\(aqweb/key1\(aq salt \(aq*\(aq consul.get key=\(aqweb\(aq recurse=True salt \(aq*\(aq consul.get key=\(aqweb\(aq recurse=True decode=True .ft P .fi .UNINDENT .UNINDENT .sp By default values stored in Consul are base64 encoded, passing the decode option will show them as the decoded values. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.get key=\(aqweb\(aq recurse=True decode=True raw=True .ft P .fi .UNINDENT .UNINDENT .sp By default Consult will return other information about the key, the raw option will return only the raw value. .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.health_checks(consul_url=None, token=None, service=None, **kwargs) Health information about the registered service. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBservice\fP \-\- The service to request health information about. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .UNINDENT .TP .B Returns Health information about the requested node. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.health_checks service=\(aqredis1\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.health_node(consul_url=None, token=None, node=None, **kwargs) Health information about the registered node. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBnode\fP \-\- The node to request health information about. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .UNINDENT .TP .B Returns Health information about the requested node. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.health_node node=\(aqnode1\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.health_service(consul_url=None, token=None, service=None, **kwargs) Health information about the registered service. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBservice\fP \-\- The service to request health information about. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .IP \(bu 2 \fBtag\fP \-\- Filter returned services with tag parameter. .IP \(bu 2 \fBpassing\fP \-\- Filter results to only nodes with all checks in the passing state. .UNINDENT .TP .B Returns Health information about the requested node. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.health_service service=\(aqredis1\(aq salt \(aq*\(aq consul.health_service service=\(aqredis1\(aq passing=\(aqTrue\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.health_state(consul_url=None, token=None, state=None, **kwargs) Returns the checks in the state provided on the path. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBstate\fP \-\- The state to show checks for. The supported states are any, unknown, passing, warning, or critical. The any state is a wildcard that can be used to return all checks. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .UNINDENT .TP .B Returns The checks in the provided state. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.health_state state=\(aqredis1\(aq salt \(aq*\(aq consul.health_state service=\(aqredis1\(aq passing=\(aqTrue\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.list_(consul_url=None, token=None, key=None, **kwargs) List keys in Consul .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBkey\fP \-\- The key to use as the starting point for the list. .UNINDENT .TP .B Returns The list of keys. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.list salt \(aq*\(aq consul.list key=\(aqweb\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.put(consul_url=None, token=None, key=None, value=None, **kwargs) Put values into Consul .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBkey\fP \-\- The key to use as the starting point for the list. .IP \(bu 2 \fBvalue\fP \-\- The value to set the key to. .IP \(bu 2 \fBflags\fP \-\- This can be used to specify an unsigned value between 0 and 2^64\-1. Clients can choose to use this however makes sense for their application. .IP \(bu 2 \fBcas\fP \-\- This flag is used to turn the PUT into a Check\-And\-Set operation. .IP \(bu 2 \fBacquire\fP \-\- This flag is used to turn the PUT into a lock acquisition operation. .IP \(bu 2 \fBrelease\fP \-\- This flag is used to turn the PUT into a lock release operation. .UNINDENT .TP .B Returns Boolean & message of success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.put key=\(aqweb/key1\(aq value=\(dqHello there\(dq salt \(aq*\(aq consul.put key=\(aqweb/key1\(aq value=\(dqHello there\(dq acquire=\(aqd5d371f4\-c380\-5280\-12fd\-8810be175592\(aq salt \(aq*\(aq consul.put key=\(aqweb/key1\(aq value=\(dqHello there\(dq release=\(aqd5d371f4\-c380\-5280\-12fd\-8810be175592\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.session_create(consul_url=None, token=None, **kwargs) Used to create a session. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBlockdelay\fP \-\- Duration string using a \(dqs\(dq suffix for seconds. The default is 15s. .IP \(bu 2 \fBnode\fP \-\- Must refer to a node that is already registered, if specified. By default, the agent\(aqs own node name is used. .IP \(bu 2 \fBname\fP \-\- A human\-readable name for the session .IP \(bu 2 \fBchecks\fP \-\- A list of associated health checks. It is highly recommended that, if you override this list, you include the default \(dqserfHealth\(dq. .IP \(bu 2 \fBbehavior\fP \-\- Can be set to either release or delete. This controls the behavior when a session is invalidated. By default, this is release, causing any locks that are held to be released. Changing this to delete causes any locks that are held to be deleted. delete is useful for creating ephemeral key/value entries. .IP \(bu 2 \fBttl\fP \-\- Session is invalidated if it is not renewed before the TTL expires .UNINDENT .TP .B Returns Boolean and message indicating success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.session_create node=\(aqnode1\(aq name=\(aqmy\-session\(aq behavior=\(aqdelete\(aq ttl=\(aq3600s\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.session_destroy(consul_url=None, token=None, session=None, **kwargs) Destroy session .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBsession\fP \-\- The ID of the session to destroy. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .UNINDENT .TP .B Returns Boolean & message of success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.session_destroy session=\(aqc1c4d223\-91cb\-3d1f\-1ee8\-f2af9e7b6716\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.session_info(consul_url=None, token=None, session=None, **kwargs) Information about a session .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBsession\fP \-\- The ID of the session to return information about. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .UNINDENT .TP .B Returns Boolean & message of success or failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.session_info session=\(aqc1c4d223\-91cb\-3d1f\-1ee8\-f2af9e7b6716\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.session_list(consul_url=None, token=None, return_list=False, **kwargs) Used to list sessions. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconsul_url\fP \-\- The Consul server URL. .IP \(bu 2 \fBdc\fP \-\- By default, the datacenter of the agent is queried; however, the dc can be provided using the \(dqdc\(dq parameter. .IP \(bu 2 \fBreturn_list\fP \-\- By default, all information about the sessions is returned, using the return_list parameter will return a list of session IDs. .UNINDENT .TP .B Returns A list of all available sessions. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.session_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.status_leader(consul_url=None, token=None) Returns the current Raft leader .INDENT 7.0 .TP .B Parameters \fBconsul_url\fP \-\- The Consul server URL. .TP .B Returns The address of the Raft leader. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.status_leader .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.consul.status_peers(consul_url, token=None) Returns the current Raft peer set .INDENT 7.0 .TP .B Parameters \fBconsul_url\fP \-\- The Consul server URL. .TP .B Returns Retrieves the Raft peers for the datacenter in which the agent is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq consul.status_peers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.container_resource .sp Common resources for LXC and systemd\-nspawn containers .sp New in version 2015.8.0. .sp These functions are not designed to be called directly, but instead from the \fI\%lxc\fP, \fI\%nspawn\fP, and \fBdocker\fP execution modules. They provide for common logic to be re\-used for common actions. .INDENT 0.0 .TP .B salt.modules.container_resource.cache_file(source) Wrapper for cp.cache_file which raises an error if the file was unable to be cached. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion container_resource.cache_file salt://foo/bar/baz.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.container_resource.copy_to(name, source, dest, container_type=None, path=None, exec_driver=None, overwrite=False, makedirs=False) Common logic for copying files to containers .INDENT 7.0 .TP .B path path to the container parent (for LXC only) default: /var/lib/lxc (system default) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion container_resource.copy_to mycontainer /local/file/path /container/file/path container_type=docker exec_driver=nsenter .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.container_resource.run(name, cmd, container_type=None, exec_driver=None, output=None, no_start=False, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, ignore_retcode=False, path=None, use_vt=False, keep_env=None) Common logic for running shell commands in containers .INDENT 7.0 .TP .B path path to the container parent (for LXC only) default: /var/lib/lxc (system default) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion container_resource.run mycontainer \(aqps aux\(aq container_type=docker exec_driver=nsenter output=stdout .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.cp .sp Minion side functions for salt\-cp .INDENT 0.0 .TP .B salt.modules.cp.cache_dest(url, saltenv=None) New in version 3000. .sp Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Returns the expected cache path for the file, if cached using \fI\%cp.cache_file\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This only returns the _expected_ path, it does not tell you if the URL is really cached. To check if the URL is cached, use \fI\%cp.is_cached\fP instead. .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_dest https://foo.com/bar.rpm salt \(aq*\(aq cp.cache_dest salt://my/file salt \(aq*\(aq cp.cache_dest salt://my/file saltenv=dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_dir(path, saltenv=None, include_empty=False, include_pat=None, exclude_pat=None) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Download and cache everything under a directory from the master .INDENT 7.0 .TP .B include_pat None Glob or regex to narrow down the files cached from the given path. If matching with a regex, the regex must be prefixed with \fBE@\fP, otherwise the expression will be interpreted as a glob. .sp New in version 2014.7.0. .TP .B exclude_pat None Glob or regex to exclude certain files from being cached from the given path. If matching with a regex, the regex must be prefixed with \fBE@\fP, otherwise the expression will be interpreted as a glob. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If used with \fBinclude_pat\fP, files matching this pattern will be excluded from the subset of files defined by \fBinclude_pat\fP\&. .UNINDENT .UNINDENT .sp New in version 2014.7.0. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_dir salt://path/to/dir salt \(aq*\(aq cp.cache_dir salt://path/to/dir include_pat=\(aqE@*.py$\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_file(path, saltenv=None, source_hash=None, verify_ssl=True, use_etag=False) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Used to cache a single file on the Minion .sp Returns the location of the new cached file on the Minion .INDENT 7.0 .TP .B source_hash If \fBname\fP is an http(s) or 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 file if the cached copy matches the specified hash. .sp New in version 2018.3.0. .TP .B verify_ssl If \fBFalse\fP, remote https file sources (\fBhttps://\fP) and source_hash will not attempt to validate the servers certificate. Default is True. .sp New in version 3002. .TP .B use_etag If \fBTrue\fP, remote http/https file sources will attempt to use the ETag header to determine if the remote file needs to be downloaded. This provides a lightweight mechanism for promptly refreshing files changed on a web server without requiring a full hash comparison via the \fBsource_hash\fP parameter. .sp New in version 3005. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_file salt://path/to/file .ft P .fi .UNINDENT .UNINDENT .sp There are two ways of defining the fileserver environment (a.k.a. \fBsaltenv\fP) from which to cache the file. One is to use the \fBsaltenv\fP parameter, and the other is to use a querystring syntax in the \fBsalt://\fP URL. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_file salt://foo/bar.conf saltenv=config salt \(aq*\(aq cp.cache_file salt://foo/bar.conf?saltenv=config .ft P .fi .UNINDENT .UNINDENT .sp If the path being cached is a \fBsalt://\fP URI, and the path does not exist, then \fBFalse\fP will be returned. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 It may be necessary to quote the URL when using the querystring method, depending on the shell being used to run the command. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_file_ssh(path, saltenv=None, source_hash=None, verify_ssl=True, use_etag=False) This function is an alias of \fBcache_file\fP\&. .INDENT 7.0 .INDENT 3.5 Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Used to cache a single file on the Minion .sp Returns the location of the new cached file on the Minion .INDENT 0.0 .TP .B source_hash If \fBname\fP is an http(s) or 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 file if the cached copy matches the specified hash. .sp New in version 2018.3.0. .TP .B verify_ssl If \fBFalse\fP, remote https file sources (\fBhttps://\fP) and source_hash will not attempt to validate the servers certificate. Default is True. .sp New in version 3002. .TP .B use_etag If \fBTrue\fP, remote http/https file sources will attempt to use the ETag header to determine if the remote file needs to be downloaded. This provides a lightweight mechanism for promptly refreshing files changed on a web server without requiring a full hash comparison via the \fBsource_hash\fP parameter. .sp New in version 3005. .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_file salt://path/to/file .ft P .fi .UNINDENT .UNINDENT .sp There are two ways of defining the fileserver environment (a.k.a. \fBsaltenv\fP) from which to cache the file. One is to use the \fBsaltenv\fP parameter, and the other is to use a querystring syntax in the \fBsalt://\fP URL. The below two examples are equivalent: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_file salt://foo/bar.conf saltenv=config salt \(aq*\(aq cp.cache_file salt://foo/bar.conf?saltenv=config .ft P .fi .UNINDENT .UNINDENT .sp If the path being cached is a \fBsalt://\fP URI, and the path does not exist, then \fBFalse\fP will be returned. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 It may be necessary to quote the URL when using the querystring method, depending on the shell being used to run the command. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_files(paths, saltenv=None) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Used to gather many files from the Master, the gathered files will be saved in the minion cachedir reflective to the paths retrieved from the Master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_files salt://pathto/file1,salt://pathto/file1 .ft P .fi .UNINDENT .UNINDENT .sp There are two ways of defining the fileserver environment (a.k.a. \fBsaltenv\fP) from which to cache the files. One is to use the \fBsaltenv\fP parameter, and the other is to use a querystring syntax in the \fBsalt://\fP URL. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_files salt://foo/bar.conf,salt://foo/baz.conf saltenv=config salt \(aq*\(aq cp.cache_files salt://foo/bar.conf?saltenv=config,salt://foo/baz.conf?saltenv=config .ft P .fi .UNINDENT .UNINDENT .sp The querystring method is less useful when all files are being cached from the same environment, but is a good way of caching files from multiple different environments in the same command. For example, the below command will cache the first file from the \fBconfig1\fP environment, and the second one from the \fBconfig2\fP environment. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_files salt://foo/bar.conf?saltenv=config1,salt://foo/bar.conf?saltenv=config2 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 It may be necessary to quote the URL when using the querystring method, depending on the shell being used to run the command. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_local_file(path) Cache a local file on the minion in the localfiles cache .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_local_file /etc/hosts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_master(saltenv=None) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Retrieve all of the files on the master and cache them locally .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.envs() List available environments for fileserver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.envs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_dir(path, dest, saltenv=None, template=None, gzip=None, **kwargs) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Used to recursively copy a directory from the salt master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.get_dir salt://path/to/dir/ /minion/dest .ft P .fi .UNINDENT .UNINDENT .sp get_dir supports the same template and gzip arguments as get_file. .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_file(path, dest, saltenv=None, makedirs=False, template=None, gzip=None, **kwargs) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Changed in version 2018.3.0: \fBdest\fP can now be a directory .sp Used to get a single file from the salt master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.get_file salt://path/to/file /minion/dest .ft P .fi .UNINDENT .UNINDENT .sp Template rendering can be enabled on both the source and destination file names like so: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.get_file \(dqsalt://{{grains.os}}/vimrc\(dq /etc/vimrc template=jinja .ft P .fi .UNINDENT .UNINDENT .sp This example would instruct all Salt minions to download the vimrc from a directory with the same name as their os grain and copy it to /etc/vimrc .sp For larger files, the cp.get_file module also supports gzip compression. Because gzip is CPU\-intensive, this should only be used in scenarios where the compression ratio is very high (e.g. pretty\-printed JSON or YAML files). .sp Use the \fIgzip\fP named argument to enable it. Valid values are 1..9, where 1 is the lightest compression and 9 the heaviest. 1 uses the least CPU on the master (and minion), 9 uses the most. .sp There are two ways of defining the fileserver environment (a.k.a. \fBsaltenv\fP) from which to retrieve the file. One is to use the \fBsaltenv\fP parameter, and the other is to use a querystring syntax in the \fBsalt://\fP URL. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.get_file salt://foo/bar.conf /etc/foo/bar.conf saltenv=config salt \(aq*\(aq cp.get_file salt://foo/bar.conf?saltenv=config /etc/foo/bar.conf .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 It may be necessary to quote the URL when using the querystring method, depending on the shell being used to run the command. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_file_str(path, saltenv=None) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Download a file from a URL to the Minion cache directory and return the contents of that file .sp Returns \fBFalse\fP if Salt was unable to cache a file from a URL. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.get_file_str salt://my/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_template(path, dest, template=\(aqjinja\(aq, saltenv=None, makedirs=False, **kwargs) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Render a file as a template before setting it down. Warning, order is not the same as in fileclient.cp for non breaking old API. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.get_template salt://path/to/template /minion/dest .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_url(path, dest=\(aq\(aq, saltenv=None, makedirs=False, source_hash=None) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Changed in version 2018.3.0: \fBdest\fP can now be a directory .sp Used to get a single file from a URL. .INDENT 7.0 .TP .B path A URL to download a file from. Supported URL schemes are: \fBsalt://\fP, \fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP, \fBs3://\fP, \fBswift://\fP and \fBfile://\fP (local filesystem). If no scheme was specified, this is equivalent of using \fBfile://\fP\&. If a \fBfile://\fP URL is given, the function just returns absolute path to that file on a local filesystem. The function returns \fBFalse\fP if Salt was unable to fetch a file from a \fBsalt://\fP URL. .TP .B dest The default behaviour is to write the fetched file to the given destination path. If this parameter is omitted or set as empty string (\fB\(aq\(aq\fP), the function places the remote file on the local filesystem inside the Minion cache directory and returns the path to that file. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To simply return the file contents instead, set destination to \fBNone\fP\&. This works with \fBsalt://\fP, \fBhttp://\fP, \fBhttps://\fP and \fBfile://\fP URLs. The files fetched by \fBhttp://\fP and \fBhttps://\fP will not be cached. .UNINDENT .UNINDENT .TP .B saltenv Salt fileserver environment from which to retrieve the file. Ignored if \fBpath\fP is not a \fBsalt://\fP URL. .TP .B source_hash If \fBpath\fP is an http(s) or 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 file if the cached copy matches the specified hash. .sp New in version 2018.3.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.get_url salt://my/file /tmp/this_file_is_mine salt \(aq*\(aq cp.get_url http://www.slashdot.org /tmp/index.html .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.hash_file(path, saltenv=None) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Return the hash of a file, to get the hash of a file on the salt master file server prepend the path with salt://<file on server> otherwise, prepend the file with / for a local file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.hash_file salt://path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.hash_file_ssh(path, saltenv=None) This function is an alias of \fBhash_file\fP\&. .INDENT 7.0 .INDENT 3.5 Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Return the hash of a file, to get the hash of a file on the salt master file server prepend the path with salt://<file on server> otherwise, prepend the file with / for a local file. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.hash_file salt://path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.is_cached(path, saltenv=None) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Returns the full path to a file if it is cached locally on the minion otherwise returns a blank string .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.is_cached salt://path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_master(saltenv=None, prefix=\(aq\(aq) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp List all of the files stored on the master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.list_master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_master_dirs(saltenv=None, prefix=\(aq\(aq) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp List all of the directories stored on the master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.list_master_dirs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_master_symlinks(saltenv=None, prefix=\(aq\(aq) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp List all of the symlinks stored on the master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.list_master_symlinks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_minion(saltenv=None) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp List all of the files cached on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.list_minion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_states(saltenv=None) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp List all of the available state files in an environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.list_states .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.push(path, keep_symlinks=False, upload_path=None, remove_source=False) WARNING Files pushed to the master will have global read permissions.. .sp Push a file from the minion up to the master, the file will be saved to the salt master in the master\(aqs minion files cachedir (defaults to \fB/var/cache/salt/master/minions/minion\-id/files\fP) .sp Since this feature allows a minion to push a file up to the master server it is disabled by default for security purposes. To enable, set \fBfile_recv\fP to \fBTrue\fP in the master configuration file, and restart the master. .INDENT 7.0 .TP .B keep_symlinks Keep the path value without resolving its canonical form .TP .B upload_path Provide a different path inside the master\(aqs minion files cachedir .TP .B remove_source Remove the source file on the minion .sp New in version 2016.3.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.push /etc/fstab salt \(aq*\(aq cp.push /etc/system\-release keep_symlinks=True salt \(aq*\(aq cp.push /etc/fstab upload_path=\(aq/new/path/fstab\(aq salt \(aq*\(aq cp.push /tmp/filename remove_source=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.push_dir(path, glob=None, upload_path=None) Push a directory from the minion up to the master, the files will be saved to the salt master in the master\(aqs minion files cachedir (defaults to \fB/var/cache/salt/master/minions/minion\-id/files\fP). It also has a glob for matching specific files using globbing. .sp New in version 2014.7.0. .sp Since this feature allows a minion to push files up to the master server it is disabled by default for security purposes. To enable, set \fBfile_recv\fP to \fBTrue\fP in the master configuration file, and restart the master. .INDENT 7.0 .TP .B upload_path Provide a different path and directory name inside the master\(aqs minion files cachedir .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.push /usr/lib/mysql salt \(aq*\(aq cp.push /usr/lib/mysql upload_path=\(aq/newmysql/path\(aq salt \(aq*\(aq cp.push_dir /etc/modprobe.d/ glob=\(aq*.conf\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.recv(files, dest) Used with salt\-cp, pass the files dict, and the destination. .sp This function receives small fast copy files from the master via salt\-cp. It does not work via the CLI. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.recv .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.recv_chunked(dest, chunk, append=False, compressed=True, mode=None) This function receives files copied to the minion using \fBsalt\-cp\fP and is not intended to be used directly on the CLI. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.recv_chunked .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.stat_file(path, saltenv=None, octal=True) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp Return the permissions of a file, to get the permissions of a file on the salt master file server prepend the path with salt://<file on server> otherwise, prepend the file with / for a local file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.stat_file salt://path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.cpan .sp Manage Perl modules using CPAN .sp New in version 2015.5.0. .INDENT 0.0 .TP .B salt.modules.cpan.install(module) Install a Perl module from CPAN .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cpan.install Template::Alloy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cpan.list_() List installed Perl modules, and the version installed .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cpan.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cpan.remove(module, details=False) Attempt to remove a Perl module that was installed from CPAN. Because the \fBcpan\fP command doesn\(aqt actually support \(dquninstall\(dq\-like functionality, this function will attempt to do what it can, with what it has from CPAN. .sp Until this function is declared stable, USE AT YOUR OWN RISK! .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cpan.remove Old::Package .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cpan.show(module) Show information about a specific Perl module .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cpan.show Template::Alloy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cpan.show_config() Return a dict of CPAN configuration values .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cpan.show_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.cron .sp Work with cron .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt does not escape cron metacharacters automatically. You should backslash\-escape percent characters and any other metacharacters that might be interpreted incorrectly by the shell. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.get_entry(user, identifier=None, cmd=None) Return the specified entry from user\(aqs crontab. identifier will be used if specified, otherwise will lookup cmd Either identifier or cmd should be specified. .INDENT 7.0 .TP .B user: User\(aqs crontab to query .TP .B identifier: Search for line with identifier .TP .B cmd: Search for cron line with cmd .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.get_entry root identifier=task1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.list_tab(user) Return the contents of the specified user\(aqs crontab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.list_tab root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.ls(user) This function is an alias of \fBlist_tab\fP\&. .INDENT 7.0 .INDENT 3.5 Return the contents of the specified user\(aqs crontab .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.list_tab root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.raw_cron(user) Return the contents of the user\(aqs crontab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.raw_cron root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.rm(user, cmd, minute=None, hour=None, daymonth=None, month=None, dayweek=None, identifier=None) This function is an alias of \fBrm_job\fP\&. .INDENT 7.0 .INDENT 3.5 Remove a cron job for a specified user. If any of the day/time params are specified, the job will only be removed if the specified params match. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.rm_job root /usr/local/weekly salt \(aq*\(aq cron.rm_job root /usr/bin/foo dayweek=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.rm_env(user, name) Remove cron environment variable for a specified user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.rm_env root MAILTO .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.rm_job(user, cmd, minute=None, hour=None, daymonth=None, month=None, dayweek=None, identifier=None) Remove a cron job for a specified user. If any of the day/time params are specified, the job will only be removed if the specified params match. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.rm_job root /usr/local/weekly salt \(aq*\(aq cron.rm_job root /usr/bin/foo dayweek=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.rm_special(user, cmd, special=None, identifier=None) Remove a special cron job for a specified user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.rm_special root /usr/bin/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.set_env(user, name, value=None) Set up an environment variable in the crontab. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.set_env root MAILTO user@example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.set_job(user, minute, hour, daymonth, month, dayweek, cmd, commented=False, comment=None, identifier=None) Sets a cron job up for a specified user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.set_job root \(aq*\(aq \(aq*\(aq \(aq*\(aq \(aq*\(aq 1 /usr/local/weekly .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.set_special(user, special, cmd, commented=False, comment=None, identifier=None) Set up a special command in the crontab. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.set_special root @hourly \(aqecho foobar\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.write_cron_file(user, path) Writes the contents of a file to a user\(aqs crontab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.write_cron_file root /tmp/new_cron .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2015.8.9. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Some OS\(aq do not support specifying user via the \fIcrontab\fP command i.e. (Solaris, AIX) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.write_cron_file_verbose(user, path) Writes the contents of a file to a user\(aqs crontab and return error message on error .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.write_cron_file_verbose root /tmp/new_cron .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2015.8.9. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Some OS\(aq do not support specifying user via the \fIcrontab\fP command i.e. (Solaris, AIX) .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.cryptdev .sp Salt module to manage Unix cryptsetup jobs and the crypttab file .sp New in version 2018.3.0. .INDENT 0.0 .TP .B salt.modules.cryptdev.active() List existing device\-mapper device details. .UNINDENT .INDENT 0.0 .TP .B salt.modules.cryptdev.close(name) Close a crypt device using \fBcryptsetup\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cryptdev.close foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cryptdev.crypttab(config=\(aq/etc/crypttab\(aq) List the contents of the crypttab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cryptdev.crypttab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cryptdev.open(name, device, keyfile) Open a crypt device using \fBcryptsetup\fP\&. The \fBkeyfile\fP must not be \fBNone\fP or \fB\(aqnone\(aq\fP, because \fBcryptsetup\fP will otherwise ask for the password interactively. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cryptdev.open foo /dev/sdz1 /path/to/keyfile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cryptdev.rm_crypttab(name, config=\(aq/etc/crypttab\(aq) Remove the named mapping from the crypttab. If the described entry does not exist, nothing is changed, but the command succeeds by returning \fB\(aqabsent\(aq\fP\&. If a line is removed, it returns \fB\(aqchange\(aq\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cryptdev.rm_crypttab foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cryptdev.set_crypttab(name, device, password=\(aqnone\(aq, options=\(aq\(aq, config=\(aq/etc/crypttab\(aq, test=False, match_on=\(aqname\(aq) Verify that this device is represented in the crypttab, change the device to match the name passed, or add the name if it is not present. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cryptdev.set_crypttab foo /dev/sdz1 mypassword swap,size=256 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.csf .SS Support for Config Server Firewall (CSF) .INDENT 0.0 .TP .B maintainer Mostafa Hussein <\fI\%mostafa.hussein91@gmail.com\fP> .TP .B maturity new .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.allow(ip, port=None, proto=\(aqtcp\(aq, direction=\(aqin\(aq, port_origin=\(aqd\(aq, ip_origin=\(aqs\(aq, ttl=None, comment=\(aq\(aq) Add an rule to csf allowed hosts See \fB_access_rule()\fP\&. 1\- Add an IP: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.allow 127.0.0.1 salt \(aq*\(aq csf.allow 127.0.0.1 comment=\(dqAllow localhost\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.allow_port(port, proto=\(aqtcp\(aq, direction=\(aqboth\(aq) Like allow_ports, but it will append to the existing entry instead of replacing it. Takes a single port instead of a list of ports. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.allow_port 22 proto=\(aqtcp\(aq direction=\(aqin\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.allow_ports(ports, proto=\(aqtcp\(aq, direction=\(aqin\(aq) Fully replace the incoming or outgoing ports line in the csf.conf file \- e.g. TCP_IN, TCP_OUT, UDP_IN, UDP_OUT, etc. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.allow_ports ports=\(dq[22,80,443,4505,4506]\(dq proto=\(aqtcp\(aq direction=\(aqin\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.build_directions(direction) .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.deny(ip, port=None, proto=\(aqtcp\(aq, direction=\(aqin\(aq, port_origin=\(aqd\(aq, ip_origin=\(aqd\(aq, ttl=None, comment=\(aq\(aq) Add an rule to csf denied hosts See \fB_access_rule()\fP\&. 1\- Deny an IP: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.deny 127.0.0.1 salt \(aq*\(aq csf.deny 127.0.0.1 comment=\(dqToo localhosty\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.disable() Disable csf permanently .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.disable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.disable_testing_mode() .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.enable() Activate csf if not running .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.enable_testing_mode() .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.exists(method, ip, port=None, proto=\(aqtcp\(aq, direction=\(aqin\(aq, port_origin=\(aqd\(aq, ip_origin=\(aqd\(aq, ttl=None, comment=\(aq\(aq) Returns true a rule for the ip already exists based on the method supplied. Returns false if not found. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.exists allow 1.2.3.4 salt \(aq*\(aq csf.exists tempdeny 1.2.3.4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.get_option(option) .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.get_ports(proto=\(aqtcp\(aq, direction=\(aqin\(aq) Lists ports from csf.conf based on direction and protocol. e.g. \- TCP_IN, TCP_OUT, UDP_IN, UDP_OUT, etc.. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.allow_port 22 proto=\(aqtcp\(aq direction=\(aqin\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.get_skipped_nics(ipv6=False) .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.get_testing_status() .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.reload() Restart csf .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.reload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.remove_rule(method, ip, port=None, proto=\(aqtcp\(aq, direction=\(aqin\(aq, port_origin=\(aqd\(aq, ip_origin=\(aqs\(aq, ttl=None, comment=\(aq\(aq) .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.remove_temp_rule(ip) .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.running() Check csf status .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.running .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.set_option(option, value) .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.skip_nic(nic, ipv6=False) .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.skip_nics(nics, ipv6=False) .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.split_option(option) .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.tempallow(ip=None, ttl=None, port=None, direction=None, comment=\(aq\(aq) Add an rule to the temporary ip allow list. See \fB_access_rule()\fP\&. 1\- Add an IP: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.tempallow 127.0.0.1 3600 port=22 direction=\(aqin\(aq comment=\(aq# Temp dev ssh access\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.tempdeny(ip=None, ttl=None, port=None, direction=None, comment=\(aq\(aq) Add a rule to the temporary ip deny list. See \fB_access_rule()\fP\&. 1\- Add an IP: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.tempdeny 127.0.0.1 300 port=22 direction=\(aqin\(aq comment=\(aq# Brute force attempt\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.unallow(ip) Remove a rule from the csf denied hosts See \fB_access_rule()\fP\&. 1\- Deny an IP: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.unallow 127.0.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.csf.undeny(ip) Remove a rule from the csf denied hosts See \fB_access_rule()\fP\&. 1\- Deny an IP: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq csf.undeny 127.0.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.cyg .sp Manage cygwin packages. .sp Module file to accompany the cyg state. .INDENT 0.0 .TP .B salt.modules.cyg.check_valid_package(package, cyg_arch=\(aqx86_64\(aq, mirrors=None) Check if the package is valid on the given mirrors. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpackage\fP \-\- The name of the package .IP \(bu 2 \fBcyg_arch\fP \-\- The cygwin architecture .IP \(bu 2 \fBmirrors\fP \-\- any mirrors to check .UNINDENT .UNINDENT .sp Returns (bool): True if Valid, otherwise False .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cyg.check_valid_package <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cyg.install(packages=None, cyg_arch=\(aqx86_64\(aq, mirrors=None) Install one or several packages. .INDENT 7.0 .TP .B packages None The packages to install .TP .B cyg_arch x86_64 Specify the architecture to install the package under Current options are x86 and x86_64 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cyg.install dos2unix salt \(aq*\(aq cyg.install dos2unix mirrors=\(dq[{\(aqhttp://mirror\(aq: \(aqhttp://url/to/public/key}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cyg.list_(package=\(aq\(aq, cyg_arch=\(aqx86_64\(aq) List locally installed packages. .INDENT 7.0 .TP .B package \(aq\(aq package name to check. else all .TP .B cyg_arch : Cygwin architecture to use Options are x86 and x86_64 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cyg.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cyg.uninstall(packages, cyg_arch=\(aqx86_64\(aq, mirrors=None) Uninstall one or several packages. .INDENT 7.0 .TP .B packages The packages to uninstall. .TP .B cyg_arch x86_64 Specify the architecture to remove the package from Current options are x86 and x86_64 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cyg.uninstall dos2unix salt \(aq*\(aq cyg.uninstall dos2unix mirrors=\(dq[{\(aqhttp://mirror\(aq: \(aqhttp://url/to/public/key}]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cyg.update(cyg_arch=\(aqx86_64\(aq, mirrors=None) Update all packages. .INDENT 7.0 .TP .B cyg_arch x86_64 Specify the cygwin architecture update Current options are x86 and x86_64 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cyg.update salt \(aq*\(aq cyg.update dos2unix mirrors=\(dq[{\(aqhttp://mirror\(aq: \(aqhttp://url/to/public/key}]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.daemontools .sp daemontools service module. This module will create daemontools type service watcher. .sp This module is compatible with the \fI\%service\fP states, so it can be used to maintain services using the \fBprovider\fP argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myservice: service.running: \- provider: daemontools .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.available foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.disabled(name) Return True if the named service is enabled, false otherwise .sp New in version 2015.5.6. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.enabled(name, **kwargs) Return True if the named service is enabled, false otherwise A service is considered enabled if in your service directory: \- an executable ./run file exist \- a file named \(dqdown\(dq does not exist .sp New in version 2015.5.7. .INDENT 7.0 .TP .B name Service name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.enabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.full_restart(name) Calls daemontools.restart() function .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.full_restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.get_all() Return a list of all available services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.missing(name) The inverse of daemontools.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.missing foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.reload_(name) Wrapper for term() .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.restart(name) Restart service via daemontools. This will stop/start service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.start(name) Starts service via daemontools .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.status(name, sig=None) Return the status for a service via daemontools, return pid if running .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.status <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.stop(name) Stops service via daemontools .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.term(name) Send a TERM to service via daemontools .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.term <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.data .sp Manage a local persistent data structure that can hold any arbitrary data specific to the minion .INDENT 0.0 .TP .B salt.modules.data.cas(key, value, old_value) Check and set a value in the minion datastore .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.cas <key> <value> <old_value> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.clear() Clear out all of the data in the minion datastore, this function is destructive! .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.clear .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.dump(new_data) Replace the entire datastore with a passed data structure .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.dump \(aq{\(aqeggs\(aq: \(aqspam\(aq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.get(key, default=None) Get a (list of) value(s) from the minion datastore .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.get key salt \(aq*\(aq data.get \(aq[\(dqkey1\(dq, \(dqkey2\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.has_key(key) Check if key is in the minion datastore .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.has_key <mykey> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.items() Get items from the minion datastore .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.items .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.keys() Get all keys from the minion datastore .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.keys .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.load() Return all of the data in the minion datastore .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.load .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.pop(key, default=None) Pop (return & delete) a value from the minion datastore .sp New in version 2015.5.2. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.pop <key> \(dqthere was no val\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.update(key, value) Update a key with a value in the minion datastore .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.update <key> <value> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.values() Get values from the minion datastore .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.values .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.datadog_api .sp An execution module that interacts with the Datadog API .INDENT 0.0 .TP .B depends \fI\%datadog\fP Python module .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The following parameters are required for all functions: .INDENT 0.0 .TP .B api_key The datadog API key .TP .B app_key The datadog application key .UNINDENT .UNINDENT .UNINDENT .sp Full argument reference is available on the Datadog API reference page \fI\%https://docs.datadoghq.com/api/\fP .INDENT 0.0 .TP .B salt.modules.datadog_api.cancel_downtime(api_key=None, app_key=None, scope=None, id=None) Cancel a downtime by id or by scope. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call datadog.cancel_downtime scope=\(aqhost:app01\(aq \e api_key=\(aq0123456789\(aq \e app_key=\(aq9876543210\(aq\(ga .ft P .fi .UNINDENT .UNINDENT .sp Arguments \- Either scope or id is required. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBid\fP \-\- The downtime ID .IP \(bu 2 \fBscope\fP \-\- The downtime scope .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.datadog_api.post_event(api_key=None, app_key=None, title=None, text=None, date_happened=None, priority=None, host=None, tags=None, alert_type=None, aggregation_key=None, source_type_name=None) Post an event to the Datadog stream. .sp CLI Example .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call datadog.post_event api_key=\(aq0123456789\(aq \e app_key=\(aq9876543210\(aq \e title=\(aqSalt Highstate\(aq \e text=\(dqSalt highstate was run on $(salt\-call grains.get id)\(dq \e tags=\(aq[\(dqservice:salt\(dq, \(dqevent:highstate\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .sp Required arguments .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtitle\fP \-\- The event title. Limited to 100 characters. .IP \(bu 2 \fBtext\fP \-\- The body of the event. Limited to 4000 characters. The text supports markdown. .UNINDENT .UNINDENT .sp Optional arguments .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdate_happened\fP \-\- POSIX timestamp of the event. .IP \(bu 2 \fBpriority\fP \-\- The priority of the event (\(aqnormal\(aq or \(aqlow\(aq). .IP \(bu 2 \fBhost\fP \-\- Host name to associate with the event. .IP \(bu 2 \fBtags\fP \-\- A list of tags to apply to the event. .IP \(bu 2 \fBalert_type\fP \-\- \(dqerror\(dq, \(dqwarning\(dq, \(dqinfo\(dq or \(dqsuccess\(dq. .IP \(bu 2 \fBaggregation_key\fP \-\- An arbitrary string to use for aggregation, max length of 100 characters. .IP \(bu 2 \fBsource_type_name\fP \-\- The type of event being posted. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.datadog_api.schedule_downtime(scope, api_key=None, app_key=None, monitor_id=None, start=None, end=None, message=None, recurrence=None, timezone=None, test=False) Schedule downtime for a scope of monitors. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call datadog.schedule_downtime \(aqhost:app2\(aq \e stop=$(date \-\-date=\(aq30 minutes\(aq +%s) \e app_key=\(aq0123456789\(aq \e api_key=\(aq9876543210\(aq .ft P .fi .UNINDENT .UNINDENT .sp Optional arguments .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmonitor_id\fP \-\- The ID of the monitor .IP \(bu 2 \fBstart\fP \-\- Start time in seconds since the epoch .IP \(bu 2 \fBend\fP \-\- End time in seconds since the epoch .IP \(bu 2 \fBmessage\fP \-\- A message to send in a notification for this downtime .IP \(bu 2 \fBrecurrence\fP \-\- Repeat this downtime periodically .IP \(bu 2 \fBtimezone\fP \-\- Specify the timezone .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ddns .sp Support for RFC 2136 dynamic DNS updates. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 dnspython Python module .UNINDENT .TP .B configuration If you want to use TSIG authentication for the server, there are a couple of optional configuration parameters made available to support this (the keyname is only needed if the keyring contains more than one key): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C keyfile: keyring file (default=None) keyname: key name in file (default=None) keyalgorithm: algorithm used to create the key (default=\(aqHMAC\-MD5.SIG\-ALG.REG.INT\(aq). Other possible values: hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384, hmac\-sha512 .ft P .fi .UNINDENT .UNINDENT .sp The keyring file needs to be in json format and the key name needs to end with an extra period in the file, similar to this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(dqkeyname.\(dq: \(dqkeycontent\(dq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ddns.add_host(zone, name, ttl, ip, nameserver=\(aq127.0.0.1\(aq, replace=True, timeout=5, port=53, **kwargs) Add, replace, or update the A and PTR (reverse) records for a host. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 ddns.add_host example.com host1 60 10.1.1.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ddns.delete(zone, name, rdtype=None, data=None, nameserver=\(aq127.0.0.1\(aq, timeout=5, port=53, **kwargs) Delete a DNS record. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 ddns.delete example.com host1 A .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ddns.delete_host(zone, name, nameserver=\(aq127.0.0.1\(aq, timeout=5, port=53, **kwargs) Delete the forward and reverse records for a host. .sp Returns true if any records are deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 ddns.delete_host example.com host1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ddns.update(zone, name, ttl, rdtype, data, nameserver=\(aq127.0.0.1\(aq, timeout=5, replace=False, port=53, **kwargs) Add, replace, or update a DNS record. nameserver must be an IP address and the minion running this module must have update privileges on that server. If replace is true, first deletes all records for this name and type. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 ddns.update example.com host1 60 A 10.0.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.deb_apache .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%apache Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Support for Apache .sp Please note: The functions in here are Debian\-specific. Placing them in this separate file will allow them to load only on Debian\-based systems, while still loading under the \fBapache\fP namespace. .INDENT 0.0 .TP .B salt.modules.deb_apache.a2disconf(conf) New in version 2016.3.0. .sp Runs a2disconf for the given conf. .sp This will only be functional on Debian\-based operating systems (Ubuntu, Mint, etc). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.a2disconf security .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.deb_apache.a2dismod(mod) Runs a2dismod for the given mod. .sp This will only be functional on Debian\-based operating systems (Ubuntu, Mint, etc). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.a2dismod vhost_alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.deb_apache.a2dissite(site) Runs a2dissite for the given site. .sp This will only be functional on Debian\-based operating systems (Ubuntu, Mint, etc). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.a2dissite example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.deb_apache.a2enconf(conf) New in version 2016.3.0. .sp Runs a2enconf for the given conf. .sp This will only be functional on Debian\-based operating systems (Ubuntu, Mint, etc). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.a2enconf security .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.deb_apache.a2enmod(mod) Runs a2enmod for the given mod. .sp This will only be functional on Debian\-based operating systems (Ubuntu, Mint, etc). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.a2enmod vhost_alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.deb_apache.a2ensite(site) Runs a2ensite for the given site. .sp This will only be functional on Debian\-based operating systems (Ubuntu, Mint, etc). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.a2ensite example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.deb_apache.check_conf_enabled(conf) New in version 2016.3.0. .sp Checks to see if the specific conf symlink is in /etc/apache2/conf\-enabled. .sp This will only be functional on Debian\-based operating systems (Ubuntu, Mint, etc). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.check_conf_enabled security salt \(aq*\(aq apache.check_conf_enabled security.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.deb_apache.check_mod_enabled(mod) Checks to see if the specific mod symlink is in /etc/apache2/mods\-enabled. .sp This will only be functional on Debian\-based operating systems (Ubuntu, Mint, etc). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.check_mod_enabled status salt \(aq*\(aq apache.check_mod_enabled status.load salt \(aq*\(aq apache.check_mod_enabled status.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.deb_apache.check_site_enabled(site) Checks to see if the specific site symlink is in /etc/apache2/sites\-enabled. .sp This will only be functional on Debian\-based operating systems (Ubuntu, Mint, etc). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.check_site_enabled example.com salt \(aq*\(aq apache.check_site_enabled example.com.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.deb_postgres .sp Module to provide Postgres compatibility to salt for debian family specific tools. .INDENT 0.0 .TP .B salt.modules.deb_postgres.cluster_create(version, name=\(aqmain\(aq, port=None, locale=None, encoding=None, datadir=None, allow_group_access=None, data_checksums=None, wal_segsize=None) Adds a cluster to the Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.cluster_create \(aq9.3\(aq salt \(aq*\(aq postgres.cluster_create \(aq9.3\(aq \(aqmain\(aq salt \(aq*\(aq postgres.cluster_create \(aq9.3\(aq locale=\(aqfr_FR\(aq salt \(aq*\(aq postgres.cluster_create \(aq11\(aq data_checksums=True wal_segsize=\(aq32\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.deb_postgres.cluster_exists(version, name=\(aqmain\(aq) Checks if a given version and name of a cluster exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.cluster_exists \(aq9.3\(aq salt \(aq*\(aq postgres.cluster_exists \(aq9.3\(aq \(aqmain\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.deb_postgres.cluster_list(verbose=False) Return a list of cluster of Postgres server (tuples of version and name). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.cluster_list salt \(aq*\(aq postgres.cluster_list verbose=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.deb_postgres.cluster_remove(version, name=\(aqmain\(aq, stop=False) Remove a cluster on a Postgres server. By default it doesn\(aqt try to stop the cluster. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.cluster_remove \(aq9.3\(aq salt \(aq*\(aq postgres.cluster_remove \(aq9.3\(aq \(aqmain\(aq salt \(aq*\(aq postgres.cluster_remove \(aq9.3\(aq \(aqmain\(aq stop=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.debconfmod .sp Support for Debconf .INDENT 0.0 .TP .B salt.modules.debconfmod.get_selections(fetchempty=True) Answers to debconf questions for all packages in the following format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqpackage\(aq: [[\(aqquestion\(aq, \(aqtype\(aq, \(aqvalue\(aq], ...]} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq debconf.get_selections .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debconfmod.set_(package, question, type, value, *extra) Set answers to debconf questions for a package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq debconf.set <package> <question> <type> <value> [<value> ...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debconfmod.set_file(path, saltenv=\(aqbase\(aq, **kwargs) Set answers to debconf questions from a file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq debconf.set_file salt://pathto/pkg.selections .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debconfmod.set_template(path, template, context, defaults, saltenv=\(aqbase\(aq, **kwargs) Set answers to debconf questions from a template. .INDENT 7.0 .TP .B path location of the file containing the package selections .TP .B template template format .TP .B context variables to add to the template environment .TP .B default default values for the template environment .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq debconf.set_template salt://pathto/pkg.selections.jinja jinja None None .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debconfmod.show(name) Answers to debconf questions for a package in the following format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [[\(aqquestion\(aq, \(aqtype\(aq, \(aqvalue\(aq], ...] .ft P .fi .UNINDENT .UNINDENT .sp If debconf doesn\(aqt know about a package, we return None. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq debconf.show <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.debian_ip .sp The networking module for Debian\-based distros .sp References: .INDENT 0.0 .IP \(bu 2 \fI\%http://www.debian.org/doc/manuals/debian\-reference/ch05.en.html\fP .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.apply_network_settings(**settings) Apply global network configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.apply_network_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.build_bond(iface, **settings) Create a bond script in /etc/modprobe.d with the passed settings and load the bonding kernel module. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_bond bond0 mode=balance\-alb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.build_interface(iface, iface_type, enabled, **settings) Build an interface script for a network interface. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_interface eth0 eth <settings> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.build_network_settings(**settings) Build the global network script. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_network_settings <settings> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.build_routes(iface, **settings) Add route scripts for a network interface using up commands. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_routes eth0 <settings> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.down(iface, iface_type) Shutdown a network interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.down eth0 eth .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.get_bond(iface) Return the content of a bond script .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_bond bond0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.get_interface(iface) Return the contents of an interface script .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_interface eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.get_network_settings() Return the contents of the global network script. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_network_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.get_routes(iface) Return the routes for the interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_routes eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.up(iface, iface_type) Start up a network interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.up eth0 eth .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.debian_service .sp Service support for Debian systems (uses update\-rc.d and /sbin/service) .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage services on a minion, and it is using a different module (or gives an error similar to \fI\(aqservice.start\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.disable(name, **kwargs) Disable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.disabled(name) Return True if the named service is disabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.enable(name, **kwargs) Enable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.enabled(name, **kwargs) Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.force_reload(name) Force\-reload the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.force_reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.get_all() Return all available boot services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.get_disabled() Return a set of services that are installed but disabled .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.get_enabled() Return a list of service that are enabled on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.missing(name) The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.reload_(name) Reload the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.restart(name) Restart the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.start(name) Start the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.status(name, sig=None) Return the status for a service. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Signature to use to find the service via ps .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> [service signature] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.stop(name) Stop the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.debuild_pkgbuild .sp Debian Package builder system .sp New in version 2015.8.0. .sp This system allows for all of the components to build debs safely in chrooted environments. This also provides a function to generate debian repositories .sp This module implements the pkgbuild interface .INDENT 0.0 .TP .B salt.modules.debuild_pkgbuild.build(runas, tgt, dest_dir, spec, sources, deps, env, template, saltenv=\(aqbase\(aq, log_dir=\(aq/var/log/salt/pkgbuild\(aq) Given the package destination directory, the tarball containing debian files (e.g. control) and package sources, use pbuilder to safely build the platform package .sp CLI Example: .sp \fBDebian\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgbuild.make_src_pkg deb\-8\-x86_64 /var/www/html https://raw.githubusercontent.com/saltstack/libnacl/master/pkg/deb/python\-libnacl.control https://pypi.python.org/packages/source/l/libnacl/libnacl\-1.3.5.tar.gz .ft P .fi .UNINDENT .UNINDENT .sp This example command should build the libnacl package for Debian using pbuilder and place it in /var/www/html/ on the minion .UNINDENT .INDENT 0.0 .TP .B salt.modules.debuild_pkgbuild.make_repo(repodir, keyid=None, env=None, use_passphrase=False, gnupghome=\(aq/etc/salt/gpgkeys\(aq, runas=\(aqroot\(aq, timeout=15.0) Make a package repository and optionally sign it and packages present .sp Given the repodir (directory to create repository in), create a Debian repository and optionally sign it and packages present. This state is best used with onchanges linked to your package building states. .INDENT 7.0 .TP .B repodir The directory to find packages that will be in the repository. .TP .B keyid Changed in version 2016.3.0. .sp Optional Key ID to use in signing packages and repository. This consists of the last 8 hex digits of the GPG key ID. .sp Utilizes Public and Private keys associated with keyid which have been loaded into the minion\(aqs Pillar data. Leverages gpg\-agent and gpg\-preset\-passphrase for caching keys, etc. These pillar values are assumed to be filenames which are present in \fBgnupghome\fP\&. The pillar keys shown below have to match exactly. .sp For example, contents from a Pillar data file with named Public and Private keys as follows: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C gpg_pkg_priv_keyname: gpg_pkg_key.pem gpg_pkg_pub_keyname: gpg_pkg_key.pub .ft P .fi .UNINDENT .UNINDENT .TP .B env Changed in version 2016.3.0. .sp A dictionary of environment variables to be utilized in creating the repository. .TP .B use_passphrase False New in version 2016.3.0. .sp Use a passphrase with the signing key presented in \fBkeyid\fP\&. Passphrase is received from Pillar data which could be passed on the command line with \fBpillar\fP parameter. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pillar=\(aq{ \(dqgpg_passphrase\(dq : \(dqmy_passphrase\(dq }\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B gnupghome /etc/salt/gpgkeys New in version 2016.3.0. .sp Location where GPG related files are stored, used with \fBkeyid\fP\&. .TP .B runas root New in version 2016.3.0. .sp User to create the repository as, and optionally sign packages. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Ensure the user has correct permissions to any files and directories which are to be utilized. .UNINDENT .UNINDENT .TP .B timeout 15.0 New in version 2016.3.4. .sp Timeout in seconds to wait for the prompt for inputting the passphrase. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgbuild.make_repo /var/www/html .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debuild_pkgbuild.make_src_pkg(dest_dir, spec, sources, env=None, saltenv=\(aqbase\(aq, runas=\(aqroot\(aq) Create a platform specific source package from the given platform spec/control file and sources .sp CLI Example: .sp \fBDebian\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgbuild.make_src_pkg /var/www/html/ https://raw.githubusercontent.com/saltstack/libnacl/master/pkg/deb/python\-libnacl.control.tar.xz https://pypi.python.org/packages/source/l/libnacl/libnacl\-1.3.5.tar.gz .ft P .fi .UNINDENT .UNINDENT .sp This example command should build the libnacl SOURCE package and place it in /var/www/html/ on the minion .INDENT 7.0 .TP .B dest_dir Absolute path for directory to write source package .TP .B spec Absolute path to spec file or equivalent .TP .B sources Absolute path to source files to build source package from .TP .B env None A list or dictionary of environment variables to be set prior to execution. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- env: \- DEB_BUILD_OPTIONS: \(aqnocheck\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The above illustrates a common PyYAML pitfall, that \fByes\fP, \fBno\fP, \fBon\fP, \fBoff\fP, \fBtrue\fP, and \fBfalse\fP are all loaded as boolean \fBTrue\fP and \fBFalse\fP values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found \fI\%here\fP\&. .UNINDENT .UNINDENT .UNINDENT .sp saltenv: base .INDENT 7.0 .INDENT 3.5 Salt environment variables .UNINDENT .UNINDENT .INDENT 7.0 .TP .B runas root New in version 2019.2.1. .sp User to create the files and directories .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Ensure the user has correct permissions to any files and directories which are to be utilized. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.defaults .sp Module to work with salt formula defaults files .INDENT 0.0 .TP .B salt.modules.defaults.deepcopy(source) Allows deep copy of objects in formulas. .INDENT 7.0 .INDENT 3.5 By default, Python does not copy objects, it creates bindings between a target and an object. .UNINDENT .UNINDENT .sp It is more typical to use this in a templating language in formulas, instead of directly on the command\-line. .UNINDENT .INDENT 0.0 .TP .B salt.modules.defaults.get(key, default=\(aq\(aq) defaults.get is used much like pillar.get except that it will read a default value for a pillar from defaults.json or defaults.yaml files that are stored in the root of a salt formula. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq defaults.get core:users:root .ft P .fi .UNINDENT .UNINDENT .sp The defaults is computed from pillar key. The first entry is considered as the formula namespace. .sp For example, querying \fBcore:users:root\fP will try to load \fBsalt://core/defaults.yaml\fP and \fBsalt://core/defaults.json\fP\&. .UNINDENT .INDENT 0.0 .TP .B salt.modules.defaults.merge(dest, src, merge_lists=False, in_place=True, convert_none=True) Allows deep merging of dicts in formulas. .INDENT 7.0 .TP .B merge_lists False If True, it will also merge lists instead of replace their items. .TP .B in_place True If True, it will merge into dest dict, if not it will make a new copy from that dict and return it. .TP .B convert_none True If True, it will convert src and dest to empty dicts if they are None. If True and dest is None but in_place is True, raises TypeError. If False it will make a new copy from that dict and return it. .sp New in version 3005. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq defaults.merge \(aq{a: b}\(aq \(aq{d: e}\(aq .ft P .fi .UNINDENT .UNINDENT .sp It is more typical to use this in a templating language in formulas, instead of directly on the command\-line. .UNINDENT .INDENT 0.0 .TP .B salt.modules.defaults.update(dest, defaults, merge_lists=True, in_place=True, convert_none=True) Allows setting defaults for group of data set e.g. group for nodes. .INDENT 7.0 .INDENT 3.5 This function is a combination of defaults.merge and defaults.deepcopy to avoid redundant in jinja. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C group01: defaults: enabled: True extra: \- test \- stage nodes: host01: index: foo upstream: bar host02: index: foo2 upstream: bar2 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% do salt[\(aqdefaults.update\(aq](group01.nodes, group01.defaults) %} .ft P .fi .UNINDENT .UNINDENT .sp Each node will look like the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C host01: enabled: True index: foo upstream: bar extra: \- test \- stage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B merge_lists True If True, it will also merge lists instead of replace their items. .TP .B in_place True If True, it will merge into dest dict. if not it will make a new copy from that dict and return it. .TP .B convert_none True If True, it will convert src and dest to empty dicts if they are None. If True and dest is None but in_place is True, raises TypeError. If False it will make a new copy from that dict and return it. .sp New in version 3005. .UNINDENT .sp It is more typical to use this in a templating language in formulas, instead of directly on the command\-line. .UNINDENT .SS salt.modules.devinfo .sp Module for devinfo :maintainer: Alberto Planas <\fI\%aplanas@suse.com\fP> :maturity: new :depends: None :platform: Linux .INDENT 0.0 .TP .B salt.modules.devinfo.filter_(udev_in=None, udev_ex=None) Returns a list of devices, filtered under udev keys. .INDENT 7.0 .TP .B udev_in A dictionary of key:values that are expected in the device udev information .TP .B udev_ex A dictionary of key:values that are not expected in the device udev information (excluded) .UNINDENT .sp The key is a lower case string, joined by dots, that represent a path in the udev information dictionary. For example, \(aqe.id_bus\(aq will represent the udev entry \fIudev[\(aqE\(aq][\(aqID_BUS\(aq]\fP .sp If the udev entry is a list, the algorithm will check that at least one item match one item of the value of the parameters. .sp Returns list of devices that match \fIudev_in\fP and do not match \fIudev_ex\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq devinfo.filter udev_in=\(aq{\(dqe.id_bus\(dq: \(dqata\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.devinfo.hwinfo(items=None, short=True, listmd=False, devices=None) Probe for hardware .INDENT 7.0 .TP .B items List of hardware items to inspect. Default [\(aqbios\(aq, \(aqcpu\(aq, \(aqdisk\(aq, \(aqmemory\(aq, \(aqnetwork\(aq, \(aqpartition\(aq] .TP .B short Show only a summary. Default True. .TP .B listmd Report RAID devices. Default False. .TP .B devices List of devices to show information from. Default None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq devinfo.hwinfo salt \(aq*\(aq devinfo.hwinfo items=\(aq[\(dqdisk\(dq]\(aq short=no salt \(aq*\(aq devinfo.hwinfo items=\(aq[\(dqdisk\(dq]\(aq short=no devices=\(aq[\(dq/dev/sda\(dq]\(aq salt \(aq*\(aq devinfo.hwinfo devices=/dev/sda .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.devmap .sp Device\-Mapper module .INDENT 0.0 .TP .B salt.modules.devmap.multipath_flush(device) Device\-Mapper Multipath flush .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq devmap.multipath_flush mpath1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.devmap.multipath_list() Device\-Mapper Multipath list .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq devmap.multipath_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dig .sp Compendium of generic DNS utilities. The \(aqdig\(aq command line tool must be installed in order to use this module. .INDENT 0.0 .TP .B salt.modules.dig.A(host, nameserver=None) Return the A record for \fBhost\fP\&. .sp Always returns a list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.A www.google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.AAAA(host, nameserver=None) Return the AAAA record for \fBhost\fP\&. .sp Always returns a list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.AAAA www.google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.CNAME(host, nameserver=None) Return the CNAME record for \fBhost\fP\&. .sp New in version 3005. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.CNAME mail.google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.MX(domain, resolve=False, nameserver=None) Return a list of lists for the MX of \fBdomain\fP\&. .sp If the \fBresolve\fP argument is True, resolve IPs for the servers. .sp It\(aqs limited to one IP, because although in practice it\(aqs very rarely a round robin, it is an acceptable configuration and pulling just one IP lets the data be similar to the non\-resolved version. If you think an MX has multiple IPs, don\(aqt use the resolver here, resolve them in a separate step. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.MX google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.NS(domain, resolve=True, nameserver=None) Return a list of IPs of the nameservers for \fBdomain\fP .sp If \fBresolve\fP is False, don\(aqt resolve names. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.NS google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.PTR(host, nameserver=None) New in version 3006.0. .sp Return the PTR record for \fBhost\fP\&. .sp Always returns a list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.PTR 1.2.3.4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.SPF(domain, record=\(aqSPF\(aq, nameserver=None) Return the allowed IPv4 ranges in the SPF record for \fBdomain\fP\&. .sp If record is \fBSPF\fP and the SPF record is empty, the TXT record will be searched automatically. If you know the domain uses TXT and not SPF, specifying that will save a lookup. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.SPF google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.TXT(host, nameserver=None) Return the TXT record for \fBhost\fP\&. .sp Always returns a list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.TXT google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.a(host, nameserver=None) Return the A record for \fBhost\fP\&. .sp Always returns a list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.A www.google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.aaaa(host, nameserver=None) Return the AAAA record for \fBhost\fP\&. .sp Always returns a list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.AAAA www.google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.check_ip(addr) Check if address is a valid IP. returns True if valid, otherwise False. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.check_ip 127.0.0.1 salt ns1 dig.check_ip 1111:2222:3333:4444:5555:6666:7777:8888 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.cname(host, nameserver=None) Return the CNAME record for \fBhost\fP\&. .sp New in version 3005. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.CNAME mail.google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.mx(domain, resolve=False, nameserver=None) Return a list of lists for the MX of \fBdomain\fP\&. .sp If the \fBresolve\fP argument is True, resolve IPs for the servers. .sp It\(aqs limited to one IP, because although in practice it\(aqs very rarely a round robin, it is an acceptable configuration and pulling just one IP lets the data be similar to the non\-resolved version. If you think an MX has multiple IPs, don\(aqt use the resolver here, resolve them in a separate step. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.MX google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.ns(domain, resolve=True, nameserver=None) Return a list of IPs of the nameservers for \fBdomain\fP .sp If \fBresolve\fP is False, don\(aqt resolve names. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.NS google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.ptr(host, nameserver=None) New in version 3006.0. .sp Return the PTR record for \fBhost\fP\&. .sp Always returns a list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.PTR 1.2.3.4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.spf(domain, record=\(aqSPF\(aq, nameserver=None) Return the allowed IPv4 ranges in the SPF record for \fBdomain\fP\&. .sp If record is \fBSPF\fP and the SPF record is empty, the TXT record will be searched automatically. If you know the domain uses TXT and not SPF, specifying that will save a lookup. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.SPF google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.disk .sp Module for managing disks and blockdevices .INDENT 0.0 .TP .B salt.modules.disk.blkid(device=None, token=None) Return block device attributes: UUID, LABEL, etc. This function only works on systems where blkid is available. .INDENT 7.0 .TP .B device Device name from the system .TP .B token Any valid token used for the search .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.blkid salt \(aq*\(aq disk.blkid /dev/sda salt \(aq*\(aq disk.blkid token=\(aqUUID=6a38ee5\-7235\-44e7\-8b22\-816a403bad5d\(aq salt \(aq*\(aq disk.blkid token=\(aqTYPE=ext4\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.dump(device, args=None) Return all contents of dumpe2fs for a specified device .INDENT 7.0 .TP .B device The device path to dump. .TP .B args A list of attributes to return. Returns all by default. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.dump /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.format_(device, fs_type=\(aqext4\(aq, inode_size=None, lazy_itable_init=None, fat=None, force=False) Format a filesystem onto a device .sp New in version 2016.11.0. .INDENT 7.0 .TP .B device The device in which to create the new filesystem .TP .B fs_type The type of filesystem to create .TP .B inode_size Size of the inodes .sp This option is only enabled for ext and xfs filesystems .TP .B lazy_itable_init If enabled and the uninit_bg feature is enabled, the inode table will not be fully initialized by mke2fs. This speeds up filesystem initialization noticeably, but it requires the kernel to finish initializing the filesystem in the background when the filesystem is first mounted. If the option value is omitted, it defaults to 1 to enable lazy inode table zeroing. .sp This option is only enabled for ext filesystems .TP .B fat FAT size option. Can be 12, 16 or 32, and can only be used on fat or vfat filesystems. .TP .B force Force mke2fs to create a filesystem, even if the specified device is not a partition on a block special device. This option is only enabled for ext and xfs filesystems .sp This option is dangerous, use it with caution. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.format /dev/sdX1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.fstype(device) Return the filesystem name of the specified device .sp New in version 2016.11.0. .INDENT 7.0 .TP .B device The name of the device .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.fstype /dev/sdX1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.get_fstype_from_path(path) Return the filesystem type of the underlying device for a specified path. .sp New in version 3006.0. .INDENT 7.0 .TP .B path The path for the function to evaluate. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.get_fstype_from_path /root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.hdparms(disks, args=\(aqaAbBcCdgHiJkMmNnQrRuW\(aq) Retrieve disk parameters. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B disks Single disk or list of disks to query. .TP .B args Sequence of \fBhdparm\fP flags to fetch. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.hdparms /dev/sda .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.hpa(disks, size=None) Get/set Host Protected Area settings .sp T13 INCITS 346\-2001 (1367D) defines the BEER (Boot Engineering Extension Record) and PARTIES (Protected Area Run Time Interface Extension Services), allowing for a Host Protected Area on a disk. .sp It\(aqs often used by OEMS to hide parts of a disk, and for overprovisioning SSD\(aqs .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Setting the HPA might clobber your data, be very careful with this on active disks! .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.hpa /dev/sda salt \(aq*\(aq disk.hpa /dev/sda 5% salt \(aq*\(aq disk.hpa /dev/sda 10543256 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.inodeusage(args=None) Return inode usage information for volumes mounted on this minion .INDENT 7.0 .TP .B args Sequence of flags to pass to the \fBdf\fP command. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.inodeusage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.iostat(interval=1, count=5, disks=None) Gather and return (averaged) IO stats. .sp New in version 2016.3.0. .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.iostat 1 5 disks=sda .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.percent(args=None) Return partition information for volumes mounted on this minion .INDENT 7.0 .TP .B args Specify a single partition for which to return data. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.percent /var .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.resize2fs(device) Resizes the filesystem. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.resize2fs /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.smart_attributes(dev, attributes=None, values=None) Fetch SMART attributes Providing attributes will deliver only requested attributes Providing values will deliver only requested values for attributes .sp Default is the Backblaze recommended set (\fI\%https://www.backblaze.com/blog/hard\-drive\-smart\-stats/\fP): (5,187,188,197,198) .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.smart_attributes /dev/sda salt \(aq*\(aq disk.smart_attributes /dev/sda attributes=(5,187,188,197,198) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.tune(device, **kwargs) Set attributes for the specified device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.tune /dev/sda1 read\-ahead=1024 read\-write=True .ft P .fi .UNINDENT .UNINDENT .sp Valid options are: \fBread\-ahead\fP, \fBfilesystem\-read\-ahead\fP, \fBread\-only\fP, \fBread\-write\fP\&. .sp See the \fBblockdev(8)\fP manpage for a more complete description of these options. .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.usage(args=None) Return usage information for volumes mounted on this minion .INDENT 7.0 .TP .B args Sequence of flags to pass to the \fBdf\fP command. .UNINDENT .sp Changed in version 2019.2.0: Default for SunOS changed to 1 kilobyte blocks .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.usage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.wipe(device) Remove the filesystem information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.wipe /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.djangomod .sp Manage Django sites .INDENT 0.0 .TP .B salt.modules.djangomod.collectstatic(settings_module, bin_env=None, no_post_process=False, ignore=None, dry_run=False, clear=False, link=False, no_default_ignore=False, pythonpath=None, env=None, runas=None) Collect static files from each of your applications into a single location that can easily be served in production. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq django.collectstatic <settings_module> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.djangomod.command(settings_module, command, bin_env=None, pythonpath=None, env=None, runas=None, *args, **kwargs) Run arbitrary django management command .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq django.command <settings_module> <command> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.djangomod.createsuperuser(settings_module, username, email, bin_env=None, database=None, pythonpath=None, env=None, runas=None) Create a super user for the database. This function defaults to use the \fB\-\-noinput\fP flag which prevents the creation of a password for the superuser. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq django.createsuperuser <settings_module> user user@example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.djangomod.loaddata(settings_module, fixtures, bin_env=None, database=None, pythonpath=None, env=None) Load fixture data .INDENT 7.0 .TP .B Fixtures: comma separated list of fixtures to load .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq django.loaddata <settings_module> <comma delimited list of fixtures> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.djangomod.migrate(settings_module, app_label=None, migration_name=None, bin_env=None, database=None, pythonpath=None, env=None, noinput=True, runas=None) Run migrate .sp Execute the Django\-Admin migrate command (requires Django 1.7 or higher). .sp New in version 3000. .INDENT 7.0 .TP .B settings_module Specifies the settings module to use. The settings module should be in Python package syntax, e.g. mysite.settings. If this isn’t provided, django\-admin will use the DJANGO_SETTINGS_MODULE environment variable. .TP .B app_label Specific app to run migrations for, instead of all apps. This may involve running other apps’ migrations too, due to dependencies. .TP .B migration_name Named migration to be applied to a specific app. Brings the database schema to a state where the named migration is applied, but no later migrations in the same app are applied. This may involve unapplying migrations if you have previously migrated past the named migration. Use the name zero to unapply all migrations for an app. .TP .B bin_env Path to pip (or to a virtualenv). This can be used to specify the path to the pip to use when more than one Python release is installed (e.g. \fB/usr/bin/pip\-2.7\fP or \fB/usr/bin/pip\-2.6\fP\&. If a directory path is specified, it is assumed to be a virtualenv. .TP .B database Database to migrate. Defaults to \(aqdefault\(aq. .TP .B pythonpath Adds the given filesystem path to the Python import search path. If this isn’t provided, django\-admin will use the PYTHONPATH environment variable. .TP .B env A list of environment variables to be set prior to execution. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C module.run: \- name: django.migrate \- settings_module: my_django_app.settings \- env: \- DATABASE_USER: \(aqmydbuser\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B noinput Suppresses all user prompts. Defaults to True. .TP .B runas The user name to run the command as. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq django.migrate <settings_module> salt \(aq*\(aq django.migrate <settings_module> <app_label> salt \(aq*\(aq django.migrate <settings_module> <app_label> <migration_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.djangomod.syncdb(settings_module, bin_env=None, migrate=False, database=None, pythonpath=None, env=None, noinput=True, runas=None) Run syncdb .sp Execute the Django\-Admin syncdb command, if South is available on the minion the \fBmigrate\fP option can be passed as \fBTrue\fP calling the migrations to run after the syncdb completes .sp NOTE: The syncdb command was deprecated in Django 1.7 and removed in Django 1.9. For Django versions 1.9 or higher use the \fImigrate\fP command instead. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq django.syncdb <settings_module> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dnsmasq .sp Module for managing dnsmasq .INDENT 0.0 .TP .B salt.modules.dnsmasq.fullversion() Shows installed version of dnsmasq and compile options. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsmasq.fullversion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsmasq.get_config(config_file=\(aq/etc/dnsmasq.conf\(aq) Dumps all options from the config file. .INDENT 7.0 .TP .B config_file The location of the config file from which to obtain contents. Defaults to \fB/etc/dnsmasq.conf\fP\&. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsmasq.get_config salt \(aq*\(aq dnsmasq.get_config config_file=/etc/dnsmasq.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsmasq.set_config(config_file=\(aq/etc/dnsmasq.conf\(aq, follow=True, **kwargs) Sets a value or a set of values in the specified file. By default, if conf\-dir is configured in this file, salt will attempt to set the option in any file inside the conf\-dir where it has already been enabled. If it does not find it inside any files, it will append it to the main config file. Setting follow to False will turn off this behavior. .sp If a config option currently appears multiple times (such as dhcp\-host, which is specified at least once per host), the new option will be added to the end of the main config file (and not to any includes). If you need an option added to a specific include file, specify it as the config_file. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconfig_file\fP (\fIstring\fP) \-\- config file where settings should be updated / added. .IP \(bu 2 \fBfollow\fP (\fI\%bool\fP) \-\- attempt to set the config option inside any file within the \fBconf\-dir\fP where it has already been enabled. .IP \(bu 2 \fBkwargs\fP \-\- key value pairs that contain the configuration settings that you want set. .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsmasq.set_config domain=mydomain.com salt \(aq*\(aq dnsmasq.set_config follow=False domain=mydomain.com salt \(aq*\(aq dnsmasq.set_config config_file=/etc/dnsmasq.conf domain=mydomain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsmasq.version() Shows installed version of dnsmasq. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsmasq.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dnsutil .sp Compendium of generic DNS utilities. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Some functions in the \fBdnsutil\fP execution module depend on \fBdig\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.A(host, nameserver=None) Return the A record(s) for \fBhost\fP\&. .sp Always returns a list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dnsutil.A www.google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.AAAA(host, nameserver=None) Return the AAAA record(s) for \fBhost\fP\&. .sp Always returns a list. .sp New in version 2014.7.5. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dnsutil.AAAA www.google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.MX(domain, resolve=False, nameserver=None) Return a list of lists for the MX of \fBdomain\fP\&. .sp If the \(aqresolve\(aq argument is True, resolve IPs for the servers. .sp It\(aqs limited to one IP, because although in practice it\(aqs very rarely a round robin, it is an acceptable configuration and pulling just one IP lets the data be similar to the non\-resolved version. If you think an MX has multiple IPs, don\(aqt use the resolver here, resolve them in a separate step. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dnsutil.MX google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.NS(domain, resolve=True, nameserver=None) Return a list of IPs of the nameservers for \fBdomain\fP .sp If \(aqresolve\(aq is False, don\(aqt resolve names. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dnsutil.NS google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.SPF(domain, record=\(aqSPF\(aq, nameserver=None) Return the allowed IPv4 ranges in the SPF record for \fBdomain\fP\&. .sp If record is \fBSPF\fP and the SPF record is empty, the TXT record will be searched automatically. If you know the domain uses TXT and not SPF, specifying that will save a lookup. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dnsutil.SPF google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.check_ip(ip_addr) Check that string ip_addr is a valid IP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dnsutil.check_ip 127.0.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.hosts_append(hostsfile=\(aq/etc/hosts\(aq, ip_addr=None, entries=None) Append a single line to the /etc/hosts file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsutil.hosts_append /etc/hosts 127.0.0.1 ad1.yuk.co,ad2.yuk.co .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.hosts_remove(hostsfile=\(aq/etc/hosts\(aq, entries=None) Remove a host from the /etc/hosts file. If doing so will leave a line containing only an IP address, then the line will be deleted. This function will leave comments and blank lines intact. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsutil.hosts_remove /etc/hosts ad1.yuk.co salt \(aq*\(aq dnsutil.hosts_remove /etc/hosts ad2.yuk.co,ad1.yuk.co .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.parse_hosts(hostsfile=\(aq/etc/hosts\(aq, hosts=None) Parse /etc/hosts file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsutil.parse_hosts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.parse_zone(zonefile=None, zone=None) Parses a zone file. Can be passed raw zone data on the API level. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dnsutil.parse_zone /var/lib/named/example.com.zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.serial(zone=\(aq\(aq, update=False) Return, store and update a dns serial for your zone files. .sp zone: a keyword for a specific zone .sp update: store an updated version of the serial in a grain .sp If \fBupdate\fP is False, the function will retrieve an existing serial or return the current date if no serial is stored. Nothing will be stored .sp If \fBupdate\fP is True, the function will set the serial to the current date if none exist or if the existing serial is for a previous date. If a serial for greater than the current date is already stored, the function will increment it. .sp This module stores the serial in a grain, you can explicitly set the stored value as a grain named \fBdnsserial_<zone_name>\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dnsutil.serial example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dockercompose .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%docker Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Module to import docker\-compose via saltstack .sp New in version 2016.3.0. .INDENT 0.0 .TP .B maintainer Jean Praloran <\fI\%jeanpralo@gmail.com\fP> .TP .B maturity new .TP .B depends docker\-compose>=1.5 .TP .B platform all .UNINDENT .SS Introduction .sp This module allows one to deal with docker\-compose file in a directory. .sp This is a first version only, the following commands are missing at the moment but will be built later on if the community is interested in this module: .INDENT 0.0 .IP \(bu 2 run .IP \(bu 2 logs .IP \(bu 2 port .IP \(bu 2 scale .UNINDENT .SS Installation Prerequisites .sp This execution module requires at least version 1.4.0 of both \fI\%docker\-compose\fP and \fI\%Docker\fP\&. docker\-compose can easily be installed using \fI\%pip.install\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pip.install docker\-compose>=1.5.0 .ft P .fi .UNINDENT .UNINDENT .SS How to use this module? .sp In order to use the module if you have no docker\-compose file on the server you can issue the command create, it takes two arguments the path where the docker\-compose.yml will be stored and the content of this latter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call \-l debug dockercompose.create /tmp/toto \(aq database: image: mongo:3.0 command: mongod \-\-smallfiles \-\-quiet \-\-logpath=/dev/null \(aq .ft P .fi .UNINDENT .UNINDENT .sp Then you can execute a list of method defined at the bottom with at least one argument (the path where the docker\-compose.yml will be read) and an optional python list which corresponds to the services names: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call \-l debug dockercompose.up /tmp/toto # salt\-call \-l debug dockercompose.restart /tmp/toto \(aq[database]\(aq # salt\-call \-l debug dockercompose.stop /tmp/toto # salt\-call \-l debug dockercompose.rm /tmp/toto .ft P .fi .UNINDENT .UNINDENT .SS Docker\-compose method supported .INDENT 0.0 .IP \(bu 2 up .IP \(bu 2 restart .IP \(bu 2 stop .IP \(bu 2 start .IP \(bu 2 pause .IP \(bu 2 unpause .IP \(bu 2 kill .IP \(bu 2 rm .IP \(bu 2 ps .IP \(bu 2 pull .IP \(bu 2 build .UNINDENT .SS Functions .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B docker\-compose.yml management .INDENT 7.0 .IP \(bu 2 \fI\%dockercompose.create\fP .IP \(bu 2 \fI\%dockercompose.get\fP .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B Manage containers .INDENT 7.0 .IP \(bu 2 \fI\%dockercompose.restart\fP .IP \(bu 2 \fI\%dockercompose.stop\fP .IP \(bu 2 \fI\%dockercompose.pause\fP .IP \(bu 2 \fI\%dockercompose.unpause\fP .IP \(bu 2 \fI\%dockercompose.start\fP .IP \(bu 2 \fI\%dockercompose.kill\fP .IP \(bu 2 \fI\%dockercompose.rm\fP .IP \(bu 2 \fI\%dockercompose.up\fP .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B Manage containers image: .INDENT 7.0 .IP \(bu 2 \fI\%dockercompose.pull\fP .IP \(bu 2 \fI\%dockercompose.build\fP .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B Gather information about containers: .INDENT 7.0 .IP \(bu 2 \fI\%dockercompose.ps\fP .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B Manage service definitions: .INDENT 7.0 .IP \(bu 2 \fI\%dockercompose.service_create\fP .IP \(bu 2 \fI\%dockercompose.service_upsert\fP .IP \(bu 2 \fI\%dockercompose.service_remove\fP .IP \(bu 2 \fI\%dockercompose.service_set_tag\fP .UNINDENT .UNINDENT .UNINDENT .SS Detailed Function Documentation .INDENT 0.0 .TP .B salt.modules.dockercompose.build(path, service_names=None) Build image for containers in the docker\-compose file, service_names is a python list, if omitted build images for all containers. Please note that at the moment the module does not allow you to upload your Dockerfile, nor any other file you could need with your docker\-compose.yml, you will have to make sure the files you need are actually in the directory specified in the \fIbuild\fP keyword .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_names If specified will pull only the image for the specified services .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.build /path/where/docker\-compose/stored salt myminion dockercompose.build /path/where/docker\-compose/stored \(aq[janus]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.create(path, docker_compose) Create and validate a docker\-compose file into a directory .INDENT 7.0 .TP .B path Path where the docker\-compose file will be stored on the server .TP .B docker_compose docker_compose file .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.create /path/where/docker\-compose/stored content .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.get(path) Get the content of the docker\-compose file into a directory .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.get /path/where/docker\-compose/stored .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.kill(path, service_names=None) Kill containers in the docker\-compose file, service_names is a python list, if omitted kill all containers .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_names If specified will kill only the specified services .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.kill /path/where/docker\-compose/stored salt myminion dockercompose.kill /path/where/docker\-compose/stored \(aq[janus]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.pause(path, service_names=None) Pause running containers in the docker\-compose file, service_names is a python list, if omitted pause all containers .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_names If specified will pause only the specified services .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.pause /path/where/docker\-compose/stored salt myminion dockercompose.pause /path/where/docker\-compose/stored \(aq[janus]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.ps(path) List all running containers and report some information about them .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.ps /path/where/docker\-compose/stored .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.pull(path, service_names=None) Pull image for containers in the docker\-compose file, service_names is a python list, if omitted pull all images .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_names If specified will pull only the image for the specified services .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.pull /path/where/docker\-compose/stored salt myminion dockercompose.pull /path/where/docker\-compose/stored \(aq[janus]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.restart(path, service_names=None) Restart container(s) in the docker\-compose file, service_names is a python list, if omitted restart all containers .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_names If specified will restart only the specified services .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.restart /path/where/docker\-compose/stored salt myminion dockercompose.restart /path/where/docker\-compose/stored \(aq[janus]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.rm(path, service_names=None) Remove stopped containers in the docker\-compose file, service_names is a python list, if omitted remove all stopped containers .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_names If specified will remove only the specified stopped services .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.rm /path/where/docker\-compose/stored salt myminion dockercompose.rm /path/where/docker\-compose/stored \(aq[janus]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.service_create(path, service_name, definition) Create the definition of a docker\-compose service This fails when the service already exists This does not pull or up the service This wil re\-write your yaml file. Comments will be lost. Indentation is set to 2 spaces .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_name Name of the service to create .TP .B definition Service definition as yaml or json string .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.service_create /path/where/docker\-compose/stored service_name definition .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.service_remove(path, service_name) Remove the definition of a docker\-compose service This does not rm the container This wil re\-write your yaml file. Comments will be lost. Indentation is set to 2 spaces .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_name Name of the service to remove .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.service_remove /path/where/docker\-compose/stored service_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.service_set_tag(path, service_name, tag) Change the tag of a docker\-compose service This does not pull or up the service This wil re\-write your yaml file. Comments will be lost. Indentation is set to 2 spaces .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_name Name of the service to remove .TP .B tag Name of the tag (often used as version) that the service image should have .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.service_create /path/where/docker\-compose/stored service_name tag .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.service_upsert(path, service_name, definition) Create or update the definition of a docker\-compose service This does not pull or up the service This wil re\-write your yaml file. Comments will be lost. Indentation is set to 2 spaces .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_name Name of the service to create .TP .B definition Service definition as yaml or json string .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.service_upsert /path/where/docker\-compose/stored service_name definition .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.start(path, service_names=None) Start containers in the docker\-compose file, service_names is a python list, if omitted start all containers .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_names If specified will start only the specified services .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.start /path/where/docker\-compose/stored salt myminion dockercompose.start /path/where/docker\-compose/stored \(aq[janus]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.stop(path, service_names=None) Stop running containers in the docker\-compose file, service_names is a python list, if omitted stop all containers .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_names If specified will stop only the specified services .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.stop /path/where/docker\-compose/stored salt myminion dockercompose.stop /path/where/docker\-compose/stored \(aq[janus]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.unpause(path, service_names=None) Un\-Pause containers in the docker\-compose file, service_names is a python list, if omitted unpause all containers .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_names If specified will un\-pause only the specified services .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.pause /path/where/docker\-compose/stored salt myminion dockercompose.pause /path/where/docker\-compose/stored \(aq[janus]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockercompose.up(path, service_names=None) Create and start containers defined in the docker\-compose.yml file located in path, service_names is a python list, if omitted create and start all containers .INDENT 7.0 .TP .B path Path where the docker\-compose file is stored on the server .TP .B service_names If specified will create and start only the specified services .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion dockercompose.up /path/where/docker\-compose/stored salt myminion dockercompose.up /path/where/docker\-compose/stored \(aq[janus]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dockermod .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%docker Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Management of Docker Containers .sp New in version 2015.8.0. .sp Changed in version 2017.7.0: This module has replaced the legacy docker execution module. .INDENT 0.0 .TP .B depends \fI\%docker\fP Python module .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Older releases of the Python bindings for Docker were called \fI\%docker\-py\fP in PyPI. All releases of \fI\%docker\fP, and releases of \fI\%docker\-py\fP >= 1.6.0 are supported. These python bindings can easily be installed using \fI\%pip.install\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pip.install docker .ft P .fi .UNINDENT .UNINDENT .sp To upgrade from \fI\%docker\-py\fP to \fI\%docker\fP, you must first uninstall \fI\%docker\-py\fP, and then install \fI\%docker\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pip.uninstall docker\-py salt myminion pip.install docker .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Authentication .sp If you have previously performed a \fBdocker login\fP from the minion, then the credentials saved in \fB~/.docker/config.json\fP will be used for any actions which require authentication. If not, then credentials can be configured in any of the following locations: .INDENT 0.0 .IP \(bu 2 Minion config file .IP \(bu 2 Grains .IP \(bu 2 Pillar data .IP \(bu 2 Master config file (requires \fBpillar_opts\fP to be set to \fBTrue\fP in Minion config file in order to work) .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 Versions prior to 3000 require that Docker credentials are configured in Pillar data. Be advised that Pillar data is still recommended though, because this keeps the configuration from being stored on the Minion. .sp Also, keep in mind that if one gets your \fB~/.docker/config.json\fP, the password can be decoded from its contents. .UNINDENT .UNINDENT .sp The configuration schema is as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C docker\-registries: <registry_url>: username: <username> password: <password> .ft P .fi .UNINDENT .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C docker\-registries: hub: username: foo password: s3cr3t .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As of the 2016.3.7, 2016.11.4, and 2017.7.0 releases of Salt, credentials for the Docker Hub can be configured simply by specifying \fBhub\fP in place of the registry URL. In earlier releases, it is necessary to specify the actual registry URL for the Docker Hub (i.e. \fBhttps://index.docker.io/v1/\fP). .UNINDENT .UNINDENT .sp More than one registry can be configured. Salt will look for Docker credentials in the \fBdocker\-registries\fP Pillar key, as well as any key ending in \fB\-docker\-registries\fP\&. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C docker\-registries: \(aqhttps://mydomain.tld/registry:5000\(aq: username: foo password: s3cr3t foo\-docker\-registries: https://index.foo.io/v1/: username: foo password: s3cr3t bar\-docker\-registries: https://index.bar.io/v1/: username: foo password: s3cr3t .ft P .fi .UNINDENT .UNINDENT .sp To login to the configured registries, use the \fI\%docker.login\fP function. This only needs to be done once for a given registry, and it will store/update the credentials in \fB~/.docker/config.json\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For Salt releases before 2016.3.7 and 2016.11.4, \fI\%docker.login\fP is not available. Instead, Salt will try to authenticate using each of your configured registries for each push/pull, behavior which is not correct and has been resolved in newer releases. .UNINDENT .UNINDENT .SS Configuration Options .sp The following configuration options can be set to fine\-tune how Salt uses Docker: .INDENT 0.0 .IP \(bu 2 \fBdocker.url\fP: URL to the docker service (default: local socket). .IP \(bu 2 \fBdocker.version\fP: API version to use (should not need to be set manually in the vast majority of cases) .IP \(bu 2 \fBdocker.exec_driver\fP: Execution driver to use, one of \fBnsenter\fP, \fBlxc\-attach\fP, or \fBdocker\-exec\fP\&. See the \fI\%Executing Commands Within a Running Container\fP section for more details on how this config parameter is used. .UNINDENT .sp These configuration options are retrieved using \fI\%config.get\fP (click the link for further information). .SS Executing Commands Within a Running Container .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 With the release of Docker 1.13.1, the Execution Driver has been removed. Starting in versions 2016.3.6, 2016.11.4, and 2017.7.0, Salt defaults to using \fBdocker exec\fP to run commands in containers, however for older Salt releases it will be necessary to set the \fBdocker.exec_driver\fP config option to either \fBdocker\-exec\fP or \fBnsenter\fP for Docker versions 1.13.1 and newer. .UNINDENT .UNINDENT .sp Multiple methods exist for executing commands within Docker containers: .INDENT 0.0 .IP \(bu 2 \fI\%lxc\-attach\fP: Default for older versions of docker .IP \(bu 2 \fI\%nsenter\fP: Enters container namespace to run command .IP \(bu 2 \fI\%docker\-exec\fP: Native support for executing commands in Docker containers (added in Docker 1.3) .UNINDENT .sp Adding a configuration option (see \fI\%config.get\fP) called \fBdocker.exec_driver\fP will tell Salt which execution driver to use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C docker.exec_driver: docker\-exec .ft P .fi .UNINDENT .UNINDENT .sp If this configuration option is not found, Salt will use the appropriate interface (either \fI\%nsenter\fP or \fI\%lxc\-attach\fP) based on the \fBExecution Driver\fP value returned from \fBdocker info\fP\&. \fI\%docker\-exec\fP will not be used by default, as it is presently (as of version 1.6.2) only able to execute commands as the effective user of the container. Thus, if a \fBUSER\fP directive was used to run as a non\-privileged user, \fI\%docker\-exec\fP would be unable to perform the action as root. Salt can still use \fI\%docker\-exec\fP as an execution driver, but must be explicitly configured (as in the example above) to do so at this time. .sp If possible, try to manually specify the execution driver, as it will save Salt a little work. .sp This execution module provides functions that shadow those from the \fI\%cmd\fP module. They are as follows: .INDENT 0.0 .IP \(bu 2 \fI\%docker.retcode\fP .IP \(bu 2 \fI\%docker.run\fP .IP \(bu 2 \fI\%docker.run_all\fP .IP \(bu 2 \fI\%docker.run_stderr\fP .IP \(bu 2 \fI\%docker.run_stdout\fP .IP \(bu 2 \fI\%docker.script\fP .IP \(bu 2 \fI\%docker.script_retcode\fP .UNINDENT .SS Detailed Function Documentation .INDENT 0.0 .TP .B class salt.modules.dockermod.DockerJSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None) .INDENT 7.0 .TP .B decode(s, _w=None) Return the Python representation of \fBs\fP (a \fBstr\fP instance containing a JSON document). .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.apply_(name, mods=None, **kwargs) New in version 2019.2.0. .sp Apply states! This function will call highstate or state.sls based on the arguments passed in, \fBapply\fP is intended to be the main gateway for all state executions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdocker\(aq docker.apply web01 salt \(aqdocker\(aq docker.apply web01 test salt \(aqdocker\(aq docker.apply web01 test,pkgs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.build(path=None, repository=None, tag=None, cache=True, rm=True, api_response=False, fileobj=None, dockerfile=None, buildargs=None) Changed in version 2018.3.0: If the built image should be tagged, then the repository and tag must now be passed separately using the \fBrepository\fP and \fBtag\fP arguments, rather than together in the (now deprecated) \fBimage\fP argument. .sp Builds a docker image from a Dockerfile or a URL .INDENT 7.0 .TP .B path Path to directory on the Minion containing a Dockerfile .TP .B repository Optional repository name for the image being built .sp New in version 2018.3.0. .TP .B tag latest Tag name for the image (required if \fBrepository\fP is passed) .sp New in version 2018.3.0. .TP .B image Deprecated since version 2018.3.0: Use both \fBrepository\fP and \fBtag\fP instead .TP .B cache True Set to \fBFalse\fP to force the build process not to use the Docker image cache, and pull all required intermediate image layers .TP .B rm True Remove intermediate containers created during build .TP .B api_response False If \fBTrue\fP: an \fBAPI_Response\fP key will be present in the return data, containing the raw output from the Docker API. .TP .B fileobj Allows for a file\-like object containing the contents of the Dockerfile to be passed in place of a file \fBpath\fP argument. This argument should not be used from the CLI, only from other Salt code. .TP .B dockerfile Allows for an alternative Dockerfile to be specified. Path to alternative Dockefile is relative to the build path for the Docker container. .sp New in version 2016.11.0. .TP .B buildargs A dictionary of build arguments provided to the docker build process. .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary containing one or more of the following keys: .INDENT 7.0 .IP \(bu 2 \fBId\fP \- ID of the newly\-built image .IP \(bu 2 \fBTime_Elapsed\fP \- Time in seconds taken to perform the build .IP \(bu 2 \fBIntermediate_Containers\fP \- IDs of containers created during the course of the build process .sp \fI(Only present if rm=False)\fP .IP \(bu 2 .INDENT 2.0 .TP .B \fBImages\fP \- A dictionary containing one or more of the following keys: .INDENT 7.0 .IP \(bu 2 \fBAlready_Pulled\fP \- Layers that that were already present on the Minion .IP \(bu 2 \fBPulled\fP \- Layers that that were pulled .UNINDENT .UNINDENT .sp \fI(Only present if the image specified by the \(dqrepository\(dq and \(dqtag\(dq arguments was not present on the Minion, or if cache=False)\fP .IP \(bu 2 \fBStatus\fP \- A string containing a summary of the pull action (usually a message saying that an image was downloaded, or that it was up to date). .sp \fI(Only present if the image specified by the \(dqrepository\(dq and \(dqtag\(dq arguments was not present on the Minion, or if cache=False)\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.build /path/to/docker/build/dir salt myminion docker.build https://github.com/myuser/myrepo.git repository=myimage tag=latest salt myminion docker.build /path/to/docker/build/dir dockerfile=Dockefile.different repository=myimage tag=dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.call(name, function, *args, **kwargs) Executes a Salt function inside a running container .sp New in version 2016.11.0. .sp The container does not need to have Salt installed, but Python is required. .INDENT 7.0 .TP .B name Container name or ID .TP .B function Salt execution module function .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.call test.ping salt myminion test.arg arg1 arg2 key1=val1 salt myminion dockerng.call compassionate_mirzakhani test.arg arg1 arg2 key1=val1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.commit(name, repository, tag=\(aqlatest\(aq, message=None, author=None) Changed in version 2018.3.0: The repository and tag must now be passed separately using the \fBrepository\fP and \fBtag\fP arguments, rather than together in the (now deprecated) \fBimage\fP argument. .sp Commits a container, thereby promoting it to an image. Equivalent to running the \fBdocker commit\fP Docker CLI command. .INDENT 7.0 .TP .B name Container name or ID to commit .TP .B repository Repository name for the image being committed .sp New in version 2018.3.0. .TP .B tag latest Tag name for the image .sp New in version 2018.3.0. .TP .B image Deprecated since version 2018.3.0: Use both \fBrepository\fP and \fBtag\fP instead .TP .B message Commit message (Optional) .TP .B author Author name (Optional) .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBId\fP \- ID of the newly\-created image .IP \(bu 2 \fBImage\fP \- Name of the newly\-created image .IP \(bu 2 \fBTime_Elapsed\fP \- Time in seconds taken to perform the commit .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.commit mycontainer myuser/myimage mytag .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.compare_container(first, second, ignore=None) This function is an alias of \fBcompare_containers\fP\&. .INDENT 7.0 .INDENT 3.5 New in version 2017.7.0. .sp Changed in version 2018.3.0: Renamed from \fBdocker.compare_container\fP to \fBdocker.compare_containers\fP (old function name remains as an alias) .sp Compare two containers\(aq Config and and HostConfig and return any differences between the two. .INDENT 0.0 .TP .B first Name or ID of first container .TP .B second Name or ID of second container .TP .B ignore A comma\-separated list (or Python list) of keys to ignore when comparing. This is useful when comparing two otherwise identical containers which have different hostnames. .UNINDENT .sp CLI Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.compare_containers foo bar salt myminion docker.compare_containers foo bar ignore=Hostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.compare_container_networks(first, second) New in version 2018.3.0. .sp Returns the differences between two containers\(aq networks. When a network is only present one of the two containers, that network\(aqs diff will simply be represented with \fBTrue\fP for the side of the diff in which the network is present) and \fBFalse\fP for the side of the diff in which the network is absent. .sp This function works by comparing the contents of both containers\(aq \fBNetworks\fP keys (under \fBNetworkSettings\fP) in the return data from \fI\%docker.inspect_container\fP\&. Because each network contains some items that either A) only set at runtime, B) naturally varying from container to container, or both, by default the following keys in each network are examined: .INDENT 7.0 .IP \(bu 2 \fBAliases\fP .IP \(bu 2 \fBLinks\fP .IP \(bu 2 \fBIPAMConfig\fP .UNINDENT .sp The exception to this is if \fBIPAMConfig\fP is unset (i.e. null) in one container but not the other. This happens when no static IP configuration is set, and automatic IP configuration is in effect. So, in order to report on changes between automatic IP configuration in one container and static IP configuration in another container (as we need to do for the \fI\%docker_container.running\fP state), automatic IP configuration will also be checked in these cases. .sp This function uses the \fI\%docker.compare_container_networks\fP minion config option to determine which keys to examine. This provides flexibility in the event that features added in a future Docker release necessitate changes to how Salt compares networks. In these cases, rather than waiting for a new Salt release one can just set \fI\%docker.compare_container_networks\fP\&. .sp Changed in version 3000: This config option can now also be set in pillar data and grains. Additionally, it can be set in the master config file, provided that \fBpillar_opts\fP is enabled on the minion. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The checks for automatic IP configuration described above only apply if \fBIPAMConfig\fP is among the keys set for static IP checks in \fI\%docker.compare_container_networks\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B first Name or ID of first container (old) .TP .B second Name or ID of second container (new) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.compare_container_networks foo bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.compare_containers(first, second, ignore=None) New in version 2017.7.0. .sp Changed in version 2018.3.0: Renamed from \fBdocker.compare_container\fP to \fBdocker.compare_containers\fP (old function name remains as an alias) .sp Compare two containers\(aq Config and and HostConfig and return any differences between the two. .INDENT 7.0 .TP .B first Name or ID of first container .TP .B second Name or ID of second container .TP .B ignore A comma\-separated list (or Python list) of keys to ignore when comparing. This is useful when comparing two otherwise identical containers which have different hostnames. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.compare_containers foo bar salt myminion docker.compare_containers foo bar ignore=Hostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.compare_networks(first, second, ignore=\(aqName,Id,Created,Containers\(aq) New in version 2018.3.0. .sp Compare two networks and return any differences between the two .INDENT 7.0 .TP .B first Name or ID of first container .TP .B second Name or ID of second container .TP .B ignore Name,Id,Created,Containers A comma\-separated list (or Python list) of keys to ignore when comparing. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.compare_network foo bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.connect_container_to_network(container, net_id, **kwargs) New in version 2015.8.3. .sp Changed in version 2017.7.0: Support for \fBipv4_address\fP argument added .sp Changed in version 2018.3.0: All arguments are now passed through to \fI\%connect_container_to_network()\fP, allowing for any new arguments added to this function to be supported automagically. .sp Connect container to network. See the \fI\%connect_container_to_network()\fP docs for information on supported arguments. .INDENT 7.0 .TP .B container Container name or ID .TP .B net_id Network name or ID .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.connect_container_to_network web\-1 mynet salt myminion docker.connect_container_to_network web\-1 mynet ipv4_address=10.20.0.10 salt myminion docker.connect_container_to_network web\-1 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.connected(name, verbose=False) New in version 2018.3.0. .sp Return a list of running containers attached to the specified network .INDENT 7.0 .TP .B name Network name .TP .B verbose False If \fBTrue\fP, return extended info about each container (IP configuration, etc.) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.connected net_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.copy_from(name, source, dest, overwrite=False, makedirs=False) Copy a file from inside a container to the Minion .INDENT 7.0 .TP .B name Container name .TP .B source Path of the file on the container\(aqs filesystem .TP .B dest Destination on the Minion. Must be an absolute path. If the destination is a directory, the file will be copied into that directory. .TP .B overwrite False Unless this option is set to \fBTrue\fP, then if a file exists at the location specified by the \fBdest\fP argument, an error will be raised. .TP .B makedirs False Create the parent directory on the container if it does not already exist. .UNINDENT .sp \fBRETURN DATA\fP .sp A boolean (\fBTrue\fP if successful, otherwise \fBFalse\fP) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.copy_from mycontainer /var/log/nginx/access.log /home/myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.copy_to(name, source, dest, exec_driver=None, overwrite=False, makedirs=False) Copy a file from the host into a container .INDENT 7.0 .TP .B name Container name .TP .B source File to be copied to the container. Can be a local path on the Minion or a remote file from the Salt fileserver. .TP .B dest Destination on the container. Must be an absolute path. If the destination is a directory, the file will be copied into that directory. .TP .B exec_driver None If not passed, the execution driver will be detected as described \fI\%above\fP\&. .TP .B overwrite False Unless this option is set to \fBTrue\fP, then if a file exists at the location specified by the \fBdest\fP argument, an error will be raised. .TP .B makedirs False Create the parent directory on the container if it does not already exist. .UNINDENT .sp \fBRETURN DATA\fP .sp A boolean (\fBTrue\fP if successful, otherwise \fBFalse\fP) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.copy_to mycontainer /tmp/foo /root/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.cp(name, source, dest, overwrite=False, makedirs=False) This function is an alias of \fBcopy_from\fP\&. .INDENT 7.0 .INDENT 3.5 Copy a file from inside a container to the Minion .INDENT 0.0 .TP .B name Container name .TP .B source Path of the file on the container\(aqs filesystem .TP .B dest Destination on the Minion. Must be an absolute path. If the destination is a directory, the file will be copied into that directory. .TP .B overwrite False Unless this option is set to \fBTrue\fP, then if a file exists at the location specified by the \fBdest\fP argument, an error will be raised. .TP .B makedirs False Create the parent directory on the container if it does not already exist. .UNINDENT .sp \fBRETURN DATA\fP .sp A boolean (\fBTrue\fP if successful, otherwise \fBFalse\fP) .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.copy_from mycontainer /var/log/nginx/access.log /home/myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.create(image, name=None, start=False, skip_translate=None, ignore_collisions=False, validate_ip_addrs=True, client_timeout=60, **kwargs) Create a new container .INDENT 7.0 .TP .B image Image from which to create the container .TP .B name Name for the new container. If not provided, Docker will randomly generate one for you (it will be included in the return data). .TP .B start False If \fBTrue\fP, start container after creating it .sp New in version 2018.3.0. .TP .B skip_translate This function translates Salt CLI or SLS input into the format which docker\-py expects. However, in the event that Salt\(aqs translation logic fails (due to potential changes in the Docker Remote API, or to bugs in the translation code), this argument can be used to exert granular control over which arguments are translated and which are not. .sp Pass this argument as a comma\-separated list (or Python list) of arguments, and translation for each passed argument name will be skipped. Alternatively, pass \fBTrue\fP and \fIall\fP translation will be skipped. .sp Skipping tranlsation allows for arguments to be formatted directly in the format which docker\-py expects. This allows for API changes and other issues to be more easily worked around. An example of using this option to skip translation would be: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.create image=centos:7.3.1611 skip_translate=environment environment=\(dq{\(aqFOO\(aq: \(aqbar\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .sp See the following links for more information: .INDENT 7.0 .IP \(bu 2 \fI\%docker\-py Low\-level API\fP .IP \(bu 2 \fI\%Docker Engine API\fP .UNINDENT .TP .B ignore_collisions False Since many of docker\-py\(aqs arguments differ in name from their CLI counterparts (with which most Docker users are more familiar), Salt detects usage of these and aliases them to the docker\-py version of that argument. However, if both the alias and the docker\-py version of the same argument (e.g. \fBenv\fP and \fBenvironment\fP) are used, an error will be raised. Set this argument to \fBTrue\fP to suppress these errors and keep the docker\-py version of the argument. .TP .B validate_ip_addrs True For parameters which accept IP addresses as input, IP address validation will be performed. To disable, set this to \fBFalse\fP .TP .B client_timeout 60 Timeout in seconds for the Docker client. This is not a timeout for this function, but for receiving a response from the API. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only used if Salt needs to pull the requested image. .UNINDENT .UNINDENT .UNINDENT .sp \fBCONTAINER CONFIGURATION ARGUMENTS\fP .INDENT 7.0 .TP .B auto_remove (or \fIrm\fP) False Enable auto\-removal of the container on daemon side when the container’s process exits (analogous to running a docker container with \fB\-\-rm\fP on the CLI). .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBauto_remove=True\fP .IP \(bu 2 \fBrm=True\fP .UNINDENT .TP .B binds Files/directories to bind mount. Each bind mount should be passed in one of the following formats: .INDENT 7.0 .IP \(bu 2 \fB<host_path>:<container_path>\fP \- \fBhost_path\fP is mounted within the container as \fBcontainer_path\fP with read\-write access. .IP \(bu 2 \fB<host_path>:<container_path>:<selinux_context>\fP \- \fBhost_path\fP is mounted within the container as \fBcontainer_path\fP with read\-write access. Additionally, the specified selinux context will be set within the container. .IP \(bu 2 \fB<host_path>:<container_path>:<read_only>\fP \- \fBhost_path\fP is mounted within the container as \fBcontainer_path\fP, with the read\-only or read\-write setting explicitly defined. .IP \(bu 2 \fB<host_path>:<container_path>:<read_only>,<selinux_context>\fP \- \fBhost_path\fP is mounted within the container as \fBcontainer_path\fP, with the read\-only or read\-write setting explicitly defined. Additionally, the specified selinux context will be set within the container. .UNINDENT .sp \fB<read_only>\fP can be either \fBro\fP for read\-write access, or \fBro\fP for read\-only access. When omitted, it is assumed to be read\-write. .sp \fB<selinux_context>\fP can be \fBz\fP if the volume is shared between multiple containers, or \fBZ\fP if the volume should be private. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When both \fB<read_only>\fP and \fB<selinux_context>\fP are specified, there must be a comma before \fB<selinux_context>\fP\&. .UNINDENT .UNINDENT .sp Binds can be expressed as a comma\-separated list or a Python list, however in cases where both ro/rw and an selinux context are specified, the binds \fImust\fP be specified as a Python list. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBbinds=/srv/www:/var/www:ro\fP .IP \(bu 2 \fBbinds=/srv/www:/var/www:rw\fP .IP \(bu 2 \fBbinds=/srv/www:/var/www\fP .IP \(bu 2 \fBbinds=\(dq[\(aq/srv/www:/var/www:ro,Z\(aq]\(dq\fP .IP \(bu 2 \fBbinds=\(dq[\(aq/srv/www:/var/www:rw,Z\(aq]\(dq\fP .IP \(bu 2 \fBbinds=/srv/www:/var/www:Z\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The second and third examples above are equivalent to each other, as are the last two examples. .UNINDENT .UNINDENT .TP .B blkio_weight Block IO weight (relative weight), accepts a weight value between 10 and 1000. .sp Example: \fBblkio_weight=100\fP .TP .B blkio_weight_device Block IO weight (relative device weight), specified as a list of expressions in the format \fBPATH:WEIGHT\fP .sp Example: \fBblkio_weight_device=/dev/sda:100\fP .TP .B cap_add List of capabilities to add within the container. Can be passed as a comma\-separated list or a Python list. Requires Docker 1.2.0 or newer. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBcap_add=SYS_ADMIN,MKNOD\fP .IP \(bu 2 \fBcap_add=\(dq[SYS_ADMIN, MKNOD]\(dq\fP .UNINDENT .TP .B cap_drop List of capabilities to drop within the container. Can be passed as a comma\-separated string or a Python list. Requires Docker 1.2.0 or newer. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBcap_drop=SYS_ADMIN,MKNOD\fP, .IP \(bu 2 \fBcap_drop=\(dq[SYS_ADMIN, MKNOD]\(dq\fP .UNINDENT .TP .B command (or \fIcmd\fP) Command to run in the container .sp Example: \fBcommand=bash\fP or \fBcmd=bash\fP .sp Changed in version 2015.8.1: \fBcmd\fP is now also accepted .TP .B cpuset_cpus (or \fIcpuset\fP) CPUs on which which to allow execution, specified as a string containing a range (e.g. \fB0\-3\fP) or a comma\-separated list of CPUs (e.g. \fB0,1\fP). .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBcpuset_cpus=\(dq0\-3\(dq\fP .IP \(bu 2 \fBcpuset=\(dq0,1\(dq\fP .UNINDENT .TP .B cpuset_mems Memory nodes on which which to allow execution, specified as a string containing a range (e.g. \fB0\-3\fP) or a comma\-separated list of MEMs (e.g. \fB0,1\fP). Only effective on NUMA systems. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBcpuset_mems=\(dq0\-3\(dq\fP .IP \(bu 2 \fBcpuset_mems=\(dq0,1\(dq\fP .UNINDENT .TP .B cpu_group The length of a CPU period in microseconds .sp Example: \fBcpu_group=100000\fP .TP .B cpu_period Microseconds of CPU time that the container can get in a CPU period .sp Example: \fBcpu_period=50000\fP .TP .B cpu_shares CPU shares (relative weight), specified as an integer between 2 and 1024. .sp Example: \fBcpu_shares=512\fP .TP .B detach False If \fBTrue\fP, run the container\(aqs command in the background (daemon mode) .sp Example: \fBdetach=True\fP .TP .B devices List of host devices to expose within the container .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBdevices=\(dq/dev/net/tun,/dev/xvda1:/dev/xvda1,/dev/xvdb1:/dev/xvdb1:r\(dq\fP .IP \(bu 2 \fBdevices=\(dq[\(aq/dev/net/tun\(aq, \(aq/dev/xvda1:/dev/xvda1\(aq, \(aq/dev/xvdb1:/dev/xvdb1:r\(aq]\(dq\fP .UNINDENT .TP .B device_read_bps Limit read rate (bytes per second) from a device, specified as a list of expressions in the format \fBPATH:RATE\fP, where \fBRATE\fP is either an integer number of bytes, or a string ending in \fBkb\fP, \fBmb\fP, or \fBgb\fP\&. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBdevice_read_bps=\(dq/dev/sda:1mb,/dev/sdb:5mb\(dq\fP .IP \(bu 2 \fBdevice_read_bps=\(dq[\(aq/dev/sda:100mb\(aq, \(aq/dev/sdb:5mb\(aq]\(dq\fP .UNINDENT .TP .B device_read_iops Limit read rate (I/O per second) from a device, specified as a list of expressions in the format \fBPATH:RATE\fP, where \fBRATE\fP is a number of I/O operations. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBdevice_read_iops=\(dq/dev/sda:1000,/dev/sdb:500\(dq\fP .IP \(bu 2 \fBdevice_read_iops=\(dq[\(aq/dev/sda:1000\(aq, \(aq/dev/sdb:500\(aq]\(dq\fP .UNINDENT .TP .B device_write_bps Limit write rate (bytes per second) from a device, specified as a list of expressions in the format \fBPATH:RATE\fP, where \fBRATE\fP is either an integer number of bytes, or a string ending in \fBkb\fP, \fBmb\fP or \fBgb\fP\&. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBdevice_write_bps=\(dq/dev/sda:100mb,/dev/sdb:50mb\(dq\fP .IP \(bu 2 \fBdevice_write_bps=\(dq[\(aq/dev/sda:100mb\(aq, \(aq/dev/sdb:50mb\(aq]\(dq\fP .UNINDENT .TP .B device_write_iops Limit write rate (I/O per second) from a device, specified as a list of expressions in the format \fBPATH:RATE\fP, where \fBRATE\fP is a number of I/O operations. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBdevice_write_iops=\(dq/dev/sda:1000,/dev/sdb:500\(dq\fP .IP \(bu 2 \fBdevice_write_iops=\(dq[\(aq/dev/sda:1000\(aq, \(aq/dev/sdb:500\(aq]\(dq\fP .UNINDENT .TP .B dns List of DNS nameservers. Can be passed as a comma\-separated list or a Python list. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBdns=8.8.8.8,8.8.4.4\fP .IP \(bu 2 \fBdns=\(dq[\(aq8.8.8.8\(aq, \(aq8.8.4.4\(aq]\(dq\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To skip IP address validation, use \fBvalidate_ip_addrs=False\fP .UNINDENT .UNINDENT .TP .B dns_opt Additional options to be added to the container’s \fBresolv.conf\fP file .sp Example: \fBdns_opt=ndots:9\fP .TP .B dns_search List of DNS search domains. Can be passed as a comma\-separated list or a Python list. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBdns_search=foo1.domain.tld,foo2.domain.tld\fP .IP \(bu 2 \fBdns_search=\(dq[foo1.domain.tld, foo2.domain.tld]\(dq\fP .UNINDENT .TP .B domainname The domain name to use for the container .sp Example: \fBdomainname=domain.tld\fP .TP .B entrypoint Entrypoint for the container. Either a string (e.g. \fB\(dqmycmd \-\-arg1 \-\-arg2\(dq\fP) or a Python list (e.g. \fB\(dq[\(aqmycmd\(aq, \(aq\-\-arg1\(aq, \(aq\-\-arg2\(aq]\(dq\fP) .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBentrypoint=\(dqcat access.log\(dq\fP .IP \(bu 2 \fBentrypoint=\(dq[\(aqcat\(aq, \(aqaccess.log\(aq]\(dq\fP .UNINDENT .TP .B environment (or \fIenv\fP) Either a dictionary of environment variable names and their values, or a Python list of strings in the format \fBVARNAME=value\fP\&. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBenvironment=\(aqVAR1=value,VAR2=value\(aq\fP .IP \(bu 2 \fBenvironment=\(dq[\(aqVAR1=value\(aq, \(aqVAR2=value\(aq]\(dq\fP .IP \(bu 2 \fBenvironment=\(dq{\(aqVAR1\(aq: \(aqvalue\(aq, \(aqVAR2\(aq: \(aqvalue\(aq}\(dq\fP .UNINDENT .TP .B extra_hosts Additional hosts to add to the container\(aqs /etc/hosts file. Can be passed as a comma\-separated list or a Python list. Requires Docker 1.3.0 or newer. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBextra_hosts=web1:10.9.8.7,web2:10.9.8.8\fP .IP \(bu 2 \fBextra_hosts=\(dq[\(aqweb1:10.9.8.7\(aq, \(aqweb2:10.9.8.8\(aq]\(dq\fP .IP \(bu 2 \fBextra_hosts=\(dq{\(aqweb1\(aq: \(aq10.9.8.7\(aq, \(aqweb2\(aq: \(aq10.9.8.8\(aq}\(dq\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To skip IP address validation, use \fBvalidate_ip_addrs=False\fP .UNINDENT .UNINDENT .TP .B group_add List of additional group names and/or IDs that the container process will run as .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBgroup_add=web,network\fP .IP \(bu 2 \fBgroup_add=\(dq[\(aqweb\(aq, \(aqnetwork\(aq]\(dq\fP .UNINDENT .TP .B hostname Hostname of the container. If not provided, and if a \fBname\fP has been provided, the \fBhostname\fP will default to the \fBname\fP that was passed. .sp Example: \fBhostname=web1\fP .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 If the container is started with \fBnetwork_mode=host\fP, the hostname will be overridden by the hostname of the Minion. .UNINDENT .UNINDENT .TP .B interactive (or \fIstdin_open\fP): False Leave stdin open, even if not attached .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBinteractive=True\fP .IP \(bu 2 \fBstdin_open=True\fP .UNINDENT .TP .B ipc_mode (or \fIipc\fP) Set the IPC mode for the container. The default behavior is to create a private IPC namespace for the container, but this option can be used to change that behavior: .INDENT 7.0 .IP \(bu 2 \fBcontainer:<container_name_or_id>\fP reuses another container shared memory, semaphores and message queues .IP \(bu 2 \fBhost\fP: use the host\(aqs shared memory, semaphores and message queues .UNINDENT .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBipc_mode=container:foo\fP .IP \(bu 2 \fBipc=host\fP .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Using \fBhost\fP gives the container full access to local shared memory and is therefore considered insecure. .UNINDENT .UNINDENT .TP .B isolation Specifies the type of isolation technology used by containers .sp Example: \fBisolation=hyperv\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The default value on Windows server is \fBprocess\fP, while the default value on Windows client is \fBhyperv\fP\&. On Linux, only \fBdefault\fP is supported. .UNINDENT .UNINDENT .TP .B labels (or \fIlabel\fP) Add metadata to the container. Labels can be set both with and without values: .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBlabels=foo,bar=baz\fP .IP \(bu 2 \fBlabels=\(dq[\(aqfoo\(aq, \(aqbar=baz\(aq]\(dq\fP .UNINDENT .sp Changed in version 2018.3.0: Labels both with and without values can now be mixed. Earlier releases only permitted one method or the other. .TP .B links Link this container to another. Links should be specified in the format \fB<container_name_or_id>:<link_alias>\fP\&. Multiple links can be passed, ether as a comma separated list or a Python list. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBlinks=web1:link1,web2:link2\fP, .IP \(bu 2 \fBlinks=\(dq[\(aqweb1:link1\(aq, \(aqweb2:link2\(aq]\(dq\fP .IP \(bu 2 \fBlinks=\(dq{\(aqweb1\(aq: \(aqlink1\(aq, \(aqweb2\(aq: \(aqlink2\(aq}\(dq\fP .UNINDENT .TP .B log_driver Set container\(aqs logging driver. Requires Docker 1.6 or newer. .sp Example: .INDENT 7.0 .IP \(bu 2 \fBlog_driver=syslog\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The logging driver feature was improved in Docker 1.13 introducing option name changes. Please see Docker\(aqs \fI\%Configure logging drivers\fP documentation for more information. .UNINDENT .UNINDENT .TP .B log_opt Config options for the \fBlog_driver\fP config option. Requires Docker 1.6 or newer. .sp Example: .INDENT 7.0 .IP \(bu 2 \fBlog_opt=\(dqsyslog\-address=tcp://192.168.0.42,syslog\-facility=daemon\(dq\fP .IP \(bu 2 \fBlog_opt=\(dq[\(aqsyslog\-address=tcp://192.168.0.42\(aq, \(aqsyslog\-facility=daemon\(aq]\(dq\fP .IP \(bu 2 \fBlog_opt=\(dq{\(aqsyslog\-address\(aq: \(aqtcp://192.168.0.42\(aq, \(aqsyslog\-facility\(aq: \(aqdaemon\(aq}\(dq\fP .UNINDENT .TP .B lxc_conf Additional LXC configuration parameters to set before starting the container. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBlxc_conf=\(dqlxc.utsname=docker,lxc.arch=x86_64\(dq\fP .IP \(bu 2 \fBlxc_conf=\(dq[\(aqlxc.utsname=docker\(aq, \(aqlxc.arch=x86_64\(aq]\(dq\fP .IP \(bu 2 \fBlxc_conf=\(dq{\(aqlxc.utsname\(aq: \(aqdocker\(aq, \(aqlxc.arch\(aq: \(aqx86_64\(aq}\(dq\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 These LXC configuration parameters will only have the desired effect if the container is using the LXC execution driver, which has been deprecated for some time. .UNINDENT .UNINDENT .TP .B mac_address MAC address to use for the container. If not specified, a random MAC address will be used. .sp Example: \fBmac_address=01:23:45:67:89:0a\fP .TP .B mem_limit (or \fImemory\fP) 0 Memory limit. Can be specified in bytes or using single\-letter units (i.e. \fB512M\fP, \fB2G\fP, etc.). A value of \fB0\fP (the default) means no memory limit. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBmem_limit=512M\fP .IP \(bu 2 \fBmemory=1073741824\fP .UNINDENT .TP .B mem_swappiness Tune a container\(aqs memory swappiness behavior. Accepts an integer between 0 and 100. .sp Example: \fBmem_swappiness=60\fP .TP .B memswap_limit (or \fImemory_swap\fP) \-1 Total memory limit (memory plus swap). Set to \fB\-1\fP to disable swap. A value of \fB0\fP means no swap limit. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBmemswap_limit=1G\fP .IP \(bu 2 \fBmemory_swap=2147483648\fP .UNINDENT .TP .B network_disabled False If \fBTrue\fP, networking will be disabled within the container .sp Example: \fBnetwork_disabled=True\fP .TP .B network_mode bridge One of the following: .INDENT 7.0 .IP \(bu 2 \fBbridge\fP \- Creates a new network stack for the container on the docker bridge .IP \(bu 2 \fBnone\fP \- No networking (equivalent of the Docker CLI argument \fB\-\-net=none\fP). Not to be confused with Python\(aqs \fBNone\fP\&. .IP \(bu 2 \fBcontainer:<name_or_id>\fP \- Reuses another container\(aqs network stack .IP \(bu 2 \fBhost\fP \- Use the host\(aqs network stack inside the container .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 Using \fBhost\fP mode gives the container full access to the hosts system\(aqs services (such as D\-Bus), and is therefore considered insecure. .UNINDENT .UNINDENT .UNINDENT .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBnetwork_mode=null\fP .IP \(bu 2 \fBnetwork_mode=container:web1\fP .UNINDENT .TP .B oom_kill_disable Whether to disable OOM killer .sp Example: \fBoom_kill_disable=False\fP .TP .B oom_score_adj An integer value containing the score given to the container in order to tune OOM killer preferences .sp Example: \fBoom_score_adj=500\fP .TP .B pid_mode Set to \fBhost\fP to use the host container\(aqs PID namespace within the container. Requires Docker 1.5.0 or newer. .sp Example: \fBpid_mode=host\fP .TP .B pids_limit Set the container\(aqs PID limit. Set to \fB\-1\fP for unlimited. .sp Example: \fBpids_limit=2000\fP .TP .B port_bindings (or \fIpublish\fP) Bind exposed ports which were exposed using the \fBports\fP argument to \fI\%docker.create\fP\&. These should be passed in the same way as the \fB\-\-publish\fP argument to the \fBdocker run\fP CLI command: .INDENT 7.0 .IP \(bu 2 \fBip:hostPort:containerPort\fP \- Bind a specific IP and port on the host to a specific port within the container. .IP \(bu 2 \fBip::containerPort\fP \- Bind a specific IP and an ephemeral port to a specific port within the container. .IP \(bu 2 \fBhostPort:containerPort\fP \- Bind a specific port on all of the host\(aqs interfaces to a specific port within the container. .IP \(bu 2 \fBcontainerPort\fP \- Bind an ephemeral port on all of the host\(aqs interfaces to a specific port within the container. .UNINDENT .sp Multiple bindings can be separated by commas, or passed as a Python list. The below two examples are equivalent: .INDENT 7.0 .IP \(bu 2 \fBport_bindings=\(dq5000:5000,2123:2123/udp,8080\(dq\fP .IP \(bu 2 \fBport_bindings=\(dq[\(aq5000:5000\(aq, \(aq2123:2123/udp\(aq, 8080]\(dq\fP .UNINDENT .sp Port bindings can also include ranges: .INDENT 7.0 .IP \(bu 2 \fBport_bindings=\(dq14505\-14506:4505\-4506\(dq\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When specifying a protocol, it must be passed in the \fBcontainerPort\fP value, as seen in the examples above. .UNINDENT .UNINDENT .TP .B ports A list of ports to expose on the container. Can be passed as comma\-separated list or a Python list. If the protocol is omitted, the port will be assumed to be a TCP port. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBports=1111,2222/udp\fP .IP \(bu 2 \fBports=\(dq[1111, \(aq2222/udp\(aq]\(dq\fP .UNINDENT .TP .B privileged False If \fBTrue\fP, runs the exec process with extended privileges .sp Example: \fBprivileged=True\fP .TP .B publish_all_ports (or \fIpublish_all\fP): False Publish all ports to the host .sp Example: \fBpublish_all_ports=True\fP .TP .B read_only False If \fBTrue\fP, mount the container’s root filesystem as read only .sp Example: \fBread_only=True\fP .TP .B restart_policy (or \fIrestart\fP) Set a restart policy for the container. Must be passed as a string in the format \fBpolicy[:retry_count]\fP where \fBpolicy\fP is one of \fBalways\fP, \fBunless\-stopped\fP, or \fBon\-failure\fP, and \fBretry_count\fP is an optional limit to the number of retries. The retry count is ignored when using the \fBalways\fP or \fBunless\-stopped\fP restart policy. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBrestart_policy=on\-failure:5\fP .IP \(bu 2 \fBrestart_policy=always\fP .UNINDENT .TP .B security_opt Security configuration for MLS systems such as SELinux and AppArmor. Can be passed as a comma\-separated list or a Python list. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBsecurity_opt=apparmor:unconfined,param2:value2\fP .IP \(bu 2 \fBsecurity_opt=\(aq[\(dqapparmor:unconfined\(dq, \(dqparam2:value2\(dq]\(aq\fP .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 Some security options can contain commas. In these cases, this argument \fImust\fP be passed as a Python list, as splitting by comma will result in an invalid configuration. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 See the documentation for security_opt at \fI\%https://docs.docker.com/engine/reference/run/#security\-configuration\fP .UNINDENT .UNINDENT .TP .B shm_size Size of /dev/shm .sp Example: \fBshm_size=128M\fP .TP .B stop_signal The signal used to stop the container. The default is \fBSIGTERM\fP\&. .sp Example: \fBstop_signal=SIGRTMIN+3\fP .TP .B stop_timeout Timeout to stop the container, in seconds .sp Example: \fBstop_timeout=5\fP .TP .B storage_opt Storage driver options for the container .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBstorage_opt=\(aqdm.basesize=40G\(aq\fP .IP \(bu 2 \fBstorage_opt=\(dq[\(aqdm.basesize=40G\(aq]\(dq\fP .IP \(bu 2 \fBstorage_opt=\(dq{\(aqdm.basesize\(aq: \(aq40G\(aq}\(dq\fP .UNINDENT .TP .B sysctls (or \fIsysctl\fP) Set sysctl options for the container .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBsysctl=\(aqfs.nr_open=1048576,kernel.pid_max=32768\(aq\fP .IP \(bu 2 \fBsysctls=\(dq[\(aqfs.nr_open=1048576\(aq, \(aqkernel.pid_max=32768\(aq]\(dq\fP .IP \(bu 2 \fBsysctls=\(dq{\(aqfs.nr_open\(aq: \(aq1048576\(aq, \(aqkernel.pid_max\(aq: \(aq32768\(aq}\(dq\fP .UNINDENT .TP .B tmpfs A map of container directories which should be replaced by tmpfs mounts, and their corresponding mount options. Can be passed as Python list of PATH:VALUE mappings, or a Python dictionary. However, since commas usually appear in the values, this option \fIcannot\fP be passed as a comma\-separated list. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBtmpfs=\(dq[\(aq/run:rw,noexec,nosuid,size=65536k\(aq, \(aq/var/lib/mysql:rw,noexec,nosuid,size=600m\(aq]\(dq\fP .IP \(bu 2 \fBtmpfs=\(dq{\(aq/run\(aq: \(aqrw,noexec,nosuid,size=65536k\(aq, \(aq/var/lib/mysql\(aq: \(aqrw,noexec,nosuid,size=600m\(aq}\(dq\fP .UNINDENT .TP .B tty False Attach TTYs .sp Example: \fBtty=True\fP .TP .B ulimits (or \fIulimit\fP) List of ulimits. These limits should be passed in the format \fB<ulimit_name>:<soft_limit>:<hard_limit>\fP, with the hard limit being optional. Can be passed as a comma\-separated list or a Python list. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBulimits=\(dqnofile=1024:1024,nproc=60\(dq\fP .IP \(bu 2 \fBulimits=\(dq[\(aqnofile=1024:1024\(aq, \(aqnproc=60\(aq]\(dq\fP .UNINDENT .TP .B user User under which to run exec process .sp Example: \fBuser=foo\fP .TP .B userns_mode (or \fIuser_ns_mode\fP) Sets the user namsepace mode, when the user namespace remapping option is enabled. .sp Example: \fBuserns_mode=host\fP .TP .B volumes (or \fIvolume\fP) List of directories to expose as volumes. Can be passed as a comma\-separated list or a Python list. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBvolumes=/mnt/vol1,/mnt/vol2\fP .IP \(bu 2 \fBvolume=\(dq[\(aq/mnt/vol1\(aq, \(aq/mnt/vol2\(aq]\(dq\fP .UNINDENT .TP .B volumes_from Container names or IDs from which the container will get volumes. Can be passed as a comma\-separated list or a Python list. .sp Example: \fBvolumes_from=foo\fP, \fBvolumes_from=foo,bar\fP, \fBvolumes_from=\(dq[foo, bar]\(dq\fP .TP .B volume_driver Sets the container\(aqs volume driver .sp Example: \fBvolume_driver=foobar\fP .TP .B working_dir (or \fIworkdir\fP) Working directory inside the container .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBworking_dir=/var/log/nginx\fP .IP \(bu 2 \fBworkdir=/var/www/myapp\fP .UNINDENT .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBId\fP \- ID of the newly\-created container .IP \(bu 2 \fBName\fP \- Name of the newly\-created container .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Create a data\-only container salt myminion docker.create myuser/mycontainer volumes=\(dq/mnt/vol1,/mnt/vol2\(dq # Create a CentOS 7 container that will stay running once started salt myminion docker.create centos:7 name=mycent7 interactive=True tty=True command=bash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.create_network(name, skip_translate=None, ignore_collisions=False, validate_ip_addrs=True, client_timeout=60, **kwargs) Changed in version 2018.3.0: Support added for network configuration options other than \fBdriver\fP and \fBdriver_opts\fP, as well as IPAM configuration. .sp Create a new network .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function supports all arguments for network and IPAM pool configuration which are available for the release of docker\-py installed on the minion. For that reason, the arguments described below in the \fI\%NETWORK CONFIGURATION ARGUMENTS\fP and \fI\%IP ADDRESS MANAGEMENT (IPAM)\fP sections may not accurately reflect what is available on the minion. The \fI\%docker.get_client_args\fP function can be used to check the available arguments for the installed version of docker\-py (they are found in the \fBnetwork_config\fP and \fBipam_config\fP sections of the return data), but Salt will not prevent a user from attempting to use an argument which is unsupported in the release of Docker which is installed. In those cases, network creation be attempted but will fail. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Network name .TP .B skip_translate This function translates Salt CLI or SLS input into the format which docker\-py expects. However, in the event that Salt\(aqs translation logic fails (due to potential changes in the Docker Remote API, or to bugs in the translation code), this argument can be used to exert granular control over which arguments are translated and which are not. .sp Pass this argument as a comma\-separated list (or Python list) of arguments, and translation for each passed argument name will be skipped. Alternatively, pass \fBTrue\fP and \fIall\fP translation will be skipped. .sp Skipping tranlsation allows for arguments to be formatted directly in the format which docker\-py expects. This allows for API changes and other issues to be more easily worked around. See the following links for more information: .INDENT 7.0 .IP \(bu 2 \fI\%docker\-py Low\-level API\fP .IP \(bu 2 \fI\%Docker Engine API\fP .UNINDENT .sp New in version 2018.3.0. .TP .B ignore_collisions False Since many of docker\-py\(aqs arguments differ in name from their CLI counterparts (with which most Docker users are more familiar), Salt detects usage of these and aliases them to the docker\-py version of that argument. However, if both the alias and the docker\-py version of the same argument (e.g. \fBoptions\fP and \fBdriver_opts\fP) are used, an error will be raised. Set this argument to \fBTrue\fP to suppress these errors and keep the docker\-py version of the argument. .sp New in version 2018.3.0. .TP .B validate_ip_addrs True For parameters which accept IP addresses as input, IP address validation will be performed. To disable, set this to \fBFalse\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When validating subnets, whether or not the IP portion of the subnet is a valid subnet boundary will not be checked. The IP will portion will be validated, and the subnet size will be checked to confirm it is a valid number (1\-32 for IPv4, 1\-128 for IPv6). .UNINDENT .UNINDENT .sp New in version 2018.3.0. .UNINDENT .sp \fBNETWORK CONFIGURATION ARGUMENTS\fP .INDENT 7.0 .TP .B driver Network driver .sp Example: \fBdriver=macvlan\fP .TP .B driver_opts (or \fIdriver_opt\fP, or \fIoptions\fP) Options for the network driver. Either a dictionary of option names and values or a Python list of strings in the format \fBvarname=value\fP\&. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBdriver_opts=\(aqmacvlan_mode=bridge,parent=eth0\(aq\fP .IP \(bu 2 \fBdriver_opts=\(dq[\(aqmacvlan_mode=bridge\(aq, \(aqparent=eth0\(aq]\(dq\fP .IP \(bu 2 \fBdriver_opts=\(dq{\(aqmacvlan_mode\(aq: \(aqbridge\(aq, \(aqparent\(aq: \(aqeth0\(aq}\(dq\fP .UNINDENT .TP .B check_duplicate True If \fBTrue\fP, checks for networks with duplicate names. Since networks are primarily keyed based on a random ID and not on the name, and network name is strictly a user\-friendly alias to the network which is uniquely identified using ID, there is no guaranteed way to check for duplicates. This option providess a best effort, checking for any networks which have the same name, but it is not guaranteed to catch all name collisions. .sp Example: \fBcheck_duplicate=False\fP .TP .B internal False If \fBTrue\fP, restricts external access to the network .sp Example: \fBinternal=True\fP .TP .B labels Add metadata to the network. Labels can be set both with and without values: .sp Examples (\fIwith\fP values): .INDENT 7.0 .IP \(bu 2 \fBlabels=\(dqlabel1=value1,label2=value2\(dq\fP .IP \(bu 2 \fBlabels=\(dq[\(aqlabel1=value1\(aq, \(aqlabel2=value2\(aq]\(dq\fP .IP \(bu 2 \fBlabels=\(dq{\(aqlabel1\(aq: \(aqvalue1\(aq, \(aqlabel2\(aq: \(aqvalue2\(aq}\(dq\fP .UNINDENT .sp Examples (\fIwithout\fP values): .INDENT 7.0 .IP \(bu 2 \fBlabels=label1,label2\fP .IP \(bu 2 \fBlabels=\(dq[\(aqlabel1\(aq, \(aqlabel2\(aq]\(dq\fP .UNINDENT .TP .B enable_ipv6 (or \fIipv6\fP) False Enable IPv6 on the network .sp Example: \fBenable_ipv6=True\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 While it should go without saying, this argument must be set to \fBTrue\fP to \fI\%configure an IPv6 subnet\fP\&. Also, if this option is turned on without an IPv6 subnet explicitly configured, you will get an error unless you have set up a fixed IPv6 subnet. Consult the \fI\%Docker IPv6 docs\fP for information on how to do this. .UNINDENT .UNINDENT .TP .B attachable False If \fBTrue\fP, and the network is in the global scope, non\-service containers on worker nodes will be able to connect to the network. .sp Example: \fBattachable=True\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 While support for this option was added in API version 1.24, its value was not added to the inpsect results until API version 1.26. The version of Docker which is available for CentOS 7 runs API version 1.24, meaning that while Salt can pass this argument to the API, it has no way of knowing the value of this config option in an existing Docker network. .UNINDENT .UNINDENT .TP .B scope Specify the network\(aqs scope (\fBlocal\fP, \fBglobal\fP or \fBswarm\fP) .sp Example: \fBscope=local\fP .TP .B ingress False If \fBTrue\fP, create an ingress network which provides the routing\-mesh in swarm mode .sp Example: \fBingress=True\fP .UNINDENT .sp \fBIP ADDRESS MANAGEMENT (IPAM)\fP .sp This function supports networks with either IPv4, or both IPv4 and IPv6. If configuring IPv4, then you can pass the IPAM arguments as shown below, as individual arguments on the Salt CLI. However, if configuring IPv4 and IPv6, the arguments must be passed as a list of dictionaries, in the \fBipam_pools\fP argument. See the \fBCLI Examples\fP below. \fI\%These docs\fP also have more information on these arguments. .sp \fIIPAM ARGUMENTS\fP .INDENT 7.0 .TP .B ipam_driver IPAM driver to use, if different from the default one .sp Example: \fBipam_driver=foo\fP .TP .B ipam_opts Options for the IPAM driver. Either a dictionary of option names and values or a Python list of strings in the format \fBvarname=value\fP\&. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBipam_opts=\(aqfoo=bar,baz=qux\(aq\fP .IP \(bu 2 \fBipam_opts=\(dq[\(aqfoo=bar\(aq, \(aqbaz=quz\(aq]\(dq\fP .IP \(bu 2 \fBipam_opts=\(dq{\(aqfoo\(aq: \(aqbar\(aq, \(aqbaz\(aq: \(aqqux\(aq}\(dq\fP .UNINDENT .UNINDENT .sp \fIIPAM POOL ARGUMENTS\fP .INDENT 7.0 .TP .B subnet Subnet in CIDR format that represents a network segment .sp Example: \fBsubnet=192.168.50.0/25\fP .TP .B iprange (or \fIip_range\fP) Allocate container IP from a sub\-range within the subnet .sp Subnet in CIDR format that represents a network segment .sp Example: \fBiprange=192.168.50.64/26\fP .TP .B gateway IPv4 gateway for the master subnet .sp Example: \fBgateway=192.168.50.1\fP .TP .B aux_addresses (or \fIaux_address\fP) A dictionary of mapping container names to IP addresses which should be allocated for them should they connect to the network. Either a dictionary of option names and values or a Python list of strings in the format \fBhost=ipaddr\fP\&. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBaux_addresses=\(aqfoo.bar.tld=192.168.50.10,hello.world.tld=192.168.50.11\(aq\fP .IP \(bu 2 \fBaux_addresses=\(dq[\(aqfoo.bar.tld=192.168.50.10\(aq, \(aqhello.world.tld=192.168.50.11\(aq]\(dq\fP .IP \(bu 2 \fBaux_addresses=\(dq{\(aqfoo.bar.tld\(aq: \(aq192.168.50.10\(aq, \(aqhello.world.tld\(aq: \(aq192.168.50.11\(aq}\(dq\fP .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.create_network web_network driver=bridge # IPv4 salt myminion docker.create_network macvlan_network driver=macvlan driver_opts=\(dq{\(aqparent\(aq:\(aqeth0\(aq}\(dq gateway=172.20.0.1 subnet=172.20.0.0/24 # IPv4 and IPv6 salt myminion docker.create_network mynet ipam_pools=\(aq[{\(dqsubnet\(dq: \(dq10.0.0.0/24\(dq, \(dqgateway\(dq: \(dq10.0.0.1\(dq}, {\(dqsubnet\(dq: \(dqfe3f:2180:26:1::60/123\(dq, \(dqgateway\(dq: \(dqfe3f:2180:26:1::61\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.create_volume(name, driver=None, driver_opts=None) Create a new volume .sp New in version 2015.8.4. .INDENT 7.0 .TP .B name name of volume .TP .B driver Driver of the volume .TP .B driver_opts Options for the driver volume .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.create_volume my_volume driver=local .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.dangling(prune=False, force=False) Return top\-level images (those on which no other images depend) which do not have a tag assigned to them. These include: .INDENT 7.0 .IP \(bu 2 Images which were once tagged but were later untagged, such as those which were superseded by committing a new copy of an existing tagged image. .IP \(bu 2 Images which were loaded using \fI\%docker.load\fP (or the \fBdocker load\fP Docker CLI command), but not tagged. .UNINDENT .INDENT 7.0 .TP .B prune False Remove these images .TP .B force False If \fBTrue\fP, and if \fBprune=True\fP, then forcibly remove these images. .UNINDENT .sp \fBRETURN DATA\fP .sp If \fBprune=False\fP, the return data will be a list of dangling image IDs. .sp If \fBprune=True\fP, the return data will be a dictionary with each key being the ID of the dangling image, and the following information for each image: .INDENT 7.0 .IP \(bu 2 \fBComment\fP \- Any error encountered when trying to prune a dangling image .sp \fI(Only present if prune failed)\fP .IP \(bu 2 \fBRemoved\fP \- A boolean (\fBTrue\fP if prune was successful, \fBFalse\fP if not) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.dangling salt myminion docker.dangling prune=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.depends(name) Returns the containers and images, if any, which depend on the given image .INDENT 7.0 .TP .B name Name or ID of image .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBContainers\fP \- A list of containers which depend on the specified image .IP \(bu 2 \fBImages\fP \- A list of IDs of images which depend on the specified image .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.depends myimage salt myminion docker.depends 0123456789ab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.diff(name) Get information on changes made to container\(aqs filesystem since it was created. Equivalent to running the \fBdocker diff\fP Docker CLI command. .INDENT 7.0 .TP .B name Container name or ID .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary containing any of the following keys: .INDENT 7.0 .IP \(bu 2 \fBAdded\fP \- A list of paths that were added. .IP \(bu 2 \fBChanged\fP \- A list of paths that were changed. .IP \(bu 2 \fBDeleted\fP \- A list of paths that were deleted. .UNINDENT .sp These keys will only be present if there were changes, so if the container has no differences the return dict will be empty. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.diff mycontainer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.disconnect_all_containers_from_network(network_id) New in version 2018.3.0. .sp Runs \fI\%docker.disconnect_container_from_network\fP on all containers connected to the specified network, and returns the names of all containers that were disconnected. .INDENT 7.0 .TP .B network_id Network name or ID .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.disconnect_all_containers_from_network mynet salt myminion docker.disconnect_all_containers_from_network 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.disconnect_container_from_network(container, network_id) New in version 2015.8.3. .sp Disconnect container from network .INDENT 7.0 .TP .B container Container name or ID .TP .B network_id Network name or ID .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.disconnect_container_from_network web\-1 mynet salt myminion docker.disconnect_container_from_network web\-1 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.exists(name) Check if a given container exists .INDENT 7.0 .TP .B name Container name or ID .UNINDENT .sp \fBRETURN DATA\fP .sp A boolean (\fBTrue\fP if the container exists, otherwise \fBFalse\fP) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.exists mycontainer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.export(name, path, overwrite=False, makedirs=False, compression=None, **kwargs) Exports a container to a tar archive. It can also optionally compress that tar archive, and push it up to the Master. .INDENT 7.0 .TP .B name Container name or ID .TP .B path Absolute path on the Minion where the container will be exported .TP .B overwrite False Unless this option is set to \fBTrue\fP, then if a file exists at the location specified by the \fBpath\fP argument, an error will be raised. .TP .B makedirs False If \fBTrue\fP, then if the parent directory of the file specified by the \fBpath\fP argument does not exist, Salt will attempt to create it. .TP .B compression None Can be set to any of the following: .INDENT 7.0 .IP \(bu 2 \fBgzip\fP or \fBgz\fP for gzip compression .IP \(bu 2 \fBbzip2\fP or \fBbz2\fP for bzip2 compression .IP \(bu 2 \fBxz\fP or \fBlzma\fP for XZ compression (requires \fI\%xz\-utils\fP, as well as the \fBlzma\fP module from Python 3.3, available in Python 2 and Python 3.0\-3.2 as \fI\%backports.lzma\fP) .UNINDENT .sp This parameter can be omitted and Salt will attempt to determine the compression type by examining the filename passed in the \fBpath\fP parameter. .TP .B push False If \fBTrue\fP, the container will be pushed to the master using \fI\%cp.push\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This requires \fI\%file_recv\fP to be set to \fBTrue\fP on the Master. .UNINDENT .UNINDENT .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBPath\fP \- Path of the file that was exported .IP \(bu 2 \fBPush\fP \- Reports whether or not the file was successfully pushed to the Master .sp \fI(Only present if push=True)\fP .IP \(bu 2 \fBSize\fP \- Size of the file, in bytes .IP \(bu 2 \fBSize_Human\fP \- Size of the file, in human\-readable units .IP \(bu 2 \fBTime_Elapsed\fP \- Time in seconds taken to perform the export .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.export mycontainer /tmp/mycontainer.tar salt myminion docker.export mycontainer /tmp/mycontainer.tar.xz push=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.freeze(name) This function is an alias of \fBpause\fP\&. .INDENT 7.0 .INDENT 3.5 Pauses a container .INDENT 0.0 .TP .B name Container name or ID .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 0.0 .IP \(bu 2 \fBstatus\fP \- A dictionary showing the prior state of the container as well as the new state .IP \(bu 2 \fBresult\fP \- A boolean noting whether or not the action was successful .IP \(bu 2 \fBcomment\fP \- Only present if the container cannot be paused .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.pause mycontainer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.get_client_args(limit=None) New in version 2016.3.6,2016.11.4,2017.7.0. .sp Changed in version 2017.7.0: Replaced the container config args with the ones from the API\(aqs \fBcreate_container\fP function. .sp Changed in version 2018.3.0: Added ability to limit the input to specific client functions .sp Many functions in Salt have been written to support the full list of arguments for a given function in the \fI\%docker\-py Low\-level API\fP\&. However, depending on the version of docker\-py installed on the minion, the available arguments may differ. This function will get the arguments for various functions in the installed version of docker\-py, to be used as a reference. .INDENT 7.0 .TP .B limit An optional list of categories for which to limit the return. This is useful if only a specific set of arguments is desired, and also keeps other function\(aqs argspecs from needlessly being examined. .UNINDENT .sp \fBAVAILABLE LIMITS\fP .INDENT 7.0 .IP \(bu 2 \fBcreate_container\fP \- arguments accepted by \fI\%create_container()\fP (used by \fI\%docker.create\fP) .IP \(bu 2 \fBhost_config\fP \- arguments accepted by \fI\%create_host_config()\fP (used to build the host config for \fI\%docker.create\fP) .IP \(bu 2 \fBconnect_container_to_network\fP \- arguments used by \fI\%connect_container_to_network()\fP to construct an endpoint config when connecting to a network (used by \fI\%docker.connect_container_to_network\fP) .IP \(bu 2 \fBcreate_network\fP \- arguments accepted by \fI\%create_network()\fP (used by \fI\%docker.create_network\fP) .IP \(bu 2 \fBipam_config\fP \- arguments used to create an \fI\%IPAM pool\fP (used by \fI\%docker.create_network\fP in the process of constructing an IPAM config dictionary) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.get_client_args salt myminion docker.get_client_args logs salt myminion docker.get_client_args create_container,connect_container_to_network .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.highstate(name, saltenv=\(aqbase\(aq, **kwargs) Apply a highstate to the running container .sp New in version 2019.2.0. .sp The container does not need to have Salt installed, but Python is required. .INDENT 7.0 .TP .B name Container name or ID .TP .B saltenv base Specify the environment from which to retrieve the SLS indicated by the \fImods\fP parameter. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.highstate compassionate_mirzakhani .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.history(name, quiet=False) Return the history for an image. Equivalent to running the \fBdocker history\fP Docker CLI command. .INDENT 7.0 .TP .B name Container name or ID .TP .B quiet False If \fBTrue\fP, the return data will simply be a list of the commands run to build the container. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ salt myminion docker.history nginx:latest quiet=True myminion: \- FROM scratch \- ADD file:ef063ed0ae9579362871b9f23d2bc0781ef7cd4de6ac822052cf6c9c5a12b1e2 in / \- CMD [/bin/bash] \- MAINTAINER NGINX Docker Maintainers \(dqdocker\-maint@nginx.com\(dq \- apt\-key adv \-\-keyserver pgp.mit.edu \-\-recv\-keys 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 \- echo \(dqdeb http://nginx.org/packages/mainline/debian/ wheezy nginx\(dq >> /etc/apt/sources.list \- ENV NGINX_VERSION=1.7.10\-1~wheezy \- apt\-get update && apt\-get install \-y ca\-certificates nginx=${NGINX_VERSION} && rm \-rf /var/lib/apt/lists/* \- ln \-sf /dev/stdout /var/log/nginx/access.log \- ln \-sf /dev/stderr /var/log/nginx/error.log \- VOLUME [/var/cache/nginx] \- EXPOSE map[80/tcp:{} 443/tcp:{}] \- CMD [nginx \-g daemon off;] https://github.com/saltstack/salt/pull/22421 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp \fBRETURN DATA\fP .sp If \fBquiet=False\fP, the return value will be a list of dictionaries containing information about each step taken to build the image. The keys in each step include the following: .INDENT 7.0 .IP \(bu 2 \fBCommand\fP \- The command executed in this build step .IP \(bu 2 \fBId\fP \- Layer ID .IP \(bu 2 \fBSize\fP \- Cumulative image size, in bytes .IP \(bu 2 \fBSize_Human\fP \- Cumulative image size, in human\-readable units .IP \(bu 2 \fBTags\fP \- Tag(s) assigned to this layer .IP \(bu 2 \fBTime_Created_Epoch\fP \- Time this build step was completed (Epoch time) .IP \(bu 2 \fBTime_Created_Local\fP \- Time this build step was completed (Minion\(aqs local timezone) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.exists mycontainer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.images(verbose=False, **kwargs) Returns information about the Docker images on the Minion. Equivalent to running the \fBdocker images\fP Docker CLI command. .INDENT 7.0 .TP .B all False If \fBTrue\fP, untagged images will also be returned .TP .B verbose False If \fBTrue\fP, a \fBdocker inspect\fP will be run on each image returned. .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary with each key being an image ID, and each value some general info about that image (time created, size, tags associated with the image, etc.) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.images salt myminion docker.images all=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.import_(source, repository, tag=\(aqlatest\(aq, api_response=False) Changed in version 2018.3.0: The repository and tag must now be passed separately using the \fBrepository\fP and \fBtag\fP arguments, rather than together in the (now deprecated) \fBimage\fP argument. .sp Imports content from a local tarball or a URL as a new docker image .INDENT 7.0 .TP .B source Content to import (URL or absolute path to a tarball). URL can be a file on the Salt fileserver (i.e. \fBsalt://path/to/rootfs/tarball.tar.xz\fP\&. To import a file from a saltenv other than \fBbase\fP (e.g. \fBdev\fP), pass it at the end of the URL (ex. \fBsalt://path/to/rootfs/tarball.tar.xz?saltenv=dev\fP). .TP .B repository Repository name for the image being imported .sp New in version 2018.3.0. .TP .B tag latest Tag name for the image .sp New in version 2018.3.0. .TP .B image Deprecated since version 2018.3.0: Use both \fBrepository\fP and \fBtag\fP instead .TP .B api_response False If \fBTrue\fP an \fBapi_response\fP key will be present in the return data, containing the raw output from the Docker API. .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBId\fP \- ID of the newly\-created image .IP \(bu 2 \fBImage\fP \- Name of the newly\-created image .IP \(bu 2 \fBTime_Elapsed\fP \- Time in seconds taken to perform the commit .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.import /tmp/cent7\-minimal.tar.xz myuser/centos salt myminion docker.import /tmp/cent7\-minimal.tar.xz myuser/centos:7 salt myminion docker.import salt://dockerimages/cent7\-minimal.tar.xz myuser/centos:7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.info() Returns a dictionary of system\-wide information. Equivalent to running the \fBdocker info\fP Docker CLI command. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.inspect(name) Changed in version 2017.7.0: Volumes and networks are now checked, in addition to containers and images. .sp This is a generic container/image/volume/network inspecton function. It will run the following functions in order: .INDENT 7.0 .IP \(bu 2 \fI\%docker.inspect_container\fP .IP \(bu 2 \fI\%docker.inspect_image\fP .IP \(bu 2 \fI\%docker.inspect_volume\fP .IP \(bu 2 \fI\%docker.inspect_network\fP .UNINDENT .sp The first of these to find a match will be returned. .INDENT 7.0 .TP .B name Container/image/volume/network name or ID .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary of container/image/volume/network information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.inspect mycontainer salt myminion docker.inspect busybox .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.inspect_container(name) Retrieves container information. Equivalent to running the \fBdocker inspect\fP Docker CLI command, but will only look for container information. .INDENT 7.0 .TP .B name Container name or ID .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary of container information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.inspect_container mycontainer salt myminion docker.inspect_container 0123456789ab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.inspect_image(name) Retrieves image information. Equivalent to running the \fBdocker inspect\fP Docker CLI command, but will only look for image information. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To inspect an image, it must have been pulled from a registry or built locally. Images on a Docker registry which have not been pulled cannot be inspected. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Image name or ID .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary of image information .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.inspect_image busybox salt myminion docker.inspect_image centos:6 salt myminion docker.inspect_image 0123456789ab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.inspect_network(network_id) Inspect Network .INDENT 7.0 .TP .B network_id ID of network .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.inspect_network 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.inspect_volume(name) Inspect Volume .sp New in version 2015.8.4. .INDENT 7.0 .TP .B name Name of volume .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.inspect_volume my_volume .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.kill(name) Kill all processes in a running container instead of performing a graceful shutdown .INDENT 7.0 .TP .B name Container name or ID .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBstatus\fP \- A dictionary showing the prior state of the container as well as the new state .IP \(bu 2 \fBresult\fP \- A boolean noting whether or not the action was successful .IP \(bu 2 \fBcomment\fP \- Only present if the container cannot be killed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.kill mycontainer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.layers(name) Returns a list of the IDs of layers belonging to the specified image, with the top\-most layer (the one correspnding to the passed name) appearing last. .INDENT 7.0 .TP .B name Image name or ID .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.layers centos:7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.list_containers(**kwargs) Returns a list of containers by name. This is different from \fI\%docker.ps\fP in that \fI\%docker.ps\fP returns its results organized by container ID. .INDENT 7.0 .TP .B all False If \fBTrue\fP, stopped containers will be included in return data .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.list_containers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.list_tags() Returns a list of tagged images .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.list_tags .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.load(path, repository=None, tag=None) Changed in version 2018.3.0: If the loaded image should be tagged, then the repository and tag must now be passed separately using the \fBrepository\fP and \fBtag\fP arguments, rather than together in the (now deprecated) \fBimage\fP argument. .sp Load a tar archive that was created using \fI\%docker.save\fP (or via the Docker CLI using \fBdocker save\fP). .INDENT 7.0 .TP .B path Path to docker tar archive. Path can be a file on the Minion, or the URL of a file on the Salt fileserver (i.e. \fBsalt://path/to/docker/saved/image.tar\fP). To load a file from a saltenv other than \fBbase\fP (e.g. \fBdev\fP), pass it at the end of the URL (ex. \fBsalt://path/to/rootfs/tarball.tar.xz?saltenv=dev\fP). .TP .B repository If specified, the topmost layer of the newly\-loaded image will be tagged with the specified repo using \fI\%docker.tag\fP\&. If a repository name is provided, then the \fBtag\fP argument is also required. .sp New in version 2018.3.0. .TP .B tag Tag name to go along with the repository name, if the loaded image is to be tagged. .sp New in version 2018.3.0. .TP .B image Deprecated since version 2018.3.0: Use both \fBrepository\fP and \fBtag\fP instead .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBPath\fP \- Path of the file that was saved .IP \(bu 2 \fBLayers\fP \- A list containing the IDs of the layers which were loaded. Any layers in the file that was loaded, which were already present on the Minion, will not be included. .IP \(bu 2 \fBImage\fP \- Name of tag applied to topmost layer .sp \fI(Only present if tag was specified and tagging was successful)\fP .IP \(bu 2 \fBTime_Elapsed\fP \- Time in seconds taken to load the file .IP \(bu 2 \fBWarning\fP \- Message describing any problems encountered in attempt to tag the topmost layer .sp \fI(Only present if tag was specified and tagging failed)\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.load /path/to/image.tar salt myminion docker.load salt://path/to/docker/saved/image.tar repository=myuser/myimage tag=mytag .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.login(*registries) New in version 2016.3.7,2016.11.4,2017.7.0. .sp Performs a \fBdocker login\fP to authenticate to one or more configured repositories. See the documentation at the top of this page to configure authentication credentials. .sp Multiple registry URLs (matching those configured in Pillar) can be passed, and Salt will attempt to login to \fIjust\fP those registries. If no registry URLs are provided, Salt will attempt to login to \fIall\fP configured registries. .sp \fBRETURN DATA\fP .sp A dictionary containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBResults\fP \- A dictionary mapping registry URLs to the authentication result. \fBTrue\fP means a successful login, \fBFalse\fP means a failed login. .IP \(bu 2 \fBErrors\fP \- A list of errors encountered during the course of this function. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.login salt myminion docker.login hub salt myminion docker.login hub https://mydomain.tld/registry/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.logout(*registries) New in version 3001. .sp Performs a \fBdocker logout\fP to remove the saved authentication details for one or more configured repositories. .sp Multiple registry URLs (matching those configured in Pillar) can be passed, and Salt will attempt to logout of \fIjust\fP those registries. If no registry URLs are provided, Salt will attempt to logout of \fIall\fP configured registries. .sp \fBRETURN DATA\fP .sp A dictionary containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBResults\fP \- A dictionary mapping registry URLs to the authentication result. \fBTrue\fP means a successful logout, \fBFalse\fP means a failed logout. .IP \(bu 2 \fBErrors\fP \- A list of errors encountered during the course of this function. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.logout salt myminion docker.logout hub salt myminion docker.logout hub https://mydomain.tld/registry/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.logs(name, **kwargs) Changed in version 2018.3.0: Support for all of docker\-py\(aqs \fI\%logs()\fP function\(aqs arguments, with the exception of \fBstream\fP\&. .sp Returns the logs for the container. An interface to docker\-py\(aqs \fI\%logs()\fP function. .INDENT 7.0 .TP .B name Container name or ID .TP .B stdout True Return stdout lines .TP .B stderr True Return stdout lines .TP .B timestamps False Show timestamps .TP .B tail all Output specified number of lines at the end of logs. Either an integer number of lines or the string \fBall\fP\&. .TP .B since Show logs since the specified time, passed as a UNIX epoch timestamp. Optionally, if \fI\%timelib\fP is installed on the minion the timestamp can be passed as a string which will be resolved to a date using \fBtimelib.strtodatetime()\fP\&. .TP .B follow False If \fBTrue\fP, this function will block until the container exits and return the logs when it does. The default behavior is to return what is in the log at the time this function is executed. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # All logs salt myminion docker.logs mycontainer # Last 100 lines of log salt myminion docker.logs mycontainer tail=100 # Just stderr salt myminion docker.logs mycontainer stdout=False # Logs since a specific UNIX timestamp salt myminion docker.logs mycontainer since=1511688459 # Flexible format for \(dqsince\(dq argument (requires timelib) salt myminion docker.logs mycontainer since=\(aq1 hour ago\(aq salt myminion docker.logs mycontainer since=\(aq1 week ago\(aq salt myminion docker.logs mycontainer since=\(aq1 fortnight ago\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.networks(names=None, ids=None) Changed in version 2017.7.0: The \fBnames\fP and \fBids\fP can be passed as a comma\-separated list now, as well as a Python list. .sp Changed in version 2018.3.0: The \fBContainers\fP key for each network is no longer always empty. .sp List existing networks .INDENT 7.0 .TP .B names Filter by name .TP .B ids Filter by id .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.networks names=network\-web salt myminion docker.networks ids=1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.pause(name) Pauses a container .INDENT 7.0 .TP .B name Container name or ID .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBstatus\fP \- A dictionary showing the prior state of the container as well as the new state .IP \(bu 2 \fBresult\fP \- A boolean noting whether or not the action was successful .IP \(bu 2 \fBcomment\fP \- Only present if the container cannot be paused .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.pause mycontainer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.pid(name) Returns the PID of a container .INDENT 7.0 .TP .B name Container name or ID .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.pid mycontainer salt myminion docker.pid 0123456789ab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.port(name, private_port=None) Returns port mapping information for a given container. Equivalent to running the \fBdocker port\fP Docker CLI command. .INDENT 7.0 .TP .B name Container name or ID .sp Changed in version 2019.2.0: This value can now be a pattern expression (using the pattern\-matching characters defined in \fI\%fnmatch\fP). If a pattern expression is used, this function will return a dictionary mapping container names which match the pattern to the mappings for those containers. When no pattern expression is used, a dictionary of the mappings for the specified container name will be returned. .TP .B private_port None If specified, get information for that specific port. Can be specified either as a port number (i.e. \fB5000\fP), or as a port number plus the protocol (i.e. \fB5000/udp\fP). .sp If this argument is omitted, all port mappings will be returned. .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary of port mappings, with the keys being the port and the values being the mapping(s) for that port. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.port mycontainer salt myminion docker.port mycontainer 5000 salt myminion docker.port mycontainer 5000/udp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.prune(containers=False, networks=False, images=False, build=False, volumes=False, system=None, **filters) New in version 2019.2.0. .sp Prune Docker\(aqs various subsystems .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This requires docker\-py version 2.1.0 or later. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B containers False If \fBTrue\fP, prunes stopped containers (\fI\%documentation\fP) .TP .B images False If \fBTrue\fP, prunes unused images (\fI\%documentation\fP) .TP .B networks False If \fBFalse\fP, prunes unreferenced networks (\fI\%documentation\fP) .TP .B build False If \fBTrue\fP, clears the builder cache .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Only supported in Docker 17.07.x and newer. Additionally, filters do not apply to this argument. .UNINDENT .UNINDENT .TP .B volumes False If \fBTrue\fP, prunes unreferenced volumes (\fI\%documentation\fP) .TP .B system If \fBTrue\fP, prunes containers, images, networks, and builder cache. Assumed to be \fBTrue\fP if none of \fBcontainers\fP, \fBimages\fP, \fBnetworks\fP, or \fBbuild\fP are set to \fBTrue\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBvolumes=True\fP must still be used to prune volumes .UNINDENT .UNINDENT .TP .B filters .INDENT 7.0 .IP \(bu 2 \fBdangling=True\fP (images only) \- remove only dangling images .IP \(bu 2 \fBuntil=<timestamp>\fP \- only remove objects created before given timestamp. Not applicable to volumes. See the documentation links above for examples of valid time expressions. .IP \(bu 2 \fBlabel\fP \- only remove objects matching the label expression. Valid expressions include \fBlabelname\fP or \fBlabelname=value\fP\&. .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.prune system=True salt myminion docker.prune system=True until=12h salt myminion docker.prune images=True dangling=True salt myminion docker.prune images=True label=foo,bar=baz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.ps_(filters=None, **kwargs) Returns information about the Docker containers on the Minion. Equivalent to running the \fBdocker ps\fP Docker CLI command. .INDENT 7.0 .TP .B all False If \fBTrue\fP, stopped containers will also be returned .TP .B host: False If \fBTrue\fP, local host\(aqs network topology will be included .TP .B verbose False If \fBTrue\fP, a \fBdocker inspect\fP will be run on each container returned. .TP .B filters: None A dictionary of filters to be processed on the container list. Available filters: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 exited (int): Only containers with specified exit code .IP \(bu 2 status (str): One of restarting, running, paused, exited .IP \(bu 2 label (str): format either \(dqkey\(dq or \(dqkey=value\(dq .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary with each key being an container ID, and each value some general info about that container (time created, name, command, etc.) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.ps salt myminion docker.ps all=True salt myminion docker.ps filters=\(dq{\(aqlabel\(aq: \(aqrole=web\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.pull(image, insecure_registry=False, api_response=False, client_timeout=60) Changed in version 2018.3.0: If no tag is specified in the \fBimage\fP argument, all tags for the image will be pulled. For this reason is it recommended to pass \fBimage\fP using the \fBrepo:tag\fP notation. .sp Pulls an image from a Docker registry .INDENT 7.0 .TP .B image Image to be pulled .TP .B insecure_registry False If \fBTrue\fP, the Docker client will permit the use of insecure (non\-HTTPS) registries. .TP .B api_response False If \fBTrue\fP, an \fBAPI_Response\fP key will be present in the return data, containing the raw output from the Docker API. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This may result in a \fBlot\fP of additional return data, especially for larger images. .UNINDENT .UNINDENT .TP .B client_timeout Timeout in seconds for the Docker client. This is not a timeout for this function, but for receiving a response from the API. .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fBLayers\fP \- A dictionary containing one or more of the following keys: .INDENT 7.0 .IP \(bu 2 \fBAlready_Pulled\fP \- Layers that that were already present on the Minion .IP \(bu 2 \fBPulled\fP \- Layers that that were pulled .UNINDENT .UNINDENT .IP \(bu 2 \fBStatus\fP \- A string containing a summary of the pull action (usually a message saying that an image was downloaded, or that it was up to date). .IP \(bu 2 \fBTime_Elapsed\fP \- Time in seconds taken to perform the pull .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.pull centos salt myminion docker.pull centos:6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.push(image, insecure_registry=False, api_response=False, client_timeout=60) Changed in version 2015.8.4: The \fBId\fP and \fBImage\fP keys are no longer present in the return data. This is due to changes in the Docker Remote API. .sp Pushes an image to a Docker registry. See the documentation at top of this page to configure authentication credentials. .INDENT 7.0 .TP .B image Image to be pushed. If just the repository name is passed, then all tagged images for the specified repo will be pushed. If the image name is passed in \fBrepo:tag\fP notation, only the specified image will be pushed. .TP .B insecure_registry False If \fBTrue\fP, the Docker client will permit the use of insecure (non\-HTTPS) registries. .TP .B api_response False If \fBTrue\fP, an \fBAPI_Response\fP key will be present in the return data, containing the raw output from the Docker API. .TP .B client_timeout Timeout in seconds for the Docker client. This is not a timeout for this function, but for receiving a response from the API. .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fBLayers\fP \- A dictionary containing one or more of the following keys: .INDENT 7.0 .IP \(bu 2 \fBAlready_Pushed\fP \- Layers that that were already present on the Minion .IP \(bu 2 \fBPushed\fP \- Layers that that were pushed .UNINDENT .UNINDENT .IP \(bu 2 \fBTime_Elapsed\fP \- Time in seconds taken to perform the push .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.push myuser/mycontainer salt myminion docker.push myuser/mycontainer:mytag .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.remove_network(network_id) Remove a network .INDENT 7.0 .TP .B network_id Network name or ID .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.remove_network mynet salt myminion docker.remove_network 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.remove_volume(name) Remove a volume .sp New in version 2015.8.4. .INDENT 7.0 .TP .B name Name of volume .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.remove_volume my_volume .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.rename(name, new_name) New in version 2017.7.0. .sp Renames a container. Returns \fBTrue\fP if successful, and raises an error if the API returns one. If unsuccessful and the API returns no error (should not happen), then \fBFalse\fP will be returned. .INDENT 7.0 .TP .B name Name or ID of existing container .TP .B new_name New name to assign to container .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.rename foo bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.resolve_image_id(name) New in version 2018.3.0. .sp Given an image name (or partial image ID), return the full image ID. If no match is found among the locally\-pulled images, then \fBFalse\fP will be returned. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.resolve_image_id foo salt myminion docker.resolve_image_id foo:bar salt myminion docker.resolve_image_id 36540f359ca3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.resolve_tag(name, **kwargs) New in version 2017.7.2. .sp Changed in version 2018.3.0: Instead of matching against pulled tags using \fI\%docker.list_tags\fP, this function now simply inspects the passed image name using \fI\%docker.inspect_image\fP and returns the first matching tag. If no matching tags are found, it is assumed that the passed image is an untagged image ID, and the full ID is returned. .sp Inspects the specified image name and returns the first matching tag in the inspect results. If the specified image is not pulled locally, this function will return \fBFalse\fP\&. .INDENT 7.0 .TP .B name Image name to resolve. If the image is found but there are no tags, this means that the image name passed was an untagged image. In this case the image ID will be returned. .TP .B all False If \fBTrue\fP, a list of all matching tags will be returned. If the image is found but there are no tags, then a list will still be returned, but it will simply contain the image ID. .sp New in version 2018.3.0. .TP .B tags Deprecated since version 2018.3.0. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.resolve_tag busybox salt myminion docker.resolve_tag centos:7 all=True salt myminion docker.resolve_tag c9f378ac27d9 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.restart(name, timeout=10) Restarts a container .INDENT 7.0 .TP .B name Container name or ID .TP .B timeout 10 Timeout in seconds after which the container will be killed (if it has not yet gracefully shut down) .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBstatus\fP \- A dictionary showing the prior state of the container as well as the new state .IP \(bu 2 \fBresult\fP \- A boolean noting whether or not the action was successful .IP \(bu 2 \fBrestarted\fP \- If restart was successful, this key will be present and will be set to \fBTrue\fP\&. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.restart mycontainer salt myminion docker.restart mycontainer timeout=20 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.retcode(name, cmd, exec_driver=None, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, ignore_retcode=False, keep_env=None) Run \fI\%cmd.retcode\fP within a container .INDENT 7.0 .TP .B name Container name or ID in which to run the command .TP .B cmd Command to run .TP .B exec_driver None If not passed, the execution driver will be detected as described \fI\%above\fP\&. .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. .TP .B keep_env None If not passed, only a sane default PATH environment variable will be set. If \fBTrue\fP, all environment variables from the container\(aqs host will be kept. Otherwise, a comma\-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.retcode mycontainer \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.rm_(name, force=False, volumes=False, **kwargs) Removes a container .INDENT 7.0 .TP .B name Container name or ID .TP .B force False If \fBTrue\fP, the container will be killed first before removal, as the Docker API will not permit a running container to be removed. This option is set to \fBFalse\fP by default to prevent accidental removal of a running container. .TP .B stop False If \fBTrue\fP, the container will be stopped first before removal, as the Docker API will not permit a running container to be removed. This option is set to \fBFalse\fP by default to prevent accidental removal of a running container. .sp New in version 2017.7.0. .TP .B timeout Optional timeout to be passed to \fI\%docker.stop\fP if stopping the container. .sp New in version 2018.3.0. .TP .B volumes False Also remove volumes associated with container .UNINDENT .sp \fBRETURN DATA\fP .sp A list of the IDs of containers which were removed .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.rm mycontainer salt myminion docker.rm mycontainer force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.rmi(*names, **kwargs) Removes an image .INDENT 7.0 .TP .B name Name (in \fBrepo:tag\fP notation) or ID of image. .TP .B force False If \fBTrue\fP, the image will be removed even if the Minion has containers created from that image .TP .B prune True If \fBTrue\fP, untagged parent image layers will be removed as well, set this to \fBFalse\fP to keep them. .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following two keys: .INDENT 7.0 .IP \(bu 2 \fBLayers\fP \- A list of the IDs of image layers that were removed .IP \(bu 2 \fBTags\fP \- A list of the tags that were removed .IP \(bu 2 \fBErrors\fP \- A list of any errors that were encountered .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.rmi busybox salt myminion docker.rmi busybox force=True salt myminion docker.rmi foo bar baz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.run(name, cmd, exec_driver=None, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, ignore_retcode=False, keep_env=None) Run \fI\%cmd.run\fP within a container .INDENT 7.0 .TP .B name Container name or ID in which to run the command .TP .B cmd Command to run .TP .B exec_driver None If not passed, the execution driver will be detected as described \fI\%above\fP\&. .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. .TP .B keep_env None If not passed, only a sane default PATH environment variable will be set. If \fBTrue\fP, all environment variables from the container\(aqs host will be kept. Otherwise, a comma\-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.run mycontainer \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.run_all(name, cmd, exec_driver=None, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, ignore_retcode=False, keep_env=None) Run \fI\%cmd.run_all\fP within a container .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 While the command is run within the container, it is initiated from the host. Therefore, the PID in the return dict is from the host, not from the container. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Container name or ID in which to run the command .TP .B cmd Command to run .TP .B exec_driver None If not passed, the execution driver will be detected as described \fI\%above\fP\&. .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. .TP .B keep_env None If not passed, only a sane default PATH environment variable will be set. If \fBTrue\fP, all environment variables from the container\(aqs host will be kept. Otherwise, a comma\-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.run_all mycontainer \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.run_container(image, name=None, skip_translate=None, ignore_collisions=False, validate_ip_addrs=True, client_timeout=60, bg=False, replace=False, force=False, networks=None, **kwargs) New in version 2018.3.0. .sp Equivalent to \fBdocker run\fP on the Docker CLI. Runs the container, waits for it to exit, and returns the container\(aqs logs when complete. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Not to be confused with \fI\%docker.run\fP, which provides a \fI\%cmd.run\fP\-like interface for executing commands in a running container. .UNINDENT .UNINDENT .sp This function accepts the same arguments as \fI\%docker.create\fP, with the exception of \fBstart\fP\&. In addition, it accepts the arguments from \fI\%docker.logs\fP, with the exception of \fBfollow\fP, to control how logs are returned. Finally, the \fBbg\fP argument described below can be used to optionally run the container in the background (the default behavior is to block until the container exits). .INDENT 7.0 .TP .B bg False If \fBTrue\fP, this function will not wait for the container to exit and will not return its logs. It will however return the container\(aqs name and ID, allowing for \fI\%docker.logs\fP to be used to view the logs. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The logs will be inaccessible once the container exits if \fBauto_remove\fP is set to \fBTrue\fP, so keep this in mind. .UNINDENT .UNINDENT .TP .B replace False If \fBTrue\fP, and if the named container already exists, this will remove the existing container. The default behavior is to return a \fBFalse\fP result when the container already exists. .TP .B force False If \fBTrue\fP, and the named container already exists, \fIand\fP \fBreplace\fP is also set to \fBTrue\fP, then the container will be forcibly removed. Otherwise, the state will not proceed and will return a \fBFalse\fP result. .TP .B networks Networks to which the container should be connected. If automatic IP configuration is being used, the networks can be a simple list of network names. If custom IP configuration is being used, then this argument must be passed as a dictionary. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.run_container myuser/myimage command=/usr/local/bin/myscript.sh # Run container in the background salt myminion docker.run_container myuser/myimage command=/usr/local/bin/myscript.sh bg=True # Connecting to two networks using automatic IP configuration salt myminion docker.run_container myuser/myimage command=\(aqperl /scripts/sync.py\(aq networks=net1,net2 # net1 using automatic IP, net2 using static IPv4 address salt myminion docker.run_container myuser/myimage command=\(aqperl /scripts/sync.py\(aq networks=\(aq{\(dqnet1\(dq: {}, \(dqnet2\(dq: {\(dqipv4_address\(dq: \(dq192.168.27.12\(dq}}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.run_stderr(name, cmd, exec_driver=None, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, ignore_retcode=False, keep_env=None) Run \fI\%cmd.run_stderr\fP within a container .INDENT 7.0 .TP .B name Container name or ID in which to run the command .TP .B cmd Command to run .TP .B exec_driver None If not passed, the execution driver will be detected as described \fI\%above\fP\&. .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. .TP .B keep_env None If not passed, only a sane default PATH environment variable will be set. If \fBTrue\fP, all environment variables from the container\(aqs host will be kept. Otherwise, a comma\-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.run_stderr mycontainer \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.run_stdout(name, cmd, exec_driver=None, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, ignore_retcode=False, keep_env=None) Run \fI\%cmd.run_stdout\fP within a container .INDENT 7.0 .TP .B name Container name or ID in which to run the command .TP .B cmd Command to run .TP .B exec_driver None If not passed, the execution driver will be detected as described \fI\%above\fP\&. .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. .TP .B keep_env None If not passed, only a sane default PATH environment variable will be set. If \fBTrue\fP, all environment variables from the container\(aqs host will be kept. Otherwise, a comma\-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.run_stdout mycontainer \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.save(name, path, overwrite=False, makedirs=False, compression=None, **kwargs) Saves an image and to a file on the minion. Equivalent to running the \fBdocker save\fP Docker CLI command, but unlike \fBdocker save\fP this will also work on named images instead of just images IDs. .INDENT 7.0 .TP .B name Name or ID of image. Specify a specific tag by using the \fBrepo:tag\fP notation. .TP .B path Absolute path on the Minion where the image will be exported .TP .B overwrite False Unless this option is set to \fBTrue\fP, then if the destination file exists an error will be raised. .TP .B makedirs False If \fBTrue\fP, then if the parent directory of the file specified by the \fBpath\fP argument does not exist, Salt will attempt to create it. .TP .B compression None Can be set to any of the following: .INDENT 7.0 .IP \(bu 2 \fBgzip\fP or \fBgz\fP for gzip compression .IP \(bu 2 \fBbzip2\fP or \fBbz2\fP for bzip2 compression .IP \(bu 2 \fBxz\fP or \fBlzma\fP for XZ compression (requires \fI\%xz\-utils\fP, as well as the \fBlzma\fP module from Python 3.3, available in Python 2 and Python 3.0\-3.2 as \fI\%backports.lzma\fP) .UNINDENT .sp This parameter can be omitted and Salt will attempt to determine the compression type by examining the filename passed in the \fBpath\fP parameter. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Since the Docker API does not support \fBdocker save\fP, compression will be a bit slower with this function than with \fI\%docker.export\fP since the image(s) will first be saved and then the compression done afterwards. .UNINDENT .UNINDENT .TP .B push False If \fBTrue\fP, the container will be pushed to the master using \fI\%cp.push\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This requires \fI\%file_recv\fP to be set to \fBTrue\fP on the Master. .UNINDENT .UNINDENT .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBPath\fP \- Path of the file that was saved .IP \(bu 2 \fBPush\fP \- Reports whether or not the file was successfully pushed to the Master .sp \fI(Only present if push=True)\fP .IP \(bu 2 \fBSize\fP \- Size of the file, in bytes .IP \(bu 2 \fBSize_Human\fP \- Size of the file, in human\-readable units .IP \(bu 2 \fBTime_Elapsed\fP \- Time in seconds taken to perform the save .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.save centos:7 /tmp/cent7.tar salt myminion docker.save 0123456789ab cdef01234567 /tmp/saved.tar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.script(name, source, saltenv=\(aqbase\(aq, args=None, template=None, exec_driver=None, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, ignore_retcode=False, use_vt=False, keep_env=None) Run \fI\%cmd.script\fP within a container .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 While the command is run within the container, it is initiated from the host. Therefore, the PID in the return dict is from the host, not from the container. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Container name or ID .TP .B source Path to the script. Can be a local path on the Minion or a remote file from the Salt fileserver. .TP .B args A string containing additional command\-line options to pass to the script. .TP .B template None Templating engine to use on the script before running. .TP .B exec_driver None If not passed, the execution driver will be detected as described \fI\%above\fP\&. .TP .B stdin None Standard input to be used for the script .TP .B output_loglevel debug Level at which to log the output from the script. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. .TP .B keep_env None If not passed, only a sane default PATH environment variable will be set. If \fBTrue\fP, all environment variables from the container\(aqs host will be kept. Otherwise, a comma\-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.script mycontainer salt://docker_script.py salt myminion docker.script mycontainer salt://scripts/runme.sh \(aqarg1 arg2 \(dqarg 3\(dq\(aq salt myminion docker.script mycontainer salt://scripts/runme.sh stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq output_loglevel=quiet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.script_retcode(name, source, saltenv=\(aqbase\(aq, args=None, template=None, exec_driver=None, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, ignore_retcode=False, use_vt=False, keep_env=None) Run \fI\%cmd.script_retcode\fP within a container .INDENT 7.0 .TP .B name Container name or ID .TP .B source Path to the script. Can be a local path on the Minion or a remote file from the Salt fileserver. .TP .B args A string containing additional command\-line options to pass to the script. .TP .B template None Templating engine to use on the script before running. .TP .B exec_driver None If not passed, the execution driver will be detected as described \fI\%above\fP\&. .TP .B stdin None Standard input to be used for the script .TP .B output_loglevel debug Level at which to log the output from the script. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. .TP .B keep_env None If not passed, only a sane default PATH environment variable will be set. If \fBTrue\fP, all environment variables from the container\(aqs host will be kept. Otherwise, a comma\-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.script_retcode mycontainer salt://docker_script.py salt myminion docker.script_retcode mycontainer salt://scripts/runme.sh \(aqarg1 arg2 \(dqarg 3\(dq\(aq salt myminion docker.script_retcode mycontainer salt://scripts/runme.sh stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq output_loglevel=quiet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.search(name, official=False, trusted=False) Searches the registry for an image .INDENT 7.0 .TP .B name Search keyword .TP .B official False Limit results to official builds .TP .B trusted False Limit results to \fI\%trusted builds\fP .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary with each key being the name of an image, and the following information for each image: .INDENT 7.0 .IP \(bu 2 \fBDescription\fP \- Image description .IP \(bu 2 \fBOfficial\fP \- A boolean (\fBTrue\fP if an official build, \fBFalse\fP if not) .IP \(bu 2 \fBStars\fP \- Number of stars the image has on the registry .IP \(bu 2 \fBTrusted\fP \- A boolean (\fBTrue\fP if a trusted build, \fBFalse\fP if not) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.search centos salt myminion docker.search centos official=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.signal_(name, signal) Send a signal to a container. Signals can be either strings or numbers, and are defined in the \fBStandard Signals\fP section of the \fBsignal(7)\fP manpage. Run \fBman 7 signal\fP on a Linux host to browse this manpage. .INDENT 7.0 .TP .B name Container name or ID .TP .B signal Signal to send to container .UNINDENT .sp \fBRETURN DATA\fP .sp If the signal was successfully sent, \fBTrue\fP will be returned. Otherwise, an error will be raised. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.signal mycontainer SIGHUP .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.sls(name, mods=None, **kwargs) Apply the states defined by the specified SLS modules to the running container .sp New in version 2016.11.0. .sp The container does not need to have Salt installed, but Python is required. .INDENT 7.0 .TP .B name Container name or ID .TP .B mods None A string containing comma\-separated list of SLS with defined states to apply to the container. .TP .B saltenv base Specify the environment from which to retrieve the SLS indicated by the \fImods\fP parameter. .TP .B pillarenv Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the \fI\%pillarenv\fP option. When neither the \fI\%pillarenv\fP minion config option nor this CLI argument is used, all Pillar environments will be merged together. .sp New in version 2018.3.0. .TP .B pillar Custom Pillar values, passed as a dictionary of key\-value pairs .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Values passed this way will override Pillar values set via \fBpillar_roots\fP or an external Pillar source. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.sls compassionate_mirzakhani mods=rails,web .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.sls_build(repository, tag=\(aqlatest\(aq, base=\(aqopensuse/python\(aq, mods=None, dryrun=False, **kwargs) Changed in version 2018.3.0: The repository and tag must now be passed separately using the \fBrepository\fP and \fBtag\fP arguments, rather than together in the (now deprecated) \fBimage\fP argument. .sp Build a Docker image using the specified SLS modules on top of base image .sp New in version 2016.11.0. .sp The base image does not need to have Salt installed, but Python is required. .INDENT 7.0 .TP .B repository Repository name for the image to be built .sp New in version 2018.3.0. .TP .B tag latest Tag name for the image to be built .sp New in version 2018.3.0. .TP .B name Deprecated since version 2018.3.0: Use both \fBrepository\fP and \fBtag\fP instead .TP .B base opensuse/python Name or ID of the base image .TP .B mods A string containing comma\-separated list of SLS with defined states to apply to the base image. .TP .B saltenv base Specify the environment from which to retrieve the SLS indicated by the \fImods\fP parameter. .TP .B pillarenv Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the \fI\%pillarenv\fP option. When neither the \fI\%pillarenv\fP minion config option nor this CLI argument is used, all Pillar environments will be merged together. .sp New in version 2018.3.0. .TP .B pillar Custom Pillar values, passed as a dictionary of key\-value pairs .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Values passed this way will override Pillar values set via \fBpillar_roots\fP or an external Pillar source. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .TP .B dryrun: False when set to True the container will not be committed at the end of the build. The dryrun succeed also when the state contains errors. .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary with the ID of the new container. In case of a dryrun, the state result is returned and the container gets removed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.sls_build imgname base=mybase mods=rails,web .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.start_(name) Start a container .INDENT 7.0 .TP .B name Container name or ID .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBstatus\fP \- A dictionary showing the prior state of the container as well as the new state .IP \(bu 2 \fBresult\fP \- A boolean noting whether or not the action was successful .IP \(bu 2 \fBcomment\fP \- Only present if the container cannot be started .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.start mycontainer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.state(name) Returns the state of the container .INDENT 7.0 .TP .B name Container name or ID .UNINDENT .sp \fBRETURN DATA\fP .sp A string representing the current state of the container (either \fBrunning\fP, \fBpaused\fP, or \fBstopped\fP) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.state mycontainer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.stop(name, timeout=None, **kwargs) Stops a running container .INDENT 7.0 .TP .B name Container name or ID .TP .B unpause False If \fBTrue\fP and the container is paused, it will be unpaused before attempting to stop the container. .TP .B timeout Timeout in seconds after which the container will be killed (if it has not yet gracefully shut down) .sp Changed in version 2017.7.0: If this argument is not passed, then the container\(aqs configuration will be checked. If the container was created using the \fBstop_timeout\fP argument, then the configured timeout will be used, otherwise the timeout will be 10 seconds. .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBstatus\fP \- A dictionary showing the prior state of the container as well as the new state .IP \(bu 2 \fBresult\fP \- A boolean noting whether or not the action was successful .IP \(bu 2 \fBcomment\fP \- Only present if the container can not be stopped .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.stop mycontainer salt myminion docker.stop mycontainer unpause=True salt myminion docker.stop mycontainer timeout=20 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.tag_(name, repository, tag=\(aqlatest\(aq, force=False) Changed in version 2018.3.0: The repository and tag must now be passed separately using the \fBrepository\fP and \fBtag\fP arguments, rather than together in the (now deprecated) \fBimage\fP argument. .sp Tag an image into a repository and return \fBTrue\fP\&. If the tag was unsuccessful, an error will be raised. .INDENT 7.0 .TP .B name ID of image .TP .B repository Repository name for the image to be built .sp New in version 2018.3.0. .TP .B tag latest Tag name for the image to be built .sp New in version 2018.3.0. .TP .B image Deprecated since version 2018.3.0: Use both \fBrepository\fP and \fBtag\fP instead .TP .B force False Force apply tag .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.tag 0123456789ab myrepo/mycontainer mytag .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.top(name) Runs the \fIdocker top\fP command on a specific container .INDENT 7.0 .TP .B name Container name or ID .UNINDENT .sp CLI Example: .sp \fBRETURN DATA\fP .sp A list of dictionaries containing information about each process .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.top mycontainer salt myminion docker.top 0123456789ab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.unfreeze(name) This function is an alias of \fBunpause\fP\&. .INDENT 7.0 .INDENT 3.5 Unpauses a container .INDENT 0.0 .TP .B name Container name or ID .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 0.0 .IP \(bu 2 \fBstatus\fP \- A dictionary showing the prior state of the container as well as the new state .IP \(bu 2 \fBresult\fP \- A boolean noting whether or not the action was successful .IP \(bu 2 \fBcomment\fP \- Only present if the container can not be unpaused .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.pause mycontainer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.unpause(name) Unpauses a container .INDENT 7.0 .TP .B name Container name or ID .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBstatus\fP \- A dictionary showing the prior state of the container as well as the new state .IP \(bu 2 \fBresult\fP \- A boolean noting whether or not the action was successful .IP \(bu 2 \fBcomment\fP \- Only present if the container can not be unpaused .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.pause mycontainer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.version() Returns a dictionary of Docker version information. Equivalent to running the \fBdocker version\fP Docker CLI command. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.volumes(filters=None) List existing volumes .sp New in version 2015.8.4. .INDENT 7.0 .TP .B filters There is one available filter: dangling=true .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.volumes filters=\(dq{\(aqdangling\(aq: True}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockermod.wait(name, ignore_already_stopped=False, fail_on_exit_status=False) Wait for the container to exit gracefully, and return its exit code .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function will block until the container is stopped. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Container name or ID .TP .B ignore_already_stopped Boolean flag that prevents execution to fail, if a container is already stopped. .TP .B fail_on_exit_status Boolean flag to report execution as failure if \fBexit_status\fP is different than 0. .UNINDENT .sp \fBRETURN DATA\fP .sp A dictionary will be returned, containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBstatus\fP \- A dictionary showing the prior state of the container as well as the new state .IP \(bu 2 \fBresult\fP \- A boolean noting whether or not the action was successful .IP \(bu 2 \fBexit_status\fP \- Exit status for the container .IP \(bu 2 \fBcomment\fP \- Only present if the container is already stopped .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.wait mycontainer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dpkg_lowpkg .sp Support for DEB packages .INDENT 0.0 .TP .B salt.modules.dpkg_lowpkg.bin_pkg_info(path, saltenv=\(aqbase\(aq) New in version 2015.8.0. .sp Parses DEB metadata and returns a dictionary of information about the package (name, version, etc.). .INDENT 7.0 .TP .B path Path to the file. Can either be an absolute path to a file on the minion, or a salt fileserver URL (e.g. \fBsalt://path/to/file.deb\fP). If a salt fileserver URL is passed, the file will be cached to the minion so that it can be examined. .TP .B saltenv base Salt fileserver environment from which to retrieve the package. Ignored if \fBpath\fP is a local file path on the minion. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.bin_pkg_info /root/foo\-1.2.3\-1ubuntu1_all.deb salt \(aq*\(aq lowpkg.bin_pkg_info salt://foo\-1.2.3\-1ubuntu1_all.deb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dpkg_lowpkg.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 lowpkg.file_dict hostname salt \(aq*\(aq lowpkg.file_dict hostname mount salt \(aq*\(aq lowpkg.file_dict .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dpkg_lowpkg.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 lowpkg.file_list hostname salt \(aq*\(aq lowpkg.file_list hostname mount salt \(aq*\(aq lowpkg.file_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dpkg_lowpkg.info(*packages, **kwargs) Returns a detailed summary of package information for provided package names. If no packages are specified, all packages will be returned. .sp New in version 2015.8.1. .INDENT 7.0 .TP .B packages 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 lowpkg.info salt \(aq*\(aq lowpkg.info apache2 bash salt \(aq*\(aq lowpkg.info \(aqphp5*\(aq failhard=false .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dpkg_lowpkg.list_pkgs(*packages, **kwargs) List the packages currently installed in a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(aq} .ft P .fi .UNINDENT .UNINDENT .sp External dependencies: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Virtual package resolution requires aptitude. Because this function uses dpkg, virtual packages will be reported as not installed. .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.list_pkgs salt \(aq*\(aq lowpkg.list_pkgs hostname salt \(aq*\(aq lowpkg.list_pkgs hostname mount .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dpkg_lowpkg.unpurge(*packages) Change package selection for each package specified to \(aqinstall\(aq .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.unpurge curl .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.drac .sp Manage Dell DRAC .INDENT 0.0 .TP .B salt.modules.drac.change_password(username, password, uid=None) Change users password .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.change_password [USERNAME] [PASSWORD] [UID \- optional] salt dell drac.change_password diana secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.create_user(username, password, permissions, users=None) Create user accounts .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.create_user [USERNAME] [PASSWORD] [PRIVILEGES] salt dell drac.create_user diana secret login,test_alerts,clear_logs .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B DRAC Privileges .INDENT 7.0 .IP \(bu 2 login : Login to iDRAC .IP \(bu 2 drac : Configure iDRAC .IP \(bu 2 user_management : Configure Users .IP \(bu 2 clear_logs : Clear Logs .IP \(bu 2 server_control_commands : Execute Server Control Commands .IP \(bu 2 console_redirection : Access Console Redirection .IP \(bu 2 virtual_media : Access Virtual Media .IP \(bu 2 test_alerts : Test Alerts .IP \(bu 2 debug_commands : Execute Debug Commands .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.delete_user(username, uid=None) Delete a user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.delete_user [USERNAME] [UID \- optional] salt dell drac.delete_user diana 4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.email_alerts(action) Enable/Disable email alerts .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.email_alerts True salt dell drac.email_alerts False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.list_users() List all DRAC users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.nameservers(*ns) Configure the nameservers on the DRAC .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.nameservers [NAMESERVERS] salt dell drac.nameservers ns1.example.com ns2.example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.network_info() Return Network Configuration .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.network_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.server_hardreset() Performs a reset (reboot) operation on the managed server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.server_hardreset .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.server_poweroff() Powers down the managed server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.server_poweroff .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.server_poweron() Powers up the managed server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.server_poweron .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.server_pxe() Configure server to PXE perform a one off PXE boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.server_pxe .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.server_reboot() Issues a power\-cycle operation on the managed server. This action is similar to pressing the power button on the system\(aqs front panel to power down and then power up the system. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.server_reboot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.set_network(ip, netmask, gateway) Configure Network .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.set_network [DRAC IP] [NETMASK] [GATEWAY] salt dell drac.set_network 192.168.0.2 255.255.255.0 192.168.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.set_permissions(username, permissions, uid=None) Configure users permissions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.set_permissions [USERNAME] [PRIVILEGES] [USER INDEX \- optional] salt dell drac.set_permissions diana login,test_alerts,clear_logs 4 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B DRAC Privileges .INDENT 7.0 .IP \(bu 2 login : Login to iDRAC .IP \(bu 2 drac : Configure iDRAC .IP \(bu 2 user_management : Configure Users .IP \(bu 2 clear_logs : Clear Logs .IP \(bu 2 server_control_commands : Execute Server Control Commands .IP \(bu 2 console_redirection : Access Console Redirection .IP \(bu 2 virtual_media : Access Virtual Media .IP \(bu 2 test_alerts : Test Alerts .IP \(bu 2 debug_commands : Execute Debug Commands .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.set_snmp(community) Configure SNMP community string .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.set_snmp [COMMUNITY] salt dell drac.set_snmp public .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.syslog(server, enable=True) Configure syslog remote logging, by default syslog will automatically be enabled if a server is specified. However, if you want to disable syslog you will need to specify a server followed by False .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.syslog [SYSLOG IP] [ENABLE/DISABLE] salt dell drac.syslog 0.0.0.0 False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drac.system_info() Return System information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.system_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dracr .sp Manage Dell DRAC. .sp New in version 2015.8.2. .INDENT 0.0 .TP .B salt.modules.dracr.bare_rac_cmd(cmd, host=None, admin_username=None, admin_password=None) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.change_password(username, password, uid=None, host=None, admin_username=None, admin_password=None, module=None) Change user\(aqs password .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.change_password [USERNAME] [PASSWORD] uid=[OPTIONAL] host=<remote DRAC> admin_username=<DRAC user> admin_password=<DRAC PW> salt dell dracr.change_password diana secret .ft P .fi .UNINDENT .UNINDENT .sp Note that if only a username is specified then this module will look up details for all 16 possible DRAC users. This is time consuming, but might be necessary if one is not sure which user slot contains the one you want. Many late\-model Dell chassis have \(aqroot\(aq as UID 1, so if you can depend on that then setting the password is much quicker. Raises an error if the supplied password is greater than 20 chars. .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.create_user(username, password, permissions, users=None, host=None, admin_username=None, admin_password=None) Create user accounts .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.create_user [USERNAME] [PASSWORD] [PRIVILEGES] salt dell dracr.create_user diana secret login,test_alerts,clear_logs .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B DRAC Privileges .INDENT 7.0 .IP \(bu 2 login : Login to iDRAC .IP \(bu 2 drac : Configure iDRAC .IP \(bu 2 user_management : Configure Users .IP \(bu 2 clear_logs : Clear Logs .IP \(bu 2 server_control_commands : Execute Server Control Commands .IP \(bu 2 console_redirection : Access Console Redirection .IP \(bu 2 virtual_media : Access Virtual Media .IP \(bu 2 test_alerts : Test Alerts .IP \(bu 2 debug_commands : Execute Debug Commands .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.delete_user(username, uid=None, host=None, admin_username=None, admin_password=None) Delete a user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.delete_user [USERNAME] [UID \- optional] salt dell dracr.delete_user diana 4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.deploy_password(username, password, host=None, admin_username=None, admin_password=None, module=None) Change the QuickDeploy password, used for switches as well .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.deploy_password [USERNAME] [PASSWORD] host=<remote DRAC> admin_username=<DRAC user> admin_password=<DRAC PW> salt dell dracr.change_password diana secret .ft P .fi .UNINDENT .UNINDENT .sp Note that if only a username is specified then this module will look up details for all 16 possible DRAC users. This is time consuming, but might be necessary if one is not sure which user slot contains the one you want. Many late\-model Dell chassis have \(aqroot\(aq as UID 1, so if you can depend on that then setting the password is much quicker. .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.deploy_snmp(snmp, host=None, admin_username=None, admin_password=None, module=None) Change the QuickDeploy SNMP community string, used for switches as well .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.deploy_snmp SNMP_STRING host=<remote DRAC or CMC> admin_username=<DRAC user> admin_password=<DRAC PW> salt dell dracr.deploy_password diana secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.email_alerts(action, host=None, admin_username=None, admin_password=None) Enable/Disable email alerts .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.email_alerts True salt dell dracr.email_alerts False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.get_chassis_datacenter(host=None, admin_username=None, admin_password=None) Get the datacenter of the chassis. .INDENT 7.0 .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dracr.set_chassis_location host=111.222.333.444 admin_username=root admin_password=secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.get_chassis_location(host=None, admin_username=None, admin_password=None) Get the location of the chassis. .INDENT 7.0 .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dracr.set_chassis_location host=111.222.333.444 admin_username=root admin_password=secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.get_chassis_name(host=None, admin_username=None, admin_password=None) Get the name of a chassis. .INDENT 7.0 .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dracr.get_chassis_name host=111.222.333.444 admin_username=root admin_password=secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.get_dns_dracname(host=None, admin_username=None, admin_password=None) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.get_general(cfg_sec, cfg_var, host=None, admin_username=None, admin_password=None) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.get_slotname(slot, host=None, admin_username=None, admin_password=None) Get the name of a slot number in the chassis. .INDENT 7.0 .TP .B slot The number of the slot for which to obtain the name. .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local dracr.get_slotname 0 host=111.222.333.444 admin_username=root admin_password=secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.idrac_general(blade_name, command, idrac_password=None, host=None, admin_username=None, admin_password=None) Run a generic racadm command against a particular blade in a chassis. Blades are usually named things like \(aqserver\-1\(aq, \(aqserver\-2\(aq, etc. If the iDRAC has a different password than the CMC, then you can pass it with the idrac_password kwarg. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBblade_name\fP \-\- Name of the blade to run the command on .IP \(bu 2 \fBcommand\fP \-\- Command like to pass to racadm .IP \(bu 2 \fBidrac_password\fP \-\- Password for the iDRAC if different from the CMC .IP \(bu 2 \fBhost\fP \-\- Chassis hostname .IP \(bu 2 \fBadmin_username\fP \-\- CMC username .IP \(bu 2 \fBadmin_password\fP \-\- CMC password .UNINDENT .TP .B Returns stdout if the retcode is 0, otherwise a standard cmd.run_all dictionary .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt fx2 chassis.cmd idrac_general server\-1 \(aqget BIOS.SysProfileSettings\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.inventory(host=None, admin_username=None, admin_password=None) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.list_slotnames(host=None, admin_username=None, admin_password=None) List the names of all slots in the chassis. .INDENT 7.0 .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local dracr.list_slotnames host=111.222.333.444 admin_username=root admin_password=secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.list_users(host=None, admin_username=None, admin_password=None, module=None) List all DRAC users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.nameservers(ns, host=None, admin_username=None, admin_password=None, module=None) Configure the nameservers on the DRAC .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.nameservers [NAMESERVERS] salt dell dracr.nameservers ns1.example.com ns2.example.com admin_username=root admin_password=calvin module=server\-1 host=192.168.1.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.network_info(host=None, admin_username=None, admin_password=None, module=None) Return Network Configuration .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.network_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.server_hardreset(host=None, admin_username=None, admin_password=None, module=None) Performs a reset (reboot) operation on the managed server. .INDENT 7.0 .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .TP .B module The element to hard reset on the chassis such as a blade. If not provided, the chassis will be reset. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.server_hardreset salt dell dracr.server_hardreset module=server\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.server_power(status, host=None, admin_username=None, admin_password=None, module=None) .INDENT 7.0 .TP .B status One of \(aqpowerup\(aq, \(aqpowerdown\(aq, \(aqpowercycle\(aq, \(aqhardreset\(aq, \(aqgraceshutdown\(aq .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .TP .B module The element to reboot on the chassis such as a blade. If not provided, the chassis will be rebooted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.server_reboot salt dell dracr.server_reboot module=server\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.server_poweroff(host=None, admin_username=None, admin_password=None, module=None) Powers down the managed server. .INDENT 7.0 .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .TP .B module The element to power off on the chassis such as a blade. If not provided, the chassis will be powered off. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.server_poweroff salt dell dracr.server_poweroff module=server\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.server_poweron(host=None, admin_username=None, admin_password=None, module=None) Powers up the managed server. .INDENT 7.0 .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .TP .B module The element to power on located on the chassis such as a blade. If not provided, the chassis will be powered on. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.server_poweron salt dell dracr.server_poweron module=server\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.server_powerstatus(host=None, admin_username=None, admin_password=None, module=None) return the power status for the passed module .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell drac.server_powerstatus .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.server_pxe(host=None, admin_username=None, admin_password=None) Configure server to PXE perform a one off PXE boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.server_pxe .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.server_reboot(host=None, admin_username=None, admin_password=None, module=None) Issues a power\-cycle operation on the managed server. This action is similar to pressing the power button on the system\(aqs front panel to power down and then power up the system. .INDENT 7.0 .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .TP .B module The element to reboot on the chassis such as a blade. If not provided, the chassis will be rebooted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.server_reboot salt dell dracr.server_reboot module=server\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.set_chassis_datacenter(location, host=None, admin_username=None, admin_password=None) Set the location of the chassis. .INDENT 7.0 .TP .B location The name of the datacenter to be set on the chassis. .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dracr.set_chassis_datacenter datacenter\-name host=111.222.333.444 admin_username=root admin_password=secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.set_chassis_location(location, host=None, admin_username=None, admin_password=None) Set the location of the chassis. .INDENT 7.0 .TP .B location The name of the location to be set on the chassis. .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dracr.set_chassis_location location\-name host=111.222.333.444 admin_username=root admin_password=secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.set_chassis_name(name, host=None, admin_username=None, admin_password=None) Set the name of the chassis. .INDENT 7.0 .TP .B name The name to be set on the chassis. .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dracr.set_chassis_name my\-chassis host=111.222.333.444 admin_username=root admin_password=secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.set_dns_dracname(name, host=None, admin_username=None, admin_password=None) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.set_general(cfg_sec, cfg_var, val, host=None, admin_username=None, admin_password=None) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.set_network(ip, netmask, gateway, host=None, admin_username=None, admin_password=None) Configure Network on the CMC or individual iDRAC. Use \fBset_niccfg\fP for blade and switch addresses. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.set_network [DRAC IP] [NETMASK] [GATEWAY] salt dell dracr.set_network 192.168.0.2 255.255.255.0 192.168.0.1 admin_username=root admin_password=calvin host=192.168.1.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.set_niccfg(ip=None, netmask=None, gateway=None, dhcp=False, host=None, admin_username=None, admin_password=None, module=None) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.set_nicvlan(vlan=None, host=None, admin_username=None, admin_password=None, module=None) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.set_permissions(username, permissions, uid=None, host=None, admin_username=None, admin_password=None) Configure users permissions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.set_permissions [USERNAME] [PRIVILEGES] [USER INDEX \- optional] salt dell dracr.set_permissions diana login,test_alerts,clear_logs 4 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B DRAC Privileges .INDENT 7.0 .IP \(bu 2 login : Login to iDRAC .IP \(bu 2 drac : Configure iDRAC .IP \(bu 2 user_management : Configure Users .IP \(bu 2 clear_logs : Clear Logs .IP \(bu 2 server_control_commands : Execute Server Control Commands .IP \(bu 2 console_redirection : Access Console Redirection .IP \(bu 2 virtual_media : Access Virtual Media .IP \(bu 2 test_alerts : Test Alerts .IP \(bu 2 debug_commands : Execute Debug Commands .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.set_slotname(slot, name, host=None, admin_username=None, admin_password=None) Set the name of a slot in a chassis. .INDENT 7.0 .TP .B slot The slot number to change. .TP .B name The name to set. Can only be 15 characters long. .TP .B host The chassis host. .TP .B admin_username The username used to access the chassis. .TP .B admin_password The password used to access the chassis. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dracr.set_slotname 2 my\-slotname host=111.222.333.444 admin_username=root admin_password=secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.set_snmp(community, host=None, admin_username=None, admin_password=None) Configure CMC or individual iDRAC SNMP community string. Use \fBdeploy_snmp\fP for configuring chassis switch SNMP. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.set_snmp [COMMUNITY] salt dell dracr.set_snmp public .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.syslog(server, enable=True, host=None, admin_username=None, admin_password=None, module=None) Configure syslog remote logging, by default syslog will automatically be enabled if a server is specified. However, if you want to disable syslog you will need to specify a server followed by False .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.syslog [SYSLOG IP] [ENABLE/DISABLE] salt dell dracr.syslog 0.0.0.0 False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.system_info(host=None, admin_username=None, admin_password=None, module=None) Return System information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.system_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.update_firmware(filename, host=None, admin_username=None, admin_password=None) Updates firmware using local firmware file .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.update_firmware firmware.exe .ft P .fi .UNINDENT .UNINDENT .sp This executes the following command on your FX2 (using username and password stored in the pillar data) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C racadm update –f firmware.exe \-u user –p pass .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dracr.update_firmware_nfs_or_cifs(filename, share, host=None, admin_username=None, admin_password=None) Executes the following for CIFS (using username and password stored in the pillar data) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C racadm update \-f <updatefile> \-u user –p pass \-l //IP\-Address/share .ft P .fi .UNINDENT .UNINDENT .sp Or for NFS (using username and password stored in the pillar data) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C racadm update \-f <updatefile> \-u user –p pass \-l IP\-address:/share .ft P .fi .UNINDENT .UNINDENT .sp Salt command for CIFS: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.update_firmware_nfs_or_cifs firmware.exe //IP\-Address/share .ft P .fi .UNINDENT .UNINDENT .sp Salt command for NFS: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dell dracr.update_firmware_nfs_or_cifs firmware.exe IP\-address:/share .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.drbd .sp DRBD administration module .INDENT 0.0 .TP .B salt.modules.drbd.overview() Show status of the DRBD devices, support two nodes only. drbd\-overview is removed since drbd\-utils\-9.6.0, use status instead. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq drbd.overview .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.drbd.status(name=\(aqall\(aq) Using drbdadm to show status of the DRBD devices, available in the latest drbd9. Support multiple nodes, multiple volumes. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- Resource name. .TP .B Returns drbd status of resource. .TP .B Return type \fI\%list\fP(\fI\%dict\fP(res)) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq drbd.status salt \(aq*\(aq drbd.status name=<resource name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dummyproxy_pkg .sp Package support for the dummy proxy used by the test suite .INDENT 0.0 .TP .B salt.modules.dummyproxy_pkg.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dummyproxy_pkg.installed(name, version=None, refresh=False, fromrepo=None, skip_verify=False, pkgs=None, sources=None, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dummyproxy_pkg.list_pkgs(versions_as_list=False, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dummyproxy_pkg.remove(name=None, pkgs=None, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dummyproxy_pkg.upgrade(name=None, pkgs=None, refresh=True, skip_verify=True, normalize=True, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.dummyproxy_pkg.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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dummyproxy_service .sp Provide the service module for the dummy proxy used in integration tests .INDENT 0.0 .TP .B salt.modules.dummyproxy_service.enabled(name, sig=None) Only the \(aqredbull\(aq service is \(aqenabled\(aq in the test .sp New in version 2016.11.3. .UNINDENT .INDENT 0.0 .TP .B salt.modules.dummyproxy_service.get_all() Return a list of all available services .sp New in version 2016.11.3. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dummyproxy_service.list_() Return a list of all available services. .sp New in version 2016.11.3. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dummyproxy_service.restart(name, sig=None) Restart the specified service with dummy. .sp New in version 2016.11.3. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dummyproxy_service.running(name, sig=None) Return whether this service is running. .sp New in version 2016.11.3. .UNINDENT .INDENT 0.0 .TP .B salt.modules.dummyproxy_service.start(name, sig=None) Start the specified service on the dummy .sp New in version 2016.11.3. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dummyproxy_service.status(name, sig=None) Return the status for a service via dummy, returns a bool whether the service is running. .sp New in version 2016.11.3. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dummyproxy_service.stop(name, sig=None) Stop the specified service on the dummy .sp New in version 2016.11.3. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ebuildpkg .sp Support for Portage .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B optdepends .INDENT 7.0 .IP \(bu 2 portage Python adapter .UNINDENT .UNINDENT .sp For now all package names \fIMUST\fP include the package category, i.e. \fB\(aqvim\(aq\fP will not work, \fB\(aqapp\-editors/vim\(aq\fP will. .INDENT 0.0 .TP .B salt.modules.ebuildpkg.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 CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.check_db(*names, **kwargs) New in version 0.17.0. .sp Returns a dict containing the following information for each specified package: .INDENT 7.0 .IP 1. 3 A key \fBfound\fP, which will be a boolean value denoting if a match was found in the package database. .IP 2. 3 If \fBfound\fP is \fBFalse\fP, then a second key called \fBsuggestions\fP will be present, which will contain a list of possible matches. This list will be empty if the package name was specified in \fBcategory/pkgname\fP format, since the suggestions are only intended to disambiguate ambiguous package names (ones submitted without a category). .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.check_db <package1> <package2> <package3> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.check_extra_requirements(pkgname, pkgver) Check if the installed package already has the given requirements. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.check_extra_requirements \(aqsys\-devel/gcc\(aq \(aq~>4.1.2:4.1::gentoo[nls,fortran]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.depclean(name=None, slot=None, fromrepo=None, pkgs=None) Portage has a function to remove unused dependencies. If a package is provided, it will only removed the package if no other package depends on it. .INDENT 7.0 .TP .B name The name of the package to be cleaned. .TP .B slot Restrict the remove to a specific slot. Ignored if \fBname\fP is None. .TP .B fromrepo Restrict the remove to a specific slot. Ignored if \fBname\fP is None. .TP .B pkgs Clean multiple packages. \fBslot\fP and \fBfromrepo\fP arguments are ignored if this argument is present. Must be passed as a python list. .UNINDENT .sp Return a list containing the removed packages: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.depclean <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.ex_mod_init(low) If the config option \fBebuild.enforce_nice_config\fP is set to True, this module will enforce a nice tree structure for /etc/portage/package.* configuration files. .sp New in version 0.17.0: Initial automatic enforcement added when pkg is used on a Gentoo system. .sp Changed in version 2014.7.0: Configure option added to make this behaviour optional, defaulting to off. .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 \fBebuild.ex_mod_init\fP is called automatically when a state invokes a pkg state on a Gentoo system. \fBsalt.states.pkg.mod_init()\fP .sp \fBebuild.ex_mod_init\fP uses \fBportage_config.enforce_nice_config\fP to do the lifting. \fI\%salt.modules.portage_config.enforce_nice_config()\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.ex_mod_init .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.install(name=None, refresh=False, pkgs=None, sources=None, slot=None, fromrepo=None, uses=None, binhost=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 emerge 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Install the passed package(s), add refresh=True to sync the portage tree before package is installed. .INDENT 7.0 .TP .B name The name of the package to be installed. Note that this parameter is ignored if either \(dqpkgs\(dq or \(dqsources\(dq is passed. Additionally, please note that this option can only be used to emerge a package from the portage tree. To install a tbz2 package manually, use the \(dqsources\(dq option described below. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B refresh Whether or not to sync the portage tree before installing. .TP .B version Install a specific version of the package, e.g. 1.0.9\-r1. Ignored if \(dqpkgs\(dq or \(dqsources\(dq is passed. .TP .B slot Similar to version, but specifies a valid slot to be installed. It will install the latest available version in the specified slot. Ignored if \(dqpkgs\(dq or \(dqsources\(dq or \(dqversion\(dq is passed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sys\-devel/gcc slot=\(aq4.4\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B fromrepo Similar to slot, but specifies the repository from the package will be installed. It will install the latest available version in the specified repository. Ignored if \(dqpkgs\(dq or \(dqsources\(dq or \(dqversion\(dq is passed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install salt fromrepo=\(aqgentoo\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B uses Similar to slot, but specifies a list of use flag. Ignored if \(dqpkgs\(dq or \(dqsources\(dq or \(dqversion\(dq is passed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sys\-devel/gcc uses=\(aq[\(dqnptl\(dq,\(dq\-nossp\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of packages to install from the portage tree. Must be passed as a python list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq,\(dqbar\(dq,\(dq~category/package:slot::repository[use]\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B sources A list of tbz2 packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sources=\(aq[{\(dqfoo\(dq: \(dqsalt://foo.tbz2\(dq},{\(dqbar\(dq: \(dqsalt://bar.tbz2\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B binhost has two options try and force. try \- tells emerge to try and install the package from a configured binhost. force \- forces emerge to install the package from a binhost otherwise it fails out. .UNINDENT .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.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 CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.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<package_name>\(aq: \(aq<version>\(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.ebuildpkg.list_upgrades(refresh=True, backtrack=3, **kwargs) List all available package upgrades. .INDENT 7.0 .TP .B refresh Whether or not to sync the portage tree before checking for upgrades. .TP .B backtrack Specifies an integer number of times to backtrack if dependency calculation fails due to a conflict or an unsatisfied dependency (default: \'3\'). .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.list_upgrades .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.porttree_matches(name) Returns a list containing the matches for a given package name from the portage tree. Note that the specific version of the package will not be provided for packages that have several versions in the portage tree, but rather the name of the package (i.e. \(dqdev\-python/paramiko\(dq). .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.purge(name=None, slot=None, fromrepo=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 emerge 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Portage does not have a purge, this function calls remove followed by depclean to emulate a purge process .INDENT 7.0 .TP .B name The name of the package to be deleted. .TP .B slot Restrict the remove to a specific slot. Ignored if name is None. .TP .B fromrepo Restrict the remove to a specific slot. Ignored if \fBname\fP is None. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs Uninstall multiple packages. \fBslot\fP and \fBfromrepo\fP arguments are ignored if this argument is present. Must be passed as a python list. .UNINDENT .sp New in version 0.16.0. .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.purge <package name> salt \(aq*\(aq pkg.purge <package name> slot=4.4 salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3> salt \(aq*\(aq pkg.purge pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.refresh_db(**kwargs) Update the portage tree using the first available method from the following list: .INDENT 7.0 .IP \(bu 2 emaint sync .IP \(bu 2 eix\-sync .IP \(bu 2 emerge\-webrsync .IP \(bu 2 emerge \-\-sync .UNINDENT .sp To prevent the portage tree from being synced within one day of the previous sync, add the following pillar data for this minion: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C portage: sync_wait_one_day: True .ft P .fi .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.ebuildpkg.remove(name=None, slot=None, fromrepo=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 emerge 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Remove packages via emerge \-\-unmerge. .INDENT 7.0 .TP .B name The name of the package to be deleted. .TP .B slot Restrict the remove to a specific slot. Ignored if \fBname\fP is None. .TP .B fromrepo Restrict the remove to a specific slot. Ignored if \fBname\fP is None. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs Uninstall multiple packages. \fBslot\fP and \fBfromrepo\fP arguments are ignored if this argument is present. Must be passed as a python list. .UNINDENT .sp New in version 0.16.0. .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> salt \(aq*\(aq pkg.remove <package name> slot=4.4 fromrepo=gentoo salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.update(pkg, slot=None, fromrepo=None, refresh=False, binhost=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 emerge 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Updates the passed package (emerge \-\-update package) .INDENT 7.0 .TP .B slot Restrict the update to a particular slot. It will update to the latest version within the slot. .TP .B fromrepo Restrict the update to a particular repository. It will update to the latest version within the repository. .TP .B binhost has two options try and force. try \- tells emerge to try and install the package from a configured binhost. force \- forces emerge to install the package from a binhost otherwise it fails out. .UNINDENT .sp Return a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.update <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.upgrade(refresh=True, binhost=None, backtrack=3, **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 emerge 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Run a full system upgrade (emerge \-uDN @world) .INDENT 7.0 .TP .B binhost has two options try and force. try \- tells emerge to try and install the package from a configured binhost. force \- forces emerge to install the package from a binhost otherwise it fails out. .TP .B backtrack Specifies an integer number of times to backtrack if dependency calculation fails due to a conflict or an unsatisfied dependency (default: \'3\'). .sp New in version 2015.8.0. .UNINDENT .sp Returns a dictionary containing the changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.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 <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.version_clean(version) Clean the version string removing extra data. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version_clean <version_string> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuildpkg.version_cmp(pkg1, pkg2, **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. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.eix .sp Support for Eix .INDENT 0.0 .TP .B salt.modules.eix.sync() Sync portage/overlay trees and update the eix database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eix.sync .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.eix.update() Update the eix database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eix.update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.elasticsearch .sp Elasticsearch \- A distributed RESTful search and analytics server .sp Module to provide Elasticsearch compatibility to Salt (compatible with Elasticsearch version 1.5.2+) .sp New in version 2015.8.0. .INDENT 0.0 .TP .B depends \fI\%elasticsearch\-py\fP .TP .B configuration This module accepts connection configuration details either as parameters or as configuration settings in /etc/salt/minion on the relevant minions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C elasticsearch: host: \(aq10.10.10.100:9200\(aq elasticsearch\-cluster: hosts: \- \(aq10.10.10.100:9200\(aq \- \(aq10.10.10.101:9200\(aq \- \(aq10.10.10.102:9200\(aq elasticsearch\-extra: hosts: \- \(aq10.10.10.100:9200\(aq use_ssl: True verify_certs: True ca_certs: /path/to/custom_ca_bundle.pem number_of_shards: 1 number_of_replicas: 0 functions_blacklist: \- \(aqsaltutil.find_job\(aq \- \(aqpillar.items\(aq \- \(aqgrains.items\(aq proxies: \- http: http://proxy:3128 \- https: http://proxy:1080 .ft P .fi .UNINDENT .UNINDENT .sp When specifying proxies the requests backend will be used and the \(aqproxies\(aq data structure is passed as\-is to that module. .sp This data can also be passed into pillar. Options passed into opts will overwrite options passed into pillar. .sp Some functionality might be limited by elasticsearch\-py and Elasticsearch server versions. .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.alias_create(indices, alias, hosts=None, body=None, profile=None, source=None) Create an alias for a specific index/indices .INDENT 7.0 .TP .B indices Single or multiple indices separated by comma, use _all to perform the operation on all indices. .TP .B alias Alias name .TP .B body Optional definition such as routing or filter as defined in \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/indices\-aliases.html\fP .TP .B source URL of file specifying optional definition such as routing or filter. Cannot be used in combination with \fBbody\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.alias_create testindex_v1 testindex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.alias_delete(indices, aliases, hosts=None, body=None, profile=None, source=None) Delete an alias of an index .INDENT 7.0 .TP .B indices Single or multiple indices separated by comma, use _all to perform the operation on all indices. .TP .B aliases Alias names separated by comma .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.alias_delete testindex_v1 testindex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.alias_exists(aliases, indices=None, hosts=None, profile=None) Return a boolean indicating whether given alias exists .INDENT 7.0 .TP .B indices Single or multiple indices separated by comma, use _all to perform the operation on all indices. .TP .B aliases Alias names separated by comma .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.alias_exists None testindex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.alias_get(indices=None, aliases=None, hosts=None, profile=None) Check for the existence of an alias and if it exists, return it .INDENT 7.0 .TP .B indices Single or multiple indices separated by comma, use _all to perform the operation on all indices. .TP .B aliases Alias names separated by comma .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.alias_get testindex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.cluster_get_settings(flat_settings=False, include_defaults=False, hosts=None, profile=None) New in version 3000. .sp Return Elasticsearch cluster settings. .INDENT 7.0 .TP .B flat_settings Return settings in flat format. .TP .B include_defaults Whether to return all default clusters setting. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.cluster_get_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.cluster_health(index=None, level=\(aqcluster\(aq, local=False, hosts=None, profile=None) New in version 2017.7.0. .sp Return Elasticsearch cluster health. .INDENT 7.0 .TP .B index Limit the information returned to a specific index .TP .B level Specify the level of detail for returned information, default \(aqcluster\(aq, valid choices are: \(aqcluster\(aq, \(aqindices\(aq, \(aqshards\(aq .TP .B local Return local information, do not retrieve the state from master node .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.cluster_health .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.cluster_put_settings(body=None, flat_settings=False, hosts=None, profile=None) New in version 3000. .sp Set Elasticsearch cluster settings. .INDENT 7.0 .TP .B body The settings to be updated. Can be either \(aqtransient\(aq or \(aqpersistent\(aq (survives cluster restart) \fI\%http://www.elastic.co/guide/en/elasticsearch/reference/current/cluster\-update\-settings.html\fP .TP .B flat_settings Return settings in flat format. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.cluster_put_settings \(aq{\(dqpersistent\(dq: {\(dqindices.recovery.max_bytes_per_sec\(dq: \(dq50mb\(dq}}\(aq salt myminion elasticsearch.cluster_put_settings \(aq{\(dqtransient\(dq: {\(dqindices.recovery.max_bytes_per_sec\(dq: \(dq50mb\(dq}}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.cluster_stats(nodes=None, hosts=None, profile=None) New in version 2017.7.0. .sp Return Elasticsearch cluster stats. .INDENT 7.0 .TP .B nodes List of cluster nodes (id or name) to display stats for. Use _local for connected node, empty for all .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.cluster_stats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.document_create(index, doc_type, body=None, id=None, hosts=None, profile=None, source=None) Create a document in a specified index .INDENT 7.0 .TP .B index Index name where the document should reside .TP .B doc_type Type of the document .TP .B body Document to store .TP .B source URL of file specifying document to store. Cannot be used in combination with \fBbody\fP\&. .TP .B id Optional unique document identifier for specified doc_type (empty for random) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.document_create testindex doctype1 \(aq{}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.document_delete(index, doc_type, id, hosts=None, profile=None) Delete a document from an index .INDENT 7.0 .TP .B index Index name where the document resides .TP .B doc_type Type of the document .TP .B id Document identifier .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.document_delete testindex doctype1 AUx\-384m0Bug_8U80wQZ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.document_exists(index, id, doc_type=\(aq_all\(aq, hosts=None, profile=None) Return a boolean indicating whether given document exists .INDENT 7.0 .TP .B index Index name where the document resides .TP .B id Document identifier .TP .B doc_type Type of the document, use _all to fetch the first document matching the ID across all types .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.document_exists testindex AUx\-384m0Bug_8U80wQZ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.document_get(index, id, doc_type=\(aq_all\(aq, hosts=None, profile=None) Check for the existence of a document and if it exists, return it .INDENT 7.0 .TP .B index Index name where the document resides .TP .B id Document identifier .TP .B doc_type Type of the document, use _all to fetch the first document matching the ID across all types .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.document_get testindex AUx\-384m0Bug_8U80wQZ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.flush_synced(hosts=None, profile=None, **kwargs) New in version 3000. .sp Perform a normal flush, then add a generated unique marker (sync_id) to all shards. \fI\%http://www.elastic.co/guide/en/elasticsearch/reference/current/indices\-synced\-flush.html\fP .INDENT 7.0 .TP .B index (Optional, string) A comma\-separated list of index names; use _all or empty string for all indices. Defaults to \(aq_all\(aq. .TP .B ignore_unavailable (Optional, boolean) If true, missing or closed indices are not included in the response. Defaults to false. .TP .B allow_no_indices (Optional, boolean) If true, the request does not return an error if a wildcard expression or _all value retrieves only missing or closed indices. This parameter also applies to index aliases that point to a missing or closed index. .TP .B expand_wildcards (Optional, string) Controls what kind of indices that wildcard expressions can expand to. .sp Valid values are: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C all \- Expand to open and closed indices. open \- Expand only to open indices. closed \- Expand only to closed indices. none \- Wildcard expressions are not accepted. .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp The defaults settings for the above parameters depend on the API being used. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.flush_synced index=\(aqindex1,index2\(aq ignore_unavailable=True allow_no_indices=True expand_wildcards=\(aqall\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.index_close(index, allow_no_indices=True, expand_wildcards=\(aqopen\(aq, ignore_unavailable=True, hosts=None, profile=None) New in version 2017.7.0. .sp Close specified index. .INDENT 7.0 .TP .B index Index to be closed .TP .B allow_no_indices Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified) .TP .B expand_wildcards Whether to expand wildcard expression to concrete indices that are open, closed or both., default ‘open’, valid choices are: ‘open’, ‘closed’, ‘none’, ‘all’ .TP .B ignore_unavailable Whether specified concrete indices should be ignored when unavailable (missing or closed) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.index_close testindex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.index_create(index, body=None, hosts=None, profile=None, source=None) Create an index .INDENT 7.0 .TP .B index Index name .TP .B body Index definition, such as settings and mappings as defined in \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/indices\-create\-index.html\fP .TP .B source URL to file specifying index definition. Cannot be used in combination with \fBbody\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.index_create testindex salt myminion elasticsearch.index_create testindex2 \(aq{\(dqsettings\(dq : {\(dqindex\(dq : {\(dqnumber_of_shards\(dq : 3, \(dqnumber_of_replicas\(dq : 2}}}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.index_delete(index, hosts=None, profile=None) Delete an index .INDENT 7.0 .TP .B index Index name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.index_delete testindex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.index_exists(index, hosts=None, profile=None) Return a boolean indicating whether given index exists .INDENT 7.0 .TP .B index Index name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.index_exists testindex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.index_get(index, hosts=None, profile=None) Check for the existence of an index and if it exists, return it .INDENT 7.0 .TP .B index Index name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.index_get testindex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.index_get_settings(hosts=None, profile=None, **kwargs) New in version 3000. .sp Check for the existence of an index and if it exists, return its settings \fI\%http://www.elastic.co/guide/en/elasticsearch/reference/current/indices\-get\-settings.html\fP .INDENT 7.0 .TP .B index (Optional, string) A comma\-separated list of index names; use _all or empty string for all indices. Defaults to \(aq_all\(aq. .TP .B name (Optional, string) The name of the settings that should be included .TP .B allow_no_indices (Optional, boolean) Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified) .TP .B expand_wildcards (Optional, string) Whether to expand wildcard expression to concrete indices that are open, closed or both. Valid choices are: ‘open’, ‘closed’, ‘none’, ‘all’ .TP .B flat_settings (Optional, boolean) Return settings in flat format .TP .B ignore_unavailable (Optional, boolean) Whether specified concrete indices should be ignored when unavailable (missing or closed) .TP .B include_defaults (Optional, boolean) Whether to return all default setting for each of the indices. .TP .B local (Optional, boolean) Return local information, do not retrieve the state from master node .UNINDENT .sp The defaults settings for the above parameters depend on the API version being used. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.index_get_settings index=testindex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.index_open(index, allow_no_indices=True, expand_wildcards=\(aqclosed\(aq, ignore_unavailable=True, hosts=None, profile=None) New in version 2017.7.0. .sp Open specified index. .INDENT 7.0 .TP .B index Index to be opened .TP .B allow_no_indices Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified) .TP .B expand_wildcards Whether to expand wildcard expression to concrete indices that are open, closed or both., default ‘closed’, valid choices are: ‘open’, ‘closed’, ‘none’, ‘all’ .TP .B ignore_unavailable Whether specified concrete indices should be ignored when unavailable (missing or closed) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.index_open testindex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.index_put_settings(body=None, hosts=None, profile=None, source=None, **kwargs) New in version 3000. .sp Update existing index settings \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/indices\-update\-settings.html\fP .INDENT 7.0 .TP .B body The index settings to be updated. .TP .B source URL to file specifying index definition. Cannot be used in combination with \fBbody\fP\&. .TP .B index (Optional, string) A comma\-separated list of index names; use _all or empty string to perform the operation on all indices .TP .B allow_no_indices (Optional, boolean) Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified) .TP .B expand_wildcards (Optional, string) Whether to expand wildcard expression to concrete indices that are open, closed or both. Valid choices are: ‘open’, ‘closed’, ‘none’, ‘all’ .TP .B flat_settings (Optional, boolean) Return settings in flat format (default: false) .TP .B ignore_unavailable (Optional, boolean) Whether specified concrete indices should be ignored when unavailable (missing or closed) .TP .B master_timeout (Optional, time units) Explicit operation timeout for connection to master node .TP .B preserve_existing (Optional, boolean) Whether to update existing settings. If set to true existing settings on an index remain unchanged, the default is false .UNINDENT .sp The defaults settings for the above parameters depend on the API version being used. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Elasticsearch time units can be found here: \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/common\-options.html#time\-units\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.index_put_settings index=testindex body=\(aq{\(dqsettings\(dq : {\(dqindex\(dq : {\(dqnumber_of_replicas\(dq : 2}}}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.index_template_create(name, body=None, hosts=None, profile=None, source=None) Create an index template .INDENT 7.0 .TP .B name Index template name .TP .B body Template definition as specified in \fI\%http://www.elastic.co/guide/en/elasticsearch/reference/current/indices\-templates.html\fP .TP .B source URL to file specifying template definition. Cannot be used in combination with \fBbody\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.index_template_create testindex_templ \(aq{ \(dqtemplate\(dq: \(dqlogstash\-*\(dq, \(dqorder\(dq: 1, \(dqsettings\(dq: { \(dqnumber_of_shards\(dq: 1 } }\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.index_template_delete(name, hosts=None, profile=None) Delete an index template (type) along with its data .INDENT 7.0 .TP .B name Index template name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.index_template_delete testindex_templ user .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.index_template_exists(name, hosts=None, profile=None) Return a boolean indicating whether given index template exists .INDENT 7.0 .TP .B name Index template name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.index_template_exists testindex_templ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.index_template_get(name, hosts=None, profile=None) Retrieve template definition of index or index/type .INDENT 7.0 .TP .B name Index template name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.index_template_get testindex_templ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.info(hosts=None, profile=None) New in version 2017.7.0. .sp Return Elasticsearch information. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.info salt myminion elasticsearch.info profile=elasticsearch\-extra .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.mapping_create(index, doc_type, body=None, hosts=None, profile=None, source=None) Create a mapping in a given index .INDENT 7.0 .TP .B index Index for the mapping .TP .B doc_type Name of the document type .TP .B body Mapping definition as specified in \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/indices\-put\-mapping.html\fP .TP .B source URL to file specifying mapping definition. Cannot be used in combination with \fBbody\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.mapping_create testindex user \(aq{ \(dquser\(dq : { \(dqproperties\(dq : { \(dqmessage\(dq : {\(dqtype\(dq : \(dqstring\(dq, \(dqstore\(dq : true } } } }\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.mapping_delete(index, doc_type, hosts=None, profile=None) Delete a mapping (type) along with its data. As of Elasticsearch 5.0 this is no longer available. .INDENT 7.0 .TP .B index Index for the mapping .TP .B doc_type Name of the document type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.mapping_delete testindex user .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.mapping_get(index, doc_type, hosts=None, profile=None) Retrieve mapping definition of index or index/type .INDENT 7.0 .TP .B index Index for the mapping .TP .B doc_type Name of the document type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.mapping_get testindex user .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.node_info(nodes=None, flat_settings=False, hosts=None, profile=None) New in version 2017.7.0. .sp Return Elasticsearch node information. .INDENT 7.0 .TP .B nodes List of cluster nodes (id or name) to display stats for. Use _local for connected node, empty for all .TP .B flat_settings Flatten settings keys .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.node_info flat_settings=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.ping(allow_failure=False, hosts=None, profile=None) New in version 2017.7.0. .sp Test connection to Elasticsearch instance. This method does not fail if not explicitly specified. .INDENT 7.0 .TP .B allow_failure Throw exception if ping fails .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.ping allow_failure=True salt myminion elasticsearch.ping profile=elasticsearch\-extra .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.pipeline_create(id, body, hosts=None, profile=None) New in version 2017.7.0. .sp Create Ingest pipeline by supplied definition. Available since Elasticsearch 5.0. .INDENT 7.0 .TP .B id Pipeline id .TP .B body Pipeline definition as specified in \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/master/pipeline.html\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.pipeline_create mypipeline \(aq{\(dqdescription\(dq: \(dqmy custom pipeline\(dq, \(dqprocessors\(dq: [{\(dqset\(dq : {\(dqfield\(dq: \(dqcollector_timestamp_millis\(dq, \(dqvalue\(dq: \(dq{{_ingest.timestamp}}\(dq}}]}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.pipeline_delete(id, hosts=None, profile=None) New in version 2017.7.0. .sp Delete Ingest pipeline. Available since Elasticsearch 5.0. .INDENT 7.0 .TP .B id Pipeline id .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.pipeline_delete mypipeline .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.pipeline_get(id, hosts=None, profile=None) New in version 2017.7.0. .sp Retrieve Ingest pipeline definition. Available since Elasticsearch 5.0. .INDENT 7.0 .TP .B id Pipeline id .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.pipeline_get mypipeline .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.pipeline_simulate(id, body, verbose=False, hosts=None, profile=None) New in version 2017.7.0. .sp Simulate existing Ingest pipeline on provided data. Available since Elasticsearch 5.0. .INDENT 7.0 .TP .B id Pipeline id .TP .B body Pipeline definition as specified in \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/master/pipeline.html\fP .TP .B verbose Specify if the output should be more verbose .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.pipeline_simulate mypipeline \(aq{\(dqdocs\(dq:[{\(dq_index\(dq:\(dqindex\(dq,\(dq_type\(dq:\(dqtype\(dq,\(dq_id\(dq:\(dqid\(dq,\(dq_source\(dq:{\(dqfoo\(dq:\(dqbar\(dq}},{\(dq_index\(dq:\(dqindex\(dq,\(dq_type\(dq:\(dqtype\(dq,\(dq_id\(dq:\(dqid\(dq,\(dq_source\(dq:{\(dqfoo\(dq:\(dqrab\(dq}}]}\(aq verbose=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.repository_create(name, body, hosts=None, profile=None) New in version 2017.7.0. .sp Create repository for storing snapshots. Note that shared repository paths have to be specified in path.repo Elasticsearch configuration option. .INDENT 7.0 .TP .B name Repository name .TP .B body Repository definition as in \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/modules\-snapshots.html\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.repository_create testrepo \(aq{\(dqtype\(dq:\(dqfs\(dq,\(dqsettings\(dq:{\(dqlocation\(dq:\(dq/tmp/test\(dq,\(dqcompress\(dq:true}}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.repository_delete(name, hosts=None, profile=None) New in version 2017.7.0. .sp Delete existing repository. .INDENT 7.0 .TP .B name Repository name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.repository_delete testrepo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.repository_get(name, local=False, hosts=None, profile=None) New in version 2017.7.0. .sp Get existing repository details. .INDENT 7.0 .TP .B name Repository name .TP .B local Retrieve only local information, default is false .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.repository_get testrepo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.repository_verify(name, hosts=None, profile=None) New in version 2017.7.0. .sp Obtain list of cluster nodes which successfully verified this repository. .INDENT 7.0 .TP .B name Repository name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.repository_verify testrepo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.search_template_create(id, body, hosts=None, profile=None) New in version 2017.7.0. .sp Create search template by supplied definition .INDENT 7.0 .TP .B id Template ID .TP .B body Search template definition .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.search_template_create mytemplate \(aq{\(dqtemplate\(dq:{\(dqquery\(dq:{\(dqmatch\(dq:{\(dqtitle\(dq:\(dq{{query_string}}\(dq}}}}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.search_template_delete(id, hosts=None, profile=None) New in version 2017.7.0. .sp Delete existing search template definition. .INDENT 7.0 .TP .B id Template ID .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.search_template_delete mytemplate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.search_template_get(id, hosts=None, profile=None) New in version 2017.7.0. .sp Obtain existing search template definition. .INDENT 7.0 .TP .B id Template ID .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.search_template_get mytemplate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.snapshot_create(repository, snapshot, body=None, hosts=None, profile=None) New in version 2017.7.0. .sp Create snapshot in specified repository by supplied definition. .INDENT 7.0 .TP .B repository Repository name .TP .B snapshot Snapshot name .TP .B body Snapshot definition as in \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/modules\-snapshots.html\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.snapshot_create testrepo testsnapshot \(aq{\(dqindices\(dq:\(dqindex_1,index_2\(dq,\(dqignore_unavailable\(dq:true,\(dqinclude_global_state\(dq:false}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.snapshot_delete(repository, snapshot, hosts=None, profile=None) New in version 2017.7.0. .sp Delete snapshot from specified repository. .INDENT 7.0 .TP .B repository Repository name .TP .B snapshot Snapshot name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.snapshot_delete testrepo testsnapshot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.snapshot_get(repository, snapshot, ignore_unavailable=False, hosts=None, profile=None) New in version 2017.7.0. .sp Obtain snapshot residing in specified repository. .INDENT 7.0 .TP .B repository Repository name .TP .B snapshot Snapshot name, use _all to obtain all snapshots in specified repository .TP .B ignore_unavailable Ignore unavailable snapshots .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.snapshot_get testrepo testsnapshot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.snapshot_restore(repository, snapshot, body=None, hosts=None, profile=None) New in version 2017.7.0. .sp Restore existing snapshot in specified repository by supplied definition. .INDENT 7.0 .TP .B repository Repository name .TP .B snapshot Snapshot name .TP .B body Restore definition as in \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/modules\-snapshots.html\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.snapshot_restore testrepo testsnapshot \(aq{\(dqindices\(dq:\(dqindex_1,index_2\(dq,\(dqignore_unavailable\(dq:true,\(dqinclude_global_state\(dq:true}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.elasticsearch.snapshot_status(repository=None, snapshot=None, ignore_unavailable=False, hosts=None, profile=None) New in version 2017.7.0. .sp Obtain status of all currently running snapshots. .INDENT 7.0 .TP .B repository Particular repository to look for snapshots .TP .B snapshot Snapshot name .TP .B ignore_unavailable Ignore unavailable snapshots .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion elasticsearch.snapshot_status ignore_unavailable=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.environ .sp Support for getting and setting the environment variables of the current salt process. .INDENT 0.0 .TP .B salt.modules.environ.get(key, default=\(aq\(aq) Get a single salt process environment variable. .INDENT 7.0 .TP .B key String used as the key for environment lookup. .TP .B default If the key is not found in the environment, return this value. Default: \(aq\(aq .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq environ.get foo salt \(aq*\(aq environ.get baz default=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.environ.has_value(key, value=None) Determine whether the key exists in the current salt process environment dictionary. Optionally compare the current value of the environment against the supplied value string. .INDENT 7.0 .TP .B key Must be a string. Used as key for environment lookup. .TP .B value: Optional. If key exists in the environment, compare the current value with this value. Return True if they are equal. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq environ.has_value foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.environ.item(keys, default=\(aq\(aq) Get one or more salt process environment variables. Returns a dict. .INDENT 7.0 .TP .B keys Either a string or a list of strings that will be used as the keys for environment lookup. .TP .B default If the key is not found in the environment, return this value. Default: \(aq\(aq .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq environ.item foo salt \(aq*\(aq environ.item \(aq[foo, baz]\(aq default=None .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.environ.items() Return a dict of the entire environment set for the salt process .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq environ.items .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.environ.setenv(environ, false_unsets=False, clear_all=False, update_minion=False, permanent=False) Set multiple salt process environment variables from a dict. Returns a dict. .INDENT 7.0 .TP .B environ Must be a dict. The top\-level keys of the dict are the names of the environment variables to set. Each key\(aqs value must be a string or False. Refer to the \(aqfalse_unsets\(aq parameter for behavior when a value set to False. .TP .B false_unsets If a key\(aqs value is False and false_unsets is True, then the key will be removed from the salt processes environment dict entirely. If a key\(aqs value is False and false_unsets is not True, then the key\(aqs value will be set to an empty string. Default: False .TP .B clear_all USE WITH CAUTION! This option can unset environment variables needed for salt to function properly. If clear_all is True, then any environment variables not defined in the environ dict will be deleted. Default: False .TP .B update_minion If True, apply these environ changes to the main salt\-minion process. If False, the environ changes will only affect the current salt subprocess. Default: False .TP .B permanent On Windows minions this will set the environment variable in the registry so that it is always added as an environment variable when applications open. If you want to set the variable to HKLM instead of HKCU just pass in \(dqHKLM\(dq for this parameter. On all other minion types this will be ignored. Note: This will only take affect on applications opened after this has been set. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq environ.setenv \(aq{\(dqfoo\(dq: \(dqbar\(dq, \(dqbaz\(dq: \(dqquux\(dq}\(aq salt \(aq*\(aq environ.setenv \(aq{\(dqa\(dq: \(dqb\(dq, \(dqc\(dq: False}\(aq false_unsets=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.environ.setval(key, val, false_unsets=False, permanent=False) Set a single salt process environment variable. Returns True on success. .INDENT 7.0 .TP .B key The environment key to set. Must be a string. .TP .B val The value to set. Must be a string or False. Refer to the \(aqfalse_unsets\(aq parameter for behavior when set to False. .TP .B false_unsets If val is False and false_unsets is True, then the key will be removed from the salt processes environment dict entirely. If val is False and false_unsets is not True, then the key\(aqs value will be set to an empty string. Default: False. .TP .B permanent On Windows minions this will set the environment variable in the registry so that it is always added as an environment variable when applications open. If you want to set the variable to HKLM instead of HKCU just pass in \(dqHKLM\(dq for this parameter. On all other minion types this will be ignored. Note: This will only take affect on applications opened after this has been set. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq environ.setval foo bar salt \(aq*\(aq environ.setval baz val=False false_unsets=True salt \(aq*\(aq environ.setval baz bar permanent=True salt \(aq*\(aq environ.setval baz bar permanent=HKLM .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.eselect .sp Support for eselect, Gentoo\(aqs configuration and management tool. .INDENT 0.0 .TP .B salt.modules.eselect.exec_action(module, action, module_parameter=None, action_parameter=None, state_only=False) Execute an arbitrary action on a module. .INDENT 7.0 .TP .B module name of the module to be executed .TP .B action name of the module\(aqs action to be run .TP .B module_parameter additional params passed to the defined module .TP .B action_parameter additional params passed to the defined action .TP .B state_only don\(aqt return any output but only the success/failure of the operation .UNINDENT .sp CLI Example (updating the \fBphp\fP implementation used for \fBapache2\fP): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eselect.exec_action php update action_parameter=\(aqapache2\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.eselect.get_current_target(module, module_parameter=None, action_parameter=None) Get the currently selected target for the given module. .INDENT 7.0 .TP .B module name of the module to be queried for its current target .TP .B module_parameter additional params passed to the defined module .TP .B action_parameter additional params passed to the \(aqshow\(aq action .UNINDENT .sp CLI Example (current target of system\-wide \fBjava\-vm\fP): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eselect.get_current_target java\-vm action_parameter=\(aqsystem\(aq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example (current target of \fBkernel\fP symlink): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eselect.get_current_target kernel .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.eselect.get_modules() List available \fBeselect\fP modules. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eselect.get_modules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.eselect.get_target_list(module, action_parameter=None) List available targets for the given module. .INDENT 7.0 .TP .B module name of the module to be queried for its targets .TP .B action_parameter additional params passed to the defined action .sp New in version 2016.11.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eselect.get_target_list kernel .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.eselect.set_target(module, target, module_parameter=None, action_parameter=None) Set the target for the given module. Target can be specified by index or name. .INDENT 7.0 .TP .B module name of the module for which a target should be set .TP .B target name of the target to be set for this module .TP .B module_parameter additional params passed to the defined module .TP .B action_parameter additional params passed to the defined action .UNINDENT .sp CLI Example (setting target of system\-wide \fBjava\-vm\fP): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eselect.set_target java\-vm icedtea\-bin\-7 action_parameter=\(aqsystem\(aq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example (setting target of \fBkernel\fP symlink): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eselect.set_target kernel linux\-3.17.5\-gentoo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.esxcluster .sp Module used to access the esxcluster proxy connection methods .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be deprecated in a future release of Salt. VMware strongly recommends using the \fI\%VMware Salt extensions\fP instead of the ESX cluster module. Because the Salt extensions are newer and actively supported by VMware, they are more compatible with current versions of ESXi and they work well with the latest features in the VMware product line. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.esxcluster.get_details() .UNINDENT .SS salt.modules.esxdatacenter .sp Module used to access the esxdatacenter proxy connection methods .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be deprecated in a future release of Salt. VMware strongly recommends using the \fI\%VMware Salt extensions\fP instead of the ESX data center module. Because the Salt extensions are newer and actively supported by VMware, they are more compatible with current versions of ESXi and they work well with the latest features in the VMware product line. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.esxdatacenter.get_details() .UNINDENT .SS salt.modules.esxi .sp Glues the VMware vSphere Execution Module to the VMware ESXi Proxy Minions to the \fI\%esxi proxymodule\fP\&. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be deprecated in a future release of Salt. VMware strongly recommends using the \fI\%VMware Salt extensions\fP instead of the ESXi module. Because the Salt extensions are newer and actively supported by VMware, they are more compatible with current versions of ESXi and they work well with the latest features in the VMware product line. .UNINDENT .UNINDENT .sp Depends: \fI\%vSphere Remote Execution Module (salt.modules.vsphere)\fP .sp For documentation on commands that you can direct to an ESXi host via proxy, look in the documentation for \fI\%salt.modules.vsphere\fP\&. .sp This execution module calls through to a function in the ESXi proxy module called \fBch_config\fP, which looks up the function passed in the \fBcommand\fP parameter in \fI\%salt.modules.vsphere\fP and calls it. .sp To execute commands with an ESXi Proxy Minion using the vSphere Execution Module, use the \fBesxi.cmd <vsphere\-function\-name>\fP syntax. Both args and kwargs needed for various vsphere execution module functions must be passed through in a kwarg\- type manor. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqesxi\-proxy\(aq esxi.cmd system_info salt \(aqexsi\-proxy\(aq esxi.cmd get_service_policy service_name=\(aqssh\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.esxi.cmd(command, *args, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.esxi.get_details() .UNINDENT .SS salt.modules.esxvm .sp Module used to access the esx proxy connection methods .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be deprecated in a future release of Salt. VMware strongly recommends using the \fI\%VMware Salt extensions\fP instead of the ESX VSM module. Because the Salt extensions are newer and actively supported by VMware, they are more compatible with current versions of ESXi and they work well with the latest features in the VMware product line. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.esxvm.get_details() .UNINDENT .SS salt.modules.etcd_mod .sp Execution module to work with etcd .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 python\-etcd or etcd3\-py .UNINDENT .UNINDENT .SS Configuration .sp To work with an etcd server you must configure an etcd profile. The etcd config can be set in either the Salt Minion configuration file or in pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_etd_config: etcd.host: 127.0.0.1 etcd.port: 4001 .ft P .fi .UNINDENT .UNINDENT .sp It is technically possible to configure etcd without using a profile, but this is not considered to be a best practice, especially when multiple etcd servers or clusters are available. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.host: 127.0.0.1 etcd.port: 4001 .ft P .fi .UNINDENT .UNINDENT .sp In order to choose whether to use etcd API v2 or v3, you can put the following configuration option in the same place as your etcd configuration. This option defaults to true, meaning you will use v2 unless you specify otherwise. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.require_v2: True .ft P .fi .UNINDENT .UNINDENT .sp When using API v3, there are some specific options available to be configured within your etcd profile. They are defaulted to the following... .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.encode_keys: False etcd.encode_values: True etcd.raw_keys: False etcd.raw_values: False etcd.unicode_errors: \(dqsurrogateescape\(dq .ft P .fi .UNINDENT .UNINDENT .sp \fBetcd.encode_keys\fP indicates whether you want to pre\-encode keys using msgpack before adding them to etcd. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you set \fBetcd.encode_keys\fP to \fBTrue\fP, all recursive functionality will no longer work. This includes \fBtree\fP and \fBls\fP and all other methods if you set \fBrecurse\fP/\fBrecursive\fP to \fBTrue\fP\&. This is due to the fact that when encoding with msgpack, keys like \fB/salt\fP and \fB/salt/stack\fP will have differing byte prefixes, and etcd v3 searches recursively using prefixes. .UNINDENT .UNINDENT .sp \fBetcd.encode_values\fP indicates whether you want to pre\-encode values using msgpack before adding them to etcd. This defaults to \fBTrue\fP to avoid data loss on non\-string values wherever possible. .sp \fBetcd.raw_keys\fP determines whether you want the raw key or a string returned. .sp \fBetcd.raw_values\fP determines whether you want the raw value or a string returned. .sp \fBetcd.unicode_errors\fP determines what you policy to follow when there are encoding/decoding errors. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The etcd configuration can also be set in the Salt Master config file, but in order to use any etcd configurations defined in the Salt Master config, the \fI\%pillar_opts\fP must be set to \fBTrue\fP\&. .sp Be aware that setting \fBpillar_opts\fP to \fBTrue\fP has security implications as this makes all master configuration settings available in all minion\(aqs pillars. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.etcd_mod.get_(key, recurse=False, profile=None, **kwargs) New in version 2014.7.0. .sp Get a value from etcd, by direct path. Returns None on failure. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion etcd.get /path/to/key salt myminion etcd.get /path/to/key profile=my_etcd_config salt myminion etcd.get /path/to/key recurse=True profile=my_etcd_config salt myminion etcd.get /path/to/key host=127.0.0.1 port=2379 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.etcd_mod.ls_(path=\(aq/\(aq, profile=None, **kwargs) New in version 2014.7.0. .sp Return all keys and dirs inside a specific path. Returns an empty dict on failure. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion etcd.ls /path/to/dir/ salt myminion etcd.ls /path/to/dir/ profile=my_etcd_config salt myminion etcd.ls /path/to/dir/ host=127.0.0.1 port=2379 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.etcd_mod.rm_(key, recurse=False, profile=None, **kwargs) New in version 2014.7.0. .sp Delete a key from etcd. Returns True if the key was deleted, False if it was not and None if there was a failure. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion etcd.rm /path/to/key salt myminion etcd.rm /path/to/key profile=my_etcd_config salt myminion etcd.rm /path/to/key host=127.0.0.1 port=2379 salt myminion etcd.rm /path/to/dir recurse=True profile=my_etcd_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.etcd_mod.set_(key, value, profile=None, ttl=None, directory=False, **kwargs) New in version 2014.7.0. .sp Set a key in etcd by direct path. Optionally, create a directory or set a TTL on the key. Returns None on failure. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion etcd.set /path/to/key value salt myminion etcd.set /path/to/key value profile=my_etcd_config salt myminion etcd.set /path/to/key value host=127.0.0.1 port=2379 salt myminion etcd.set /path/to/dir \(aq\(aq directory=True salt myminion etcd.set /path/to/key value ttl=5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.etcd_mod.tree(path=\(aq/\(aq, profile=None, **kwargs) New in version 2014.7.0. .sp Recurse through etcd and return all values. Returns None on failure. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion etcd.tree salt myminion etcd.tree profile=my_etcd_config salt myminion etcd.tree host=127.0.0.1 port=2379 salt myminion etcd.tree /path/to/keys profile=my_etcd_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.etcd_mod.update(fields, path=\(aq\(aq, profile=None, **kwargs) New in version 2016.3.0. .sp Sets a dictionary of values in one call. Useful for large updates in syndic environments. The dictionary can contain a mix of formats such as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aq/some/example/key\(aq: \(aqbar\(aq, \(aq/another/example/key\(aq: \(aqbaz\(aq } .ft P .fi .UNINDENT .UNINDENT .sp Or it may be a straight dictionary, which will be flattened to look like the above format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqsome\(aq: { \(aqexample\(aq: { \(aqkey\(aq: \(aqbar\(aq } }, \(aqanother\(aq: { \(aqexample\(aq: { \(aqkey\(aq: \(aqbaz\(aq } } } .ft P .fi .UNINDENT .UNINDENT .sp You can even mix the two formats and it will be flattened to the first format. Leading and trailing \(aq/\(aq will be removed. .sp Empty directories can be created by setting the value of the key to an empty dictionary. .sp The \(aqpath\(aq parameter will optionally set the root of the path to use. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion etcd.update \(dq{\(aq/path/to/key\(aq: \(aqbaz\(aq, \(aq/another/key\(aq: \(aqbar\(aq}\(dq salt myminion etcd.update \(dq{\(aq/path/to/key\(aq: \(aqbaz\(aq, \(aq/another/key\(aq: \(aqbar\(aq}\(dq profile=my_etcd_config salt myminion etcd.update \(dq{\(aq/path/to/key\(aq: \(aqbaz\(aq, \(aq/another/key\(aq: \(aqbar\(aq}\(dq host=127.0.0.1 port=2379 salt myminion etcd.update \(dq{\(aq/path/to/key\(aq: \(aqbaz\(aq, \(aq/another/key\(aq: \(aqbar\(aq}\(dq path=\(aq/some/root\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.etcd_mod.watch(key, recurse=False, profile=None, timeout=0, index=None, **kwargs) New in version 2016.3.0. .sp Makes a best effort to watch for a key or tree change in etcd. Returns a dict containing the new key value ( or None if the key was deleted ), the modifiedIndex of the key, whether the key changed or not, the path to the key that changed and whether it is a directory or not. .sp If something catastrophic happens, returns {} .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion etcd.watch /path/to/key salt myminion etcd.watch /path/to/key timeout=10 salt myminion etcd.watch /patch/to/key profile=my_etcd_config index=10 salt myminion etcd.watch /patch/to/key host=127.0.0.1 port=2379 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ethtool .sp Module for running ethtool command .sp New in version 2016.3.0. .INDENT 0.0 .TP .B codeauthor Krzysztof Pawlowski <\fI\%msciciel@msciciel.eu\fP> .TP .B maturity new .TP .B depends python\-ethtool .TP .B platform linux .UNINDENT .INDENT 0.0 .TP .B salt.modules.ethtool.set_coalesce(devname, **kwargs) Changes the coalescing settings of the specified network device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ethtool.set_coalesce <devname> [adaptive_rx=on|off] [adaptive_tx=on|off] [rx_usecs=N] [rx_frames=N] [rx_usecs_irq=N] [rx_frames_irq=N] [tx_usecs=N] [tx_frames=N] [tx_usecs_irq=N] [tx_frames_irq=N] [stats_block_usecs=N] [pkt_rate_low=N] [rx_usecs_low=N] [rx_frames_low=N] [tx_usecs_low=N] [tx_frames_low=N] [pkt_rate_high=N] [rx_usecs_high=N] [rx_frames_high=N] [tx_usecs_high=N] [tx_frames_high=N] [sample_interval=N] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ethtool.set_feature(devname, **kwargs) New in version 3006.0. .sp Changes the feature parameters of the specified network device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ethtool.set_feature <devname> sg=off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ethtool.set_offload(devname, **kwargs) Changes the offload parameters and other features of the specified network device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ethtool.set_offload <devname> tcp_segmentation_offload=on .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ethtool.set_pause(devname, **kwargs) New in version 3006.0. .sp Changes the pause parameters of the specified network device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ethtool.set_pause <devname> autoneg=off rx=off tx=off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ethtool.set_ring(devname, **kwargs) Changes the rx/tx ring parameters of the specified network device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ethtool.set_ring <devname> [rx=N] [rx_mini=N] [rx_jumbo=N] [tx=N] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ethtool.show_coalesce(devname) Queries the specified network device for coalescing information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ethtool.show_coalesce <devname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ethtool.show_driver(devname) Queries the specified network device for associated driver information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ethtool.show_driver <devname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ethtool.show_features(devname) New in version 3006.0. .sp Queries the specified network device for associated feature information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ethtool.show_features <devname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ethtool.show_offload(devname) Queries the specified network device for the state of protocol offload and other features .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ethtool.show_offload <devname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ethtool.show_pause(devname) New in version 3006.0. .sp Queries the specified network device for associated pause information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ethtool.show_pause <devname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ethtool.show_ring(devname) Queries the specified network device for rx/tx ring parameter information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ethtool.show_ring <devname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.event .sp Use the \fI\%Salt Event System\fP to fire events from the master to the minion and vice\-versa. .INDENT 0.0 .TP .B salt.modules.event.fire(data, tag) Fire an event on the local minion event bus. Data must be formed as a dict. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq event.fire \(aq{\(dqdata\(dq:\(dqmy event data\(dq}\(aq \(aqtag\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.event.fire_master(data, tag, preload=None) Fire an event off up to the master server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq event.fire_master \(aq{\(dqdata\(dq:\(dqmy event data\(dq}\(aq \(aqtag\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.event.send(tag, data=None, preload=None, with_env=False, with_grains=False, with_pillar=False, with_env_opts=False, **kwargs) Send an event to the Salt Master .sp New in version 2014.7.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtag\fP \-\- A tag to give the event. Use slashes to create a namespace for related events. E.g., \fBmyco/build/buildserver1/start\fP, \fBmyco/build/buildserver1/success\fP, \fBmyco/build/buildserver1/failure\fP\&. .IP \(bu 2 \fBdata\fP \-\- A dictionary of data to send in the event. This is free\-form. Send any data points that are needed for whoever is consuming the event. Arguments on the CLI are interpreted as YAML so complex data structures are possible. .IP \(bu 2 \fBwith_env\fP (Specify \fBTrue\fP to include all environment variables, or specify a list of strings of variable names to include.) \-\- Include environment variables from the current shell environment in the event data as \fBenviron\fP\&.. This is a short\-hand for working with systems that seed the environment with relevant data such as Jenkins. .IP \(bu 2 \fBwith_grains\fP (Specify \fBTrue\fP to include all grains, or specify a list of strings of grain names to include.) \-\- Include grains from the current minion in the event data as \fBgrains\fP\&. .IP \(bu 2 \fBwith_pillar\fP (Specify \fBTrue\fP to include all Pillar values, or specify a list of strings of Pillar keys to include. It is a best\-practice to only specify a relevant subset of Pillar data.) \-\- Include Pillar values from the current minion in the event data as \fBpillar\fP\&. Remember Pillar data is often sensitive data so be careful. This is useful for passing ephemeral Pillar values through an event. Such as passing the \fBpillar={}\fP kwarg in \fI\%state.sls\fP from the Master, through an event on the Minion, then back to the Master. .IP \(bu 2 \fBwith_env_opts\fP (Specify \fBTrue\fP to include \fBsaltenv\fP and \fBpillarenv\fP values or \fBFalse\fP to omit them.) \-\- Include \fBsaltenv\fP and \fBpillarenv\fP set on minion at the moment when event is send into event data. .IP \(bu 2 \fBkwargs\fP \-\- Any additional keyword arguments passed to this function will be interpreted as key\-value pairs and included in the event data. This provides a convenient alternative to YAML for simple values. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call event.send myco/mytag foo=Foo bar=Bar salt\-call event.send \(aqmyco/mytag\(aq \(aq{foo: Foo, bar: Bar}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.extfs .sp Module for managing ext2/3/4 file systems .INDENT 0.0 .TP .B salt.modules.extfs.attributes(device, args=None) Return attributes from dumpe2fs for a specified device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq extfs.attributes /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.extfs.blocks(device, args=None) Return block and inode info from dumpe2fs for a specified device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq extfs.blocks /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.extfs.dump(device, args=None) Return all contents of dumpe2fs for a specified device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq extfs.dump /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.extfs.mkfs(device, fs_type, full_return=False, **kwargs) Create a file system on the specified device .INDENT 7.0 .TP .B full_return False If \fBTrue\fP, the full \fBcmd.run_all\fP dictionary will be returned instead of just stdout/stderr text. Useful for setting the result of the \fBmodule.run\fP state. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq extfs.mkfs /dev/sda1 fs_type=ext4 opts=\(aqacl,noexec\(aq .ft P .fi .UNINDENT .UNINDENT .sp Valid options are: .INDENT 7.0 .IP \(bu 2 \fBblock_size\fP: 1024, 2048 or 4096 .IP \(bu 2 \fBcheck\fP: check for bad blocks .IP \(bu 2 \fBdirect\fP: use direct IO .IP \(bu 2 \fBext_opts\fP: extended file system options (comma\-separated) .IP \(bu 2 \fBfragment_size\fP: size of fragments .IP \(bu 2 \fBforce\fP: setting force to True will cause mke2fs to specify the \-F option twice (it is already set once); this is truly dangerous .IP \(bu 2 \fBblocks_per_group\fP: number of blocks in a block group .IP \(bu 2 \fBnumber_of_groups\fP: ext4 option for a virtual block group .IP \(bu 2 \fBbytes_per_inode\fP: set the bytes/inode ratio .IP \(bu 2 \fBinode_size\fP: size of the inode .IP \(bu 2 \fBjournal\fP: set to True to create a journal (default on ext3/4) .IP \(bu 2 \fBjournal_opts\fP: options for the fs journal (comma separated) .IP \(bu 2 \fBblocks_file\fP: read bad blocks from file .IP \(bu 2 \fBlabel\fP: label to apply to the file system .IP \(bu 2 \fBreserved\fP: percentage of blocks reserved for super\-user .IP \(bu 2 \fBlast_dir\fP: last mounted directory .IP \(bu 2 \fBtest\fP: set to True to not actually create the file system (mke2fs \-n) .IP \(bu 2 \fBnumber_of_inodes\fP: override default number of inodes .IP \(bu 2 \fBcreator_os\fP: override \(dqcreator operating system\(dq field .IP \(bu 2 \fBopts\fP: mount options (comma separated) .IP \(bu 2 \fBrevision\fP: set the filesystem revision (default 1) .IP \(bu 2 \fBsuper\fP: write superblock and group descriptors only .IP \(bu 2 \fBfs_type\fP: set the filesystem type (REQUIRED) .IP \(bu 2 \fBusage_type\fP: how the filesystem is going to be used .IP \(bu 2 \fBuuid\fP: set the UUID for the file system .IP \(bu 2 \fBcluster_size\fP: specify the size of cluster in bytes for file systems using the bigalloc feature .IP \(bu 2 \fBroot_directory\fP: copy the contents of the given directory into the root directory of the file system .IP \(bu 2 \fBerrors_behavior\fP: change the behavior of the kernel code when errors are detected .UNINDENT .sp See the \fBmke2fs(8)\fP manpage for a more complete description of these options. .UNINDENT .INDENT 0.0 .TP .B salt.modules.extfs.tune(device, full_return=False, **kwargs) Set attributes for the specified device (using tune2fs) .INDENT 7.0 .TP .B full_return False If \fBTrue\fP, the full \fBcmd.run_all\fP dictionary will be returned instead of just stdout/stderr text. Useful for setting the result of the \fBmodule.run\fP state. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq extfs.tune /dev/sda1 force=True label=wildstallyns opts=\(aqacl,noexec\(aq .ft P .fi .UNINDENT .UNINDENT .sp Valid options are: .INDENT 7.0 .IP \(bu 2 \fBmax\fP: max mount count .IP \(bu 2 \fBcount\fP: mount count .IP \(bu 2 \fBerror\fP: error behavior .IP \(bu 2 \fBextended_opts\fP: extended options (comma separated) .IP \(bu 2 \fBforce\fP: force, even if there are errors (set to True) .IP \(bu 2 \fBgroup\fP: group name or gid that can use the reserved blocks .IP \(bu 2 \fBinterval\fP: interval between checks .IP \(bu 2 \fBjournal\fP: set to True to create a journal (default on ext3/4) .IP \(bu 2 \fBjournal_opts\fP: options for the fs journal (comma separated) .IP \(bu 2 \fBlabel\fP: label to apply to the file system .IP \(bu 2 \fBreserved_percentage\fP: percentage of blocks reserved for super\-user .IP \(bu 2 \fBlast_dir\fP: last mounted directory .IP \(bu 2 \fBopts\fP: mount options (comma separated) .IP \(bu 2 \fBfeature\fP: set or clear a feature (comma separated) .IP \(bu 2 \fBmmp_check\fP: mmp check interval .IP \(bu 2 \fBreserved\fP: reserved blocks count .IP \(bu 2 \fBquota_opts\fP: quota options (comma separated) .IP \(bu 2 \fBtime\fP: time last checked .IP \(bu 2 \fBuser\fP: user or uid who can use the reserved blocks .IP \(bu 2 \fBuuid\fP: set the UUID for the file system .UNINDENT .sp See the \fBmke2fs(8)\fP manpage for a more complete description of these options. .UNINDENT .SS salt.modules.file .sp Manage information about regular files, directories, and special files on the minion, set/read user, group, mode, and data .INDENT 0.0 .TP .B class salt.modules.file.AttrChanges(added, removed) .INDENT 7.0 .TP .B added Alias for field number 0 .UNINDENT .INDENT 7.0 .TP .B removed Alias for field number 1 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.access(path, mode) New in version 2014.1.0. .sp Test whether the Salt process has the specified access to the file. One of the following modes must be specified: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C f: Test the existence of the path r: Test the readability of the path w: Test the writability of the path x: Test whether the path can be executed .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.access /path/to/file f salt \(aq*\(aq file.access /path/to/file x .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.append(path, *args, **kwargs) New in version 0.9.5. .sp Append text to the end of a file .INDENT 7.0 .TP .B path path to file .TP .B \fI*args\fP strings to append to file .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.append /etc/motd \e \(dqWith all thine offerings thou shalt offer salt.\(dq \e \(dqSalt is what makes things taste bad when it isn\(aqt in them.\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .IP "Attention" .sp If you need to pass a string to append and that string contains an equal sign, you \fBmust\fP include the argument name, args. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.append /etc/motd args=\(aqcheese=spam\(aq salt \(aq*\(aq file.append /etc/motd args=\(dq[\(aqcheese=spam\(aq,\(aqspam=cheese\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.apply_template_on_contents(contents, template, context, defaults, saltenv) Return the contents after applying the templating engine .INDENT 7.0 .TP .B contents template string .TP .B template template format .TP .B context Overrides default context variables passed to the template. .TP .B defaults Default context passed to the template. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.apply_template_on_contents \e contents=\(aqThis is a {{ template }} string.\(aq \e template=jinja \e \(dqcontext={}\(dq \(dqdefaults={\(aqtemplate\(aq: \(aqcool\(aq}\(dq \e saltenv=base .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.basename(path) Returns the final component of a pathname .sp New in version 2015.5.0. .sp This can be useful at the CLI but is frequently useful when scripting. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set filename = salt[\(aqfile.basename\(aq](source_file) %} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.basename \(aqtest/test.config\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.blockreplace(path, marker_start=\(aq#\-\- start managed zone \-\-\(aq, marker_end=\(aq#\-\- end managed zone \-\-\(aq, content=\(aq\(aq, append_if_not_found=False, prepend_if_not_found=False, backup=\(aq.bak\(aq, dry_run=False, show_changes=True, append_newline=False, insert_before_match=None, insert_after_match=None) New in version 2014.1.0. .sp Replace content of a text block in a file, delimited by line markers .sp A block of content delimited by comments can help you manage several lines entries without worrying about old entries removal. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function will store two copies of the file in\-memory (the original version and the edited version) in order to detect changes and only edit the targeted file if necessary. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path Filesystem path to the file to be edited .TP .B marker_start The line content identifying a line as the start of the content block. Note that the whole line containing this marker will be considered, so whitespace or extra content before or after the marker is included in final output .TP .B marker_end The line content identifying the end of the content block. As of versions 2017.7.5 and 2018.3.1, everything up to the text matching the marker will be replaced, so it\(aqs important to ensure that your marker includes the beginning of the text you wish to replace. .TP .B content The content to be used between the two lines identified by marker_start and marker_stop. .TP .B append_if_not_found: False If markers are not found and set to \fBTrue\fP then, the markers and content will be appended to the file. .TP .B prepend_if_not_found: False If markers are not found and set to \fBTrue\fP then, the markers and content will be prepended to the file. .TP .B insert_before_match If markers are not found, this parameter can be set to a regex which will insert the block before the first found occurrence in the file. .sp New in version 3001. .TP .B insert_after_match If markers are not found, this parameter can be set to a regex which will insert the block after the first found occurrence in the file. .sp New in version 3001. .TP .B backup The file extension to use for a backup of the file if any edit is made. Set to \fBFalse\fP to skip making a backup. .TP .B dry_run: False If \fBTrue\fP, do not make any edits to the file and simply return the changes that \fIwould\fP be made. .TP .B show_changes: True Controls how changes are presented. If \fBTrue\fP, this function will return a unified diff of the changes made. If False, then it will return a boolean (\fBTrue\fP if any changes were made, otherwise \fBFalse\fP). .TP .B append_newline: False Controls whether or not a newline is appended to the content block. If the value of this argument is \fBTrue\fP then a newline will be added to the content block. If it is \fBFalse\fP, then a newline will \fInot\fP be added to the content block. If it is \fBNone\fP then a newline will only be added to the content block if it does not already end in a newline. .sp New in version 2016.3.4. .sp Changed in version 2017.7.5,2018.3.1: New behavior added when value is \fBNone\fP\&. .sp Changed in version 2019.2.0: The default value of this argument will change to \fBNone\fP to match the behavior of the \fI\%file.blockreplace state\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.blockreplace /etc/hosts \(aq#\-\- start managed zone foobar : DO NOT EDIT \-\-\(aq \e \(aq#\-\- end managed zone foobar \-\-\(aq $\(aq10.0.1.1 foo.foobar\en10.0.1.2 bar.foobar\(aq True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.chattr(*files, **kwargs) New in version 2018.3.0. .sp Change the attributes of files. This function accepts one or more files and the following options: .INDENT 7.0 .TP .B operator Can be wither \fBadd\fP or \fBremove\fP\&. Determines whether attributes should be added or removed from files .TP .B attributes One or more of the following characters: \fBaAcCdDeijPsStTu\fP, representing attributes to add to/remove from files .TP .B version a version number to assign to the file(s) .TP .B flags One or more of the following characters: \fBRVf\fP, representing flags to assign to chattr (recurse, verbose, suppress most errors) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.chattr foo1.txt foo2.txt operator=add attributes=ai salt \(aq*\(aq file.chattr foo3.txt operator=remove attributes=i version=2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.check_file_meta(name, sfn, source, source_sum, user, group, mode, attrs, saltenv, contents=None, seuser=None, serole=None, setype=None, serange=None, verify_ssl=True, follow_symlinks=False) Check for the changes in the file metadata. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.check_file_meta /etc/httpd/conf.d/httpd.conf None salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\(aq root root \(aq755\(aq None base .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Supported hash types include sha512, sha384, sha256, sha224, sha1, and md5. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Path to file destination .TP .B sfn Template\-processed source file contents .TP .B source URL to file source .TP .B source_sum File checksum information as a dictionary .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {hash_type: md5, hsum: <md5sum>} .ft P .fi .UNINDENT .UNINDENT .TP .B user Destination file user owner .TP .B group Destination file group owner .TP .B mode Destination file permissions mode .TP .B attrs Destination file attributes .sp New in version 2018.3.0. .TP .B saltenv Salt environment used to resolve source files .TP .B contents File contents .TP .B seuser selinux user attribute .sp New in version 3001. .TP .B serole selinux role attribute .sp New in version 3001. .TP .B setype selinux type attribute .sp New in version 3001. .TP .B serange selinux range attribute .sp New in version 3001. .TP .B verify_ssl If \fBFalse\fP, remote https file sources (\fBhttps://\fP) will not attempt to validate the servers certificate. Default is True. .sp New in version 3002. .TP .B follow_symlinks If the desired path is a symlink, follow it and check the permissions of the file to which the symlink points. .sp New in version 3005. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.check_hash(path, file_hash) Check if a file matches the given hash string .sp Returns \fBTrue\fP if the hash matches, otherwise \fBFalse\fP\&. .INDENT 7.0 .TP .B path Path to a file local to the minion. .TP .B hash The hash to check against the file specified in the \fBpath\fP argument. .sp Changed in version 2016.11.4. .sp For this and newer versions the hash can be specified without an accompanying hash type (e.g. \fBe138491e9d5b97023cea823fe17bac22\fP), but for earlier releases it is necessary to also specify the hash type in the format \fB<hash_type>=<hash_value>\fP (e.g. \fBmd5=e138491e9d5b97023cea823fe17bac22\fP). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.check_hash /etc/fstab e138491e9d5b97023cea823fe17bac22 salt \(aq*\(aq file.check_hash /etc/fstab md5=e138491e9d5b97023cea823fe17bac22 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.check_managed(name, source, source_hash, source_hash_name, user, group, mode, attrs, template, context, defaults, saltenv, contents=None, skip_verify=False, seuser=None, serole=None, setype=None, serange=None, follow_symlinks=False, **kwargs) Check to see what changes need to be made for a file .INDENT 7.0 .TP .B follow_symlinks If the desired path is a symlink, follow it and check the permissions of the file to which the symlink points. .sp New in version 3005. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.check_managed /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\(aq root, root, \(aq755\(aq jinja True None None base .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.check_managed_changes(name, source, source_hash, source_hash_name, user, group, mode, attrs, template, context, defaults, saltenv, contents=None, skip_verify=False, keep_mode=False, seuser=None, serole=None, setype=None, serange=None, verify_ssl=True, follow_symlinks=False, **kwargs) Return a dictionary of what changes need to be made for a file .sp Changed in version 3001: selinux attributes added .INDENT 7.0 .TP .B verify_ssl If \fBFalse\fP, remote https file sources (\fBhttps://\fP) and source_hash will not attempt to validate the servers certificate. Default is True. .sp New in version 3002. .TP .B follow_symlinks If the desired path is a symlink, follow it and check the permissions of the file to which the symlink points. .sp New in version 3005. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.check_managed_changes /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\(aq root, root, \(aq755\(aq jinja True None None base .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.check_perms(name, ret, user, group, mode, attrs=None, follow_symlinks=False, seuser=None, serole=None, setype=None, serange=None) Changed in version 3001: Added selinux options .sp Check the permissions on files, modify attributes and chown if needed. File attributes are only verified if lsattr(1) is installed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.check_perms /etc/sudoers \(aq{}\(aq root root 400 ai .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.1.3: \fBfollow_symlinks\fP option added .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.chgrp(path, group) Change the group of a file .INDENT 7.0 .TP .B path path to the file or directory .TP .B group group owner .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.chgrp /etc/passwd root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.chown(path, user, group) Chown a file, pass the file the desired user and group .INDENT 7.0 .TP .B path path to the file or directory .TP .B user user owner .TP .B group group owner .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.chown /etc/passwd root root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.comment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Deprecated since version 0.17.0: Use \fI\%replace()\fP instead. .sp Comment out specified lines in a file .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B regex A regular expression used to find the lines that are to be commented; this pattern will be wrapped in parenthesis and will move any preceding/trailing \fB^\fP or \fB$\fP characters outside the parenthesis (e.g., the pattern \fB^foo$\fP will be rewritten as \fB^(foo)$\fP) .TP .B char: \fB#\fP The character to be inserted at the beginning of a line in order to comment it out .TP .B backup: \fB\&.bak\fP The file will be backed up before edit with this file extension .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This backup will be overwritten each time \fBsed\fP / \fBcomment\fP / \fBuncomment\fP is called. Meaning the backup will only be useful after the first invocation. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.comment /etc/modules pcspkr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.comment_line(path, regex, char=\(aq#\(aq, cmnt=True, backup=\(aq.bak\(aq) Comment or Uncomment a line in a text file. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- string The full path to the text file. .IP \(bu 2 \fBregex\fP \-\- string A regex expression that begins with \fB^\fP that will find the line you wish to comment. Can be as simple as \fB^color =\fP .IP \(bu 2 \fBchar\fP \-\- string The character used to comment a line in the type of file you\(aqre referencing. Default is \fB#\fP .IP \(bu 2 \fBcmnt\fP \-\- boolean True to comment the line. False to uncomment the line. Default is True. .IP \(bu 2 \fBbackup\fP \-\- string The file extension to give the backup file. Default is \fB\&.bak\fP Set to False/None to not keep a backup. .UNINDENT .TP .B Returns boolean Returns True if successful, False if not .UNINDENT .sp CLI Example: .sp The following example will comment out the \fBpcspkr\fP line in the \fB/etc/modules\fP file using the default \fB#\fP character and create a backup file named \fBmodules.bak\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.comment_line \(aq/etc/modules\(aq \(aq^pcspkr\(aq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .sp The following example will uncomment the \fBlog_level\fP setting in \fBminion\fP config file if it is set to either \fBwarning\fP, \fBinfo\fP, or \fBdebug\fP using the \fB#\fP character and create a backup file named \fBminion.bk\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.comment_line \(aqC:\esalt\econf\eminion\(aq \(aq^log_level: (warning|info|debug)\(aq \(aq#\(aq False \(aq.bk\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.contains(path, text) Deprecated since version 0.17.0: Use \fI\%search()\fP instead. .sp Return \fBTrue\fP if the file at \fBpath\fP contains \fBtext\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.contains /etc/crontab \(aqmymaintenance.sh\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.contains_glob(path, glob_expr) Deprecated since version 0.17.0: Use \fI\%search()\fP instead. .sp Return \fBTrue\fP if the given glob matches a string in the named file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.contains_glob /etc/foobar \(aq*cheese*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.contains_regex(path, regex, lchar=\(aq\(aq) Deprecated since version 0.17.0: Use \fI\%search()\fP instead. .sp Return True if the given regular expression matches on any line in the text of a given file. .sp If the lchar argument (leading char) is specified, it will strip \fIlchar\fP from the left side of each line before trying to match .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.contains_regex /etc/crontab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.copy(src, dst, recurse=False, remove_existing=False) Copy a file or directory from source to dst .sp In order to copy a directory, the recurse flag is required, and will by default overwrite files in the destination with the same path, and retain all other existing files. (similar to cp \-r on unix) .sp remove_existing will remove all files in the target directory, and then copy files from the source. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The copy function accepts paths that are local to the Salt minion. This function does not support salt://, http://, or the other additional file paths that are supported by \fI\%states.file.managed\fP and \fI\%states.file.recurse\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.copy /path/to/src /path/to/dst salt \(aq*\(aq file.copy /path/to/src_dir /path/to/dst_dir recurse=True salt \(aq*\(aq file.copy /path/to/src_dir /path/to/dst_dir recurse=True remove_existing=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.delete_backup(path, backup_id) New in version 0.17.0. .sp Delete a previous version of a file that was backed up using Salt\(aqs \fI\%file state backup\fP system. .INDENT 7.0 .TP .B path The path on the minion to check for backups .TP .B backup_id The numeric id for the backup you wish to delete, as found using \fI\%file.list_backups\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.delete_backup /var/cache/salt/minion/file_backup/home/foo/bar/baz.txt 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.directory_exists(path) Tests to see if path is a valid directory. Returns True/False. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.directory_exists /etc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.dirname(path) Returns the directory component of a pathname .sp New in version 2015.5.0. .sp This can be useful at the CLI but is frequently useful when scripting. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- from salt[\(aqfile.dirname\(aq](tpldir) + \(aq/vars.jinja\(aq import parent_vars %} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.dirname \(aqtest/path/filename.config\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.diskusage(path) Recursively calculate disk usage of path and return it in bytes .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.diskusage /path/to/check .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.extract_hash(hash_fn, hash_type=\(aqsha256\(aq, file_name=\(aq\(aq, source=\(aq\(aq, source_hash_name=None) Changed in version 2016.3.5: Prior to this version, only the \fBfile_name\fP argument was considered for filename matches in the hash file. This would be problematic for cases in which the user was relying on a remote checksum file that they do not control, and they wished to use a different name for that file on the minion from the filename on the remote server (and in the checksum file). For example, managing \fB/tmp/myfile.tar.gz\fP when the remote file was at \fBhttps://mydomain.tld/different_name.tar.gz\fP\&. The \fI\%file.managed\fP state now also passes this function the source URI as well as the \fBsource_hash_name\fP (if specified). In cases where \fBsource_hash_name\fP is specified, it takes precedence over both the \fBfile_name\fP and \fBsource\fP\&. When it is not specified, \fBfile_name\fP takes precedence over \fBsource\fP\&. This allows for better capability for matching hashes. .sp Changed in version 2016.11.0: File name and source URI matches are no longer disregarded when \fBsource_hash_name\fP is specified. They will be used as fallback matches if there is no match to the \fBsource_hash_name\fP value. .sp This routine is called from the \fI\%file.managed\fP state to pull a hash from a remote file. Regular expressions are used line by line on the \fBsource_hash\fP file, to find a potential candidate of the indicated hash type. This avoids many problems of arbitrary file layout rules. It specifically permits pulling hash codes from debian \fB*.dsc\fP files. .sp If no exact match of a hash and filename are found, then the first hash found (if any) will be returned. If no hashes at all are found, then \fBNone\fP will be returned. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C openerp_7.0\-latest\-1.tar.gz: file.managed: \- name: /tmp/openerp_7.0\-20121227\-075624\-1_all.deb \- source: http://nightly.openerp.com/7.0/nightly/deb/openerp_7.0\-20121227\-075624\-1.tar.gz \- source_hash: http://nightly.openerp.com/7.0/nightly/deb/openerp_7.0\-20121227\-075624\-1.dsc .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.extract_hash /path/to/hash/file sha512 /etc/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.file_exists(path) Tests to see if path is a valid file. Returns True/False. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.file_exists /etc/passwd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.find(path, *args, **kwargs) Approximate the Unix \fBfind(1)\fP command and return a list of paths that meet the specified criteria. .sp The options include match criteria: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C name = path\-glob # case sensitive iname = path\-glob # case insensitive regex = path\-regex # case sensitive iregex = path\-regex # case insensitive type = file\-types # match any listed type user = users # match any listed user group = groups # match any listed group size = [+\-]number[size\-unit] # default unit = byte mtime = interval # modified since date grep = regex # search file contents .ft P .fi .UNINDENT .UNINDENT .sp and/or actions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C delete [= file\-types] # default type = \(aqf\(aq exec = command [arg ...] # where {} is replaced by pathname print [= print\-opts] .ft P .fi .UNINDENT .UNINDENT .sp and/or depth criteria: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C maxdepth = maximum depth to transverse in path mindepth = minimum depth to transverse before checking files or directories .ft P .fi .UNINDENT .UNINDENT .sp The default action is \fBprint=path\fP .sp \fBpath\-glob\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C * = match zero or more chars ? = match any char [abc] = match a, b, or c [!abc] or [^abc] = match anything except a, b, and c [x\-y] = match chars x through y [!x\-y] or [^x\-y] = match anything except chars x through y {a,b,c} = match a or b or c .ft P .fi .UNINDENT .UNINDENT .sp \fBpath\-regex\fP: a Python Regex (regular expression) pattern to match pathnames .sp \fBfile\-types\fP: a string of one or more of the following: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C a: all file types b: block device c: character device d: directory p: FIFO (named pipe) f: plain file l: symlink s: socket .ft P .fi .UNINDENT .UNINDENT .sp \fBusers\fP: a space and/or comma separated list of user names and/or uids .sp \fBgroups\fP: a space and/or comma separated list of group names and/or gids .sp \fBsize\-unit\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C b: bytes k: kilobytes m: megabytes g: gigabytes t: terabytes .ft P .fi .UNINDENT .UNINDENT .sp interval: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [<num>w] [<num>d] [<num>h] [<num>m] [<num>s] where: w: week d: day h: hour m: minute s: second .ft P .fi .UNINDENT .UNINDENT .sp print\-opts: a comma and/or space separated list of one or more of the following: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C group: group name md5: MD5 digest of file contents mode: file permissions (as integer) mtime: last modification time (as time_t) name: file basename path: file absolute path size: file size in bytes type: file type user: user name .ft P .fi .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.find / type=f name=\e*.bak size=+10m salt \(aq*\(aq file.find /var mtime=+30d size=+10m print=path,size,mtime salt \(aq*\(aq file.find /var/log name=\e*.[0\-9] mtime=+30d size=+10m delete .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_devmm(name) Get major/minor info from a device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_devmm /dev/chr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_diff(file1, file2, saltenv=\(aqbase\(aq, show_filenames=True, show_changes=True, template=False, source_hash_file1=None, source_hash_file2=None) Return unified diff of two files .INDENT 7.0 .TP .B file1 The first file to feed into the diff utility .sp Changed in version 2018.3.0: Can now be either a local or remote file. In earlier releases, thuis had to be a file local to the minion. .TP .B file2 The second file to feed into the diff utility .sp Changed in version 2018.3.0: Can now be either a local or remote file. In earlier releases, this had to be a file on the salt fileserver (i.e. \fBsalt://somefile.txt\fP) .TP .B show_filenames: True Set to \fBFalse\fP to hide the filenames in the top two lines of the diff. .TP .B show_changes: True If set to \fBFalse\fP, and there are differences, then instead of a diff a simple message stating that show_changes is set to \fBFalse\fP will be returned. .TP .B template: False Set to \fBTrue\fP if two templates are being compared. This is not useful except for within states, with the \fBobfuscate_templates\fP option set to \fBTrue\fP\&. .sp New in version 2018.3.0. .TP .B source_hash_file1 If \fBfile1\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. .TP .B source_hash_file2 If \fBfile2\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 file.get_diff /home/fred/.vimrc salt://users/fred/.vimrc salt \(aq*\(aq file.get_diff /tmp/foo.txt /tmp/bar.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_gid(path, follow_symlinks=True) Return the id of the group that owns a given file .INDENT 7.0 .TP .B path file or directory of which to get the gid .TP .B follow_symlinks indicated if symlinks should be followed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_gid /etc/passwd .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 0.16.4: \fBfollow_symlinks\fP option added .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_group(path, follow_symlinks=True) Return the group that owns a given file .INDENT 7.0 .TP .B path file or directory of which to get the group .TP .B follow_symlinks indicated if symlinks should be followed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_group /etc/passwd .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 0.16.4: \fBfollow_symlinks\fP option added .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_hash(path, form=\(aqsha256\(aq, chunk_size=65536) Get the hash sum of a file .INDENT 7.0 .TP .B This is better than \fBget_sum\fP for the following reasons: .INDENT 7.0 .IP \(bu 2 It does not read the entire file into memory. .IP \(bu 2 .INDENT 2.0 .TP .B It does not return a string on error. The returned value of \fBget_sum\fP cannot really be trusted since it is vulnerable to collisions: \fBget_sum(..., \(aqxyz\(aq) == \(aqHash xyz not supported\(aq\fP .UNINDENT .UNINDENT .TP .B path path to the file or directory .TP .B form desired sum format .TP .B chunk_size amount to sum at once .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_hash /etc/shadow .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_managed(name, template, source, source_hash, source_hash_name, user, group, mode, attrs, saltenv, context, defaults, skip_verify=False, verify_ssl=True, use_etag=False, source_hash_sig=None, signed_by_any=None, signed_by_all=None, keyring=None, gnupghome=None, **kwargs) Return the managed file data for file.managed .INDENT 7.0 .TP .B name location where the file lives on the server .TP .B template template format .TP .B source managed source file .TP .B source_hash hash of the source file .TP .B source_hash_name When \fBsource_hash\fP refers to a remote file, this specifies the filename to look for in that file. .sp New in version 2016.3.5. .TP .B user Owner of file .TP .B group Group owner of file .TP .B mode Permissions of file .TP .B attrs Attributes of file .sp New in version 2018.3.0. .TP .B context Variables to add to the template context .TP .B defaults Default values of for context_dict .TP .B skip_verify If \fBTrue\fP, hash verification of remote file sources (\fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP) will be skipped, and the \fBsource_hash\fP argument will be ignored. .sp New in version 2016.3.0. .TP .B verify_ssl If \fBFalse\fP, remote https file sources (\fBhttps://\fP) and source_hash will not attempt to validate the servers certificate. Default is True. .sp New in version 3002. .TP .B use_etag If \fBTrue\fP, remote http/https file sources will attempt to use the ETag header to determine if the remote file needs to be downloaded. This provides a lightweight mechanism for promptly refreshing files changed on a web server without requiring a full hash comparison via the \fBsource_hash\fP parameter. .sp New in version 3005. .TP .B source_hash_sig When \fBsource\fP is a remote file source, \fBsource_hash\fP is a file, \fBskip_verify\fP is not true and \fBuse_etag\fP is not true, ensure a valid GPG signature exists on the source hash file. Set this to \fBtrue\fP for an inline (clearsigned) signature, or to a file URI retrievable by \fI:py:func:\(gacp.cache_file <salt.modules.cp.cache_file>\fP for a detached one. .sp New in version 3007.0. .TP .B signed_by_any When verifying \fBsource_hash_sig\fP, require at least one valid signature from one of a list of key fingerprints. This is passed to \fI\%gpg.verify\fP\&. .sp New in version 3007.0. .TP .B signed_by_all When verifying \fBsource_hash_sig\fP, require a valid signature from each of the key fingerprints in this list. This is passed to \fI\%gpg.verify\fP\&. .sp New in version 3007.0. .TP .B keyring When verifying \fBsource_hash_sig\fP, use this keyring. .sp New in version 3007.0. .TP .B gnupghome When verifying \fBsource_hash_sig\fP, use this GnuPG home. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_managed /etc/httpd/conf.d/httpd.conf jinja salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\(aq None root root \(aq755\(aq base None None .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_mode(path, follow_symlinks=True) Return the mode of a file .INDENT 7.0 .TP .B path file or directory of which to get the mode .TP .B follow_symlinks indicated if symlinks should be followed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_mode /etc/passwd .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.1.0: \fBfollow_symlinks\fP option added .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_selinux_context(path) Get an SELinux context from a given path .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_selinux_context /etc/hosts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_source_sum(file_name=\(aq\(aq, source=\(aq\(aq, source_hash=None, source_hash_name=None, saltenv=\(aqbase\(aq, verify_ssl=True, source_hash_sig=None, signed_by_any=None, signed_by_all=None, keyring=None, gnupghome=None) New in version 2016.11.0. .sp Used by \fI\%file.get_managed\fP to obtain the hash and hash type from the parameters specified below. .INDENT 7.0 .TP .B file_name Optional file name being managed, for matching with \fI\%file.extract_hash\fP\&. .TP .B source Source file, as used in \fI\%file\fP and other states. If \fBsource_hash\fP refers to a file containing hashes, then this filename will be used to match a filename in that file. If the \fBsource_hash\fP is a hash expression, then this argument will be ignored. .TP .B source_hash Hash file/expression, as used in \fI\%file\fP and other states. If this value refers to a remote URL or absolute path to a local file, it will be cached and \fI\%file.extract_hash\fP will be used to obtain a hash from it. .TP .B source_hash_name Specific file name to look for when \fBsource_hash\fP refers to a remote file, used to disambiguate ambiguous matches. .TP .B saltenv: base Salt fileserver environment from which to retrieve the source_hash. This value will only be used when \fBsource_hash\fP refers to a file on the Salt fileserver (i.e. one beginning with \fBsalt://\fP). .TP .B verify_ssl If \fBFalse\fP, remote https file sources (\fBhttps://\fP) and source_hash will not attempt to validate the servers certificate. Default is True. .sp New in version 3002. .TP .B source_hash_sig When \fBsource\fP is a remote file source and \fBsource_hash\fP is a file, ensure a valid GPG signature exists on the source hash file. Set this to \fBtrue\fP for an inline (clearsigned) signature, or to a file URI retrievable by \fI:py:func:\(gacp.cache_file <salt.modules.cp.cache_file>\fP for a detached one. .sp New in version 3007.0. .TP .B signed_by_any When verifying \fBsource_hash_sig\fP, require at least one valid signature from one of a list of key fingerprints. This is passed to \fI\%gpg.verify\fP\&. .sp New in version 3007.0. .TP .B signed_by_all When verifying \fBsource_hash_sig\fP, require a valid signature from each of the key fingerprints in this list. This is passed to \fI\%gpg.verify\fP\&. .sp New in version 3007.0. .TP .B keyring When verifying \fBsource_hash_sig\fP, use this keyring. .sp New in version 3007.0. .TP .B gnupghome When verifying \fBsource_hash_sig\fP, use this GnuPG home. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_source_sum /tmp/foo.tar.gz source=http://mydomain.tld/foo.tar.gz source_hash=499ae16dcae71eeb7c3a30c75ea7a1a6 salt \(aq*\(aq file.get_source_sum /tmp/foo.tar.gz source=http://mydomain.tld/foo.tar.gz source_hash=https://mydomain.tld/hashes.md5 salt \(aq*\(aq file.get_source_sum /tmp/foo.tar.gz source=http://mydomain.tld/foo.tar.gz source_hash=https://mydomain.tld/hashes.md5 source_hash_name=./dir2/foo.tar.gz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_sum(path, form=\(aqsha256\(aq) Return the checksum for the given file. The following checksum algorithms are supported: .INDENT 7.0 .IP \(bu 2 md5 .IP \(bu 2 sha1 .IP \(bu 2 sha224 .IP \(bu 2 sha256 \fB(default)\fP .IP \(bu 2 sha384 .IP \(bu 2 sha512 .UNINDENT .INDENT 7.0 .TP .B path path to the file or directory .TP .B form desired sum format .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_sum /etc/passwd sha512 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_uid(path, follow_symlinks=True) Return the id of the user that owns a given file .INDENT 7.0 .TP .B path file or directory of which to get the uid .TP .B follow_symlinks indicated if symlinks should be followed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_uid /etc/passwd .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 0.16.4: \fBfollow_symlinks\fP option added .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_user(path, follow_symlinks=True) Return the user that owns a given file .INDENT 7.0 .TP .B path file or directory of which to get the user .TP .B follow_symlinks indicated if symlinks should be followed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_user /etc/passwd .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 0.16.4: \fBfollow_symlinks\fP option added .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.gid_to_group(gid) Convert the group id to the group name on this system .INDENT 7.0 .TP .B gid gid to convert to a group name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.gid_to_group 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.grep(path, pattern, *opts) Grep for a string in the specified file .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function\(aqs return value is slated for refinement in future versions of Salt .sp Windows does not support the \fBgrep\fP functionality. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path Path to the file to be searched .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Globbing is supported (i.e. \fB/var/log/foo/*.log\fP, but if globbing is being used then the path should be quoted to keep the shell from attempting to expand the glob expression. .UNINDENT .UNINDENT .TP .B pattern Pattern to match. For example: \fBtest\fP, or \fBa[0\-5]\fP .TP .B opts Additional command\-line flags to pass to the grep command. For example: \fB\-v\fP, or \fB\-i \-B2\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The options should come after a double\-dash (as shown in the examples below) to keep Salt\(aqs own argument parser from interpreting them. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.grep /etc/passwd nobody salt \(aq*\(aq file.grep /etc/sysconfig/network\-scripts/ifcfg\-eth0 ipaddr \-\- \-i salt \(aq*\(aq file.grep /etc/sysconfig/network\-scripts/ifcfg\-eth0 ipaddr \-\- \-i \-B2 salt \(aq*\(aq file.grep \(dq/etc/sysconfig/network\-scripts/*\(dq ipaddr \-\- \-i \-l .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.group_to_gid(group) Convert the group to the gid on this system .INDENT 7.0 .TP .B group group to convert to its gid .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.group_to_gid root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.is_blkdev(name) Check if a file exists and is a block device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.is_blkdev /dev/blk .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.is_chrdev(name) Check if a file exists and is a character device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.is_chrdev /dev/chr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.is_fifo(name) Check if a file exists and is a FIFO. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.is_fifo /dev/fifo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.is_hardlink(path) Check if the path is a hard link by verifying that the number of links is larger than 1 .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.is_hardlink /path/to/link .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.is_link(path) Check if the path is a symbolic link .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.is_link /path/to/link .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.join(*args) Return a normalized file system path for the underlying OS .sp New in version 2014.7.0. .sp This can be useful at the CLI but is frequently useful when scripting combining path variables: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set www_root = \(aq/var\(aq %} {% set app_dir = \(aqmyapp\(aq %} myapp_config: file: \- managed \- name: {{ salt[\(aqfile.join\(aq](www_root, app_dir, \(aqconfig.yaml\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.join \(aq/\(aq \(aqusr\(aq \(aqlocal\(aq \(aqbin\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.lchown(path, user, group) Chown a file, pass the file the desired user and group without following symlinks. .INDENT 7.0 .TP .B path path to the file or directory .TP .B user user owner .TP .B group group owner .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.chown /etc/passwd root root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.line(path, content=None, match=None, mode=None, location=None, before=None, after=None, show_changes=True, backup=False, quiet=False, indent=True) New in version 2015.8.0. .sp Line\-focused editing of a file. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBfile.line\fP exists for historic reasons, and is not generally recommended. It has a lot of quirks. You may find \fBfile.replace\fP to be more suitable. .UNINDENT .UNINDENT .sp \fBfile.line\fP is most useful if you have single lines in a file (potentially a config file) that you would like to manage. It can remove, add, and replace a single line at a time. .INDENT 7.0 .TP .B path Filesystem path to the file to be edited. .TP .B content Content of the line. Allowed to be empty if \fBmode=\(aqdelete\(aq\fP\&. .TP .B match Match the target line for an action by a fragment of a string or regular expression. .sp If neither \fBbefore\fP nor \fBafter\fP are provided, and \fBmatch\fP is also \fBNone\fP, match falls back to the \fBcontent\fP value. .TP .B mode Defines how to edit a line. One of the following options is required: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B ensure If line does not exist, it will be added. If \fBbefore\fP and \fBafter\fP are specified either zero lines, or lines that contain the \fBcontent\fP line are allowed to be in between \fBbefore\fP and \fBafter\fP\&. If there are lines, and none of them match then it will produce an error. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B replace If line already exists, the entire line will be replaced. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B delete Delete the line, if found. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B insert Nearly identical to \fBensure\fP\&. If a line does not exist, it will be added. .sp The differences are that multiple (and non\-matching) lines are alloweed between \fBbefore\fP and \fBafter\fP, if they are specified. The line will always be inserted right before \fBbefore\fP\&. \fBinsert\fP also allows the use of \fBlocation\fP to specify that the line should be added at the beginning or end of the file. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If \fBmode=\(aqinsert\(aq\fP is used, at least one of \fBlocation\fP, \fBbefore\fP, or \fBafter\fP is required. If \fBlocation\fP is used, \fBbefore\fP and \fBafter\fP are ignored. .UNINDENT .UNINDENT .TP .B location In \fBmode=\(aqinsert\(aq\fP only, whether to place the \fBcontent\fP at the beginning or end of a the file. If \fBlocation\fP is provided, \fBbefore\fP and \fBafter\fP are ignored. Valid locations: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B start Place the content at the beginning of the file. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B end Place the content at the end of the file. .UNINDENT .UNINDENT .TP .B before Regular expression or an exact case\-sensitive fragment of the string. Will be tried as \fBboth\fP a regex \fBand\fP a part of the line. Must match \fBexactly\fP one line in the file. This value is only used in \fBensure\fP and \fBinsert\fP modes. The \fBcontent\fP will be inserted just before this line, with matching indentation unless \fBindent=False\fP\&. .TP .B after Regular expression or an exact case\-sensitive fragment of the string. Will be tried as \fBboth\fP a regex \fBand\fP a part of the line. Must match \fBexactly\fP one line in the file. This value is only used in \fBensure\fP and \fBinsert\fP modes. The \fBcontent\fP will be inserted directly after this line, unless \fBbefore\fP is also provided. If \fBbefore\fP is not provided, indentation will match this line, unless \fBindent=False\fP\&. .TP .B show_changes Output a unified diff of the old file and the new file. If \fBFalse\fP return a boolean if any changes were made. Default is \fBTrue\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Using this option will store two copies of the file in\-memory (the original version and the edited version) in order to generate the diff. .UNINDENT .UNINDENT .TP .B backup Create a backup of the original file with the extension: \(dqYear\-Month\-Day\-Hour\-Minutes\-Seconds\(dq. .TP .B quiet Do not raise any exceptions. E.g. ignore the fact that the file that is tried to be edited does not exist and nothing really happened. .TP .B indent Keep indentation with the previous line. This option is not considered when the \fBdelete\fP mode is specified. Default is \fBTrue\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.line /etc/nsswitch.conf \(dqnetworks: files dns\(dq after=\(dqhosts:.*?\(dq mode=\(aqensure\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If an equal sign (\fB=\fP) appears in an argument to a Salt command, it is interpreted as a keyword argument in the format of \fBkey=val\fP\&. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.line /path/to/file content=\(dqCREATEMAIL_SPOOL=no\(dq match=\(dqCREATE_MAIL_SPOOL=yes\(dq mode=\(dqreplace\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBExamples:\fP .sp Here\(aqs a simple config file. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [some_config] # Some config file # this line will go away here=False away=True goodybe=away .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \e* file.line /some/file.conf mode=delete match=away .ft P .fi .UNINDENT .UNINDENT .sp This will produce: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [some_config] # Some config file here=False away=True goodbye=away .ft P .fi .UNINDENT .UNINDENT .sp If that command is executed 2 more times, this will be the result: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [some_config] # Some config file here=False .ft P .fi .UNINDENT .UNINDENT .sp If we reset the file to its original state and run .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \e* file.line /some/file.conf mode=replace match=away content=here .ft P .fi .UNINDENT .UNINDENT .sp Three passes will this state will result in this file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [some_config] # Some config file here here=False here here .ft P .fi .UNINDENT .UNINDENT .sp Each pass replacing the first line found. .sp Given this file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C insert after me something insert before me .ft P .fi .UNINDENT .UNINDENT .sp The following command .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \e* file.line /some/file.txt mode=insert after=\(dqinsert after me\(dq before=\(dqinsert before me\(dq content=thrice .ft P .fi .UNINDENT .UNINDENT .sp If that command is executed 3 times, the result will be: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C insert after me something thrice thrice thrice insert before me .ft P .fi .UNINDENT .UNINDENT .sp If the mode is \fBensure\fP instead, it will fail each time. To succeed, we need to remove the incorrect line between before and after: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C insert after me insert before me .ft P .fi .UNINDENT .UNINDENT .sp With an ensure mode, this will insert \fBthrice\fP the first time and make no changes for subsequent calls. For something simple this is fine, but if you have instead blocks like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Begin SomeBlock foo = bar End Begin AnotherBlock another = value End .ft P .fi .UNINDENT .UNINDENT .sp And you try to use ensure this way: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \e* file.line /tmp/fun.txt mode=\(dqensure\(dq content=\(dqthis = should be my content\(dq after=\(dqBegin SomeBlock\(dq before=\(dqEnd\(dq .ft P .fi .UNINDENT .UNINDENT .sp This will fail because there are multiple \fBEnd\fP lines. Without that problem, it still would fail because there is a non\-matching line, \fBfoo = bar\fP\&. Ensure \fBonly\fP allows either zero, or the matching line present to be present in between \fBbefore\fP and \fBafter\fP\&. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.link(src, path) New in version 2014.1.0. .sp Create a hard link to a file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.link /path/to/file /path/to/link .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.list_backup(path, limit=None) This function is an alias of \fBlist_backups\fP\&. .INDENT 7.0 .INDENT 3.5 New in version 0.17.0. .sp Lists the previous versions of a file backed up using Salt\(aqs \fI\%file state backup\fP system. .INDENT 0.0 .TP .B path The path on the minion to check for backups .TP .B limit Limit the number of results to the most recent N backups .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.list_backups /foo/bar/baz.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.list_backups(path, limit=None) New in version 0.17.0. .sp Lists the previous versions of a file backed up using Salt\(aqs \fI\%file state backup\fP system. .INDENT 7.0 .TP .B path The path on the minion to check for backups .TP .B limit Limit the number of results to the most recent N backups .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.list_backups /foo/bar/baz.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.list_backups_dir(path, limit=None) Lists the previous versions of a directory backed up using Salt\(aqs \fI\%file state backup\fP system. .INDENT 7.0 .TP .B path The directory on the minion to check for backups .TP .B limit Limit the number of results to the most recent N backups .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.list_backups_dir /foo/bar/baz/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.lsattr(path) New in version 2018.3.0. .sp Changed in version 2018.3.1: If \fBlsattr\fP is not installed on the system, \fBNone\fP is returned. .sp Changed in version 2018.3.4: If on \fBAIX\fP, \fBNone\fP is returned even if in filesystem as lsattr on \fBAIX\fP is not the same thing as the linux version. .sp Obtain the modifiable attributes of the given file. If path is to a directory, an empty list is returned. .INDENT 7.0 .TP .B path path to file to obtain attributes of. File/directory must exist. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.lsattr foo1.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.lstat(path) New in version 2014.1.0. .sp Returns the lstat attributes for the given file or dir. Does not support symbolic links. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.lstat /path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.makedirs_(path, user=None, group=None, mode=None) Ensure that the directory containing this path is available. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The path must end with a trailing slash otherwise the directory/directories will be created up to the parent directory. For example if path is \fB/opt/code\fP, then it would be treated as \fB/opt/\fP but if the path ends with a trailing slash like \fB/opt/code/\fP, then it would be treated as \fB/opt/code/\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.makedirs /opt/code/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.makedirs_perms(name, user=None, group=None, mode=\(aq0755\(aq) Taken and modified from os.makedirs to set user, group and mode for each directory created. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.makedirs_perms /opt/code .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.manage_file(name, sfn, ret, source, source_sum, user, group, mode, attrs, saltenv, backup, makedirs=False, template=None, show_changes=True, contents=None, dir_mode=None, follow_symlinks=True, skip_verify=False, keep_mode=False, encoding=None, encoding_errors=\(aqstrict\(aq, seuser=None, serole=None, setype=None, serange=None, verify_ssl=True, use_etag=False, signature=None, source_hash_sig=None, signed_by_any=None, signed_by_all=None, keyring=None, gnupghome=None, **kwargs) Checks the destination against what was retrieved with get_managed and makes the appropriate modifications (if necessary). .INDENT 7.0 .TP .B name location to place the file .TP .B sfn location of cached file on the minion .sp This is the path to the file stored on the minion. This file is placed on the minion using cp.cache_file. If the hash sum of that file matches the source_sum, we do not transfer the file to the minion again. .sp This file is then grabbed and if it has template set, it renders the file to be placed into the correct place on the system using salt.files.utils.copyfile() .TP .B ret The initial state return data structure. Pass in \fBNone\fP to use the default structure. .TP .B source file reference on the master .TP .B source_sum sum hash for source .TP .B user user owner .TP .B group group owner .TP .B backup backup_mode .TP .B attrs attributes to be set on file: \(aq\(aq means remove all of them .sp New in version 2018.3.0. .TP .B makedirs make directories if they do not exist .TP .B template format of templating .TP .B show_changes Include diff in state return .TP .B contents: contents to be placed in the file .TP .B dir_mode mode for directories created with makedirs .TP .B skip_verify: False If \fBTrue\fP, hash verification of remote file sources (\fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP) will be skipped, and the \fBsource_hash\fP argument will be ignored. .sp New in version 2016.3.0. .TP .B keep_mode: False If \fBTrue\fP, and the \fBsource\fP is a file from the Salt fileserver (or a local file on the minion), the mode of the destination file will be set to the mode of the source file. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 keep_mode does not work with salt\-ssh. .sp As a consequence of how the files are transferred to the minion, and the inability to connect back to the master with salt\-ssh, salt is unable to stat the file as it exists on the fileserver and thus cannot mirror the mode on the salt\-ssh minion .UNINDENT .UNINDENT .TP .B encoding If specified, then the specified encoding will be used. Otherwise, the file will be encoded using the system locale (usually UTF\-8). See \fI\%https://docs.python.org/3/library/codecs.html#standard\-encodings\fP for the list of available encodings. .sp New in version 2017.7.0. .TP .B encoding_errors: \(aqstrict\(aq Default is \fB\(ga\(aqstrict\(aq\(ga\fP\&. See \fI\%https://docs.python.org/2/library/codecs.html#codec\-base\-classes\fP for the error handling schemes. .sp New in version 2017.7.0. .TP .B seuser selinux user attribute .sp New in version 3001. .TP .B serange selinux range attribute .sp New in version 3001. .TP .B setype selinux type attribute .sp New in version 3001. .TP .B serange selinux range attribute .sp New in version 3001. .TP .B verify_ssl If \fBFalse\fP, remote https file sources (\fBhttps://\fP) will not attempt to validate the servers certificate. Default is True. .sp New in version 3002. .TP .B use_etag If \fBTrue\fP, remote http/https file sources will attempt to use the ETag header to determine if the remote file needs to be downloaded. This provides a lightweight mechanism for promptly refreshing files changed on a web server without requiring a full hash comparison via the \fBsource_hash\fP parameter. .sp New in version 3005. .TP .B signature Ensure a valid GPG signature exists on the selected \fBsource\fP file. Set this to true for inline signatures, or to a file URI retrievable by \fI:py:func:\(gacp.cache_file <salt.modules.cp.cache_file>\fP for a detached one. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A signature is only enforced directly after caching the file, before it is moved to its final destination. Existing target files (with the correct checksum) will neither be checked nor deleted. .sp It will be enforced regardless of source type and will be required on the final output, therefore this does not lend itself well when templates are rendered. The file will not be modified, meaning inline signatures are not removed. .UNINDENT .UNINDENT .sp New in version 3007.0. .TP .B source_hash_sig When \fBsource\fP is a remote file source, \fBsource_hash\fP is a file, \fBskip_verify\fP is not true and \fBuse_etag\fP is not true, ensure a valid GPG signature exists on the source hash file. Set this to \fBtrue\fP for an inline (clearsigned) signature, or to a file URI retrievable by \fI:py:func:\(gacp.cache_file <salt.modules.cp.cache_file>\fP for a detached one. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A signature on the \fBsource_hash\fP file is enforced regardless of changes since its contents are used to check if an existing file is in the correct state \- but only for remote sources! As for \fBsignature\fP, existing target files will not be modified, only the cached source_hash and source_hash_sig files will be removed. .UNINDENT .UNINDENT .sp New in version 3007.0. .TP .B signed_by_any When verifying signatures either on the managed file or its source hash file, require at least one valid signature from one of a list of key fingerprints. This is passed to \fI\%gpg.verify\fP\&. .sp New in version 3007.0. .TP .B signed_by_all When verifying signatures either on the managed file or its source hash file, require a valid signature from each of the key fingerprints in this list. This is passed to \fI\%gpg.verify\fP\&. .sp New in version 3007.0. .TP .B keyring When verifying signatures, use this keyring. .sp New in version 3007.0. .TP .B gnupghome When verifying signatures, use this GnuPG home. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.manage_file /etc/httpd/conf.d/httpd.conf \(aq\(aq \(aq{}\(aq salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\(aq root root \(aq755\(aq \(aq\(aq base \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.7.0: \fBfollow_symlinks\fP option added .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.mkdir(dir_path, user=None, group=None, mode=None) Ensure that a directory is available. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.mkdir /opt/jetty/context .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.mknod(name, ntype, major=0, minor=0, user=None, group=None, mode=\(aq0600\(aq) New in version 0.17.0. .sp Create a block device, character device, or fifo pipe. Identical to the gnu mknod. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.mknod /dev/chr c 180 31 salt \(aq*\(aq file.mknod /dev/blk b 8 999 salt \(aq*\(aq file.nknod /dev/fifo p .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.mknod_blkdev(name, major, minor, user=None, group=None, mode=\(aq0660\(aq) New in version 0.17.0. .sp Create a block device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.mknod_blkdev /dev/blk 8 999 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.mknod_chrdev(name, major, minor, user=None, group=None, mode=\(aq0660\(aq) New in version 0.17.0. .sp Create a character device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.mknod_chrdev /dev/chr 180 31 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.mknod_fifo(name, user=None, group=None, mode=\(aq0660\(aq) New in version 0.17.0. .sp Create a FIFO pipe. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.mknod_fifo /dev/fifo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.move(src, dst, disallow_copy_and_unlink=False) Move a file or directory .INDENT 7.0 .TP .B disallow_copy_and_unlink If \fBTrue\fP, the operation is offloaded to the \fBfile.rename\fP execution module function. This will use \fBos.rename\fP underneath, which will fail in the event that \fBsrc\fP and \fBdst\fP are on different filesystems. If \fBFalse\fP (the default), \fBshutil.move\fP will be used in order to fall back on a \(dqcopy then unlink\(dq approach, which is required for moving across filesystems. .sp New in version 3006.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.move /path/to/src /path/to/dst .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.normpath(path) Returns Normalize path, eliminating double slashes, etc. .sp New in version 2015.5.0. .sp This can be useful at the CLI but is frequently useful when scripting. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- from salt[\(aqfile.normpath\(aq](tpldir + \(aq/../vars.jinja\(aq) import parent_vars %} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.normpath \(aqa/b/c/..\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.open_files(by_pid=False) Return a list of all physical open files on the system. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.open_files salt \(aq*\(aq file.open_files by_pid=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.pardir() Return the relative parent directory path symbol for underlying OS .sp New in version 2014.7.0. .sp This can be useful when constructing Salt Formulas. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set pardir = salt[\(aqfile.pardir\(aq]() %} {% set final_path = salt[\(aqfile.join\(aq](\(aqsubdir\(aq, pardir, \(aqconfdir\(aq) %} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.pardir .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.patch(originalfile, patchfile, options=\(aq\(aq, dry_run=False) New in version 0.10.4. .sp Apply a patch to a file or directory. .sp Equivalent to: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C patch <options> \-i <patchfile> <originalfile> .ft P .fi .UNINDENT .UNINDENT .sp Or, when a directory is patched: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C patch <options> \-i <patchfile> \-d <originalfile> \-p0 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B originalfile The full path to the file or directory to be patched .TP .B patchfile A patch file to apply to \fBoriginalfile\fP .TP .B options Options to pass to patch. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Windows now supports using patch as of 3004. .sp In order to use this function in Windows, please install the patch binary through your own means and ensure it\(aqs found in the system Path. If installing through git\-for\-windows, please select the optional \(dqUse Git and optional Unix tools from the Command Prompt\(dq option when installing Git. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.patch /opt/file.txt /tmp/file.txt.patch salt \(aq*\(aq file.patch C:\efile1.txt C:\efile3.patch .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.path_exists_glob(path) Tests to see if path after expansion is a valid path (file or directory). Expansion allows usage of ? * and character ranges []. Tilde expansion is not supported. Returns True/False. .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.path_exists_glob /etc/pam*/pass* .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.prepend(path, *args, **kwargs) New in version 2014.7.0. .sp Prepend text to the beginning of a file .INDENT 7.0 .TP .B path path to file .TP .B \fI*args\fP strings to prepend to the file .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.prepend /etc/motd \e \(dqWith all thine offerings thou shalt offer salt.\(dq \e \(dqSalt is what makes things taste bad when it isn\(aqt in them.\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .IP "Attention" .sp If you need to pass a string to append and that string contains an equal sign, you \fBmust\fP include the argument name, args. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.prepend /etc/motd args=\(aqcheese=spam\(aq salt \(aq*\(aq file.prepend /etc/motd args=\(dq[\(aqcheese=spam\(aq,\(aqspam=cheese\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.psed(path, before, after, limit=\(aq\(aq, backup=\(aq.bak\(aq, flags=\(aqgMS\(aq, escape_all=False, multi=False) Deprecated since version 0.17.0: Use \fI\%replace()\fP instead. .sp Make a simple edit to a file (pure Python version) .sp Equivalent to: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sed <backup> <options> \(dq/<limit>/ s/<before>/<after>/<flags> <file>\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B before A pattern to find in order to replace with \fBafter\fP .TP .B after Text that will replace \fBbefore\fP .TP .B limit: \fB\(aq\(aq\fP An initial pattern to search for before searching for \fBbefore\fP .TP .B backup: \fB\&.bak\fP The file will be backed up before edit with this file extension; \fBWARNING:\fP each time \fBsed\fP/\fBcomment\fP/\fBuncomment\fP is called will overwrite this backup .TP .B flags: \fBgMS\fP .INDENT 7.0 .TP .B Flags to modify the search. Valid values are: .INDENT 7.0 .IP \(bu 2 \fBg\fP: Replace all occurrences of the pattern, not just the first. .IP \(bu 2 \fBI\fP: Ignore case. .IP \(bu 2 \fBL\fP: Make \fB\ew\fP, \fB\eW\fP, \fB\eb\fP, \fB\eB\fP, \fB\es\fP and \fB\eS\fP dependent on the locale. .IP \(bu 2 \fBM\fP: Treat multiple lines as a single line. .IP \(bu 2 \fBS\fP: Make \fI\&.\fP match all characters, including newlines. .IP \(bu 2 \fBU\fP: Make \fB\ew\fP, \fB\eW\fP, \fB\eb\fP, \fB\eB\fP, \fB\ed\fP, \fB\eD\fP, \fB\es\fP and \fB\eS\fP dependent on Unicode. .IP \(bu 2 \fBX\fP: Verbose (whitespace is ignored). .UNINDENT .UNINDENT .TP .B multi: \fBFalse\fP If True, treat the entire file as a single line .UNINDENT .sp Forward slashes and single quotes will be escaped automatically in the \fBbefore\fP and \fBafter\fP patterns. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.sed /etc/httpd/httpd.conf \(aqLogLevel warn\(aq \(aqLogLevel info\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.read(path, binary=False) New in version 2017.7.0. .sp Return the content of the file. .INDENT 7.0 .TP .B Parameters \fBbinary\fP (\fI\%bool\fP) \-\- Whether to read and return binary data .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.read /path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.readdir(path) New in version 2014.1.0. .sp Return a list containing the contents of a directory .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.readdir /path/to/dir/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.readlink(path, canonicalize=False) New in version 2014.1.0. .sp Return the path that a symlink points to .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the symlink .IP \(bu 2 \fBcanonicalize\fP (\fI\%bool\fP) \-\- Get the canonical path eliminating any symbolic links encountered in the path .UNINDENT .TP .B Returns The path that the symlink points to .TP .B Return type \fI\%str\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%SaltInvocationError\fP \-\- path is not absolute .IP \(bu 2 \fI\%SaltInvocationError\fP \-\- path is not a link .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- error reading the symbolic link .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.readlink /path/to/link .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.remove(path, **kwargs) Remove the named file. If a directory is supplied, it will be recursively deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.remove /tmp/foo .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3000: The method now works on all types of file system entries, not just files, directories and symlinks. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.remove_backup(path, backup_id) This function is an alias of \fBdelete_backup\fP\&. .INDENT 7.0 .INDENT 3.5 New in version 0.17.0. .sp Delete a previous version of a file that was backed up using Salt\(aqs \fI\%file state backup\fP system. .INDENT 0.0 .TP .B path The path on the minion to check for backups .TP .B backup_id The numeric id for the backup you wish to delete, as found using \fI\%file.list_backups\fP .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.delete_backup /var/cache/salt/minion/file_backup/home/foo/bar/baz.txt 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.rename(src, dst) Rename a file or directory .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.rename /path/to/src /path/to/dst .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.replace(path, pattern, repl, count=0, flags=8, bufsize=1, append_if_not_found=False, prepend_if_not_found=False, not_found_content=None, backup=\(aq.bak\(aq, dry_run=False, search_only=False, show_changes=True, ignore_if_missing=False, preserve_inode=True, backslash_literal=False) New in version 0.17.0. .sp Replace occurrences of a pattern in a file. If \fBshow_changes\fP is \fBTrue\fP, then a diff of what changed will be returned, otherwise a \fBTrue\fP will be returned when changes are made, and \fBFalse\fP when no changes are made. .sp This is a pure Python implementation that wraps Python\(aqs \fI\%sub()\fP\&. .INDENT 7.0 .TP .B path Filesystem path to the file to be edited. If a symlink is specified, it will be resolved to its target. .TP .B pattern A regular expression, to be matched using Python\(aqs \fI\%search()\fP\&. .TP .B repl The replacement text .TP .B count: 0 Maximum number of pattern occurrences to be replaced. If count is a positive integer \fBn\fP, only \fBn\fP occurrences will be replaced, otherwise all occurrences will be replaced. .TP .B flags (list or int) A list of flags defined in the \fBre\fP module documentation from the Python standard library. Each list item should be a string that will correlate to the human\-friendly flag name. E.g., \fB[\(aqIGNORECASE\(aq, \(aqMULTILINE\(aq]\fP\&. Optionally, \fBflags\fP may be an int, with a value corresponding to the XOR (\fB|\fP) of all the desired flags. Defaults to 8 (which supports \(aqMULTILINE\(aq). .TP .B bufsize (int or str) How much of the file to buffer into memory at once. The default value \fB1\fP processes one line at a time. The special value \fBfile\fP may be specified which will read the entire file into memory before processing. .TP .B append_if_not_found: False New in version 2014.7.0. .sp If set to \fBTrue\fP, and pattern is not found, then the content will be appended to the file. .TP .B prepend_if_not_found: False New in version 2014.7.0. .sp If set to \fBTrue\fP and pattern is not found, then the content will be prepended to the file. .TP .B not_found_content New in version 2014.7.0. .sp Content to use for append/prepend if not found. If None (default), uses \fBrepl\fP\&. Useful when \fBrepl\fP uses references to group in pattern. .TP .B backup: .bak The file extension to use for a backup of the file before editing. Set to \fBFalse\fP to skip making a backup. .TP .B dry_run: False If set to \fBTrue\fP, no changes will be made to the file, the function will just return the changes that would have been made (or a \fBTrue\fP/\fBFalse\fP value if \fBshow_changes\fP is set to \fBFalse\fP). .TP .B search_only: False If set to true, this no changes will be performed on the file, and this function will simply return \fBTrue\fP if the pattern was matched, and \fBFalse\fP if not. .TP .B show_changes: True If \fBTrue\fP, return a diff of changes made. Otherwise, return \fBTrue\fP if changes were made, and \fBFalse\fP if not. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Using this option will store two copies of the file in memory (the original version and the edited version) in order to generate the diff. This may not normally be a concern, but could impact performance if used with large files. .UNINDENT .UNINDENT .TP .B ignore_if_missing: False New in version 2015.8.0. .sp If set to \fBTrue\fP, this function will simply return \fBFalse\fP if the file doesn\(aqt exist. Otherwise, an error will be thrown. .TP .B preserve_inode: True New in version 2015.8.0. .sp Preserve the inode of the file, so that any hard links continue to share the inode with the original filename. This works by \fIcopying\fP the file, reading from the copy, and writing to the file at the original inode. If \fBFalse\fP, the file will be \fImoved\fP rather than copied, and a new file will be written to a new inode, but using the original filename. Hard links will then share an inode with the backup, instead (if using \fBbackup\fP to create a backup copy). .TP .B backslash_literal: False New in version 2016.11.7. .sp Interpret backslashes as literal backslashes for the repl and not escape characters. This will help when using append/prepend so that the backslashes are not interpreted for the repl on the second run of the state. .UNINDENT .sp If an equal sign (\fB=\fP) appears in an argument to a Salt command it is interpreted as a keyword argument in the format \fBkey=val\fP\&. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.replace /path/to/file pattern=\(aq=\(aq repl=\(aq:\(aq salt \(aq*\(aq file.replace /path/to/file pattern=\(dqbind\-address\es*=\(dq repl=\(aqbind\-address:\(aq .ft P .fi .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.replace /etc/httpd/httpd.conf pattern=\(aqLogLevel warn\(aq repl=\(aqLogLevel info\(aq salt \(aq*\(aq file.replace /some/file pattern=\(aqbefore\(aq repl=\(aqafter\(aq flags=\(aq[MULTILINE, IGNORECASE]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.restore_backup(path, backup_id) New in version 0.17.0. .sp Restore a previous version of a file that was backed up using Salt\(aqs \fI\%file state backup\fP system. .INDENT 7.0 .TP .B path The path on the minion to check for backups .TP .B backup_id The numeric id for the backup you wish to restore, as found using \fI\%file.list_backups\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.restore_backup /foo/bar/baz.txt 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.restorecon(path, recursive=False) Reset the SELinux context on a given path .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.restorecon /home/user/.ssh/authorized_keys .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.rmdir(path, recurse=False, verbose=False, older_than=None) New in version 2014.1.0. .sp Changed in version 3006.0: Changed return value for failure to a boolean. .sp Remove the specified directory. Fails if a directory is not empty. .INDENT 7.0 .TP .B recurse When \fBrecurse\fP is set to \fBTrue\fP, all empty directories within the path are pruned. .sp New in version 3006.0. .TP .B verbose When \fBverbose\fP is set to \fBTrue\fP, a dictionary is returned which contains more information about the removal process. .sp New in version 3006.0. .TP .B older_than When \fBolder_than\fP is set to a number, it is used to determine the \fBnumber of days\fP which must have passed since the last modification timestamp before a directory will be allowed to be removed. Setting the value to 0 is equivalent to leaving it at the default of \fBNone\fP\&. .sp New in version 3006.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.rmdir /tmp/foo/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.search(path, pattern, flags=8, bufsize=1, ignore_if_missing=False, multiline=False) New in version 0.17.0. .sp Search for occurrences of a pattern in a file .sp Except for multiline, params are identical to \fI\%replace()\fP\&. .INDENT 7.0 .TP .B multiline If true, inserts \(aqMULTILINE\(aq into \fBflags\fP and sets \fBbufsize\fP to \(aqfile\(aq. .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.search /etc/crontab \(aqmymaintenance.sh\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.sed(path, before, after, limit=\(aq\(aq, backup=\(aq.bak\(aq, options=\(aq\-r \-e\(aq, flags=\(aqg\(aq, escape_all=False, negate_match=False) Deprecated since version 0.17.0: Use \fI\%replace()\fP instead. .sp Make a simple edit to a file .sp Equivalent to: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sed <backup> <options> \(dq/<limit>/ s/<before>/<after>/<flags> <file>\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B before A pattern to find in order to replace with \fBafter\fP .TP .B after Text that will replace \fBbefore\fP .TP .B limit: \fB\(aq\(aq\fP An initial pattern to search for before searching for \fBbefore\fP .TP .B backup: \fB\&.bak\fP The file will be backed up before edit with this file extension; \fBWARNING:\fP each time \fBsed\fP/\fBcomment\fP/\fBuncomment\fP is called will overwrite this backup .TP .B options: \fB\-r \-e\fP Options to pass to sed .TP .B flags: \fBg\fP Flags to modify the sed search; e.g., \fBi\fP for case\-insensitive pattern matching .TP .B negate_match: False Negate the search command (\fB!\fP) .sp New in version 0.17.0. .UNINDENT .sp Forward slashes and single quotes will be escaped automatically in the \fBbefore\fP and \fBafter\fP patterns. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.sed /etc/httpd/httpd.conf \(aqLogLevel warn\(aq \(aqLogLevel info\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.sed_contains(path, text, limit=\(aq\(aq, flags=\(aqg\(aq) Deprecated since version 0.17.0: Use \fI\%search()\fP instead. .sp Return True if the file at \fBpath\fP contains \fBtext\fP\&. Utilizes sed to perform the search (line\-wise search). .sp Note: the \fBp\fP flag will be added to any flags you pass in. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.contains /etc/crontab \(aqmymaintenance.sh\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.seek_read(path, size, offset) New in version 2014.1.0. .sp Seek to a position on a file and read it .INDENT 7.0 .TP .B path path to file .TP .B seek amount to read at once .TP .B offset offset to start into the file .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.seek_read /path/to/file 4096 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.seek_write(path, data, offset) New in version 2014.1.0. .sp Seek to a position on a file and write to it .INDENT 7.0 .TP .B path path to file .TP .B data data to write to file .TP .B offset position in file to start writing .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.seek_write /path/to/file \(aqsome data\(aq 4096 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.set_mode(path, mode) Set the mode of a file .INDENT 7.0 .TP .B path file or directory of which to set the mode .TP .B mode mode to set the path to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.set_mode /etc/passwd 0644 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.set_selinux_context(path, user=None, role=None, type=None, range=None, persist=False) Changed in version 3001: Added persist option .sp Set a specific SELinux label on a given path .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.set_selinux_context path <user> <role> <type> <range> salt \(aq*\(aq file.set_selinux_context /etc/yum.repos.d/epel.repo system_u object_r system_conf_t s0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.source_list(source, source_hash, saltenv) Check the source list and return the source to use .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.source_list salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\(aq base .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.stats(path, hash_type=None, follow_symlinks=True) Return a dict containing the stats for a given file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.stats /etc/passwd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.statvfs(path) New in version 2014.1.0. .sp Perform a statvfs call against the filesystem that the file resides on .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.statvfs /path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.symlink(src, path, force=False, atomic=False, follow_symlinks=True) Create a symbolic link (symlink, soft link) to a file .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsrc\fP (\fI\%str\fP) \-\- The path to a file or directory .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the link. Must be an absolute path .IP \(bu 2 \fBforce\fP (\fI\%bool\fP) \-\- Overwrite an existing symlink with the same name \&.. versionadded:: 3005 .IP \(bu 2 \fBatomic\fP (\fI\%bool\fP) \-\- Use atomic file operations to create the symlink \&.. versionadded:: 3006.0 .IP \(bu 2 \fBfollow_symlinks\fP (\fI\%bool\fP) \-\- If set to \fBFalse\fP, use \fBos.path.lexists()\fP for existence checks instead of \fBos.path.exists()\fP\&. \&.. versionadded:: 3007.0 .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise raises \fBCommandExecutionError\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.symlink /path/to/file /path/to/link .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.touch(name, atime=None, mtime=None) New in version 0.9.5. .sp Just like the \fBtouch\fP command, create a file if it doesn\(aqt exist or simply update the atime and mtime if it already does. .INDENT 7.0 .TP .B atime: Access time in Unix epoch time. Set it to 0 to set atime of the file with Unix date of birth. If this parameter isn\(aqt set, atime will be set with current time. .TP .B mtime: Last modification in Unix epoch time. Set it to 0 to set mtime of the file with Unix date of birth. If this parameter isn\(aqt set, mtime will be set with current time. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.touch /var/log/emptyfile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.truncate(path, length) New in version 2014.1.0. .sp Seek to a position on a file and delete everything after that point .INDENT 7.0 .TP .B path path to file .TP .B length offset into file to truncate .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.truncate /path/to/file 512 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.uid_to_user(uid) Convert a uid to a user name .INDENT 7.0 .TP .B uid uid to convert to a username .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.uid_to_user 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.uncomment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Deprecated since version 0.17.0: Use \fI\%replace()\fP instead. .sp Uncomment specified commented lines in a file .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B regex A regular expression used to find the lines that are to be uncommented. This regex should not include the comment character. A leading \fB^\fP character will be stripped for convenience (for easily switching between comment() and uncomment()). .TP .B char: \fB#\fP The character to remove in order to uncomment a line .TP .B backup: \fB\&.bak\fP The file will be backed up before edit with this file extension; \fBWARNING:\fP each time \fBsed\fP/\fBcomment\fP/\fBuncomment\fP is called will overwrite this backup .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.uncomment /etc/hosts.deny \(aqALL: PARANOID\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.user_to_uid(user) Convert user name to a uid .INDENT 7.0 .TP .B user user name to convert to its uid .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.user_to_uid root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.write(path, *args, **kwargs) New in version 2014.7.0. .sp Write text to a file, overwriting any existing contents. .INDENT 7.0 .TP .B path path to file .TP .B \fI*args\fP strings to write to the file .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.write /etc/motd \e \(dqWith all thine offerings thou shalt offer salt.\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .IP "Attention" .sp If you need to pass a string to append and that string contains an equal sign, you \fBmust\fP include the argument name, args. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.write /etc/motd args=\(aqcheese=spam\(aq salt \(aq*\(aq file.write /etc/motd args=\(dq[\(aqcheese=spam\(aq,\(aqspam=cheese\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.firewalld .sp Support for firewalld. .sp New in version 2015.2.0. .INDENT 0.0 .TP .B salt.modules.firewalld.add_interface(zone, interface, permanent=True) Bind an interface to a zone .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.add_interface zone eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.add_masquerade(zone=None, permanent=True) Enable masquerade on a zone. If zone is omitted, default zone will be used. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.add_masquerade .ft P .fi .UNINDENT .UNINDENT .sp To enable masquerade on a specific zone .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.add_masquerade dmz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.add_port(zone, port, permanent=True, force_masquerade=False) Allow specific ports in a zone. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.add_port internal 443/tcp .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B force_masquerade when a zone is created ensure masquerade is also enabled on that zone. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.add_port_fwd(zone, src, dest, proto=\(aqtcp\(aq, dstaddr=\(aq\(aq, permanent=True, force_masquerade=False) Add port forwarding. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.add_port_fwd public 80 443 tcp .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B force_masquerade when a zone is created ensure masquerade is also enabled on that zone. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.add_rich_rule(zone, rule, permanent=True) Add a rich rule to a zone .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.add_rich_rule zone \(aqrule\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.add_service(service, zone=None, permanent=True) Add a service for zone. If zone is omitted, default zone will be used. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.add_service ssh .ft P .fi .UNINDENT .UNINDENT .sp To assign a service to a specific zone: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.add_service ssh my_zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.add_service_port(service, port) Add a new port to the specified service. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.add_service_port zone 80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.add_service_protocol(service, protocol) Add a new protocol to the specified service. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.add_service_protocol zone ssh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.add_source(zone, source, permanent=True) Bind a source to a zone .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.add_source zone 192.168.1.0/24 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.allow_icmp(zone, icmp, permanent=True) Allow a specific ICMP type on a zone .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.allow_icmp zone echo\-reply .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.block_icmp(zone, icmp, permanent=True) Block a specific ICMP type on a zone .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.block_icmp zone echo\-reply .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.default_zone() Print default zone for connections and interfaces .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.default_zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.delete_service(name, restart=True) Delete an existing service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.delete_service my_service .ft P .fi .UNINDENT .UNINDENT .sp By default firewalld will be reloaded. However, to avoid reloading you need to specify the restart as False .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.delete_service my_service False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.delete_zone(zone, restart=True) Delete an existing zone .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.delete_zone my_zone .ft P .fi .UNINDENT .UNINDENT .sp By default firewalld will be reloaded. However, to avoid reloading you need to specify the restart as False .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.delete_zone my_zone False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.get_icmp_types(permanent=True) Print predefined icmptypes .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.get_icmp_types .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.get_interfaces(zone, permanent=True) List interfaces bound to a zone .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.get_interfaces zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.get_masquerade(zone=None, permanent=True) Show if masquerading is enabled on a zone. If zone is omitted, default zone will be used. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.get_masquerade zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.get_rich_rules(zone, permanent=True) List rich rules bound to a zone .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.get_rich_rules zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.get_service_ports(service) List ports of a service. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.get_service_ports zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.get_service_protocols(service) List protocols of a service. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.get_service_protocols zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.get_services(permanent=True) Print predefined services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.get_services .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.get_sources(zone, permanent=True) List sources bound to a zone .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.get_sources zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.get_zones(permanent=True) Print predefined zones .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.get_zones .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.list_all(zone=None, permanent=True) List everything added for or enabled in a zone .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.list_all .ft P .fi .UNINDENT .UNINDENT .sp List a specific zone .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.list_all my_zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.list_icmp_block(zone, permanent=True) List ICMP blocks on a zone .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewlld.list_icmp_block zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.list_port_fwd(zone, permanent=True) List port forwarding .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.list_port_fwd public .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.list_ports(zone, permanent=True) List all ports in a zone. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.list_ports .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.list_services(zone=None, permanent=True) List services added for zone as a space separated list. If zone is omitted, default zone will be used. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.list_services .ft P .fi .UNINDENT .UNINDENT .sp List a specific zone .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.list_services my_zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.list_zones(permanent=True) List everything added for or enabled in all zones .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.list_zones .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.make_permanent() Make current runtime configuration permanent. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.make_permanent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.new_service(name, restart=True) Add a new service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.new_service my_service .ft P .fi .UNINDENT .UNINDENT .sp By default firewalld will be reloaded. However, to avoid reloading you need to specify the restart as False .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.new_service my_service False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.new_zone(zone, restart=True) Add a new zone .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.new_zone my_zone .ft P .fi .UNINDENT .UNINDENT .sp By default firewalld will be reloaded. However, to avoid reloading you need to specify the restart as False .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.new_zone my_zone False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.reload_rules() Reload the firewall rules, which makes the permanent configuration the new runtime configuration without losing state information. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.reload_rules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.remove_interface(zone, interface, permanent=True) Remove an interface bound to a zone .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.remove_interface zone eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.remove_masquerade(zone=None, permanent=True) Remove masquerade on a zone. If zone is omitted, default zone will be used. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.remove_masquerade .ft P .fi .UNINDENT .UNINDENT .sp To remove masquerade on a specific zone .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.remove_masquerade dmz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.remove_port(zone, port, permanent=True) Remove a specific port from a zone. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.remove_port internal 443/tcp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.remove_port_fwd(zone, src, dest, proto=\(aqtcp\(aq, dstaddr=\(aq\(aq, permanent=True) Remove Port Forwarding. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.remove_port_fwd public 80 443 tcp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.remove_rich_rule(zone, rule, permanent=True) Add a rich rule to a zone .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.remove_rich_rule zone \(aqrule\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.remove_service(service, zone=None, permanent=True) Remove a service from zone. This option can be specified multiple times. If zone is omitted, default zone will be used. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.remove_service ssh .ft P .fi .UNINDENT .UNINDENT .sp To remove a service from a specific zone .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.remove_service ssh dmz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.remove_service_port(service, port) Remove a port from the specified service. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.remove_service_port zone 80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.remove_service_protocol(service, protocol) Remove a protocol from the specified service. .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.remove_service_protocol zone ssh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.remove_source(zone, source, permanent=True) Remove a source bound to a zone .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.remove_source zone 192.168.1.0/24 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.set_default_zone(zone) Set default zone .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.set_default_zone damian .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.firewalld.version() Return version from firewall\-cmd .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewalld.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.freebsd_sysctl .sp Module for viewing and modifying sysctl parameters .INDENT 0.0 .TP .B salt.modules.freebsd_sysctl.assign(name, value) Assign a single sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.assign net.inet.icmp.icmplim 50 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_sysctl.get(name) Return a single sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.get hw.physmem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_sysctl.persist(name, value, config=\(aq/etc/sysctl.conf\(aq) Assign and persist a simple sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.persist net.inet.icmp.icmplim 50 salt \(aq*\(aq sysctl.persist coretemp_load NO config=/boot/loader.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_sysctl.show(config_file=False) Return a list of sysctl parameters for this minion .INDENT 7.0 .TP .B config: Pull the data from the system configuration file instead of the live data. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.show .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.freebsd_update .sp Support for freebsd\-update utility on FreeBSD. .sp New in version 2017.7.0. .INDENT 0.0 .TP .B maintainer George Mamalakis <\fI\%mamalos@gmail.com\fP> .TP .B maturity new .TP .B platform FreeBSD .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_update.fetch(**kwargs) New in version 2016.3.4. .sp freebsd\-update fetch wrapper. Based on the currently installed world and the configuration options set, fetch all available binary updates. .INDENT 7.0 .TP .B kwargs: Parameters of freebsd\-update command. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_update.ids(**kwargs) New in version 2016.3.4. .sp freebsd\-update IDS wrapper function. Compares the system against a \(dqknown good\(dq index of the installed release. .INDENT 7.0 .TP .B kwargs: Parameters of freebsd\-update command. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_update.install(**kwargs) New in version 2016.3.4. .sp freebsd\-update install wrapper. Install the most recently fetched updates or upgrade. .INDENT 7.0 .TP .B kwargs: Parameters of freebsd\-update command. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_update.rollback(**kwargs) New in version 2016.3.4. .sp freebsd\-update rollback wrapper. Uninstalls the most recently installed updates. .INDENT 7.0 .TP .B kwargs: Parameters of freebsd\-update command. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_update.update(**kwargs) New in version 2016.3.4. .sp Command that simplifies freebsd\-update by running freebsd\-update fetch first and then freebsd\-update install. .INDENT 7.0 .TP .B kwargs: Parameters of freebsd\-update command. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_update.upgrade(**kwargs) New in version 2016.3.4. .sp Dummy function used only to print a message that upgrade is not available. The reason is that upgrade needs manual intervention and reboot, so even if used with: .INDENT 7.0 .INDENT 3.5 yes | freebsd\-upgrade \-r VERSION .UNINDENT .UNINDENT .sp the additional freebsd\-update install that needs to run after the reboot cannot be implemented easily. .INDENT 7.0 .TP .B kwargs: Parameters of freebsd\-update command. .UNINDENT .UNINDENT .SS salt.modules.freebsdjail .sp The jail module for FreeBSD .INDENT 0.0 .TP .B salt.modules.freebsdjail.fstab(jail) Display contents of a fstab(5) file defined in specified jail\(aqs configuration. If no file is defined, return False. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.fstab <jail name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.get_enabled() Return which jails are set to be run .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.is_enabled() See if jail service is actually enabled on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.is_enabled <jail name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.restart(jail=\(aq\(aq) Restart the specified jail or all, if none specified .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.restart [<jail name>] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.show_config(jail) Display specified jail\(aqs configuration .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.show_config <jail name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.start(jail=\(aq\(aq) Start the specified jail or all, if none specified .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.start [<jail name>] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.status(jail) See if specified jail is currently running .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.status <jail name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.stop(jail=\(aq\(aq) Stop the specified jail or all, if none specified .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.stop [<jail name>] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.sysctl() Dump all jail related kernel states (sysctl) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.sysctl .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.freebsdkmod .sp Module to manage FreeBSD kernel modules .INDENT 0.0 .TP .B salt.modules.freebsdkmod.available() Return a list of all available kernel modules .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.available .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.check_available(mod) Check to see if the specified kernel module is available .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.check_available vmm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.is_loaded(mod) Check to see if the specified kernel module is loaded .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.is_loaded vmm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.load(mod, persist=False) Load the specified kernel module .INDENT 7.0 .TP .B mod Name of the module to add .TP .B persist Write the module to sysrc kld_modules to make it load on system reboot .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.load bhyve .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.lsmod() Return a dict containing information about currently loaded modules .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.lsmod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.mod_list(only_persist=False) Return a list of the loaded module names .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.mod_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.remove(mod, persist=False, comment=True) Remove the specified kernel module .INDENT 7.0 .TP .B mod Name of module to remove .TP .B persist Also remove module from /boot/loader.conf .TP .B comment If persist is set don\(aqt remove line from /boot/loader.conf but only comment it .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.remove vmm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.freebsdpkg .sp Remote package support using \fBpkg_add(1)\fP .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module has been completely rewritten. Up to and including version 0.17.0, it supported \fBpkg_add(1)\fP, but checked for the existence of a pkgng local database and, if found, would provide some of pkgng\(aqs functionality. The rewrite of this module has removed all pkgng support, and moved it to the \fI\%pkgng\fP execution module. For versions <= 0.17.0, the documentation here should not be considered accurate. If your Minion is running one of these versions, then the documentation for this module can be viewed using the \fBsys.doc\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt bsdminion sys.doc pkg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp This module acts as the default package provider for FreeBSD 9 and older. If you need to use pkgng on a FreeBSD 9 system, you will need to override the \fBpkg\fP provider by setting the \fI\%providers\fP parameter in your Minion config file, in order to use pkgng. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C providers: pkg: pkgng .ft P .fi .UNINDENT .UNINDENT .sp More information on pkgng support can be found in the documentation for the \fI\%pkgng\fP module. .sp This module will respect the \fBPACKAGEROOT\fP and \fBPACKAGESITE\fP environment variables, if set, but these values can also be overridden in several ways: .INDENT 0.0 .IP 1. 3 \fBSalt configuration parameters.\fP The configuration parameters \fBfreebsdpkg.PACKAGEROOT\fP and \fBfreebsdpkg.PACKAGESITE\fP are recognized. These config parameters are looked up using \fI\%config.get\fP and can thus be specified in the Master config file, Grains, Pillar, or in the Minion config file. Example: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C freebsdpkg.PACKAGEROOT: ftp://ftp.freebsd.org/ freebsdpkg.PACKAGESITE: ftp://ftp.freebsd.org/pub/FreeBSD/ports/ia64/packages\-9\-stable/Latest/ .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 \fBCLI arguments.\fP Both the \fBpackageroot\fP (used interchangeably with \fBfromrepo\fP for API compatibility) and \fBpackagesite\fP CLI arguments are recognized, and override their config counterparts from section 1 above. .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos:FreeBSD\(aq pkg.install zsh fromrepo=ftp://ftp2.freebsd.org/ salt \-G \(aqos:FreeBSD\(aq pkg.install zsh packageroot=ftp://ftp2.freebsd.org/ salt \-G \(aqos:FreeBSD\(aq pkg.install zsh packagesite=ftp://ftp2.freebsd.org/pub/FreeBSD/ports/ia64/packages\-9\-stable/Latest/ \&.. note:: These arguments can also be passed through in states: .. code\-block:: yaml zsh: pkg.installed: \- fromrepo: ftp://ftp2.freebsd.org/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.available_version(*names, **kwargs) This function is an alias of \fBlatest_version\fP\&. .INDENT 7.0 .INDENT 3.5 \fBpkg_add(1)\fP is not capable of querying for remote packages, so this function will always return results as if there is no package available for install or upgrade. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.delete(name=None, pkgs=None, **kwargs) This function is an alias of \fBremove\fP\&. .INDENT 7.0 .INDENT 3.5 Remove packages using \fBpkg_delete(1)\fP .INDENT 0.0 .TP .B name The name of the package to be deleted. .UNINDENT .sp Multiple Package Options: .INDENT 0.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 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.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.freebsdpkg.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.freebsdpkg.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs) Install package(s) using \fBpkg_add(1)\fP .INDENT 7.0 .TP .B name The name of the package to be installed. .TP .B refresh Whether or not to refresh the package database before installing. .TP .B fromrepo or packageroot Specify a package repository from which to install. Overrides the system default, as well as the PACKAGEROOT environment variable. .TP .B packagesite Specify the exact directory from which to install the remote package. Overrides the PACKAGESITE environment variable, if present. .UNINDENT .sp Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of packages to install from a software repository. Must be passed as a python list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B sources A list of packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sources=\(aq[{\(dqfoo\(dq: \(dqsalt://foo.deb\(dq}, {\(dqbar\(dq: \(dqsalt://bar.deb\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Return a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.latest_version(*names, **kwargs) \fBpkg_add(1)\fP is not capable of querying for remote packages, so this function will always return results as if there is no package available for install or upgrade. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.list_pkgs(versions_as_list=False, with_origin=False, **kwargs) List the packages currently installed as a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(aq} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B with_origin False Return a nested dictionary containing both the origin name and version for each installed package. .sp New in version 2014.1.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.purge(name=None, pkgs=None, **kwargs) This function is an alias of \fBremove\fP\&. .INDENT 7.0 .INDENT 3.5 Remove packages using \fBpkg_delete(1)\fP .INDENT 0.0 .TP .B name The name of the package to be deleted. .UNINDENT .sp Multiple Package Options: .INDENT 0.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 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.refresh_db(**kwargs) \fBpkg_add(1)\fP does not use a local database of available packages, so this function simply returns \fBTrue\fP\&. it exists merely for API compatibility. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.remove(name=None, pkgs=None, **kwargs) Remove packages using \fBpkg_delete(1)\fP .INDENT 7.0 .TP .B name The name of the package to be deleted. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to delete. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .UNINDENT .sp New in version 0.16.0. .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.version(*names, **kwargs) Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned. .INDENT 7.0 .TP .B with_origin False Return a nested dictionary containing both the origin name and version for each specified package. .sp New in version 2014.1.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.freebsdports .sp Install software from the FreeBSD \fBports(7)\fP system .sp New in version 2014.1.0. .sp This module allows you to install ports using \fBBATCH=yes\fP to bypass configuration prompts. It is recommended to use the \fBports state\fP to install ports, but it is also possible to use this module exclusively from the command line. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt minion\-id ports.config security/nmap IPV6=off salt minion\-id ports.install security/nmap .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.config(name, reset=False, **kwargs) Modify configuration options for a given port. Multiple options can be specified. To see the available options for a port, use \fI\%ports.showconfig\fP\&. .INDENT 7.0 .TP .B name The port name, in \fBcategory/name\fP format .TP .B reset False If \fBTrue\fP, runs a \fBmake rmconfig\fP for the port, clearing its configuration before setting the desired options .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.config security/nmap IPV6=off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.deinstall(name) De\-install a port. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.deinstall security/nmap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.install(name, clean=True) Install a port from the ports tree. Installs using \fBBATCH=yes\fP for non\-interactive building. To set config options for a given port, use \fI\%ports.config\fP\&. .INDENT 7.0 .TP .B clean True If \fBTrue\fP, cleans after installation. Equivalent to running \fBmake install clean BATCH=yes\fP\&. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 It may be helpful to run this function using the \fB\-t\fP option to set a higher timeout, since compiling a port may cause the Salt command to exceed the default timeout. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-t 1200 \(aq*\(aq ports.install security/nmap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.list_all() Lists all ports available. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.list_all .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Takes a while to run, and returns a \fBLOT\fP of output .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.rmconfig(name) Clear the cached options for the specified port; run a \fBmake rmconfig\fP .INDENT 7.0 .TP .B name The name of the port to clear .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.rmconfig security/nmap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.search(name) Search for matches in the ports tree. Globs are supported, and the category is optional .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.search \(aqsecurity/*\(aq salt \(aq*\(aq ports.search \(aqsecurity/n*\(aq salt \(aq*\(aq ports.search nmap .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Takes a while to run .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.showconfig(name, default=False, dict_return=False) Show the configuration options for a given port. .INDENT 7.0 .TP .B default False Show the default options for a port (not necessarily the same as the current configuration) .TP .B dict_return False Instead of returning the output of \fBmake showconfig\fP, return the data in an dictionary .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.showconfig security/nmap salt \(aq*\(aq ports.showconfig security/nmap default=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.update(extract=False) Update the ports tree .INDENT 7.0 .TP .B extract False If \fBTrue\fP, runs a \fBportsnap extract\fP after fetching, should be used for first\-time installation of the ports tree. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.freebsdservice .sp The service module for FreeBSD .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage services on a minion, and it is using a different module (or gives an error similar to \fI\(aqservice.start\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.available(name, jail=None) Check that the given service is available. .sp Changed in version 2016.3.4. .sp jail: optional jid or jail name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.disable(name, **kwargs) Disable the named service to start at boot .sp Arguments the same as for enable() .sp Changed in version 2016.3.4. .INDENT 7.0 .TP .B jail (optional keyword argument) the jail\(aqs id or name .TP .B chroot (optional keyword argument) the jail\(aqs chroot, if the jail\(aqs /etc is not mounted read\-write .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.disabled(name, **kwargs) Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.enable(name, **kwargs) Enable the named service to start at boot .INDENT 7.0 .TP .B name service name .TP .B config /etc/rc.conf Config file for managing service. If config value is empty string, then /etc/rc.conf.d/<service> used. See man rc.conf(5) for details. .sp Also service.config variable can be used to change default. .UNINDENT .sp Changed in version 2016.3.4. .INDENT 7.0 .TP .B jail (optional keyword argument) the jail\(aqs id or name .TP .B chroot (optional keyword argument) the jail\(aqs chroot, if the jail\(aqs /etc is not mounted read\-write .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.enabled(name, **kwargs) Return True if the named service is enabled, false otherwise .INDENT 7.0 .TP .B name Service name .UNINDENT .sp Changed in version 2016.3.4. .sp Support for jail (representing jid or jail name) keyword argument in kwargs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.get_all(jail=None) Return a list of all available services .sp Changed in version 2016.3.4. .sp jail: optional jid or jail name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.get_disabled(jail=None) Return what services are available but not enabled to start at boot .sp Changed in version 2016.3.4. .sp Support for jail (representing jid or jail name) keyword argument in kwargs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.get_enabled(jail=None) Return what services are set to run on boot .sp Changed in version 2016.3.4. .sp Support for jail (representing jid or jail name) keyword argument in kwargs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.missing(name, jail=None) The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp Changed in version 2016.3.4. .sp jail: optional jid or jail name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.reload_(name, jail=None) Restart the named service .sp Changed in version 2016.3.4. .sp jail: optional jid or jail name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.restart(name, jail=None) Restart the named service .sp Changed in version 2016.3.4. .sp jail: optional jid or jail name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.start(name, jail=None) Start the specified service .sp Changed in version 2016.3.4. .sp jail: optional jid or jail name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.status(name, sig=None, jail=None) Return the status for a service. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp Changed in version 2016.3.4. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Signature to use to find the service via ps .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> [service signature] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.stop(name, jail=None) Stop the specified service .sp Changed in version 2016.3.4. .sp jail: optional jid or jail name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.freezer .sp Module for freezer :maintainer: Alberto Planas <\fI\%aplanas@suse.com\fP> :maturity: new :depends: None :platform: Linux .INDENT 0.0 .TP .B salt.modules.freezer.compare(old, new) Display the difference between two frozen states. The results are shown as as a dictionary with keys for packages and repositories. Each key may contain a changes dictionary showing items that differ between the two frozen states. Items shown in the \(dqold\(dq changes but not the \(dqnew\(dq were removed. Items in \(dqnew\(dq but not \(dqold\(dq were added. Items shown in both probably updated/changed versions between freezes. .INDENT 7.0 .TP .B old Name of the \(dqold\(dq frozen state. Required. .TP .B new Name of the \(dqnew\(dq frozen state. Required. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq freezer.freeze pre_install post_install .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freezer.freeze(name=None, force=False, **kwargs) Save the list of package and repos in a freeze file. .sp As this module is build on top of the pkg module, the user can send extra attributes to the underlying pkg module via kwargs. This function will call \fBpkg.list_pkgs\fP and \fBpkg.list_repos\fP, and any additional arguments will be passed through to those functions. .INDENT 7.0 .TP .B name Name of the frozen state. Optional. .TP .B force If true, overwrite the state. Optional. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq freezer.freeze salt \(aq*\(aq freezer.freeze pre_install salt \(aq*\(aq freezer.freeze force=True root=/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freezer.list_() Return the list of frozen states. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq freezer.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freezer.restore(name=None, clean=False, **kwargs) Make sure that the system contains the packages and repos from a frozen state. .sp Read the list of packages and repositories from the freeze file, and compare it with the current list of packages and repos. If there is any difference, all the missing packages are repos will be installed, and all the extra packages and repos will be removed. .sp As this module is build on top of the pkg module, the user can send extra attributes to the underlying pkg module via kwargs. This function will call \fBpkg.list_repos\fP, \fBpkg.mod_repo\fP, \fBpkg.list_pkgs\fP, \fBpkg.install\fP, \fBpkg.remove\fP and \fBpkg.del_repo\fP, and any additional arguments will be passed through to those functions. .INDENT 7.0 .TP .B name Name of the frozen state. Optional. .TP .B clean If True remove the frozen information YAML from the cache .sp New in version 3000. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq freezer.restore salt \(aq*\(aq freezer.restore root=/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freezer.status(name=None) Return True if there is already a frozen state. .sp A frozen state is merely a list of packages (including the version) in a specific time. This information can be used to compare with the current list of packages, and revert the installation of some extra packages that are in the system. .INDENT 7.0 .TP .B name Name of the frozen state. Optional. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq freezer.status salt \(aq*\(aq freezer.status pre_install .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.gcp_addon .sp A route is a rule that specifies how certain packets should be handled by the virtual network. Routes are associated with virtual machine instances by tag, and the set of routes for a particular VM is called its routing table. For each packet leaving a virtual machine, the system searches that machine\(aqs routing table for a single best matching route. .sp New in version 2018.3.0. .sp This module will create a route to send traffic destined to the Internet through your gateway instance. .INDENT 0.0 .TP .B codeauthor \fIPratik Bandarkar <pratik.bandarkar@gmail.com>\fP .TP .B maturity new .TP .B depends google\-api\-python\-client .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.modules.gcp_addon.route_create(credential_file=None, project_id=None, name=None, dest_range=None, next_hop_instance=None, instance_zone=None, tags=None, network=None, priority=None) Create a route to send traffic destined to the Internet through your gateway instance .INDENT 7.0 .TP .B credential_file string File location of application default credential. For more information, refer: \fI\%https://developers.google.com/identity/protocols/application\-default\-credentials\fP .TP .B project_id string Project ID where instance and network resides. .TP .B name string name of the route to create .TP .B next_hop_instance string the name of an instance that should handle traffic matching this route. .TP .B instance_zone string zone where instance(\(dqnext_hop_instance\(dq) resides .TP .B network string Specifies the network to which the route will be applied. .TP .B dest_range string The destination range of outgoing packets that the route will apply to. .TP .B tags list (optional) Identifies the set of instances that this route will apply to. .TP .B priority int (optional) Specifies the priority of this route relative to other routes. default=1000 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqsalt\-master.novalocal\(aq gcp.route_create credential_file=/root/secret_key.json project_id=cp100\-170315 name=derby\-db\-route1 next_hop_instance=instance\-1 instance_zone=us\-central1\-a network=default dest_range=0.0.0.0/0 tags=[\(aqno\-ip\(aq] priority=700 .ft P .fi .UNINDENT .UNINDENT .sp In above example, the instances which are having tag \(dqno\-ip\(dq will route the packet to instance \(dqinstance\-1\(dq(if packet is intended to other network) .UNINDENT .SS salt.modules.gem .sp Manage ruby gems. .INDENT 0.0 .TP .B salt.modules.gem.install(gems, ruby=None, gem_bin=None, runas=None, version=None, rdoc=False, ri=False, pre_releases=False, proxy=None, source=None) Installs one or several gems. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgems\fP \-\- string The gems to install .IP \(bu 2 \fBgem_bin\fP \-\- string : None Full path to \fBgem\fP binary to use. .IP \(bu 2 \fBruby\fP \-\- string : None If RVM or rbenv are installed, the ruby version and gemset to use. Ignored if \fBgem_bin\fP is specified. .IP \(bu 2 \fBrunas\fP \-\- string : None The user to run gem as. .IP \(bu 2 \fBversion\fP \-\- string : None Specify the version to install for the gem. Doesn\(aqt play nice with multiple gems at once .IP \(bu 2 \fBrdoc\fP \-\- boolean : False Generate RDoc documentation for the gem(s). For rubygems > 3 this is interpreted as the \-\-no\-document arg and the ri option will then be ignored .IP \(bu 2 \fBri\fP \-\- boolean : False Generate RI documentation for the gem(s). For rubygems > 3 this is interpreted as the \-\-no\-document arg and the rdoc option will then be ignored .IP \(bu 2 \fBpre_releases\fP \-\- boolean : False Include pre\-releases in the available versions .IP \(bu 2 \fBproxy\fP \-\- string : None Use the specified HTTP proxy server for all outgoing traffic. Format: \fI\%http://hostname[:port\fP] .UNINDENT .UNINDENT .INDENT 7.0 .TP .B source None Use the specified HTTP gem source server to download gem. Format: \fI\%http://hostname[:port\fP] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.install vagrant salt \(aq*\(aq gem.install redphone gem_bin=/opt/sensu/embedded/bin/gem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.list_(prefix=\(aq\(aq, ruby=None, runas=None, gem_bin=None) List locally installed gems. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprefix\fP \-\- string : Only list gems when the name matches this prefix. .IP \(bu 2 \fBgem_bin\fP \-\- string : None Full path to \fBgem\fP binary to use. .IP \(bu 2 \fBruby\fP \-\- string : None If RVM or rbenv are installed, the ruby version and gemset to use. Ignored if \fBgem_bin\fP is specified. .IP \(bu 2 \fBrunas\fP \-\- string : None The user to run gem as. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.list_upgrades(ruby=None, runas=None, gem_bin=None) New in version 2015.8.0. .sp Check if an upgrade is available for installed gems .INDENT 7.0 .TP .B gem_bin None Full path to \fBgem\fP binary to use. .TP .B ruby None If RVM or rbenv are installed, the ruby version and gemset to use. Ignored if \fBgem_bin\fP is specified. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.list_upgrades .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.sources_add(source_uri, ruby=None, runas=None, gem_bin=None) Add a gem source. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsource_uri\fP \-\- string The source URI to add. .IP \(bu 2 \fBgem_bin\fP \-\- string : None Full path to \fBgem\fP binary to use. .IP \(bu 2 \fBruby\fP \-\- string : None If RVM or rbenv are installed, the ruby version and gemset to use. Ignored if \fBgem_bin\fP is specified. .IP \(bu 2 \fBrunas\fP \-\- string : None The user to run gem as. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.sources_add http://rubygems.org/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.sources_list(ruby=None, runas=None, gem_bin=None) List the configured gem sources. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgem_bin\fP \-\- string : None Full path to \fBgem\fP binary to use. .IP \(bu 2 \fBruby\fP \-\- string : None If RVM or rbenv are installed, the ruby version and gemset to use. Ignored if \fBgem_bin\fP is specified. .IP \(bu 2 \fBrunas\fP \-\- string : None The user to run gem as. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.sources_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.sources_remove(source_uri, ruby=None, runas=None, gem_bin=None) Remove a gem source. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsource_uri\fP \-\- string The source URI to remove. .IP \(bu 2 \fBgem_bin\fP \-\- string : None Full path to \fBgem\fP binary to use. .IP \(bu 2 \fBruby\fP \-\- string : None If RVM or rbenv are installed, the ruby version and gemset to use. Ignored if \fBgem_bin\fP is specified. .IP \(bu 2 \fBrunas\fP \-\- string : None The user to run gem as. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.sources_remove http://rubygems.org/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.uninstall(gems, ruby=None, runas=None, gem_bin=None) Uninstall one or several gems. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgems\fP \-\- string The gems to uninstall. .IP \(bu 2 \fBgem_bin\fP \-\- string : None Full path to \fBgem\fP binary to use. .IP \(bu 2 \fBruby\fP \-\- string : None If RVM or rbenv are installed, the ruby version and gemset to use. Ignored if \fBgem_bin\fP is specified. .IP \(bu 2 \fBrunas\fP \-\- string : None The user to run gem as. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.uninstall vagrant .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.update(gems, ruby=None, runas=None, gem_bin=None) Update one or several gems. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgems\fP \-\- string The gems to update. .IP \(bu 2 \fBgem_bin\fP \-\- string : None Full path to \fBgem\fP binary to use. .IP \(bu 2 \fBruby\fP \-\- string : None If RVM or rbenv are installed, the ruby version and gemset to use. Ignored if \fBgem_bin\fP is specified. .IP \(bu 2 \fBrunas\fP \-\- string : None The user to run gem as. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.update vagrant .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.update_system(version=\(aq\(aq, ruby=None, runas=None, gem_bin=None) Update rubygems. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBversion\fP \-\- string : (newest) The version of rubygems to install. .IP \(bu 2 \fBgem_bin\fP \-\- string : None Full path to \fBgem\fP binary to use. .IP \(bu 2 \fBruby\fP \-\- string : None If RVM or rbenv are installed, the ruby version and gemset to use. Ignored if \fBgem_bin\fP is specified. .IP \(bu 2 \fBrunas\fP \-\- string : None The user to run gem as. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.update_system .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.version(ruby=None, runas=None, gem_bin=None) Print out the version of gem .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgem_bin\fP \-\- string : None Full path to \fBgem\fP binary to use. .IP \(bu 2 \fBruby\fP \-\- string : None If RVM or rbenv are installed, the ruby version and gemset to use. Ignored if \fBgem_bin\fP is specified. .IP \(bu 2 \fBrunas\fP \-\- string : None The user to run gem as. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.genesis .sp Module for managing container and VM images .sp New in version 2014.7.0. .INDENT 0.0 .TP .B salt.modules.genesis.avail_platforms() Return which platforms are available .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion genesis.avail_platforms .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.genesis.bootstrap(platform, root, img_format=\(aqdir\(aq, fs_format=\(aqext2\(aq, fs_opts=None, arch=None, flavor=None, repo_url=None, static_qemu=None, img_size=None, mount_dir=None, pkg_cache=None, pkgs=None, exclude_pkgs=None, epel_url=\(aqhttp://download.fedoraproject.org/pub/epel/6/i386/epel\-release\-6\-8.noarch.rpm\(aq) Create an image for a specific platform. .sp Please note that this function \fIMUST\fP be run as root, as images that are created make files belonging to root. .INDENT 7.0 .TP .B platform Which platform to use to create the image. Currently supported platforms are rpm, deb and pacman. .TP .B root Local path to create the root of the image filesystem. .TP .B img_format Which format to create the image in. By default, just copies files into a directory on the local filesystem (\fBdir\fP). Future support will exist for \fBsparse\fP\&. .TP .B fs_format When using a non\-\fBdir\fP \fBimg_format\fP, which filesystem to format the image to. By default, \fBext2\fP\&. .TP .B fs_opts When using a non\-\fBdir\fP \fBimg_format\fP, a dict of opts may be specified. .TP .B arch Architecture to install packages for, if supported by the underlying bootstrap tool. Currently only used for deb. .TP .B flavor Which flavor of operating system to install. This correlates to a specific directory on the distribution repositories. For instance, \fBwheezy\fP on Debian. .TP .B repo_url Mainly important for Debian\-based repos. Base URL for the mirror to install from. (e.x.: \fI\%http://ftp.debian.org/debian/\fP) .TP .B static_qemu Local path to the static qemu binary required for this arch. (e.x.: /usr/bin/qemu\-amd64\-static) .TP .B pkg_confs The location of the conf files to copy into the image, to point the installer to the right repos and configuration. .TP .B img_size If img_format is not \fBdir\fP, then the size of the image must be specified. .TP .B mount_dir If img_format is not \fBdir\fP, then the image must be mounted somewhere. If the \fBmount_dir\fP is not specified, then it will be created at \fB/opt/salt\-genesis.<random_uuid>\fP\&. This directory will be unmounted and removed when the process is finished. .TP .B pkg_cache This points to a directory containing a cache of package files to be copied to the image. It does not need to be specified. .TP .B pkgs A list of packages to be installed on this image. For RedHat, this will include \fByum\fP, \fBcentos\-release\fP and \fBiputils\fP by default. .TP .B exclude_pkgs A list of packages to be excluded. If you do not want to install the defaults, you need to include them in this list. .TP .B epel_url The URL to download the EPEL release package from. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion genesis.bootstrap pacman /root/arch salt myminion genesis.bootstrap rpm /root/redhat salt myminion genesis.bootstrap deb /root/wheezy arch=amd64 flavor=wheezy static_qemu=/usr/bin/qemu\-x86_64\-static .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.genesis.ldd_deps(filename, ret=None) Recurse through a set of dependencies reported by \fBldd\fP, to find associated dependencies. .sp Please note that this does not necessarily resolve all (non\-package) dependencies for a file; but it does help. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion genesis.ldd_deps bash salt myminion genesis.ldd_deps /bin/bash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.genesis.mksls(fmt, src, dst=None) Convert an installation file/script to an SLS file. Currently supports \fBkickstart\fP, \fBpreseed\fP, and \fBautoyast\fP\&. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <minion> genesis.mksls kickstart /path/to/kickstart.cfg salt <minion> genesis.mksls kickstart /path/to/kickstart.cfg /path/to/dest.sls .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.genesis.pack(name, root, path=None, pack_format=\(aqtar\(aq, compress=\(aqbzip2\(aq) Pack up a directory structure, into a specific format .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion genesis.pack centos /root/centos salt myminion genesis.pack centos /root/centos pack_format=\(aqtar\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.genesis.unpack(name, dest=None, path=None, pack_format=\(aqtar\(aq, compress=\(aqbz2\(aq) Unpack an image into a directory structure .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion genesis.unpack centos /root/centos .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.gentoo_service .sp Top level package command wrapper, used to translate the os detected by grains to the correct service manager .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage services on a minion, and it is using a different module (or gives an error similar to \fI\(aqservice.start\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.disable(name, **kwargs) Disable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable <service name> <runlevels=single\-runlevel> salt \(aq*\(aq service.disable <service name> <runlevels=[runlevel1,runlevel2]> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.disabled(name) Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> <runlevels=[runlevel]> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.enable(name, **kwargs) Enable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable <service name> <runlevels=single\-runlevel> salt \(aq*\(aq service.enable <service name> <runlevels=[runlevel1,runlevel2]> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.enabled(name, **kwargs) Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> <runlevels=single\-runlevel> salt \(aq*\(aq service.enabled <service name> <runlevels=[runlevel1,runlevel2]> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.get_all() Return all available boot services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.get_disabled() Return a set of services that are installed but disabled .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.get_enabled() Return a list of service that are enabled on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.missing(name) The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.reload_(name) Reload the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.restart(name) Restart the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.start(name) Start the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.status(name, sig=None) Return the status for a service. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Signature to use to find the service via ps .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> [service signature] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.stop(name) Stop the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.zap(name) Resets service state .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.zap <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.gentoolkitmod .sp Support for Gentoolkit .INDENT 0.0 .TP .B salt.modules.gentoolkitmod.eclean_dist(destructive=False, package_names=False, size_limit=0, time_limit=0, fetch_restricted=False, exclude_file=\(aq/etc/eclean/distfiles.exclude\(aq) Clean obsolete portage sources .INDENT 7.0 .TP .B destructive Only keep minimum for reinstallation .TP .B package_names Protect all versions of installed packages. Only meaningful if used with destructive=True .TP .B size_limit <size> Don\(aqt delete distfiles bigger than <size>. <size> is a size specification: \(dq10M\(dq is \(dqten megabytes\(dq, \(dq200K\(dq is \(dqtwo hundreds kilobytes\(dq, etc. Units are: G, M, K and B. .TP .B time_limit <time> Don\(aqt delete distfiles files modified since <time> <time> is an amount of time: \(dq1y\(dq is \(dqone year\(dq, \(dq2w\(dq is \(dqtwo weeks\(dq, etc. Units are: y (years), m (months), w (weeks), d (days) and h (hours). .TP .B fetch_restricted Protect fetch\-restricted files. Only meaningful if used with destructive=True .TP .B exclude_file Path to exclusion file. Default is /etc/eclean/distfiles.exclude This is the same default eclean\-dist uses. Use None if this file exists and you want to ignore. .UNINDENT .sp Returns a dict containing the cleaned, saved, and deprecated dists: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqcleaned\(aq: {<dist file>: <size>}, \(aqdeprecated\(aq: {<package>: <dist file>}, \(aqsaved\(aq: {<package>: <dist file>}, \(aqtotal_cleaned\(aq: <size>} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gentoolkit.eclean_dist destructive=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoolkitmod.eclean_pkg(destructive=False, package_names=False, time_limit=0, exclude_file=\(aq/etc/eclean/packages.exclude\(aq) Clean obsolete binary packages .INDENT 7.0 .TP .B destructive Only keep minimum for reinstallation .TP .B package_names Protect all versions of installed packages. Only meaningful if used with destructive=True .TP .B time_limit <time> Don\(aqt delete distfiles files modified since <time> <time> is an amount of time: \(dq1y\(dq is \(dqone year\(dq, \(dq2w\(dq is \(dqtwo weeks\(dq, etc. Units are: y (years), m (months), w (weeks), d (days) and h (hours). .TP .B exclude_file Path to exclusion file. Default is /etc/eclean/packages.exclude This is the same default eclean\-pkg uses. Use None if this file exists and you want to ignore. .UNINDENT .sp Returns a dict containing the cleaned binary packages: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqcleaned\(aq: {<dist file>: <size>}, \(aqtotal_cleaned\(aq: <size>} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gentoolkit.eclean_pkg destructive=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoolkitmod.glsa_check_list(glsa_list) List the status of Gentoo Linux Security Advisories .INDENT 7.0 .TP .B glsa_list can contain an arbitrary number of GLSA ids, filenames containing GLSAs or the special identifiers \(aqall\(aq and \(aqaffected\(aq .UNINDENT .sp Returns a dict containing glsa ids with a description, status, and CVEs: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {<glsa_id>: {\(aqdescription\(aq: <glsa_description>, \(aqstatus\(aq: <glsa status>, \(aqCVEs\(aq: [<list of CVEs>]}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gentoolkit.glsa_check_list \(aqaffected\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoolkitmod.revdep_rebuild(lib=None) Fix up broken reverse dependencies .INDENT 7.0 .TP .B lib Search for reverse dependencies for a particular library rather than every library on the system. It can be a full path to a library or basic regular expression. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gentoolkit.revdep_rebuild .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.git .sp Support for the Git SCM .INDENT 0.0 .TP .B salt.modules.git.add(cwd, filename, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) Changed in version 2015.8.0: The \fB\-\-verbose\fP command line argument is now implied .sp Interface to \fI\%git\-add(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B filename The location of the file/directory to add, relative to \fBcwd\fP .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBadd\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.add /path/to/repo foo/bar.py salt myminion git.add /path/to/repo foo/bar.py opts=\(aq\-\-dry\-run\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.archive(cwd, output, rev=\(aqHEAD\(aq, prefix=None, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None, **kwargs) Changed in version 2015.8.0: Returns \fBTrue\fP if successful, raises an error if not. .sp Interface to \fI\%git\-archive(1)\fP, exports a tarball/zip file of the repository .INDENT 7.0 .TP .B cwd The path to be archived .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBgit archive\fP permits a partial archive to be created. Thus, this path does not need to be the root of the git repository. Only the files within the directory specified by \fBcwd\fP (and its subdirectories) will be in the resulting archive. For example, if there is a git checkout at \fB/tmp/foo\fP, then passing \fB/tmp/foo/bar\fP as the \fBcwd\fP will result in just the files underneath \fB/tmp/foo/bar\fP to be exported as an archive. .UNINDENT .UNINDENT .TP .B output The path of the archive to be created .TP .B overwrite False Unless set to \fBTrue\fP, Salt will over overwrite an existing archive at the path specified by the \fBoutput\fP argument. .sp New in version 2015.8.0. .TP .B rev HEAD The revision from which to create the archive .TP .B format Manually specify the file format of the resulting archive. This argument can be omitted, and \fBgit archive\fP will attempt to guess the archive type (and compression) from the filename. \fBzip\fP, \fBtar\fP, \fBtar.gz\fP, and \fBtgz\fP are extensions that are recognized automatically, and git can be configured to support other archive types with the addition of git configuration keys. .sp See the \fI\%git\-archive(1)\fP manpage explanation of the \fB\-\-format\fP argument (as well as the \fBCONFIGURATION\fP section of the manpage) for further information. .sp New in version 2015.8.0. .TP .B prefix Prepend \fB<prefix>\fP to every filename in the archive. If unspecified, the name of the directory at the top level of the repository will be used as the prefix (e.g. if \fBcwd\fP is set to \fB/foo/bar/baz\fP, the prefix will be \fBbaz\fP, and the resulting archive will contain a top\-level directory by that name). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The default behavior if the \fB\-\-prefix\fP option for \fBgit archive\fP is not specified is to not prepend a prefix, so Salt\(aqs behavior differs slightly from \fBgit archive\fP in this respect. Use \fBprefix=\(aq\(aq\fP to create an archive with no prefix. .UNINDENT .UNINDENT .sp Changed in version 2015.8.0: The behavior of this argument has been changed slightly. As of this version, it is necessary to include the trailing slash when specifying a prefix, if the prefix is intended to create a top\-level directory. .TP .B git_opts Any additional options to add to git command itself (not the \fBarchive\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.archive /path/to/repo /path/to/archive.tar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.branch(cwd, name=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) Interface to \fI\%git\-branch(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B name Name of the branch on which to operate. If not specified, the current branch will be assumed. .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To create a branch based on something other than HEAD, pass the name of the revision as \fBopts\fP\&. If the revision is in the format \fBremotename/branch\fP, then this will also set the remote tracking branch. .sp Additionally, on the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBbranch\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Set remote tracking branch salt myminion git.branch /path/to/repo mybranch opts=\(aq\-\-set\-upstream\-to origin/mybranch\(aq # Create new branch salt myminion git.branch /path/to/repo mybranch upstream/somebranch # Delete branch salt myminion git.branch /path/to/repo mybranch opts=\(aq\-d\(aq # Rename branch (2015.8.0 and later) salt myminion git.branch /path/to/repo newbranch opts=\(aq\-m oldbranch\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.checkout(cwd, rev=None, force=False, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) Interface to \fI\%git\-checkout(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBcheckout\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B rev The remote branch or revision to checkout. .sp Changed in version 2015.8.0: Optional when using \fB\-b\fP or \fB\-B\fP in \fBopts\fP\&. .TP .B force False Force a checkout even if there might be overwritten changes .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Checking out local local revisions salt myminion git.checkout /path/to/repo somebranch user=jeff salt myminion git.checkout /path/to/repo opts=\(aqtestbranch \-\- conf/file1 file2\(aq salt myminion git.checkout /path/to/repo rev=origin/mybranch opts=\(aq\-\-track\(aq # Checking out remote revision into new branch salt myminion git.checkout /path/to/repo upstream/master opts=\(aq\-b newbranch\(aq # Checking out current revision into new branch (2015.8.0 and later) salt myminion git.checkout /path/to/repo opts=\(aq\-b newbranch\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.clone(cwd, url=None, name=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, identity=None, https_user=None, https_pass=None, ignore_retcode=False, saltenv=\(aqbase\(aq, output_encoding=None) Interface to \fI\%git\-clone(1)\fP .INDENT 7.0 .TP .B cwd Location of git clone .sp Changed in version 2015.8.0: If \fBname\fP is passed, then the clone will be made \fIwithin\fP this directory. .TP .B url The URL of the repository to be cloned .sp Changed in version 2015.8.0: Argument renamed from \fBrepository\fP to \fBurl\fP .TP .B name Optional alternate name for the top\-level directory to be created by the clone .sp New in version 2015.8.0. .TP .B opts Any additional options to add to the command line, in a single string .TP .B git_opts Any additional options to add to git command itself (not the \fBclone\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B identity Path to a private key to use for ssh URLs .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Unless Salt is invoked from the minion using \fBsalt\-call\fP, the key(s) must be passphraseless. For greater security with passphraseless private keys, see the \fI\%sshd(8)\fP manpage for information on securing the keypair from the remote side in the \fBauthorized_keys\fP file. .UNINDENT .UNINDENT .sp Changed in version 2015.8.7: Salt will no longer attempt to use passphrase\-protected keys unless invoked from the minion using \fBsalt\-call\fP, to prevent blocking waiting for user input. .sp Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file .sp Changed in version 2016.3.0. .TP .B https_user Set HTTP Basic Auth username. Only accepted for HTTPS URLs. .sp New in version 2015.5.0. .TP .B https_pass Set HTTP Basic Auth password. Only accepted for HTTPS URLs. .sp New in version 2015.5.0. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B saltenv The default salt environment to pull sls files from .sp New in version 2016.3.1. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.clone /path/to/repo_parent_dir git://github.com/saltstack/salt.git .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.commit(cwd, message, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, filename=None, ignore_retcode=False, output_encoding=None) Interface to \fI\%git\-commit(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B message Commit message .TP .B opts Any additional options to add to the command line, in a single string. These opts will be added to the end of the git command being run. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .sp The \fB\-m\fP option should not be passed here, as the commit message will be defined by the \fBmessage\fP argument. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBcommit\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B filename The location of the file/directory to commit, relative to \fBcwd\fP\&. This argument is optional, and can be used to commit a file without first staging it. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument only works on files which are already tracked by the git repository. .UNINDENT .UNINDENT .sp New in version 2015.8.0. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.commit /path/to/repo \(aqThe commit message\(aq salt myminion git.commit /path/to/repo \(aqThe commit message\(aq filename=foo/bar.py .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.config_get(key, cwd=None, user=None, password=None, ignore_retcode=False, output_encoding=None, **kwargs) Get the value of a key in the git configuration file .INDENT 7.0 .TP .B key The name of the configuration key to get .sp Changed in version 2015.8.0: Argument renamed from \fBsetting_name\fP to \fBkey\fP .TP .B cwd The path to the git checkout .sp Changed in version 2015.8.0: Now optional if \fBglobal\fP is set to \fBTrue\fP .TP .B global False If \fBTrue\fP, query the global git configuration. Otherwise, only the local git configuration will be queried. .sp New in version 2015.8.0. .TP .B all False If \fBTrue\fP, return a list of all values set for \fBkey\fP\&. If the key does not exist, \fBNone\fP will be returned. .sp New in version 2015.8.0. .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.config_get user.name cwd=/path/to/repo salt myminion git.config_get user.email global=True salt myminion git.config_get core.gitproxy cwd=/path/to/repo all=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.config_get_regex(key, value_regex=None, cwd=None, user=None, password=None, ignore_retcode=False, output_encoding=None, **kwargs) This function is an alias of \fBconfig_get_regexp\fP\&. .INDENT 7.0 .INDENT 3.5 New in version 2015.8.0. .sp Get the value of a key or keys in the git configuration file using regexes for more flexible matching. The return data is a dictionary mapping keys to lists of values matching the \fBvalue_regex\fP\&. If no values match, an empty dictionary will be returned. .INDENT 0.0 .TP .B key Regex on which key names will be matched .TP .B value_regex If specified, return all values matching this regex. The return data will be a dictionary mapping keys to lists of values matching the regex. .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 Only values matching the \fBvalue_regex\fP will be part of the return data. So, if \fBkey\fP matches a multivar, then it is possible that not all of the values will be returned. To get all values set for a multivar, simply omit the \fBvalue_regex\fP argument. .UNINDENT .UNINDENT .TP .B cwd The path to the git checkout .TP .B global False If \fBTrue\fP, query the global git configuration. Otherwise, only the local git configuration will be queried. .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Matches any values for key \(aqfoo.bar\(aq salt myminion git.config_get_regexp /path/to/repo foo.bar # Matches any value starting with \(aqbaz\(aq set for key \(aqfoo.bar\(aq salt myminion git.config_get_regexp /path/to/repo foo.bar \(aqbaz.*\(aq # Matches any key starting with \(aquser.\(aq salt myminion git.config_get_regexp \(aq^user\e.\(aq global=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.config_get_regexp(key, value_regex=None, cwd=None, user=None, password=None, ignore_retcode=False, output_encoding=None, **kwargs) New in version 2015.8.0. .sp Get the value of a key or keys in the git configuration file using regexes for more flexible matching. The return data is a dictionary mapping keys to lists of values matching the \fBvalue_regex\fP\&. If no values match, an empty dictionary will be returned. .INDENT 7.0 .TP .B key Regex on which key names will be matched .TP .B value_regex If specified, return all values matching this regex. The return data will be a dictionary mapping keys to lists of values matching the regex. .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 Only values matching the \fBvalue_regex\fP will be part of the return data. So, if \fBkey\fP matches a multivar, then it is possible that not all of the values will be returned. To get all values set for a multivar, simply omit the \fBvalue_regex\fP argument. .UNINDENT .UNINDENT .TP .B cwd The path to the git checkout .TP .B global False If \fBTrue\fP, query the global git configuration. Otherwise, only the local git configuration will be queried. .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Matches any values for key \(aqfoo.bar\(aq salt myminion git.config_get_regexp /path/to/repo foo.bar # Matches any value starting with \(aqbaz\(aq set for key \(aqfoo.bar\(aq salt myminion git.config_get_regexp /path/to/repo foo.bar \(aqbaz.*\(aq # Matches any key starting with \(aquser.\(aq salt myminion git.config_get_regexp \(aq^user\e.\(aq global=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.config_set(key, value=None, multivar=None, cwd=None, user=None, password=None, ignore_retcode=False, output_encoding=None, **kwargs) Changed in version 2015.8.0: Return the value(s) of the key being set .sp Set a key in the git configuration file .INDENT 7.0 .TP .B cwd The path to the git checkout. Must be an absolute path, or the word \fBglobal\fP to indicate that a global key should be set. .sp Changed in version 2014.7.0: Made \fBcwd\fP argument optional if \fBis_global=True\fP .TP .B key The name of the configuration key to set .sp Changed in version 2015.8.0: Argument renamed from \fBsetting_name\fP to \fBkey\fP .TP .B value The value to set for the specified key. Incompatible with the \fBmultivar\fP argument. .sp Changed in version 2015.8.0: Argument renamed from \fBsetting_value\fP to \fBvalue\fP .TP .B add False Add a value to a key, creating/updating a multivar .sp New in version 2015.8.0. .TP .B multivar Set a multivar all at once. Values can be comma\-separated or passed as a Python list. Incompatible with the \fBvalue\fP argument. .sp New in version 2015.8.0. .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B global False If \fBTrue\fP, set a global variable .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.config_set user.email me@example.com cwd=/path/to/repo salt myminion git.config_set user.email foo@bar.com global=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.config_unset(key, value_regex=None, cwd=None, user=None, password=None, ignore_retcode=False, output_encoding=None, **kwargs) New in version 2015.8.0. .sp Unset a key in the git configuration file .INDENT 7.0 .TP .B cwd The path to the git checkout. Must be an absolute path, or the word \fBglobal\fP to indicate that a global key should be unset. .TP .B key The name of the configuration key to unset .TP .B value_regex Regular expression that matches exactly one key, used to delete a single value from a multivar. Ignored if \fBall\fP is set to \fBTrue\fP\&. .TP .B all False If \fBTrue\fP unset all values for a multivar. If \fBFalse\fP, and \fBkey\fP is a multivar, an error will be raised. .TP .B global False If \fBTrue\fP, unset set a global variable. Otherwise, a local variable will be unset. .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.config_unset /path/to/repo foo.bar salt myminion git.config_unset /path/to/repo foo.bar all=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.current_branch(cwd, user=None, password=None, ignore_retcode=False, output_encoding=None) Returns the current branch name of a local checkout. If HEAD is detached, return the SHA1 of the revision which is currently checked out. .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.current_branch /path/to/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.describe(cwd, rev=\(aqHEAD\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) Returns the \fI\%git\-describe(1)\fP string (or the SHA1 hash if there are no tags) for the given revision. .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B rev HEAD The revision to describe .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.describe /path/to/repo salt myminion git.describe /path/to/repo develop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.diff(cwd, item1=None, item2=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, no_index=False, cached=False, paths=None, output_encoding=None) New in version 2015.8.12,2016.3.3,2016.11.0. .sp Interface to \fI\%git\-diff(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B item1 and item2 Revision(s) to pass to the \fBgit diff\fP command. One or both of these arguments may be ignored if some of the options below are set to \fBTrue\fP\&. When \fBcached\fP is \fBFalse\fP, and no revisions are passed to this function, then the current working tree will be compared against the index (i.e. unstaged changes). When two revisions are passed, they will be compared to each other. .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBdiff\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B no_index False When it is necessary to diff two files in the same repo against each other, and not diff two different revisions, set this option to \fBTrue\fP\&. If this is left \fBFalse\fP in these instances, then a normal \fBgit diff\fP will be performed against the index (i.e. unstaged changes), and files in the \fBpaths\fP option will be used to narrow down the diff output. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Requires Git 1.5.1 or newer. Additionally, when set to \fBTrue\fP, \fBitem1\fP and \fBitem2\fP will be ignored. .UNINDENT .UNINDENT .TP .B cached False If \fBTrue\fP, compare staged changes to \fBitem1\fP (if specified), otherwise compare them to the most recent commit. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBitem2\fP is ignored if this option is is set to \fBTrue\fP\&. .UNINDENT .UNINDENT .TP .B paths File paths to pass to the \fBgit diff\fP command. Can be passed as a comma\-separated list or a Python list. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Perform diff against the index (staging area for next commit) salt myminion git.diff /path/to/repo # Compare staged changes to the most recent commit salt myminion git.diff /path/to/repo cached=True # Compare staged changes to a specific revision salt myminion git.diff /path/to/repo mybranch cached=True # Perform diff against the most recent commit (includes staged changes) salt myminion git.diff /path/to/repo HEAD # Diff two commits salt myminion git.diff /path/to/repo abcdef1 aabbccd # Diff two commits, only showing differences in the specified paths salt myminion git.diff /path/to/repo abcdef1 aabbccd paths=path/to/file1,path/to/file2 # Diff two files with one being outside the working tree salt myminion git.diff /path/to/repo no_index=True paths=path/to/file1,/absolute/path/to/file2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.discard_local_changes(cwd, path=\(aq.\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) New in version 2019.2.0. .sp Runs a \fBgit checkout \-\- <path>\fP from the directory specified by \fBcwd\fP\&. .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B path path relative to cwd (defaults to \fB\&.\fP) .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.discard_local_changes /path/to/repo salt myminion git.discard_local_changes /path/to/repo path=foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.fetch(cwd, remote=None, force=False, refspecs=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, identity=None, ignore_retcode=False, saltenv=\(aqbase\(aq, output_encoding=None) Changed in version 2015.8.2: Return data is now a dictionary containing information on branches and tags that were added/updated .sp Interface to \fI\%git\-fetch(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B remote Optional remote name to fetch. If not passed, then git will use its default behavior (as detailed in \fI\%git\-fetch(1)\fP). .sp New in version 2015.8.0. .TP .B force Force the fetch even when it is not a fast\-forward. .sp New in version 2015.8.0. .TP .B refspecs Override the refspec(s) configured for the remote with this argument. Multiple refspecs can be passed, comma\-separated. .sp New in version 2015.8.0. .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBfetch\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B identity Path to a private key to use for ssh URLs .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Unless Salt is invoked from the minion using \fBsalt\-call\fP, the key(s) must be passphraseless. For greater security with passphraseless private keys, see the \fI\%sshd(8)\fP manpage for information on securing the keypair from the remote side in the \fBauthorized_keys\fP file. .UNINDENT .UNINDENT .sp Changed in version 2015.8.7: Salt will no longer attempt to use passphrase\-protected keys unless invoked from the minion using \fBsalt\-call\fP, to prevent blocking waiting for user input. .sp Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file .sp Changed in version 2016.3.0. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B saltenv The default salt environment to pull sls files from .sp New in version 2016.3.1. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.fetch /path/to/repo upstream salt myminion git.fetch /path/to/repo identity=/root/.ssh/id_rsa .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.init(cwd, bare=False, template=None, separate_git_dir=None, shared=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) Interface to \fI\%git\-init(1)\fP .INDENT 7.0 .TP .B cwd The path to the directory to be initialized .TP .B bare False If \fBTrue\fP, init a bare repository .sp New in version 2015.8.0. .TP .B template Set this argument to specify an alternate \fI\%template directory\fP .sp New in version 2015.8.0. .TP .B separate_git_dir Set this argument to specify an alternate \fB$GIT_DIR\fP .sp New in version 2015.8.0. .TP .B shared Set sharing permissions on git repo. See \fI\%git\-init(1)\fP for more details. .sp New in version 2015.8.0. .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBinit\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.init /path/to/repo # Init a bare repo (before 2015.8.0) salt myminion git.init /path/to/bare/repo.git opts=\(aq\-\-bare\(aq # Init a bare repo (2015.8.0 and later) salt myminion git.init /path/to/bare/repo.git bare=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.is_worktree(cwd, user=None, password=None, output_encoding=None) New in version 2015.8.0. .sp This function will attempt to determine if \fBcwd\fP is part of a worktree by checking its \fB\&.git\fP to see if it is a file containing a reference to another gitdir. .INDENT 7.0 .TP .B cwd path to the worktree to be removed .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.is_worktree /path/to/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.list_branches(cwd, remote=False, user=None, password=None, ignore_retcode=False, output_encoding=None) New in version 2015.8.0. .sp Return a list of branches .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B remote False If \fBTrue\fP, list remote branches. Otherwise, local branches will be listed. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This option will only return remote branches of which the local checkout is aware, use \fI\%git.fetch\fP to update remotes. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.list_branches /path/to/repo salt myminion git.list_branches /path/to/repo remote=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.list_tags(cwd, user=None, password=None, ignore_retcode=False, output_encoding=None) New in version 2015.8.0. .sp Return a list of tags .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.list_tags /path/to/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.list_worktrees(cwd, stale=False, user=None, password=None, output_encoding=None, **kwargs) New in version 2015.8.0. .sp Returns information on worktrees .sp Changed in version 2015.8.4: Version 2.7.0 added the \fBlist\fP subcommand to \fI\%git\-worktree(1)\fP which provides a lot of additional information. The return data has been changed to include this information, even for pre\-2.7.0 versions of git. In addition, if a worktree has a detached head, then any tags which point to the worktree\(aqs HEAD will be included in the return data. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 By default, only worktrees for which the worktree directory is still present are returned, but this can be changed using the \fBall\fP and \fBstale\fP arguments (described below). .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B all False If \fBTrue\fP, then return all worktrees tracked under $GIT_DIR/worktrees, including ones for which the gitdir is no longer present. .TP .B stale False If \fBTrue\fP, return \fIonly\fP worktrees whose gitdir is no longer present. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Only one of \fBall\fP and \fBstale\fP can be set to \fBTrue\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.list_worktrees /path/to/repo salt myminion git.list_worktrees /path/to/repo all=True salt myminion git.list_worktrees /path/to/repo stale=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.ls_remote(cwd=None, remote=\(aqorigin\(aq, ref=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, identity=None, https_user=None, https_pass=None, ignore_retcode=False, output_encoding=None, saltenv=\(aqbase\(aq) Interface to \fI\%git\-ls\-remote(1)\fP\&. Returns the upstream hash for a remote reference. .INDENT 7.0 .TP .B cwd The path to the git checkout. Optional (and ignored if present) when \fBremote\fP is set to a URL instead of a remote name. .TP .B remote origin The name of the remote to query. Can be the name of a git remote (which exists in the git checkout defined by the \fBcwd\fP parameter), or the URL of a remote repository. .sp Changed in version 2015.8.0: Argument renamed from \fBrepository\fP to \fBremote\fP .TP .B ref The name of the ref to query. Optional, if not specified, all refs are returned. Can be a branch or tag name, or the full name of the reference (for example, to get the hash for a Github pull request number 1234, \fBref\fP can be set to \fBrefs/pull/1234/head\fP .sp Changed in version 2015.8.0: Argument renamed from \fBbranch\fP to \fBref\fP .sp Changed in version 2015.8.4: Defaults to returning all refs instead of master. .TP .B opts Any additional options to add to the command line, in a single string .sp New in version 2015.8.0. .TP .B git_opts Any additional options to add to git command itself (not the \fBls\-remote\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B identity Path to a private key to use for ssh URLs .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Unless Salt is invoked from the minion using \fBsalt\-call\fP, the key(s) must be passphraseless. For greater security with passphraseless private keys, see the \fI\%sshd(8)\fP manpage for information on securing the keypair from the remote side in the \fBauthorized_keys\fP file. .UNINDENT .UNINDENT .sp Changed in version 2015.8.7: Salt will no longer attempt to use passphrase\-protected keys unless invoked from the minion using \fBsalt\-call\fP, to prevent blocking waiting for user input. .sp Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file .sp Changed in version 2016.3.0. .TP .B https_user Set HTTP Basic Auth username. Only accepted for HTTPS URLs. .sp New in version 2015.5.0. .TP .B https_pass Set HTTP Basic Auth password. Only accepted for HTTPS URLs. .sp New in version 2015.5.0. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B saltenv The default salt environment to pull sls files from .sp New in version 2016.3.1. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.ls_remote /path/to/repo origin master salt myminion git.ls_remote remote=https://mydomain.tld/repo.git ref=mytag opts=\(aq\-\-tags\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.merge(cwd, rev=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, identity=None, ignore_retcode=False, output_encoding=None, **kwargs) Interface to \fI\%git\-merge(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B rev Revision to merge into the current branch. If not specified, the remote tracking branch will be merged. .sp New in version 2015.8.0. .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBmerge\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B identity Path to a private key to use for ssh URLs. Salt will not attempt to use passphrase\-protected keys unless invoked from the minion using \fBsalt\-call\fP, to prevent blocking waiting for user input. Key can also be specified as a SaltStack file server URL, eg. \fBsalt://location/identity_file\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For greater security with passphraseless private keys, see the \fI\%sshd(8)\fP manpage for information on securing the keypair from the remote side in the \fBauthorized_keys\fP file. .UNINDENT .UNINDENT .sp New in version 2018.3.5,2019.2.1,3000. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Fetch first... salt myminion git.fetch /path/to/repo # ... then merge the remote tracking branch salt myminion git.merge /path/to/repo # .. or merge another rev salt myminion git.merge /path/to/repo rev=upstream/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.merge_base(cwd, refs=None, octopus=False, is_ancestor=False, independent=False, fork_point=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None, **kwargs) New in version 2015.8.0. .sp Interface to \fI\%git\-merge\-base(1)\fP\&. .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B refs Any refs/commits to check for a merge base. Can be passed as a comma\-separated list or a Python list. .TP .B all False Return a list of all matching merge bases. Not compatible with any of the below options except for \fBoctopus\fP\&. .TP .B octopus False If \fBTrue\fP, then this function will determine the best common ancestors of all specified commits, in preparation for an n\-way merge. See \fI\%here\fP for a description of how these bases are determined. .sp Set \fBall\fP to \fBTrue\fP with this option to return all computed merge bases, otherwise only the \(dqbest\(dq will be returned. .TP .B is_ancestor False If \fBTrue\fP, then instead of returning the merge base, return a boolean telling whether or not the first commit is an ancestor of the second commit. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option requires two commits to be passed. .UNINDENT .UNINDENT .sp Changed in version 2015.8.2: Works properly in git versions older than 1.8.0, where the \fB\-\-is\-ancestor\fP CLI option is not present. .TP .B independent False If \fBTrue\fP, this function will return the IDs of the refs/commits passed which cannot be reached by another commit. .TP .B fork_point If passed, then this function will return the commit where the commit diverged from the ref specified by \fBfork_point\fP\&. If no fork point is found, \fBNone\fP is returned. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 At most one commit is permitted to be passed if a \fBfork_point\fP is specified. If no commits are passed, then \fBHEAD\fP is assumed. .UNINDENT .UNINDENT .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .sp This option should not be necessary unless new CLI arguments are added to \fI\%git\-merge\-base(1)\fP and are not yet supported in Salt. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBmerge\-base\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False if \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.merge_base /path/to/repo HEAD upstream/mybranch salt myminion git.merge_base /path/to/repo 8f2e542,4ad8cab,cdc9886 octopus=True salt myminion git.merge_base /path/to/repo refs=8f2e542,4ad8cab,cdc9886 independent=True salt myminion git.merge_base /path/to/repo refs=8f2e542,4ad8cab is_ancestor=True salt myminion git.merge_base /path/to/repo fork_point=upstream/master salt myminion git.merge_base /path/to/repo refs=mybranch fork_point=upstream/master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.merge_tree(cwd, ref1, ref2, base=None, user=None, password=None, ignore_retcode=False, output_encoding=None) New in version 2015.8.0. .sp Interface to \fI\%git\-merge\-tree(1)\fP, shows the merge results and conflicts from a 3\-way merge without touching the index. .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B ref1 First ref/commit to compare .TP .B ref2 Second ref/commit to compare .TP .B base The base tree to use for the 3\-way\-merge. If not provided, then \fI\%git.merge_base\fP will be invoked on \fBref1\fP and \fBref2\fP to determine the merge base to use. .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False if \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.merge_tree /path/to/repo HEAD upstream/dev salt myminion git.merge_tree /path/to/repo HEAD upstream/dev base=aaf3c3d .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.pull(cwd, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, identity=None, ignore_retcode=False, saltenv=\(aqbase\(aq, output_encoding=None) Interface to \fI\%git\-pull(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBpull\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B identity Path to a private key to use for ssh URLs .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Unless Salt is invoked from the minion using \fBsalt\-call\fP, the key(s) must be passphraseless. For greater security with passphraseless private keys, see the \fI\%sshd(8)\fP manpage for information on securing the keypair from the remote side in the \fBauthorized_keys\fP file. .UNINDENT .UNINDENT .sp Changed in version 2015.8.7: Salt will no longer attempt to use passphrase\-protected keys unless invoked from the minion using \fBsalt\-call\fP, to prevent blocking waiting for user input. .sp Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file .sp Changed in version 2016.3.0. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B saltenv The default salt environment to pull sls files from .sp New in version 2016.3.1. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.pull /path/to/repo opts=\(aq\-\-rebase origin master\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.push(cwd, remote=None, ref=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, identity=None, ignore_retcode=False, saltenv=\(aqbase\(aq, output_encoding=None, **kwargs) Interface to \fI\%git\-push(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B remote Name of the remote to which the ref should being pushed .sp New in version 2015.8.0. .TP .B ref master Name of the ref to push .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Being a \fI\%refspec\fP, this argument can include a colon to define local and remote ref names. .UNINDENT .UNINDENT .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBpush\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B identity Path to a private key to use for ssh URLs .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Unless Salt is invoked from the minion using \fBsalt\-call\fP, the key(s) must be passphraseless. For greater security with passphraseless private keys, see the \fI\%sshd(8)\fP manpage for information on securing the keypair from the remote side in the \fBauthorized_keys\fP file. .UNINDENT .UNINDENT .sp Changed in version 2015.8.7: Salt will no longer attempt to use passphrase\-protected keys unless invoked from the minion using \fBsalt\-call\fP, to prevent blocking waiting for user input. .sp Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file .sp Changed in version 2016.3.0. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B saltenv The default salt environment to pull sls files from .sp New in version 2016.3.1. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Push master as origin/master salt myminion git.push /path/to/repo origin master # Push issue21 as upstream/develop salt myminion git.push /path/to/repo upstream issue21:develop # Delete remote branch \(aqupstream/temp\(aq salt myminion git.push /path/to/repo upstream :temp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.rebase(cwd, rev=\(aqmaster\(aq, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) Interface to \fI\%git\-rebase(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B rev master The revision to rebase onto the current branch .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBrebase\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.rebase /path/to/repo master salt myminion git.rebase /path/to/repo \(aqorigin master\(aq salt myminion git.rebase /path/to/repo origin/master opts=\(aq\-\-onto newbranch\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.remote_get(cwd, remote=\(aqorigin\(aq, user=None, password=None, redact_auth=True, ignore_retcode=False, output_encoding=None) Get the fetch and push URL for a specific remote .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B remote origin Name of the remote to query .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B redact_auth True Set to \fBFalse\fP to include the username/password if the remote uses HTTPS Basic Auth. Otherwise, this information will be redacted. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Setting this to \fBFalse\fP will not only reveal any HTTPS Basic Auth that is configured, but the return data will also be written to the job cache. When possible, it is recommended to use SSH for authentication. .UNINDENT .UNINDENT .sp New in version 2015.5.6. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.remote_get /path/to/repo salt myminion git.remote_get /path/to/repo upstream .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.remote_refs(url, heads=False, tags=False, user=None, password=None, identity=None, https_user=None, https_pass=None, ignore_retcode=False, output_encoding=None, saltenv=\(aqbase\(aq, **kwargs) New in version 2015.8.0. .sp Return the remote refs for the specified URL by running \fBgit ls\-remote\fP\&. .INDENT 7.0 .TP .B url URL of the remote repository .TP .B filter Optionally provide a ref name to \fBgit ls\-remote\fP\&. This can be useful to make this function run faster on repositories with many branches/tags. .sp New in version 2019.2.0. .TP .B heads False Restrict output to heads. Can be combined with \fBtags\fP\&. .TP .B tags False Restrict output to tags. Can be combined with \fBheads\fP\&. .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B identity Path to a private key to use for ssh URLs .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Unless Salt is invoked from the minion using \fBsalt\-call\fP, the key(s) must be passphraseless. For greater security with passphraseless private keys, see the \fI\%sshd(8)\fP manpage for information on securing the keypair from the remote side in the \fBauthorized_keys\fP file. .UNINDENT .UNINDENT .sp Changed in version 2015.8.7: Salt will no longer attempt to use passphrase\-protected keys unless invoked from the minion using \fBsalt\-call\fP, to prevent blocking waiting for user input. .sp Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file .sp Changed in version 2016.3.0. .TP .B https_user Set HTTP Basic Auth username. Only accepted for HTTPS URLs. .TP .B https_pass Set HTTP Basic Auth password. Only accepted for HTTPS URLs. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .TP .B saltenv The default salt environment to pull sls files from .sp New in version 2016.3.1. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.remote_refs https://github.com/saltstack/salt.git salt myminion git.remote_refs https://github.com/saltstack/salt.git filter=develop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.remote_set(cwd, url, remote=\(aqorigin\(aq, user=None, password=None, https_user=None, https_pass=None, push_url=None, push_https_user=None, push_https_pass=None, ignore_retcode=False, output_encoding=None) .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B url Remote URL to set .TP .B remote origin Name of the remote to set .TP .B push_url If unset, the push URL will be identical to the fetch URL. .sp New in version 2015.8.0. .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B https_user Set HTTP Basic Auth username. Only accepted for HTTPS URLs. .sp New in version 2015.5.0. .TP .B https_pass Set HTTP Basic Auth password. Only accepted for HTTPS URLs. .sp New in version 2015.5.0. .TP .B push_https_user Set HTTP Basic Auth user for \fBpush_url\fP\&. Ignored if \fBpush_url\fP is unset. Only accepted for HTTPS URLs. .sp New in version 2015.8.0. .TP .B push_https_pass Set HTTP Basic Auth password for \fBpush_url\fP\&. Ignored if \fBpush_url\fP is unset. Only accepted for HTTPS URLs. .sp New in version 2015.8.0. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.remote_set /path/to/repo git@github.com:user/repo.git salt myminion git.remote_set /path/to/repo git@github.com:user/repo.git remote=upstream salt myminion git.remote_set /path/to/repo https://github.com/user/repo.git remote=upstream push_url=git@github.com:user/repo.git .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.remotes(cwd, user=None, password=None, redact_auth=True, ignore_retcode=False, output_encoding=None) Get fetch and push URLs for each remote in a git checkout .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B redact_auth True Set to \fBFalse\fP to include the username/password for authenticated remotes in the return data. Otherwise, this information will be redacted. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Setting this to \fBFalse\fP will not only reveal any HTTPS Basic Auth that is configured, but the return data will also be written to the job cache. When possible, it is recommended to use SSH for authentication. .UNINDENT .UNINDENT .sp New in version 2015.5.6. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.remotes /path/to/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.reset(cwd, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, identity=None, ignore_retcode=False, output_encoding=None) Interface to \fI\%git\-reset(1)\fP, returns the stdout from the git command .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBreset\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B identity Path to a private key to use for ssh URLs. Salt will not attempt to use passphrase\-protected keys unless invoked from the minion using \fBsalt\-call\fP, to prevent blocking waiting for user input. Key can also be specified as a SaltStack file server URL, eg. \fBsalt://location/identity_file\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For greater security with passphraseless private keys, see the \fI\%sshd(8)\fP manpage for information on securing the keypair from the remote side in the \fBauthorized_keys\fP file. .UNINDENT .UNINDENT .sp New in version 2018.3.5,2019.2.1,3000. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Soft reset to a specific commit ID salt myminion git.reset /path/to/repo ac3ee5c # Hard reset salt myminion git.reset /path/to/repo opts=\(aq\-\-hard origin/master\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.rev_parse(cwd, rev=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) New in version 2015.8.0. .sp Interface to \fI\%git\-rev\-parse(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B rev Revision to parse. See the \fI\%SPECIFYING REVISIONS\fP section of the \fI\%git\-rev\-parse(1)\fP manpage for details on how to format this argument. .sp This argument is optional when using the options in the \fIOptions for Files\fP section of the \fI\%git\-rev\-parse(1)\fP manpage. .TP .B opts Any additional options to add to the command line, in a single string .TP .B git_opts Any additional options to add to git command itself (not the \fBrev\-parse\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Get the full SHA1 for HEAD salt myminion git.rev_parse /path/to/repo HEAD # Get the short SHA1 for HEAD salt myminion git.rev_parse /path/to/repo HEAD opts=\(aq\-\-short\(aq # Get the develop branch\(aqs upstream tracking branch salt myminion git.rev_parse /path/to/repo \(aqdevelop@{upstream}\(aq opts=\(aq\-\-abbrev\-ref\(aq # Get the SHA1 for the commit corresponding to tag v1.2.3 salt myminion git.rev_parse /path/to/repo \(aqv1.2.3^{commit}\(aq # Find out whether or not the repo at /path/to/repo is a bare repository salt myminion git.rev_parse /path/to/repo opts=\(aq\-\-is\-bare\-repository\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.revision(cwd, rev=\(aqHEAD\(aq, short=False, user=None, password=None, ignore_retcode=False, output_encoding=None) Returns the SHA1 hash of a given identifier (hash, branch, tag, HEAD, etc.) .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B rev HEAD The revision .TP .B short False If \fBTrue\fP, return an abbreviated SHA1 git hash .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.revision /path/to/repo mybranch .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.rm_(cwd, filename, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) Interface to \fI\%git\-rm(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B filename The location of the file/directory to remove, relative to \fBcwd\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To remove a directory, \fB\-r\fP must be part of the \fBopts\fP parameter. .UNINDENT .UNINDENT .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBrm\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.rm /path/to/repo foo/bar.py salt myminion git.rm /path/to/repo foo/bar.py opts=\(aq\-\-dry\-run\(aq salt myminion git.rm /path/to/repo foo/baz opts=\(aq\-r\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.stash(cwd, action=\(aqsave\(aq, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) Interface to \fI\%git\-stash(1)\fP, returns the stdout from the git command .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B opts Any additional options to add to the command line, in a single string. Use this to complete the \fBgit stash\fP command by adding the remaining arguments (i.e. \fB\(aqsave <stash comment>\(aq\fP, \fB\(aqapply stash@{2}\(aq\fP, \fB\(aqshow\(aq\fP, etc.). Omitting this argument will simply run \fBgit stash\fP\&. .TP .B git_opts Any additional options to add to git command itself (not the \fBstash\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.stash /path/to/repo save opts=\(aqwork in progress\(aq salt myminion git.stash /path/to/repo apply opts=\(aqstash@{1}\(aq salt myminion git.stash /path/to/repo drop opts=\(aqstash@{1}\(aq salt myminion git.stash /path/to/repo list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.status(cwd, user=None, password=None, ignore_retcode=False, output_encoding=None) Changed in version 2015.8.0: Return data has changed from a list of lists to a dictionary .sp Returns the changes to the repository .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.status /path/to/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.submodule(cwd, command, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, identity=None, ignore_retcode=False, saltenv=\(aqbase\(aq, output_encoding=None, **kwargs) Changed in version 2015.8.0: Added the \fBcommand\fP argument to allow for operations other than \fBupdate\fP to be run on submodules, and deprecated the \fBinit\fP argument. To do a submodule update with \fBinit=True\fP moving forward, use \fBcommand=update opts=\(aq\-\-init\(aq\fP .sp Interface to \fI\%git\-submodule(1)\fP .INDENT 7.0 .TP .B cwd The path to the submodule .TP .B command Submodule command to run, see \fIgit\-submodule(1) <git submodule>\fP for more information. Any additional arguments after the command (such as the URL when adding a submodule) must be passed in the \fBopts\fP parameter. .sp New in version 2015.8.0. .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBsubmodule\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B init False If \fBTrue\fP, ensures that new submodules are initialized .sp Deprecated since version 2015.8.0: Pass \fBinit\fP as the \fBcommand\fP parameter, or include \fB\-\-init\fP in the \fBopts\fP param with \fBcommand\fP set to update. .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B identity Path to a private key to use for ssh URLs .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Unless Salt is invoked from the minion using \fBsalt\-call\fP, the key(s) must be passphraseless. For greater security with passphraseless private keys, see the \fI\%sshd(8)\fP manpage for information on securing the keypair from the remote side in the \fBauthorized_keys\fP file. .UNINDENT .UNINDENT .sp Changed in version 2015.8.7: Salt will no longer attempt to use passphrase\-protected keys unless invoked from the minion using \fBsalt\-call\fP, to prevent blocking waiting for user input. .sp Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file .sp Changed in version 2016.3.0. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B saltenv The default salt environment to pull sls files from .sp New in version 2016.3.1. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Update submodule and ensure it is initialized (before 2015.8.0) salt myminion git.submodule /path/to/repo/sub/repo init=True # Update submodule and ensure it is initialized (2015.8.0 and later) salt myminion git.submodule /path/to/repo/sub/repo update opts=\(aq\-\-init\(aq # Rebase submodule (2015.8.0 and later) salt myminion git.submodule /path/to/repo/sub/repo update opts=\(aq\-\-rebase\(aq # Add submodule (2015.8.0 and later) salt myminion git.submodule /path/to/repo/sub/repo add opts=\(aqhttps://mydomain.tld/repo.git\(aq # Unregister submodule (2015.8.0 and later) salt myminion git.submodule /path/to/repo/sub/repo deinit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.symbolic_ref(cwd, ref, value=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) New in version 2015.8.0. .sp Interface to \fI\%git\-symbolic\-ref(1)\fP .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B ref Symbolic ref to read/modify .TP .B value If passed, then the symbolic ref will be set to this value and an empty string will be returned. .sp If not passed, then the ref to which \fBref\fP points will be returned, unless \fB\-\-delete\fP is included in \fBopts\fP (in which case the symbolic ref will be deleted). .TP .B opts Any additional options to add to the command line, in a single string .TP .B git_opts Any additional options to add to git command itself (not the \fBsymbolic\-refs\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Get ref to which HEAD is pointing salt myminion git.symbolic_ref /path/to/repo HEAD # Set/overwrite symbolic ref \(aqFOO\(aq to local branch \(aqfoo\(aq salt myminion git.symbolic_ref /path/to/repo FOO refs/heads/foo # Delete symbolic ref \(aqFOO\(aq salt myminion git.symbolic_ref /path/to/repo FOO opts=\(aq\-\-delete\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.tag(cwd, name, ref=\(aqHEAD\(aq, message=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) New in version 2018.3.4. .sp Interface to \fI\%git\-tag(1)\fP, adds and removes tags. .INDENT 7.0 .TP .B cwd The path to the main git checkout or a linked worktree .TP .B name Name of the tag .TP .B ref HEAD Which ref to tag (defaults to local clone\(aqs HEAD) .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument is ignored when either \fB\-d\fP or \fB\-\-delete\fP is present in the \fBopts\fP passed to this function. .UNINDENT .UNINDENT .TP .B message Optional message to include with the tag. If provided, an annotated tag will be created. .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Additionally, on the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP (as in the CLI examples below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBworktree\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Create an non\-annotated tag salt myminion git.tag /path/to/repo v1.2 # Create an annotated tag salt myminion git.tag /path/to/repo v1.2 message=\(aqVersion 1.2\(aq # Delete the tag salt myminion git.tag /path/to/repo v1.2 opts=\(aq\-d\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.version(versioninfo=False) New in version 2015.8.0. .sp Returns the version of Git installed on the minion .INDENT 7.0 .TP .B versioninfo False If \fBTrue\fP, return the version in a versioninfo list (e.g. \fB[2, 5, 0]\fP) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.worktree_add(cwd, worktree_path, ref=None, reset_branch=None, force=None, detach=False, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None, **kwargs) New in version 2015.8.0. .sp Interface to \fI\%git\-worktree(1)\fP, adds a worktree .INDENT 7.0 .TP .B cwd The path to the git checkout .TP .B worktree_path Path to the new worktree. Can be either absolute, or relative to \fBcwd\fP\&. .TP .B branch Name of new branch to create. If omitted, will be set to the basename of the \fBworktree_path\fP\&. For example, if the \fBworktree_path\fP is \fB/foo/bar/baz\fP, then \fBbranch\fP will be \fBbaz\fP\&. .TP .B ref Name of the ref on which to base the new worktree. If omitted, then \fBHEAD\fP is use, and a new branch will be created, named for the basename of the \fBworktree_path\fP\&. For example, if the \fBworktree_path\fP is \fB/foo/bar/baz\fP then a new branch \fBbaz\fP will be created, and pointed at \fBHEAD\fP\&. .TP .B reset_branch False If \fBFalse\fP, then \fI\%git\-worktree(1)\fP will fail to create the worktree if the targeted branch already exists. Set this argument to \fBTrue\fP to reset the targeted branch to point at \fBref\fP, and checkout the newly\-reset branch into the new worktree. .TP .B force False By default, \fI\%git\-worktree(1)\fP will not permit the same branch to be checked out in more than one worktree. Set this argument to \fBTrue\fP to override this. .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP to avoid causing errors with Salt\(aqs own argument parsing. .sp All CLI options for adding worktrees as of Git 2.5.0 are already supported by this function as of Salt 2015.8.0, so using this argument is unnecessary unless new CLI arguments are added to \fI\%git\-worktree(1)\fP and are not yet supported in Salt. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBworktree\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.worktree_add /path/to/repo/main ../hotfix ref=origin/master salt myminion git.worktree_add /path/to/repo/main ../hotfix branch=hotfix21 ref=v2.1.9.3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.worktree_prune(cwd, dry_run=False, verbose=True, expire=None, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False, output_encoding=None) New in version 2015.8.0. .sp Interface to \fI\%git\-worktree(1)\fP, prunes stale worktree administrative data from the gitdir .INDENT 7.0 .TP .B cwd The path to the main git checkout or a linked worktree .TP .B dry_run False If \fBTrue\fP, then this function will report what would have been pruned, but no changes will be made. .TP .B verbose True Report all changes made. Set to \fBFalse\fP to suppress this output. .TP .B expire Only prune unused worktree data older than a specific period of time. The date format for this parameter is described in the documentation for the \fBgc.pruneWorktreesExpire\fP config param in the \fI\%git\-config(1)\fP manpage. .TP .B opts Any additional options to add to the command line, in a single string .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On the Salt CLI, if the opts are preceded with a dash, it is necessary to precede them with \fBopts=\fP to avoid causing errors with Salt\(aqs own argument parsing. .sp All CLI options for pruning worktrees as of Git 2.5.0 are already supported by this function as of Salt 2015.8.0, so using this argument is unnecessary unless new CLI arguments are added to \fI\%git\-worktree(1)\fP and are not yet supported in Salt. .UNINDENT .UNINDENT .TP .B git_opts Any additional options to add to git command itself (not the \fBworktree\fP subcommand), in a single string. This is useful for passing \fB\-c\fP to run git with temporary changes to the git configuration. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only supported in git 1.7.2 and newer. .UNINDENT .UNINDENT .TP .B user User under which to run the git command. By default, the command is run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B ignore_retcode False If \fBTrue\fP, do not log an error to the minion log if the git command returns a nonzero exit status. .sp New in version 2015.8.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.worktree_prune /path/to/repo salt myminion git.worktree_prune /path/to/repo dry_run=True salt myminion git.worktree_prune /path/to/repo expire=1.day.ago .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.worktree_rm(cwd, user=None, output_encoding=None) New in version 2015.8.0. .sp Recursively removes the worktree located at \fBcwd\fP, returning \fBTrue\fP if successful. This function will attempt to determine if \fBcwd\fP is actually a worktree by invoking \fI\%git.is_worktree\fP\&. If the path does not correspond to a worktree, then an error will be raised and no action will be taken. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 There is no undoing this action. Be \fBVERY\fP careful before running this function. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B cwd Path to the worktree to be removed .TP .B user Used for path expansion when \fBcwd\fP is not an absolute path. By default, when \fBcwd\fP is not absolute, the path will be assumed to be relative to the home directory of the user under which the minion is running. Setting this option will change the home directory from which path expansion is performed. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion git.worktree_rm /path/to/worktree .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.github .sp Module for interacting with the GitHub v3 API. .sp New in version 2016.3.0. .INDENT 0.0 .TP .B depends PyGithub python module .UNINDENT .SS Configuration .sp Configure this module by specifying the name of a configuration profile in the minion config, minion pillar, or master config. The module will use the \(aqgithub\(aq key by default, if defined. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C github: token: abc1234 org_name: my_organization # optional: some functions require a repo_name, which # can be set in the config file, or passed in at the CLI. repo_name: my_repo # optional: it can be dangerous to change the privacy of a repository # in an automated way. set this to True to allow privacy modifications allow_repo_privacy_changes: False .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.add_repo(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, auto_init=None, gitignore_template=None, license_template=None, profile=\(aqgithub\(aq) Create a new github repository. .INDENT 7.0 .TP .B name The name of the team to be created. .TP .B description The description of the repository. .TP .B homepage The URL with more information about the repository. .TP .B private The visiblity of the repository. Note that private repositories require a paid GitHub account. .TP .B has_issues Whether to enable issues for this repository. .TP .B has_wiki Whether to enable the wiki for this repository. .TP .B has_downloads Whether to enable downloads for this repository. .TP .B auto_init Whether to create an initial commit with an empty README. .TP .B gitignore_template The desired language or platform for a .gitignore, e.g \(dqHaskell\(dq. .TP .B license_template The desired LICENSE template to apply, e.g \(dqmit\(dq or \(dqmozilla\(dq. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.add_repo \(aqrepo_name\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.add_team(name, description=None, repo_names=None, privacy=None, permission=None, profile=\(aqgithub\(aq) Create a new Github team within an organization. .INDENT 7.0 .TP .B name The name of the team to be created. .TP .B description The description of the team. .TP .B repo_names The names of repositories to add the team to. .TP .B privacy The level of privacy for the team, can be \(aqsecret\(aq or \(aqclosed\(aq. .TP .B permission The default permission for new repositories added to the team, can be \(aqpull\(aq, \(aqpush\(aq or \(aqadmin\(aq. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.add_team \(aqteam_name\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.add_team_member(name, team_name, profile=\(aqgithub\(aq) Adds a team member to a team with team_name. .INDENT 7.0 .TP .B name The name of the team member to add. .TP .B team_name The name of the team of which to add the user. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.add_team_member \(aquser_name\(aq \(aqteam_name\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.add_team_repo(repo_name, team_name, profile=\(aqgithub\(aq, permission=None) Adds a repository to a team with team_name. .INDENT 7.0 .TP .B repo_name The name of the repository to add. .TP .B team_name The name of the team of which to add the repository. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B permission The permission for team members within the repository, can be \(aqpull\(aq, \(aqpush\(aq or \(aqadmin\(aq. If not specified, the default permission specified on the team will be used. .sp New in version 2017.7.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.add_team_repo \(aqmy_repo\(aq \(aqteam_name\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.add_user(name, profile=\(aqgithub\(aq) Add a GitHub user. .INDENT 7.0 .TP .B name The user for which to obtain information. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.add_user github\-handle .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.edit_repo(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, profile=\(aqgithub\(aq) Updates an existing Github repository. .INDENT 7.0 .TP .B name The name of the team to be created. .TP .B description The description of the repository. .TP .B homepage The URL with more information about the repository. .TP .B private The visiblity of the repository. Note that private repositories require a paid GitHub account. .TP .B has_issues Whether to enable issues for this repository. .TP .B has_wiki Whether to enable the wiki for this repository. .TP .B has_downloads Whether to enable downloads for this repository. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.add_repo \(aqrepo_name\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.edit_team(name, description=None, privacy=None, permission=None, profile=\(aqgithub\(aq) Updates an existing Github team. .INDENT 7.0 .TP .B name The name of the team to be edited. .TP .B description The description of the team. .TP .B privacy The level of privacy for the team, can be \(aqsecret\(aq or \(aqclosed\(aq. .TP .B permission The default permission for new repositories added to the team, can be \(aqpull\(aq, \(aqpush\(aq or \(aqadmin\(aq. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.edit_team \(aqteam_name\(aq description=\(aqTeam description\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.get_issue(issue_number, repo_name=None, profile=\(aqgithub\(aq, output=\(aqmin\(aq) Return information about a single issue in a named repository. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B issue_number The number of the issue to retrieve. .TP .B repo_name The name of the repository from which to get the issue. This argument is required, either passed via the CLI, or defined in the configured profile. A \fBrepo_name\fP passed as a CLI argument will override the repo_name defined in the configured profile, if provided. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B output The amount of data returned by each issue. Defaults to \fBmin\fP\&. Change to \fBfull\fP to see all issue output. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.get_issue 514 salt myminion github.get_issue 514 repo_name=salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.get_issue_comments(issue_number, repo_name=None, profile=\(aqgithub\(aq, since=None, output=\(aqmin\(aq) Return information about the comments for a given issue in a named repository. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B issue_number The number of the issue for which to retrieve comments. .TP .B repo_name The name of the repository to which the issue belongs. This argument is required, either passed via the CLI, or defined in the configured profile. A \fBrepo_name\fP passed as a CLI argument will override the repo_name defined in the configured profile, if provided. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B since Only comments updated at or after this time are returned. This is a timestamp in ISO 8601 format: \fBYYYY\-MM\-DDTHH:MM:SSZ\fP\&. .TP .B output The amount of data returned by each issue. Defaults to \fBmin\fP\&. Change to \fBfull\fP to see all issue output. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.get_issue_comments 514 salt myminion github.get_issue 514 repo_name=salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.get_issues(repo_name=None, profile=\(aqgithub\(aq, milestone=None, state=\(aqopen\(aq, assignee=None, creator=None, mentioned=None, labels=None, sort=\(aqcreated\(aq, direction=\(aqdesc\(aq, since=None, output=\(aqmin\(aq, per_page=None) Returns information for all issues in a given repository, based on the search options. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B repo_name The name of the repository for which to list issues. This argument is required, either passed via the CLI, or defined in the configured profile. A \fBrepo_name\fP passed as a CLI argument will override the repo_name defined in the configured profile, if provided. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B milestone The number of a GitHub milestone, or a string of either \fB*\fP or \fBnone\fP\&. .sp If a number is passed, it should refer to a milestone by its number field. Use the \fBgithub.get_milestone\fP function to obtain a milestone\(aqs number. .sp If the string \fB*\fP is passed, issues with any milestone are accepted. If the string \fBnone\fP is passed, issues without milestones are returned. .TP .B state Indicates the state of the issues to return. Can be either \fBopen\fP, \fBclosed\fP, or \fBall\fP\&. Default is \fBopen\fP\&. .TP .B assignee Can be the name of a user. Pass in \fBnone\fP (as a string) for issues with no assigned user or \fB*\fP for issues assigned to any user. .TP .B creator The user that created the issue. .TP .B mentioned A user that\(aqs mentioned in the issue. .TP .B labels A string of comma separated label names. For example, \fBbug,ui,@high\fP\&. .TP .B sort What to sort results by. Can be either \fBcreated\fP, \fBupdated\fP, or \fBcomments\fP\&. Default is \fBcreated\fP\&. .TP .B direction The direction of the sort. Can be either \fBasc\fP or \fBdesc\fP\&. Default is \fBdesc\fP\&. .TP .B since Only issues updated at or after this time are returned. This is a timestamp in ISO 8601 format: \fBYYYY\-MM\-DDTHH:MM:SSZ\fP\&. .TP .B output The amount of data returned by each issue. Defaults to \fBmin\fP\&. Change to \fBfull\fP to see all issue output. .TP .B per_page GitHub paginates data in their API calls. Use this value to increase or decrease the number of issues gathered from GitHub, per page. If not set, GitHub defaults are used. Maximum is 100. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.get_issues my\-github\-repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.get_milestone(number=None, name=None, repo_name=None, profile=\(aqgithub\(aq, output=\(aqmin\(aq) Return information about a single milestone in a named repository. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B number The number of the milestone to retrieve. If provided, this option will be favored over \fBname\fP\&. .TP .B name The name of the milestone to retrieve. .TP .B repo_name The name of the repository for which to list issues. This argument is required, either passed via the CLI, or defined in the configured profile. A \fBrepo_name\fP passed as a CLI argument will override the repo_name defined in the configured profile, if provided. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B output The amount of data returned by each issue. Defaults to \fBmin\fP\&. Change to \fBfull\fP to see all issue output. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.get_milestone 72 salt myminion github.get_milestone name=my_milestone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.get_milestones(repo_name=None, profile=\(aqgithub\(aq, state=\(aqopen\(aq, sort=\(aqdue_on\(aq, direction=\(aqasc\(aq, output=\(aqmin\(aq, per_page=None) Return information about milestones for a given repository. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B repo_name The name of the repository for which to list issues. This argument is required, either passed via the CLI, or defined in the configured profile. A \fBrepo_name\fP passed as a CLI argument will override the repo_name defined in the configured profile, if provided. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B state The state of the milestone. Either \fBopen\fP, \fBclosed\fP, or \fBall\fP\&. Default is \fBopen\fP\&. .TP .B sort What to sort results by. Either \fBdue_on\fP or \fBcompleteness\fP\&. Default is \fBdue_on\fP\&. .TP .B direction The direction of the sort. Either \fBasc\fP or \fBdesc\fP\&. Default is \fBasc\fP\&. .TP .B output The amount of data returned by each issue. Defaults to \fBmin\fP\&. Change to \fBfull\fP to see all issue output. .TP .B per_page GitHub paginates data in their API calls. Use this value to increase or decrease the number of issues gathered from GitHub, per page. If not set, GitHub defaults are used. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.get_milestones .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.get_prs(repo_name=None, profile=\(aqgithub\(aq, state=\(aqopen\(aq, head=None, base=None, sort=\(aqcreated\(aq, direction=\(aqdesc\(aq, output=\(aqmin\(aq, per_page=None) Returns information for all pull requests in a given repository, based on the search options provided. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B repo_name The name of the repository for which to list pull requests. This argument is required, either passed via the CLI, or defined in the configured profile. A \fBrepo_name\fP passed as a CLI argument will override the \fBrepo_name\fP defined in the configured profile, if provided. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B state Indicates the state of the pull requests to return. Can be either \fBopen\fP, \fBclosed\fP, or \fBall\fP\&. Default is \fBopen\fP\&. .TP .B head Filter pull requests by head user and branch name in the format of \fBuser:ref\-name\fP\&. Example: \fB\(aqgithub:new\-script\-format\(aq\fP\&. Default is \fBNone\fP\&. .TP .B base Filter pulls by base branch name. Example: \fBgh\-pages\fP\&. Default is \fBNone\fP\&. .TP .B sort What to sort results by. Can be either \fBcreated\fP, \fBupdated\fP, \fBpopularity\fP (comment count), or \fBlong\-running\fP (age, filtering by pull requests updated within the last month). Default is \fBcreated\fP\&. .TP .B direction The direction of the sort. Can be either \fBasc\fP or \fBdesc\fP\&. Default is \fBdesc\fP\&. .TP .B output The amount of data returned by each pull request. Defaults to \fBmin\fP\&. Change to \fBfull\fP to see all pull request output. .TP .B per_page GitHub paginates data in their API calls. Use this value to increase or decrease the number of pull requests gathered from GitHub, per page. If not set, GitHub defaults are used. Maximum is 100. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.get_prs salt myminion github.get_prs base=2016.11 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.get_repo_info(repo_name, profile=\(aqgithub\(aq, ignore_cache=False) Return information for a given repo. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B repo_name The name of the repository. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.get_repo_info salt salt myminion github.get_repo_info salt profile=\(aqmy\-github\-profile\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.get_repo_teams(repo_name, profile=\(aqgithub\(aq) Return teams belonging to a repository. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B repo_name The name of the repository from which to retrieve teams. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.get_repo_teams salt salt myminion github.get_repo_teams salt profile=\(aqmy\-github\-profile\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.get_team(name, profile=\(aqgithub\(aq) Returns the team details if a team with the given name exists, or None otherwise. .INDENT 7.0 .TP .B name The team name for which to obtain information. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.get_team \(aqteam_name\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.get_user(name, profile=\(aqgithub\(aq, user_details=False) Get a GitHub user by name. .INDENT 7.0 .TP .B name The user for which to obtain information. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B user_details Prints user information details. Defaults to \fBFalse\fP\&. If the user is already in the organization and user_details is set to False, the get_user function returns \fBTrue\fP\&. If the user is not already present in the organization, user details will be printed by default. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.get_user github\-handle salt myminion github.get_user github\-handle user_details=true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.is_team_member(name, team_name, profile=\(aqgithub\(aq) Returns True if the github user is in the team with team_name, or False otherwise. .INDENT 7.0 .TP .B name The name of the user whose membership to check. .TP .B team_name The name of the team to check membership in. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.is_team_member \(aquser_name\(aq \(aqteam_name\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.list_members_without_mfa(profile=\(aqgithub\(aq, ignore_cache=False) List all members (in lower case) without MFA turned on. .INDENT 7.0 .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B ignore_cache Bypasses the use of cached team repos. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.list_members_without_mfa .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.list_private_repos(profile=\(aqgithub\(aq) List private repositories within the organization. Dependent upon the access rights of the profile token. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.list_private_repos salt myminion github.list_private_repos profile=\(aqmy\-github\-profile\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.list_public_repos(profile=\(aqgithub\(aq) List public repositories within the organization. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.list_public_repos salt myminion github.list_public_repos profile=\(aqmy\-github\-profile\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.list_repos(profile=\(aqgithub\(aq) List all repositories within the organization. Includes public and private repositories within the organization Dependent upon the access rights of the profile token. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.list_repos salt myminion github.list_repos profile=\(aqmy\-github\-profile\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.list_team_members(team_name, profile=\(aqgithub\(aq, ignore_cache=False) Gets the names of team members in lower case. .INDENT 7.0 .TP .B team_name The name of the team from which to list members. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B ignore_cache Bypasses the use of cached team members. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.list_team_members \(aqteam_name\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.list_team_repos(team_name, profile=\(aqgithub\(aq, ignore_cache=False) Gets the repo details for a given team as a dict from repo_name to repo details. Note that repo names are always in lower case. .INDENT 7.0 .TP .B team_name The name of the team from which to list repos. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B ignore_cache Bypasses the use of cached team repos. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.list_team_repos \(aqteam_name\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.list_teams(profile=\(aqgithub\(aq, ignore_cache=False) Lists all teams with the organization. .INDENT 7.0 .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B ignore_cache Bypasses the use of cached teams. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.list_teams .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.list_users(profile=\(aqgithub\(aq, ignore_cache=False) List all users within the organization. .INDENT 7.0 .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .TP .B ignore_cache Bypasses the use of cached users. .sp New in version 2016.11.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.list_users salt myminion github.list_users profile=\(aqmy\-github\-profile\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.remove_repo(name, profile=\(aqgithub\(aq) Remove a Github repository. .INDENT 7.0 .TP .B name The name of the repository to be removed. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.remove_repo \(aqmy\-repo\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.remove_team(name, profile=\(aqgithub\(aq) Remove a github team. .INDENT 7.0 .TP .B name The name of the team to be removed. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.remove_team \(aqteam_name\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.remove_team_member(name, team_name, profile=\(aqgithub\(aq) Removes a team member from a team with team_name. .INDENT 7.0 .TP .B name The name of the team member to remove. .TP .B team_name The name of the team from which to remove the user. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.remove_team_member \(aquser_name\(aq \(aqteam_name\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.remove_team_repo(repo_name, team_name, profile=\(aqgithub\(aq) Removes a repository from a team with team_name. .INDENT 7.0 .TP .B repo_name The name of the repository to remove. .TP .B team_name The name of the team of which to remove the repository. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.remove_team_repo \(aqmy_repo\(aq \(aqteam_name\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.github.remove_user(name, profile=\(aqgithub\(aq) Remove a Github user by name. .INDENT 7.0 .TP .B name The user for which to obtain information. .TP .B profile The name of the profile configuration to use. Defaults to \fBgithub\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion github.remove_user github\-handle .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.glanceng .sp Glance module for interacting with OpenStack Glance .sp New in version 2018.3.0. .sp :depends:shade .sp Example configuration .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C glance: cloud: default .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C glance: auth: username: admin password: password123 user_domain_name: mydomain project_name: myproject project_domain_name: myproject auth_url: https://example.org:5000/v3 identity_api_version: 3 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glanceng.compare_changes(obj, **kwargs) Compare two dicts returning only keys that exist in the first dict and are different in the second one .UNINDENT .INDENT 0.0 .TP .B salt.modules.glanceng.get_openstack_cloud(auth=None) Return an openstack_cloud .UNINDENT .INDENT 0.0 .TP .B salt.modules.glanceng.get_operator_cloud(auth=None) Return an operator_cloud .UNINDENT .INDENT 0.0 .TP .B salt.modules.glanceng.image_create(auth=None, **kwargs) Create an image .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glanceng.image_create name=cirros file=cirros.raw disk_format=raw salt \(aq*\(aq glanceng.image_create name=cirros file=cirros.raw disk_format=raw hw_scsi_model=virtio\-scsi hw_disk_bus=scsi .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glanceng.image_delete(auth=None, **kwargs) Delete an image .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glanceng.image_delete name=image1 salt \(aq*\(aq glanceng.image_delete name=0e4febc2a5ab4f2c8f374b054162506d .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glanceng.image_get(auth=None, **kwargs) Get a single image .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glanceng.image_get name=image1 salt \(aq*\(aq glanceng.image_get name=0e4febc2a5ab4f2c8f374b054162506d .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glanceng.image_list(auth=None, **kwargs) List images .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glanceng.image_list salt \(aq*\(aq glanceng.image_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glanceng.image_search(auth=None, **kwargs) Search for images .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glanceng.image_search name=image1 salt \(aq*\(aq glanceng.image_search .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glanceng.setup_clouds(auth=None) Call functions to create Shade cloud objects in __context__ to take advantage of Shade\(aqs in\-memory caching across several states .UNINDENT .INDENT 0.0 .TP .B salt.modules.glanceng.update_image_properties(auth=None, **kwargs) Update properties for an image .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glanceng.update_image_properties name=image1 hw_scsi_model=virtio\-scsi hw_disk_bus=scsi salt \(aq*\(aq glanceng.update_image_properties name=0e4febc2a5ab4f2c8f374b054162506d min_ram=1024 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.glassfish .sp Module for working with the Glassfish/Payara 4.x management API \&.. versionadded:: 2016.11.0 :depends: requests .INDENT 0.0 .TP .B salt.modules.glassfish.create_admin_object_resource(name, server=None, **kwargs) Create a JMS destination .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.create_connector_c_pool(name, server=None, **kwargs) Create a connection pool .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.create_connector_resource(name, server=None, **kwargs) Create a connection resource .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.create_jdbc_connection_pool(name, server=None, **kwargs) Create a connection resource .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.create_jdbc_resource(name, server=None, **kwargs) Create a JDBC resource .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.delete_admin_object_resource(name, target=\(aqserver\(aq, server=None) Delete a JMS destination .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.delete_connector_c_pool(name, target=\(aqserver\(aq, cascade=True, server=None) Delete a connection pool .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.delete_connector_resource(name, target=\(aqserver\(aq, server=None) Delete a connection resource .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.delete_jdbc_connection_pool(name, target=\(aqserver\(aq, cascade=False, server=None) Delete a JDBC pool .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.delete_jdbc_resource(name, target=\(aqserver\(aq, server=None) Delete a JDBC resource .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.delete_system_properties(name, server=None) Delete a system property .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.enum_admin_object_resource(server=None) Enum JMS destinations .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.enum_connector_c_pool(server=None) Enum connection pools .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.enum_connector_resource(server=None) Enum connection resources .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.enum_jdbc_connection_pool(server=None) Enum JDBC pools .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.enum_jdbc_resource(server=None) Enum JDBC resources .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.get_admin_object_resource(name, server=None) Get a specific JMS destination .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.get_connector_c_pool(name, server=None) Get a specific connection pool .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.get_connector_resource(name, server=None) Get a specific connection resource .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.get_jdbc_connection_pool(name, server=None) Get a specific JDBC pool .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.get_jdbc_resource(name, server=None) Get a specific JDBC resource .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.get_system_properties(server=None) Get system properties .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.update_admin_object_resource(name, server=None, **kwargs) Update a JMS destination .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.update_connector_c_pool(name, server=None, **kwargs) Update a connection pool .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.update_connector_resource(name, server=None, **kwargs) Update a connection resource .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.update_jdbc_connection_pool(name, server=None, **kwargs) Update a JDBC pool .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.update_jdbc_resource(name, server=None, **kwargs) Update a JDBC resource .UNINDENT .INDENT 0.0 .TP .B salt.modules.glassfish.update_system_properties(data, server=None) Update system properties .UNINDENT .SS salt.modules.glusterfs .sp Manage a glusterfs pool .INDENT 0.0 .TP .B salt.modules.glusterfs.add_volume_bricks(name, bricks) Add brick(s) to an existing volume .INDENT 7.0 .TP .B name Volume name .TP .B bricks List of bricks to add to the volume .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.add_volume_bricks <volume> <bricks> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.create_volume(name, bricks, stripe=False, replica=False, device_vg=False, transport=\(aqtcp\(aq, start=False, force=False, arbiter=False) Create a glusterfs volume .INDENT 7.0 .TP .B name Name of the gluster volume .TP .B bricks Bricks to create volume from, in <peer>:<brick path> format. For multiple bricks use list format: \(aq[\(dq<peer1>:<brick1>\(dq, \(dq<peer2>:<brick2>\(dq]\(aq .TP .B stripe Stripe count, the number of bricks should be a multiple of the stripe count for a distributed striped volume .TP .B replica Replica count, the number of bricks should be a multiple of the replica count for a distributed replicated volume .TP .B arbiter If true, specifies volume should use arbiter brick(s). Valid configuration limited to \(dqreplica 3 arbiter 1\(dq per Gluster documentation. Every third brick in the brick list is used as an arbiter brick. .sp New in version 2019.2.0. .TP .B device_vg If true, specifies volume should use block backend instead of regular posix backend. Block device backend volume does not support multiple bricks .TP .B transport Transport protocol to use, can be \(aqtcp\(aq, \(aqrdma\(aq or \(aqtcp,rdma\(aq .TP .B start Start the volume after creation .TP .B force Force volume creation, this works even if creating in root FS .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt host1 glusterfs.create newvolume host1:/brick salt gluster1 glusterfs.create vol2 \(aq[\(dqgluster1:/export/vol2/brick\(dq, \(dqgluster2:/export/vol2/brick\(dq]\(aq replica=2 start=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.delete_volume(target, stop=True) Deletes a gluster volume .INDENT 7.0 .TP .B target Volume to delete .TP .B stop True If \fBTrue\fP, stop volume before delete .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.delete_volume <volume> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.disable_quota_volume(name) Disable quota on a glusterfs volume. .INDENT 7.0 .TP .B name Name of the gluster volume .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.disable_quota_volume <volume> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.enable_quota_volume(name) Enable quota on a glusterfs volume. .INDENT 7.0 .TP .B name Name of the gluster volume .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.enable_quota_volume <volume> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.get_max_op_version() New in version 2019.2.0. .sp Returns the glusterfs volume\(aqs max op\-version value Requires Glusterfs version > 3.9 .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.get_max_op_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.get_op_version(name) New in version 2019.2.0. .sp Returns the glusterfs volume op\-version .INDENT 7.0 .TP .B name Name of the glusterfs volume .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.get_op_version <volume> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.get_version() New in version 2019.2.0. .sp Returns the version of glusterfs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.get_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.info(name=None) New in version 2015.8.4. .sp Return gluster volume info. .INDENT 7.0 .TP .B name Optional name to retrieve only information of one volume .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.list_quota_volume(name) List quotas of glusterfs volume .INDENT 7.0 .TP .B name Name of the gluster volume .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.list_quota_volume <volume> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.list_volumes() List configured volumes .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.list_volumes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.peer(name) Add another node into the peer list. .INDENT 7.0 .TP .B name The remote host to probe. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqone.gluster.*\(aq glusterfs.peer two .ft P .fi .UNINDENT .UNINDENT .sp GLUSTER direct CLI example (to show what salt is sending to gluster): .INDENT 7.0 .INDENT 3.5 $ gluster peer probe ftp2 .UNINDENT .UNINDENT .INDENT 7.0 .TP .B GLUSTER CLI 3.4.4 return example (so we know what we are parsing): #if the \(dqpeer\(dq is the local host: peer probe: success: on localhost not needed .sp #if the peer was just added: peer probe: success .sp #if the peer was already part of the cluster: peer probe: success: host ftp2 port 24007 already in peer list .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.peer_status() Return peer status information .sp The return value is a dictionary with peer UUIDs as keys and dicts of peer information as values. Hostnames are listed in one list. GlusterFS separates one of the hostnames but the only reason for this seems to be which hostname happens to be used first in peering. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.peer_status .ft P .fi .UNINDENT .UNINDENT .sp GLUSTER direct CLI example (to show what salt is sending to gluster): .INDENT 7.0 .INDENT 3.5 $ gluster peer status .UNINDENT .UNINDENT .sp GLUSTER CLI 3.4.4 return example (so we know what we are parsing): .INDENT 7.0 .INDENT 3.5 Number of Peers: 2 .sp Hostname: ftp2 Port: 24007 Uuid: cbcb256b\-e66e\-4ec7\-a718\-21082d396c24 State: Peer in Cluster (Connected) .sp Hostname: ftp3 Uuid: 5ea10457\-6cb2\-427b\-a770\-7897509625e9 State: Peer in Cluster (Connected) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.set_op_version(version) New in version 2019.2.0. .sp Set the glusterfs volume op\-version .INDENT 7.0 .TP .B version Version to set the glusterfs volume op\-version .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.set_op_version <volume> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.set_quota_volume(name, path, size, enable_quota=False) Set quota to glusterfs volume. .INDENT 7.0 .TP .B name Name of the gluster volume .TP .B path Folder path for restriction in volume (\(dq/\(dq) .TP .B size Hard\-limit size of the volume (MB/GB) .TP .B enable_quota Enable quota before set up restriction .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.set_quota_volume <volume> <path> <size> enable_quota=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.start_volume(name, force=False) Start a gluster volume .INDENT 7.0 .TP .B name Volume name .TP .B force Force the volume start even if the volume is started \&.. versionadded:: 2015.8.4 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.start mycluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.status(name) Check the status of a gluster volume. .INDENT 7.0 .TP .B name Volume name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.status myvolume .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.stop_volume(name, force=False) Stop a gluster volume .INDENT 7.0 .TP .B name Volume name .TP .B force Force stop the volume .sp New in version 2015.8.4. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.stop_volume mycluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.glusterfs.unset_quota_volume(name, path) Unset quota on glusterfs volume .INDENT 7.0 .TP .B name Name of the gluster volume .TP .B path Folder path for restriction in volume .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq glusterfs.unset_quota_volume <volume> <path> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.gnomedesktop .sp GNOME implementations .INDENT 0.0 .TP .B salt.modules.gnomedesktop.get(schema=None, key=None, user=None, **kwargs) Get key in a particular GNOME schema .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gnome.get user=<username> schema=org.gnome.desktop.screensaver key=idle\-activation\-enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gnomedesktop.getClockFormat(**kwargs) Return the current clock format, either 12h or 24h format. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gnome.getClockFormat user=<username> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gnomedesktop.getClockShowDate(**kwargs) Return the current setting, if the date is shown in the clock .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gnome.getClockShowDate user=<username> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gnomedesktop.getIdleActivation(**kwargs) Get whether the idle activation is enabled .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gnome.getIdleActivation user=<username> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gnomedesktop.getIdleDelay(**kwargs) Return the current idle delay setting in seconds .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gnome.getIdleDelay user=<username> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gnomedesktop.ping(**kwargs) A test to ensure the GNOME module is loaded .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gnome.ping user=<username> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gnomedesktop.setClockFormat(clockFormat, **kwargs) Set the clock format, either 12h or 24h format. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gnome.setClockFormat <12h|24h> user=<username> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gnomedesktop.setClockShowDate(kvalue, **kwargs) Set whether the date is visible in the clock .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gnome.setClockShowDate <True|False> user=<username> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gnomedesktop.setIdleActivation(kvalue, **kwargs) Set whether the idle activation is enabled .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gnome.setIdleActivation <True|False> user=<username> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gnomedesktop.setIdleDelay(delaySeconds, **kwargs) Set the current idle delay setting in seconds .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gnome.setIdleDelay <seconds> user=<username> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gnomedesktop.set_(schema=None, key=None, user=None, value=None, **kwargs) Set key in a particular GNOME schema .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gnome.set user=<username> schema=org.gnome.desktop.screensaver key=idle\-activation\-enabled value=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.google_chat .sp Module for sending messages to google chat. .sp New in version 2019.2.0. .sp To use this module you need to configure a webhook in the google chat room where you would like the message to be sent, see: .INDENT 0.0 .INDENT 3.5 \fI\%https://developers.google.com/hangouts/chat/how\-tos/webhooks\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.google_chat.send_message(url, message) Send a message to the google chat room specified in the webhook url. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq google_chat.send_message \(dqhttps://chat.googleapis.com/v1/spaces/example_space/messages?key=example_key\(dq \(dqThis is a test message\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.gpg .sp Manage GPG keychains, add keys, create keys, retrieve keys from keyservers. Sign, encrypt, sign plus encrypt and verify text and files. .sp New in version 2015.5.0. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBpython\-gnupg\fP library and \fBgpg\fP binary are required to be installed. Be aware that the alternate \fBgnupg\fP and \fBpretty\-bad\-protocol\fP libraries are not supported. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.gpg.FixedVerify(gpg) This is a workaround for \fI\%https://github.com/vsajip/python\-gnupg/issues/214\fP\&. It ensures invalid or otherwise unverified signatures are not merged into sig_info in any way. .sp \fI\%https://github.com/vsajip/python\-gnupg/commit/ee94a7ecc1a86484c9f02337e2bbdd05fd32b383\fP .INDENT 7.0 .TP .B handle_status(key, value) Handle status messages from the \fIgpg\fP child process. These are lines of the format .INDENT 7.0 .INDENT 3.5 [GNUPG:] <key> <value> .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- Identifies what the status message is. .IP \(bu 2 \fBvalue\fP (\fI\%str\fP) \-\- Identifies additional data, which differs depending on the key. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.create_key(key_type=\(aqRSA\(aq, key_length=1024, name_real=\(aqAutogenerated Key\(aq, name_comment=\(aqGenerated by SaltStack\(aq, name_email=None, subkey_type=None, subkey_length=None, expire_date=None, use_passphrase=False, user=None, gnupghome=None, keyring=None) Create a key in the GPG keychain .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 GPG key generation requires \fIa lot\fP of entropy and randomness. Difficult to do over a remote connection, consider having another process available which is generating randomness for the machine. Also especially difficult on virtual machines, consider the \fI\%rng\-tools\fP package. .sp The create_key process takes awhile so increasing the timeout may be necessary, e.g. \-t 15. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B key_type The type of the primary key to generate. It must be capable of signing. \(aqRSA\(aq or \(aqDSA\(aq. .TP .B key_length The length of the primary key in bits. .TP .B name_real The real name of the user identity which is represented by the key. .TP .B name_comment A comment to attach to the user id. .TP .B name_email An email address for the user. .TP .B subkey_type The type of the secondary key to generate. .TP .B subkey_length The length of the secondary key in bits. .TP .B expire_date The expiration date for the primary and any secondary key. You can specify an ISO date, A number of days/weeks/months/years, an epoch value, or 0 for a non\-expiring key. .TP .B use_passphrase Whether to use a passphrase with the signing key. The passphrase is retrieved from the Pillar key \fBgpg_passphrase\fP\&. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-t 15 \(aq*\(aq gpg.create_key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.decrypt(user=None, text=None, filename=None, output=None, use_passphrase=False, gnupghome=None, bare=False, keyring=None) Decrypt a message or a file .INDENT 7.0 .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B text The encrypted text to decrypt. .TP .B filename The path of the encrypted file to decrypt. .TP .B output Instead of printing to standard out, write the output to this path. .TP .B use_passphrase Whether to use a passphrase with the signing key. The passphrase is retrieved from Pillar value \fBgpg_passphrase\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B bare If \fBTrue\fP, return the (armored) decrypted block as a string without the standard comment/res dict. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.decrypt filename=\(aq/path/to/important.file.gpg\(aq salt \(aq*\(aq gpg.decrypt filename=\(aq/path/to/important.file.gpg\(aq use_passphrase=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.delete_key(keyid=None, fingerprint=None, delete_secret=False, user=None, gnupghome=None, use_passphrase=True, keyring=None) Delete a key from the GPG keychain. .INDENT 7.0 .TP .B keyid The keyid of the key to be deleted. .TP .B fingerprint The fingerprint of the key to be deleted. .TP .B delete_secret Whether to delete a corresponding secret key prior to deleting the public key. Secret keys must be deleted before deleting any corresponding public keys. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B use_passphrase Whether to use a passphrase with the signing key. The passphrase is retrieved from the Pillar key \fBgpg_passphrase\fP\&. Note that this defaults to True here, contrary to the rest of the module functions that provide this parameter. .sp New in version 3003. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.delete_key keyid=3FAD9F1E salt \(aq*\(aq gpg.delete_key fingerprint=53C96788253E58416D20BCD352952C84C3252192 salt \(aq*\(aq gpg.delete_key keyid=3FAD9F1E user=username salt \(aq*\(aq gpg.delete_key keyid=3FAD9F1E user=username delete_secret=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.encrypt(user=None, recipients=None, text=None, filename=None, output=None, sign=None, use_passphrase=False, always_trust=False, gnupghome=None, bare=False, keyring=None) Encrypt a message or a file .INDENT 7.0 .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B recipients The key ID, fingerprint, user ID or email address associated with the recipients key can be used. .TP .B text The text to encrypt. .TP .B filename The path of the file to encrypt. .TP .B output Instead of printing to standard out, write the output to this path. .TP .B sign Whether to sign, in addition to encrypt, the data. \fBTrue\fP to use default key or fingerprint to specify a different key to sign with. .TP .B use_passphrase Whether to use a passphrase with the signing key. The passphrase is retrieved from the Pillar key \fBgpg_passphrase\fP\&. .TP .B always_trust Skip key validation and assume that used keys are fully trusted. .sp New in version 3006.0. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B bare If \fBTrue\fP, return the (armored) encrypted block as a string without the standard comment/res dict. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.encrypt text=\(aqHello there. How are you?\(aq recipients=recipient@example.com salt \(aq*\(aq gpg.encrypt filename=\(aq/path/to/important.file\(aq recipients=recipient@example.com salt \(aq*\(aq gpg.encrypt filename=\(aq/path/to/important.file\(aq sign=True use_passphrase=True \e recipients=recipient@example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.export_key(keyids=None, secret=False, user=None, gnupghome=None, use_passphrase=False, output=None, bare=False, keyring=None) Export a key from the GPG keychain .INDENT 7.0 .TP .B keyids The key ID(s) of the key(s) to be exported. Can be specified as a comma separated string or a list. Anything which GnuPG itself accepts to identify a key for example, the key ID, fingerprint, user ID or email address could be used. .TP .B secret Export the secret key identified by the \fBkeyids\fP information passed. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B use_passphrase Whether to use a passphrase to export the secret key. The passphrase is retrieved from the Pillar key \fBgpg_passphrase\fP\&. .sp New in version 3003. .TP .B output Instead of printing to standard out, write the output to this path. .sp New in version 3006.0. .TP .B bare If \fBTrue\fP, return the (armored) exported key block as a string without the standard comment/res dict. .sp New in version 3006.0. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.export_key keyids=3FAD9F1E salt \(aq*\(aq gpg.export_key keyids=3FAD9F1E secret=True salt \(aq*\(aq gpg.export_key keyids=\(dq[\(aq3FAD9F1E\(aq,\(aq3FBD8F1E\(aq]\(dq user=username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.get_key(keyid=None, fingerprint=None, user=None, gnupghome=None, keyring=None) Get a key from the GPG keychain .INDENT 7.0 .TP .B keyid The key ID (short or long) of the key to be retrieved. .TP .B fingerprint The fingerprint of the key to be retrieved. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.get_key keyid=3FAD9F1E salt \(aq*\(aq gpg.get_key fingerprint=53C96788253E58416D20BCD352952C84C3252192 salt \(aq*\(aq gpg.get_key keyid=3FAD9F1E user=username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.get_secret_key(keyid=None, fingerprint=None, user=None, gnupghome=None, keyring=None) Get a secret key from the GPG keychain .INDENT 7.0 .TP .B keyid The key ID (short or long) of the key to be retrieved. .TP .B fingerprint The fingerprint of the key to be retrieved. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.get_secret_key keyid=3FAD9F1E salt \(aq*\(aq gpg.get_secret_key fingerprint=53C96788253E58416D20BCD352952C84C3252192 salt \(aq*\(aq gpg.get_secret_key keyid=3FAD9F1E user=username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.import_key(text=None, filename=None, user=None, gnupghome=None, keyring=None) Import a key from text or a file .INDENT 7.0 .TP .B text The text containing the key to import. .TP .B filename The path of the file containing the key to import. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.import_key text=\(aq\-\-\-\-\-BEGIN PGP PUBLIC KEY BLOCK\-\-\-\-\-\en ... \-\-\-\-\-END PGP PUBLIC KEY BLOCK\-\-\-\-\-\(aq salt \(aq*\(aq gpg.import_key filename=\(aq/path/to/public\-key\-file\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.list_keys(user=None, gnupghome=None, keyring=None) List keys in GPG keychain .INDENT 7.0 .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.list_keys .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.list_secret_keys(user=None, gnupghome=None, keyring=None) List secret keys in GPG keychain .INDENT 7.0 .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.list_secret_keys .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.receive_keys(keyserver=None, keys=None, user=None, gnupghome=None, keyring=None) Receive key(s) from keyserver and add them to the keychain .INDENT 7.0 .TP .B keyserver Keyserver to use for searching for GPG keys, defaults to keys.openpgp.org .TP .B keys The keyID(s) to retrieve from the keyserver. Can be specified as a comma separated string or a list. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.receive_keys keys=\(aq3FAD9F1E\(aq salt \(aq*\(aq gpg.receive_keys keys=\(dq[\(aq3FAD9F1E\(aq,\(aq3FBD9F2E\(aq]\(dq salt \(aq*\(aq gpg.receive_keys keys=3FAD9F1E user=username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.search_keys(text, keyserver=None, user=None, gnupghome=None) Search for keys on a keyserver .INDENT 7.0 .TP .B text Text to search the keyserver for, e.g. email address, keyID or fingerprint. .TP .B keyserver Keyserver to use for searching for GPG keys, defaults to keys.openpgp.org. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.search_keys user@example.com salt \(aq*\(aq gpg.search_keys user@example.com keyserver=keyserver.ubuntu.com salt \(aq*\(aq gpg.search_keys user@example.com keyserver=keyserver.ubuntu.com user=username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.sign(user=None, keyid=None, text=None, filename=None, output=None, use_passphrase=False, gnupghome=None, keyring=None) Sign a message or a file .INDENT 7.0 .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B keyid The keyid of the key to use for signing, defaults to the first key in the secret keyring. .TP .B text The text to sign. .TP .B filename The path of the file to sign. .TP .B output Instead of printing to standard out, write the output to this path. .TP .B use_passphrase Whether to use a passphrase with the signing key. The passphrase is retrieved from the Pillar key \fBgpg_passphrase\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.sign text=\(aqHello there. How are you?\(aq salt \(aq*\(aq gpg.sign filename=\(aq/path/to/important.file\(aq salt \(aq*\(aq gpg.sign filename=\(aq/path/to/important.file\(aq use_passphrase=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.trust_key(keyid=None, fingerprint=None, trust_level=None, user=None, gnupghome=None, keyring=None) Set the trust level for a key in the GPG keychain .INDENT 7.0 .TP .B keyid The keyid of the key to set the trust level for. .TP .B fingerprint The fingerprint of the key to set the trust level for. .TP .B trust_level The trust level to set for the specified key, must be one of the following: expired, unknown, not_trusted, marginally, fully, ultimately .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .sp New in version 3007.0. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.trust_key keyid=\(aq3FAD9F1E\(aq trust_level=\(aqmarginally\(aq salt \(aq*\(aq gpg.trust_key fingerprint=\(aq53C96788253E58416D20BCD352952C84C3252192\(aq trust_level=\(aqnot_trusted\(aq salt \(aq*\(aq gpg.trust_key keys=3FAD9F1E trust_level=\(aqultimately\(aq user=\(aqusername\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gpg.verify(text=None, user=None, filename=None, gnupghome=None, signature=None, trustmodel=None, signed_by_any=None, signed_by_all=None, keyring=None) Verify a message or a file .INDENT 7.0 .TP .B text The text to verify. .TP .B filename The path of the file to verify. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome Specify the location where the GPG keyring and related files are stored. .TP .B signature Specify the path of a detached signature. .sp New in version 2018.3.0. .TP .B trustmodel .INDENT 7.0 .TP .B Explicitly define the used trust model. One of: .INDENT 7.0 .IP \(bu 2 pgp .IP \(bu 2 classic .IP \(bu 2 tofu .IP \(bu 2 tofu+pgp .IP \(bu 2 direct .IP \(bu 2 always .IP \(bu 2 auto .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B signed_by_any A list of key fingerprints from which any valid signature will mark verification as passed. If none of the provided keys signed the data, verification will fail. Optional. Note that this does not take into account trust. .sp New in version 3007.0. .TP .B signed_by_all A list of key fingerprints whose signatures are required for verification to pass. If a single provided key did not sign the data, verification will fail. Optional. Note that this does not take into account trust. .sp New in version 3007.0. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gpg.verify text=\(aqHello there. How are you?\(aq salt \(aq*\(aq gpg.verify filename=\(aq/path/to/important.file\(aq salt \(aq*\(aq gpg.verify filename=\(aq/path/to/important.file\(aq trustmodel=direct .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.grafana4 .sp Module for working with the Grafana v4 API .sp New in version 2017.7.0. .INDENT 0.0 .TP .B depends requests .TP .B configuration This module requires a configuration profile to be configured in the minion config, minion pillar, or master config. The module will use the \(aqgrafana\(aq key by default, if defined. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grafana: grafana_url: http://grafana.localhost grafana_user: admin grafana_password: admin grafana_timeout: 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.create_datasource(orgname=None, profile=\(aqgrafana\(aq, **kwargs) Create a new datasource in an organisation. .INDENT 7.0 .TP .B name Name of the data source. .TP .B type Type of the datasource (\(aqgraphite\(aq, \(aqinfluxdb\(aq etc.). .TP .B access Use proxy or direct. .TP .B url The URL to the data source API. .TP .B user Optional \- user to authenticate with the data source. .TP .B password Optional \- password to authenticate with the data source. .TP .B database Optional \- database to use with the data source. .TP .B basicAuth Optional \- set to True to use HTTP basic auth to authenticate with the data source. .TP .B basicAuthUser Optional \- HTTP basic auth username. .TP .B basicAuthPassword Optional \- HTTP basic auth password. .TP .B jsonData Optional \- additional json data to post (eg. \(dqtimeInterval\(dq). .TP .B isDefault Optional \- set data source as default. .TP .B withCredentials Optional \- Whether credentials such as cookies or auth headers should be sent with cross\-site requests. .TP .B typeLogoUrl Optional \- Logo to use for this datasource. .TP .B orgname Name of the organization in which the data source should be created. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.create_datasource .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.create_org(profile=\(aqgrafana\(aq, **kwargs) Create a new organization. .INDENT 7.0 .TP .B name Name of the organization. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.create_org <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.create_org_user(orgname=None, profile=\(aqgrafana\(aq, **kwargs) Add user to the organization. .INDENT 7.0 .TP .B loginOrEmail Login or email of the user. .TP .B role .INDENT 7.0 .TP .B Role of the user for this organization. Should be one of: .INDENT 7.0 .IP \(bu 2 Admin .IP \(bu 2 Editor .IP \(bu 2 Read Only Editor .IP \(bu 2 Viewer .UNINDENT .UNINDENT .TP .B orgname Name of the organization in which users are added. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.create_org_user <orgname> loginOrEmail=<loginOrEmail> role=<role> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.create_update_dashboard(orgname=None, profile=\(aqgrafana\(aq, **kwargs) Create or update a dashboard. .INDENT 7.0 .TP .B dashboard A dict that defines the dashboard to create/update. .TP .B overwrite Whether the dashboard should be overwritten if already existing. .TP .B orgname Name of the organization. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.create_update_dashboard dashboard=<dashboard> overwrite=True orgname=<orgname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.create_user(profile=\(aqgrafana\(aq, **kwargs) Create a new user. .INDENT 7.0 .TP .B login Login of the new user. .TP .B password Password of the new user. .TP .B email Email of the new user. .TP .B name Optional \- Full name of the new user. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.create_user login=<login> password=<password> email=<email> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.delete_dashboard(slug, orgname=None, profile=\(aqgrafana\(aq) Delete a dashboard. .INDENT 7.0 .TP .B slug Slug (name) of the dashboard. .TP .B orgname Name of the organization. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.delete_dashboard <slug> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.delete_datasource(datasourceid, orgname=None, profile=\(aqgrafana\(aq) Delete a datasource. .INDENT 7.0 .TP .B datasourceid Id of the datasource. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.delete_datasource <datasource_id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.delete_org(orgid, profile=\(aqgrafana\(aq) Delete an organization. .INDENT 7.0 .TP .B orgid Id of the organization. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.delete_org <org_id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.delete_org_user(userid, orgname=None, profile=\(aqgrafana\(aq) Remove user from the organization. .INDENT 7.0 .TP .B userid Id of the user. .TP .B orgname Name of the organization in which users are updated. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.delete_org_user <user_id> <orgname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.delete_user(userid, profile=\(aqgrafana\(aq) Delete a user. .INDENT 7.0 .TP .B userid Id of the user. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.delete_user <user_id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.delete_user_org(userid, orgid, profile=\(aqgrafana\(aq) Remove a user from an organization. .INDENT 7.0 .TP .B userid Id of the user. .TP .B orgid Id of the organization. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.delete_user_org <user_id> <org_id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.get_dashboard(slug, orgname=None, profile=\(aqgrafana\(aq) Get a dashboard. .INDENT 7.0 .TP .B slug Slug (name) of the dashboard. .TP .B orgname Name of the organization. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.get_dashboard <slug> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.get_datasource(name, orgname=None, profile=\(aqgrafana\(aq) Show a single datasource in an organisation. .INDENT 7.0 .TP .B name Name of the datasource. .TP .B orgname Name of the organization. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.get_datasource <name> <orgname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.get_datasources(orgname=None, profile=\(aqgrafana\(aq) List all datasources in an organisation. .INDENT 7.0 .TP .B orgname Name of the organization. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.get_datasources <orgname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.get_org(name, profile=\(aqgrafana\(aq) Show a single organization. .INDENT 7.0 .TP .B name Name of the organization. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.get_org <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.get_org_address(orgname=None, profile=\(aqgrafana\(aq) Get the organization address. .INDENT 7.0 .TP .B orgname Name of the organization in which users are updated. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.get_org_address <orgname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.get_org_prefs(orgname=None, profile=\(aqgrafana\(aq) Get the organization preferences. .INDENT 7.0 .TP .B orgname Name of the organization in which users are updated. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.get_org_prefs <orgname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.get_org_users(orgname=None, profile=\(aqgrafana\(aq) Get the list of users that belong to the organization. .INDENT 7.0 .TP .B orgname Name of the organization. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.get_org_users <orgname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.get_orgs(profile=\(aqgrafana\(aq) List all organizations. .INDENT 7.0 .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.get_orgs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.get_user(login, profile=\(aqgrafana\(aq) Show a single user. .INDENT 7.0 .TP .B login Login of the user. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.get_user <login> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.get_user_data(userid, profile=\(aqgrafana\(aq) Get user data. .INDENT 7.0 .TP .B userid Id of the user. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.get_user_data <user_id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.get_user_orgs(userid, profile=\(aqgrafana\(aq) Get the list of organisations a user belong to. .INDENT 7.0 .TP .B userid Id of the user. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.get_user_orgs <user_id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.get_users(profile=\(aqgrafana\(aq) List all users. .INDENT 7.0 .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.get_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.switch_org(orgname, profile=\(aqgrafana\(aq) Switch the current organization. .INDENT 7.0 .TP .B name Name of the organization to switch to. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.switch_org <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.update_datasource(datasourceid, orgname=None, profile=\(aqgrafana\(aq, **kwargs) Update a datasource. .INDENT 7.0 .TP .B datasourceid Id of the datasource. .TP .B name Name of the data source. .TP .B type Type of the datasource (\(aqgraphite\(aq, \(aqinfluxdb\(aq etc.). .TP .B access Use proxy or direct. .TP .B url The URL to the data source API. .TP .B user Optional \- user to authenticate with the data source. .TP .B password Optional \- password to authenticate with the data source. .TP .B database Optional \- database to use with the data source. .TP .B basicAuth Optional \- set to True to use HTTP basic auth to authenticate with the data source. .TP .B basicAuthUser Optional \- HTTP basic auth username. .TP .B basicAuthPassword Optional \- HTTP basic auth password. .TP .B jsonData Optional \- additional json data to post (eg. \(dqtimeInterval\(dq). .TP .B isDefault Optional \- set data source as default. .TP .B withCredentials Optional \- Whether credentials such as cookies or auth headers should be sent with cross\-site requests. .TP .B typeLogoUrl Optional \- Logo to use for this datasource. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.update_datasource <datasourceid> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.update_org(orgid, profile=\(aqgrafana\(aq, **kwargs) Update an existing organization. .INDENT 7.0 .TP .B orgid Id of the organization. .TP .B name New name of the organization. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.update_org <org_id> name=<name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.update_org_address(orgname=None, profile=\(aqgrafana\(aq, **kwargs) Update the organization address. .INDENT 7.0 .TP .B orgname Name of the organization in which users are updated. .TP .B address1 Optional \- address1 of the org. .TP .B address2 Optional \- address2 of the org. .TP .B city Optional \- city of the org. .TP .B zip_code Optional \- zip_code of the org. .TP .B state Optional \- state of the org. .TP .B country Optional \- country of the org. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.update_org_address <orgname> country=<country> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.update_org_prefs(orgname=None, profile=\(aqgrafana\(aq, **kwargs) Update the organization preferences. .INDENT 7.0 .TP .B orgname Name of the organization in which users are updated. .TP .B theme Selected theme for the org. .TP .B homeDashboardId Home dashboard for the org. .TP .B timezone Timezone for the org (one of: \(dqbrowser\(dq, \(dqutc\(dq, or \(dq\(dq). .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.update_org_prefs <orgname> theme=<theme> timezone=<timezone> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.update_org_user(userid, orgname=None, profile=\(aqgrafana\(aq, **kwargs) Update user role in the organization. .INDENT 7.0 .TP .B userid Id of the user. .TP .B loginOrEmail Login or email of the user. .TP .B role .INDENT 7.0 .TP .B Role of the user for this organization. Should be one of: .INDENT 7.0 .IP \(bu 2 Admin .IP \(bu 2 Editor .IP \(bu 2 Read Only Editor .IP \(bu 2 Viewer .UNINDENT .UNINDENT .TP .B orgname Name of the organization in which users are updated. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.update_org_user <user_id> <orgname> loginOrEmail=<loginOrEmail> role=<role> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.update_user(userid, profile=\(aqgrafana\(aq, **kwargs) Update an existing user. .INDENT 7.0 .TP .B userid Id of the user. .TP .B login Optional \- Login of the user. .TP .B email Optional \- Email of the user. .TP .B name Optional \- Full name of the user. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.update_user <user_id> login=<login> email=<email> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.update_user_password(userid, profile=\(aqgrafana\(aq, **kwargs) Update a user password. .INDENT 7.0 .TP .B userid Id of the user. .TP .B password New password of the user. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.update_user_password <user_id> password=<password> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grafana4.update_user_permissions(userid, profile=\(aqgrafana\(aq, **kwargs) Update a user password. .INDENT 7.0 .TP .B userid Id of the user. .TP .B isGrafanaAdmin Whether user is a Grafana admin. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grafana4.update_user_permissions <user_id> isGrafanaAdmin=<true|false> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.grains .sp Return/control aspects of the grains data .sp Grains set or altered with this module are stored in the \(aqgrains\(aq file on the minions. By default, this file is located at: \fB/etc/salt/grains\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This does \fBNOT\fP override any grains set in the minion config file. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.append(key, val, convert=False, delimiter=\(aq:\(aq) New in version 0.17.0. .sp Append a value to a list in the grains config file. If the grain doesn\(aqt exist, the grain key is added and the value is appended to the new grain as a list item. .INDENT 7.0 .TP .B key The grain key to be appended to .TP .B val The value to append to the grain key .TP .B convert If convert is True, convert non\-list contents into a list. If convert is False and the grain contains non\-list contents, an error is given. Defaults to False. .TP .B delimiter The key can be a nested dict key. Use this parameter to specify the delimiter you use, instead of the default \fB:\fP\&. You can now append values to a list in nested dictionary grains. If the list doesn\(aqt exist at this level, it will be created. .sp New in version 2014.7.6. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.append key val .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.delkey(key, force=False) New in version 2017.7.0. .sp Remove a grain completely from the grain system, this will remove the grain key and value .INDENT 7.0 .TP .B key The grain key from which to delete the value. .TP .B force Force remove the grain even when it is a mapped value. Defaults to False .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.delkey key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.delval(key, destructive=False, force=False) New in version 0.17.0. .sp Delete a grain value from the grains config file. This will just set the grain value to \fBNone\fP\&. To completely remove the grain, run \fBgrains.delkey\fP or pass \fBdestructive=True\fP to \fBgrains.delval\fP\&. .INDENT 7.0 .TP .B key The grain key from which to delete the value. .TP .B destructive Delete the key, too. Defaults to False. .TP .B force Force remove the grain even when it is a mapped value. Defaults to False .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.delval key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.equals(key, value) Used to make sure the minion\(aqs grain key/value matches. .sp Returns \fBTrue\fP if matches otherwise \fBFalse\fP\&. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.equals fqdn <expected_fqdn> salt \(aq*\(aq grains.equals systemd:version 219 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.fetch(key, default=\(aq\(aq, delimiter=\(aq:\(aq, ordered=True) Attempt to retrieve the named value from grains, if the named value is not available return the passed default. The default return is an empty string. .sp The value can also represent a value in a nested dict using a \(dq:\(dq delimiter for the dict. This means that if a dict in grains looks like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqpkg\(aq: {\(aqapache\(aq: \(aqhttpd\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp To retrieve the value associated with the apache key in the pkg dict this key can be passed: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pkg:apache .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdelimiter\fP \-\- .sp Specify an alternate delimiter to use when traversing a nested dict. This is useful for when the desired key contains a colon. See CLI example below for usage. .sp New in version 2014.7.0. .IP \(bu 2 \fBordered\fP \-\- .sp Outputs an ordered dict if applicable (default: True) .sp New in version 2016.11.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.get pkg:apache salt \(aq*\(aq grains.get abc::def|ghi delimiter=\(aq|\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.filter_by(lookup_dict, grain=\(aqos_family\(aq, merge=None, default=\(aqdefault\(aq, base=None) New in version 0.17.0. .sp Look up the given grain in a given dictionary for the current OS and return the result .sp Although this may occasionally be useful at the CLI, the primary intent of this function is for use in Jinja to make short work of creating lookup tables for OS\-specific data. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set apache = salt[\(aqgrains.filter_by\(aq]({ \(aqDebian\(aq: {\(aqpkg\(aq: \(aqapache2\(aq, \(aqsrv\(aq: \(aqapache2\(aq}, \(aqRedHat\(aq: {\(aqpkg\(aq: \(aqhttpd\(aq, \(aqsrv\(aq: \(aqhttpd\(aq}, }, default=\(aqDebian\(aq) %} myapache: pkg.installed: \- name: {{ apache.pkg }} service.running: \- name: {{ apache.srv }} .ft P .fi .UNINDENT .UNINDENT .sp Values in the lookup table may be overridden by values in Pillar. An example Pillar to override values in the example above could be as follows: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C apache: lookup: pkg: apache_13 srv: apache .ft P .fi .UNINDENT .UNINDENT .sp The call to \fBfilter_by()\fP would be modified as follows to reference those Pillar values: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set apache = salt[\(aqgrains.filter_by\(aq]({ ... }, merge=salt[\(aqpillar.get\(aq](\(aqapache:lookup\(aq)) %} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBlookup_dict\fP \-\- .sp A dictionary, keyed by a grain, containing a value or values relevant to systems matching that grain. For example, a key could be the grain for an OS and the value could the name of a package on that particular OS. .sp Changed in version 2016.11.0: The dictionary key could be a globbing pattern. The function will return the corresponding \fBlookup_dict\fP value where grain value matches the pattern. For example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C # this will render \(aqgot some salt\(aq if Minion ID begins from \(aqsalt\(aq salt \(aq*\(aq grains.filter_by \(aq{salt*: got some salt, default: salt is not here}\(aq id .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBgrain\fP \-\- .sp The name of a grain to match with the current system\(aqs grains. For example, the value of the \(dqos_family\(dq grain for the current system could be used to pull values from the \fBlookup_dict\fP dictionary. .sp Changed in version 2016.11.0: The grain value could be a list. The function will return the \fBlookup_dict\fP value for a first found item in the list matching one of the \fBlookup_dict\fP keys. .IP \(bu 2 \fBmerge\fP \-\- A dictionary to merge with the results of the grain selection from \fBlookup_dict\fP\&. This allows Pillar to override the values in the \fBlookup_dict\fP\&. This could be useful, for example, to override the values for non\-standard package names such as when using a different Python version from the default Python version provided by the OS (e.g., \fBpython26\-mysql\fP instead of \fBpython\-mysql\fP). .IP \(bu 2 \fBdefault\fP \-\- .sp default lookup_dict\(aqs key used if the grain does not exists or if the grain value has no match on lookup_dict. If unspecified the value is \(dqdefault\(dq. .sp New in version 2014.1.0. .IP \(bu 2 \fBbase\fP \-\- .sp A lookup_dict key to use for a base dictionary. The grain\-selected \fBlookup_dict\fP is merged over this and then finally the \fBmerge\fP dictionary is merged. This allows common values for each case to be collected in the base and overridden by the grain selection dictionary and the merge dictionary. Default is unset. .sp New in version 2015.5.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.filter_by \(aq{Debian: Debheads rule, RedHat: I love my hat}\(aq # this one will render {D: {E: I, G: H}, J: K} salt \(aq*\(aq grains.filter_by \(aq{A: B, C: {D: {E: F, G: H}}}\(aq \(aqxxx\(aq \(aq{D: {E: I}, J: K}\(aq \(aqC\(aq # next one renders {A: {B: G}, D: J} salt \(aq*\(aq grains.filter_by \(aq{default: {A: {B: C}, D: E}, F: {A: {B: G}}, H: {D: I}}\(aq \(aqxxx\(aq \(aq{D: J}\(aq \(aqF\(aq \(aqdefault\(aq # next same as above when default=\(aqH\(aq instead of \(aqF\(aq renders {A: {B: C}, D: J} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.get(key, default=\(aq\(aq, delimiter=\(aq:\(aq, ordered=True) Attempt to retrieve the named value from grains, if the named value is not available return the passed default. The default return is an empty string. .sp The value can also represent a value in a nested dict using a \(dq:\(dq delimiter for the dict. This means that if a dict in grains looks like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqpkg\(aq: {\(aqapache\(aq: \(aqhttpd\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp To retrieve the value associated with the apache key in the pkg dict this key can be passed: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pkg:apache .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdelimiter\fP \-\- .sp Specify an alternate delimiter to use when traversing a nested dict. This is useful for when the desired key contains a colon. See CLI example below for usage. .sp New in version 2014.7.0. .IP \(bu 2 \fBordered\fP \-\- .sp Outputs an ordered dict if applicable (default: True) .sp New in version 2016.11.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.get pkg:apache salt \(aq*\(aq grains.get abc::def|ghi delimiter=\(aq|\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.has_value(key) Determine whether a key exists in the grains dictionary. .sp Given a grains dictionary that contains the following structure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqpkg\(aq: {\(aqapache\(aq: \(aqhttpd\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp One would determine if the apache key in the pkg dict exists by: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pkg:apache .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.has_value pkg:apache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.item(*args, **kwargs) Return one or more grains .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.item os salt \(aq*\(aq grains.item os osrelease oscodename .ft P .fi .UNINDENT .UNINDENT .sp Sanitized CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.item host sanitize=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.items(sanitize=False) Return all of the minion\(aqs grains .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.items .ft P .fi .UNINDENT .UNINDENT .sp Sanitized CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.items sanitize=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.ls() Return a list of all available grains .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.ls .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.remove(key, val, delimiter=\(aq:\(aq) New in version 0.17.0. .sp Remove a value from a list in the grains config file .INDENT 7.0 .TP .B key The grain key to remove. .TP .B val The value to remove. .TP .B delimiter The key can be a nested dict key. Use this parameter to specify the delimiter you use, instead of the default \fB:\fP\&. You can now append values to a list in nested dictionary grains. If the list doesn\(aqt exist at this level, it will be created. .sp New in version 2015.8.2. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.remove key val .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.set(key, val=\(aq\(aq, force=False, destructive=False, delimiter=\(aq:\(aq) Set a key to an arbitrary value. It is used like setval but works with nested keys. .sp This function is conservative. It will only overwrite an entry if its value and the given one are not a list or a dict. The \fBforce\fP parameter is used to allow overwriting in all cases. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBforce\fP \-\- Force writing over existing entry if given or existing values are list or dict. Defaults to False. .IP \(bu 2 \fBdestructive\fP \-\- If an operation results in a key being removed, delete the key, too. Defaults to False. .IP \(bu 2 \fBdelimiter\fP \-\- Specify an alternate delimiter to use when traversing a nested dict, the default being \fB:\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.set \(aqapps:myApp:port\(aq 2209 salt \(aq*\(aq grains.set \(aqapps:myApp\(aq \(aq{port: 2209}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.setval(key, val, destructive=False, refresh_pillar=True) Set a grains value in the grains config file .INDENT 7.0 .TP .B key The grain key to be set. .TP .B val The value to set the grain key to. .TP .B destructive If an operation results in a key being removed, delete the key, too. Defaults to False. .TP .B refresh_pillar Whether pillar will be refreshed. Defaults to True. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.setval key val salt \(aq*\(aq grains.setval key \(dq{\(aqsub\-key\(aq: \(aqval\(aq, \(aqsub\-key2\(aq: \(aqval2\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.setvals(grains, destructive=False, refresh_pillar=True) Set new grains values in the grains config file .INDENT 7.0 .TP .B destructive If an operation results in a key being removed, delete the key, too. Defaults to False. .TP .B refresh_pillar Whether pillar will be refreshed. Defaults to True. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.setvals \(dq{\(aqkey1\(aq: \(aqval1\(aq, \(aqkey2\(aq: \(aqval2\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.groupadd .sp Manage groups on Linux, OpenBSD and NetBSD .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.groupadd.add(name, gid=None, system=False, root=None, non_unique=False, local=False) Changed in version 3006.0. .sp Add the specified group .INDENT 7.0 .TP .B name Name of the new group .TP .B gid Use GID for the new group .TP .B system Create a system account .TP .B root Directory to chroot into .TP .B non_unique Allow creating groups with duplicate (non\-unique) GIDs .sp New in version 3006.0. .TP .B local Specifically add the group locally rather than through remote providers (e.g. LDAP) .sp New in version 3007.0. .UNINDENT .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.groupadd.adduser(name, username, root=None) Add a user in the group. .INDENT 7.0 .TP .B name Name of the group to modify .TP .B username Username to add to the group .TP .B root Directory to chroot into .UNINDENT .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.groupadd.chgid(name, gid, root=None, non_unique=False) Changed in version 3006.0. .sp Change the gid for a named group .INDENT 7.0 .TP .B name Name of the group to modify .TP .B gid Change the group ID to GID .TP .B root Directory to chroot into .TP .B non_unique Allow modifying groups with duplicate (non\-unique) GIDs .sp New in version 3006.0. .UNINDENT .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.groupadd.delete(name, root=None, local=False) Remove the named group .INDENT 7.0 .TP .B name Name group to delete .TP .B root Directory to chroot into .TP .B local (Only on systems with lgroupdel available): Ensure the group account is removed locally ignoring global account management (default is False). .sp New in version 3007.0. .UNINDENT .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.groupadd.deluser(name, username, root=None) Remove a user from the group. .INDENT 7.0 .TP .B name Name of the group to modify .TP .B username Username to delete from the group .TP .B root Directory to chroot into .UNINDENT .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.groupadd.getent(refresh=False, root=None) Return info on all groups .INDENT 7.0 .TP .B refresh Force a refresh of group information .TP .B root Directory to chroot into .UNINDENT .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.groupadd.info(name, root=None) Return information about a group .INDENT 7.0 .TP .B name Name of the group .TP .B root Directory to chroot into .UNINDENT .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.groupadd.members(name, members_list, root=None) Replaces members of the group with a provided list. .INDENT 7.0 .TP .B name Name of the group to modify .TP .B members_list Username list to set into the group .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.members foo \(aquser1,user2,user3,...\(aq .ft P .fi .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.grub_legacy .sp Support for GRUB Legacy .INDENT 0.0 .TP .B salt.modules.grub_legacy.conf() Parse GRUB conf file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grub.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.grub_legacy.version() Return server version from grub \-\-version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grub.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.guestfs .sp Interact with virtual machine images via libguestfs .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 libguestfs .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.guestfs.mount(location, access=\(aqrw\(aq, root=None) Mount an image .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq guest.mount /srv/images/fedora.qcow .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.guestfs.umount(name, disk=None) Unmount an image .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq guestfs.umount /mountpoint disk=/srv/images/fedora.qcow .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.hadoop .sp Support for hadoop .INDENT 0.0 .TP .B maintainer Yann Jouanin <\fI\%yann.jouanin@intelunix.fr\fP> .TP .B maturity new .TP .B depends .TP .B platform linux .UNINDENT .INDENT 0.0 .TP .B salt.modules.hadoop.dfs(command=None, *args) Execute a command on DFS .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hadoop.dfs ls / .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hadoop.dfs_absent(path) Check if a file or directory is absent on the distributed FS. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hadoop.dfs_absent /some_random_file .ft P .fi .UNINDENT .UNINDENT .sp Returns True if the file is absent .UNINDENT .INDENT 0.0 .TP .B salt.modules.hadoop.dfs_present(path) Check if a file or directory is present on the distributed FS. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hadoop.dfs_present /some_random_file .ft P .fi .UNINDENT .UNINDENT .sp Returns True if the file is present .UNINDENT .INDENT 0.0 .TP .B salt.modules.hadoop.dfsadmin_report(arg=None) New in version 2019.2.0. .sp Reports basic filesystem information and statistics. Optional flags may be used to filter the list of displayed DataNodes. .INDENT 7.0 .TP .B arg [live] [dead] [decommissioning] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hadoop.dfsadmin \-report .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hadoop.namenode_format(force=None) Format a name node .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hadoop.namenode_format force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hadoop.version() Return version from hadoop version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hadoop.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.haproxyconn .sp Support for haproxy .sp New in version 2014.7.0. .INDENT 0.0 .TP .B salt.modules.haproxyconn.disable_server(name, backend, socket=\(aq/var/run/haproxy.sock\(aq) Disable server in haproxy. .INDENT 7.0 .TP .B name Server to disable .TP .B backend haproxy backend, or all backends if \(dq*\(dq is supplied .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.disable_server db1.example.com mysql .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.haproxyconn.enable_server(name, backend, socket=\(aq/var/run/haproxy.sock\(aq) Enable Server in haproxy .INDENT 7.0 .TP .B name Server to enable .TP .B backend haproxy backend, or all backends if \(dq*\(dq is supplied .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.enable_server web1.example.com www .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.haproxyconn.get_backend(backend, socket=\(aq/var/run/haproxy.sock\(aq) Receive information about a specific backend. .INDENT 7.0 .TP .B backend haproxy backend .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.get_backend mysql .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.haproxyconn.get_sessions(name, backend, socket=\(aq/var/run/haproxy.sock\(aq) New in version 2016.11.0. .sp Get number of current sessions on server in backend (scur) .INDENT 7.0 .TP .B name Server name .TP .B backend haproxy backend .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.get_sessions web1.example.com www .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.haproxyconn.get_weight(name, backend, socket=\(aq/var/run/haproxy.sock\(aq) Get server weight .INDENT 7.0 .TP .B name Server name .TP .B backend haproxy backend .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.get_weight web1.example.com www .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.haproxyconn.list_backends(servers=True, socket=\(aq/var/run/haproxy.sock\(aq) List HaProxy Backends .INDENT 7.0 .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .TP .B servers list backends with servers .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.list_backends .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.haproxyconn.list_frontends(socket=\(aq/var/run/haproxy.sock\(aq) List HaProxy frontends .INDENT 7.0 .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.list_frontends .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.haproxyconn.list_servers(backend, socket=\(aq/var/run/haproxy.sock\(aq, objectify=False) List servers in haproxy backend. .INDENT 7.0 .TP .B backend haproxy backend .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.list_servers mysql .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.haproxyconn.set_state(name, backend, state, socket=\(aq/var/run/haproxy.sock\(aq) Force a server\(aqs administrative state to a new state. This can be useful to disable load balancing and/or any traffic to a server. Setting the state to \(dqready\(dq puts the server in normal mode, and the command is the equivalent of the \(dqenable server\(dq command. Setting the state to \(dqmaint\(dq disables any traffic to the server as well as any health checks. This is the equivalent of the \(dqdisable server\(dq command. Setting the mode to \(dqdrain\(dq only removes the server from load balancing but still allows it to be checked and to accept new persistent connections. Changes are propagated to tracking servers if any. .INDENT 7.0 .TP .B name Server name .TP .B backend haproxy backend .TP .B state A string of the state to set. Must be \(aqready\(aq, \(aqdrain\(aq, or \(aqmaint\(aq .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.set_state my_proxy_server my_backend ready .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.haproxyconn.set_weight(name, backend, weight=0, socket=\(aq/var/run/haproxy.sock\(aq) Set server weight .INDENT 7.0 .TP .B name Server name .TP .B backend haproxy backend .TP .B weight Server Weight .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.set_weight web1.example.com www 13 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.haproxyconn.show_backends(socket=\(aq/var/run/haproxy.sock\(aq) Show HaProxy Backends .INDENT 7.0 .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.show_backends .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.haproxyconn.show_frontends(socket=\(aq/var/run/haproxy.sock\(aq) Show HaProxy frontends .INDENT 7.0 .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.show_frontends .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.haproxyconn.wait_state(backend, server, value=\(aqup\(aq, timeout=300, socket=\(aq/var/run/haproxy.sock\(aq) Wait for a specific server state .INDENT 7.0 .TP .B backend haproxy backend .TP .B server targeted server .TP .B value state value .TP .B timeout timeout before giving up state value, default 5 min .TP .B socket haproxy stats socket, default \fB/var/run/haproxy.sock\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq haproxy.wait_state mysql server01 up 60 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.hashutil .sp A collection of hashing and encoding functions .INDENT 0.0 .TP .B salt.modules.hashutil.base64_b64decode(instr) Decode a base64\-encoded string using the \(dqmodern\(dq Python interface .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.base64_b64decode \(aqZ2V0IHNhbHRlZA==\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.base64_b64encode(instr) Encode a string as base64 using the \(dqmodern\(dq Python interface. .sp Among other possible differences, the \(dqmodern\(dq encoder does not include newline (\(aqn\(aq) characters in the encoded output. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.base64_b64encode \(aqget salted\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.base64_decodefile(instr, outfile) Decode a base64\-encoded string and write the result to a file .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.base64_decodefile instr=\(aqZ2V0IHNhbHRlZAo=\(aq outfile=\(aq/path/to/binary_file\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.base64_decodestring(instr) Decode a base64\-encoded byte\-like object using the \(dqmodern\(dq Python interface .sp New in version 3000. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.base64_decodestring instr=\(aqZ2V0IHNhbHRlZAo=\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.base64_encodefile(fname) Read a file from the file system and return as a base64 encoded string .sp New in version 2016.3.0. .sp Pillar example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C path: to: data: | {{ salt.hashutil.base64_encodefile(\(aq/path/to/binary_file\(aq) | indent(6) }} .ft P .fi .UNINDENT .UNINDENT .sp The \fI\%file.decode\fP state function can be used to decode this data and write it to disk. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.base64_encodefile /path/to/binary_file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.base64_encodestring(instr) Encode a byte\-like object as base64 using the \(dqmodern\(dq Python interface. .sp Among other possible differences, the \(dqmodern\(dq encoder includes a newline (\(aqn\(aq) character after every 76 characters and always at the end of the encoded byte\-like object. .sp New in version 3000. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.base64_encodestring \(aqget salted\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.digest(instr, checksum=\(aqmd5\(aq) Return a checksum digest for a string .INDENT 7.0 .TP .B instr A string .TP .B checksum \fBmd5\fP The hashing algorithm to use to generate checksums. Valid options: md5, sha256, sha512. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.digest \(aqget salted\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.digest_file(infile, checksum=\(aqmd5\(aq) Return a checksum digest for a file .INDENT 7.0 .TP .B infile A file path .TP .B checksum \fBmd5\fP The hashing algorithm to use to generate checksums. Wraps the \fI\%hashutil.digest\fP execution function. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.digest_file /path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.github_signature(string, shared_secret, challenge_hmac) Verify a challenging hmac signature against a string / shared\-secret for github webhooks. .sp New in version 2017.7.0. .sp Returns a boolean if the verification succeeded or failed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.github_signature \(aq{\(dqref\(dq:....} \(aq \(aqshared secret\(aq \(aqsha1=bc6550fc290acf5b42283fa8deaf55cea0f8c206\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.hmac_compute(string, shared_secret) New in version 3000. .sp Compute a HMAC SHA256 digest using a string and secret. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.hmac_compute \(aqget salted\(aq \(aqshared secret\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.hmac_signature(string, shared_secret, challenge_hmac) Verify a challenging hmac signature against a string / shared\-secret .sp New in version 2014.7.0. .sp Returns a boolean if the verification succeeded or failed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.hmac_signature \(aqget salted\(aq \(aqshared secret\(aq \(aqeBWf9bstXg+NiP5AOwppB5HMvZiYMPzEM9W5YMm/AmQ=\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.md5_digest(instr) Generate an md5 hash of a given string .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.md5_digest \(aqget salted\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.sha256_digest(instr) Generate an sha256 hash of a given string .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.sha256_digest \(aqget salted\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hashutil.sha512_digest(instr) Generate an sha512 hash of a given string .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hashutil.sha512_digest \(aqget salted\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.heat .sp Module for handling OpenStack Heat calls .sp New in version 2017.7.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 heatclient Python module .UNINDENT .TP .B configuration This module is not usable until the user, password, tenant, and auth URL are specified either in a pillar or in the minion\(aqs config file. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C keystone.user: admin keystone.password: verybadpass keystone.tenant: admin keystone.insecure: False #(optional) keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq # Optional keystone.region_name: \(aqRegionOne\(aq .ft P .fi .UNINDENT .UNINDENT .sp If configuration for multiple OpenStack accounts is required, they can be set up as different configuration profiles: For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C openstack1: keystone.user: admin keystone.password: verybadpass keystone.tenant: admin keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq openstack2: keystone.user: admin keystone.password: verybadpass keystone.tenant: admin keystone.auth_url: \(aqhttp://127.0.0.2:5000/v2.0/\(aq .ft P .fi .UNINDENT .UNINDENT .sp With this configuration in place, any of the heat functions can make use of a configuration profile by declaring it explicitly. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq heat.flavor_list profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.heat.create_stack(name=None, template_file=None, environment=None, parameters=None, poll=0, rollback=False, timeout=60, profile=None) Create a stack (heat stack\-create) .INDENT 7.0 .TP .B name Name of the new stack .TP .B template_file File of template .TP .B environment File of environment .TP .B parameters Parameter dict used to create the stack .TP .B poll Poll and report events until stack complete .TP .B rollback Enable rollback on create failure .TP .B timeout Stack creation timeout in minutes .TP .B profile Profile to build on .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq heat.create_stack name=mystack \e template_file=salt://template.yaml \e environment=salt://environment.yaml \e parameters=\(dq{\(dqimage\(dq: \(dqDebian 8\(dq, \(dqflavor\(dq: \(dqm1.small\(dq}\(dq \e poll=5 rollback=False timeout=60 profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.5,2018.3.1: The spelling mistake in parameter \fIenviroment\fP was corrected to \fIenvironment\fP\&. The \fIenviroment\fP spelling mistake has been removed in Salt 3000. .UNINDENT .INDENT 0.0 .TP .B salt.modules.heat.delete_stack(name=None, poll=0, timeout=60, profile=None) Delete a stack (heat stack\-delete) .INDENT 7.0 .TP .B name Name of the stack .TP .B poll Poll and report events until stack complete .TP .B timeout Stack creation timeout in minute .TP .B profile Profile to use .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq heat.delete_stack name=mystack poll=5 \e profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.heat.list_stack(profile=None) Return a list of available stack (heat stack\-list) .INDENT 7.0 .TP .B profile Profile to use .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq heat.list_stack profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.heat.show_stack(name=None, profile=None) Return details about a specific stack (heat stack\-show) .INDENT 7.0 .TP .B name Name of the stack .TP .B profile Profile to use .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq heat.show_stack name=mystack profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.heat.template_stack(name=None, profile=None) Return template a specific stack (heat stack\-template) .INDENT 7.0 .TP .B name Name of the stack .TP .B profile Profile to use .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq heat.template_stack name=mystack profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.heat.update_stack(name=None, template_file=None, environment=None, parameters=None, poll=0, rollback=False, timeout=60, profile=None) Update a stack (heat stack\-template) .INDENT 7.0 .TP .B name Name of the stack .TP .B template_file File of template .TP .B environment File of environment .TP .B parameters Parameter dict used to update the stack .TP .B poll Poll and report events until stack complete .TP .B rollback Enable rollback on update failure .TP .B timeout Stack creation timeout in minutes .TP .B profile Profile to build on .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq heat.update_stack name=mystack \e template_file=salt://template.yaml \e environment=salt://environment.yaml \e parameters=\(dq{\(dqimage\(dq: \(dqDebian 8\(dq, \(dqflavor\(dq: \(dqm1.small\(dq}\(dq \e poll=5 rollback=False timeout=60 profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.5,2018.3.1: The spelling mistake in parameter \fIenviroment\fP was corrected to \fIenvironment\fP\&. The \fIenviroment\fP spelling mistake has been removed in Salt 3000. .UNINDENT .SS salt.modules.helm .sp Interface with Helm .INDENT 0.0 .TP .B depends \fI\%pyhelm\fP Python package .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This module use the helm\-cli. The helm\-cli binary have to be present in your Salt\-Minion path. .UNINDENT .UNINDENT .SS Helm\-CLI vs Salt\-Modules .sp This module is a wrapper of the helm binary. All helm v3.0 command are implemented. .sp To install a chart with the helm\-cli: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C helm install grafana stable/grafana \-\-wait \-\-values /path/to/values.yaml .ft P .fi .UNINDENT .UNINDENT .sp To install a chart with the Salt\-Module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.install grafana stable/grafana values=\(aq/path/to/values.yaml\(aq flags=\(dq[\(aqwait\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .SS Detailed Function Documentation .INDENT 0.0 .TP .B salt.modules.helm.completion(shell, flags=None, kvflags=None) Generate auto\-completions script for Helm for the specified shell (bash or zsh). Return the shell auto\-completion content. .INDENT 7.0 .TP .B shell (string) One of [\(aqbash\(aq, \(aqzsh\(aq]. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.completion bash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.create(name, flags=None, kvflags=None) Creates a chart directory along with the common files and directories used in a chart. Return True if succeed, else the error message. .INDENT 7.0 .TP .B name (string) The chart name to create. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.create NAME .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.dependency_build(chart, flags=None, kvflags=None) Build out the charts/ directory from the Chart.lock file. Return True if succeed, else the error message. .INDENT 7.0 .TP .B chart (string) The chart name to build dependency. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.dependency_build CHART .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.dependency_list(chart, flags=None, kvflags=None) List all of the dependencies declared in a chart. Return chart dependencies if succeed, else the error message. .INDENT 7.0 .TP .B chart (string) The chart name to list dependency. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.dependency_list CHART .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.dependency_update(chart, flags=None, kvflags=None) Update the on\-disk dependencies to mirror Chart.yaml. Return True if succeed, else the error message. .INDENT 7.0 .TP .B chart (string) The chart name to update dependency. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.dependency_update CHART .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.env(flags=None, kvflags=None) Prints out all the environment information in use by Helm. Return Helm environments variables if succeed, else the error message. .INDENT 7.0 .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.env .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.get_all(release, flags=None, kvflags=None) Prints a human readable collection of information about the notes, hooks, supplied values, and generated manifest file of the given release. Return release information if succeed, else the error message. .INDENT 7.0 .TP .B release (string) Release name to get information from. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.get_all RELEASE .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.get_hooks(release, flags=None, kvflags=None) Prints a human readable collection of information about the hooks of the given release. Return release hooks information if succeed, else the error message. .INDENT 7.0 .TP .B release (string) Release name to get hooks information from. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.get_hooks RELEASE .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.get_manifest(release, flags=None, kvflags=None) Prints a human readable collection of information about the manifest of the given release. Return release manifest information if succeed, else the error message. .INDENT 7.0 .TP .B release (string) Release name to get manifest information from. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.get_manifest RELEASE .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.get_notes(release, flags=None, kvflags=None) Prints a human readable collection of information about the notes of the given release. Return release notes information if succeed, else the error message. .INDENT 7.0 .TP .B release (string) Release name to get notes information from. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.get_notes RELEASE .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.get_values(release, flags=None, kvflags=None) Prints a human readable collection of information about the values of the given release. Return release values information if succeed, else the error message. .INDENT 7.0 .TP .B release (string) Release name to get values information from. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.get_values RELEASE # In YAML format salt \(aq*\(aq helm.get_values RELEASE kvflags=\(dq{\(aqoutput\(aq: \(aqyaml\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.help_(command, flags=None, kvflags=None) Provides help for any command in the application. Return the full help if succeed, else the error message. .INDENT 7.0 .TP .B command (string) Command to get help. ex: \(aqget\(aq .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.help COMMAND .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.history(release, flags=None, kvflags=None) Prints historical revisions for a given release. Return release historic if succeed, else the error message. .INDENT 7.0 .TP .B release (string) Release name to get history from. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.history RELEASE # In YAML format salt \(aq*\(aq helm.history RELEASE kvflags=\(dq{\(aqoutput\(aq: \(aqyaml\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.install(release, chart, values=None, version=None, namespace=None, set=None, flags=None, kvflags=None) Installs a chart archive. Return True if succeed, else the error message. .INDENT 7.0 .TP .B release (string) Release name to get values information from. .TP .B chart (string) Chart name to install. .TP .B values (string) Absolute path to the values.yaml file. .TP .B version (string) The exact chart version to install. If this is not specified, the latest version is installed. .TP .B namespace (string) The namespace scope for this request. .TP .B set (string or list) Set a values on the command line. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.install RELEASE CHART # With values file. salt \(aq*\(aq helm.install RELEASE CHART values=\(aq/path/to/values.yaml\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.lint(path, values=None, namespace=None, set=None, flags=None, kvflags=None) Takes a path to a chart and runs a series of tests to verify that the chart is well\-formed. Return True if succeed, else the error message. .INDENT 7.0 .TP .B path (string) The path to the chart to lint. .TP .B values (string) Absolute path to the values.yaml file. .TP .B namespace (string) The namespace scope for this request. .TP .B set (string or list) Set a values on the command line. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.lint PATH .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.list_(namespace=None, flags=None, kvflags=None) Lists all of the releases. By default, it lists only releases that are deployed or failed. Return the list of release if succeed, else the error message. .INDENT 7.0 .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.list # In YAML format salt \(aq*\(aq helm.list kvflags=\(dq{\(aqoutput\(aq: \(aqyaml\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.package(chart, flags=None, kvflags=None) Packages a chart into a versioned chart archive file. If a path is given, this will look at that path for a chart (which must contain a Chart.yaml file) and then package that directory. Return True if succeed, else the error message. .INDENT 7.0 .TP .B chart (string) Chart name to package. Can be an absolute path. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.package CHART # With destination path. salt \(aq*\(aq helm.package CHART kvflags=\(dq{\(aqdestination\(aq: \(aq/path/to/the/package\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.plugin_install(path, flags=None, kvflags=None) Install a Helm plugin from a url to a VCS repo or a local path. Return True if succeed, else the error message. .INDENT 7.0 .TP .B path (string) Path to the local plugin. Can be an url. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.plugin_install PATH .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.plugin_list(flags=None, kvflags=None) List installed Helm plugins. Return the plugin list if succeed, else the error message. .INDENT 7.0 .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.plugin_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.plugin_uninstall(plugin, flags=None, kvflags=None) Uninstall a Helm plugin. Return True if succeed, else the error message. .INDENT 7.0 .TP .B plugin (string) The plugin to uninstall. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.plugin_uninstall PLUGIN .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.plugin_update(plugin, flags=None, kvflags=None) Update a Helm plugin. Return True if succeed, else the error message. .INDENT 7.0 .TP .B plugin (string) The plugin to update. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.plugin_update PLUGIN .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.pull(pkg, flags=None, kvflags=None) Retrieve a package from a package repository, and download it locally. Return True if succeed, else the error message. .INDENT 7.0 .TP .B pkg (string) The package to pull. Can be url or repo/chartname. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.pull PKG # With destination path to write the chart. salt \(aq*\(aq helm.pull PKG kvflags=\(dq{\(aqdestination\(aq: \(aq/path/to/the/chart\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.repo_add(name, url, namespace=None, flags=None, kvflags=None) Add a chart repository. Return True if succeed, else the error message. .INDENT 7.0 .TP .B name (string) The local name of the repository to install. Have to be unique. .TP .B url (string) The url to the repository. .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.repo_add NAME URL .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.repo_index(directory, namespace=None, flags=None, kvflags=None) Read the current directory and generate an index file based on the charts found. Return True if succeed, else the error message. .INDENT 7.0 .TP .B directory (string) The path to the index. .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.index DIRECTORY .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.repo_list(namespace=None, flags=None, kvflags=None) List a chart repository. Return the repository list if succeed, else the error message. .INDENT 7.0 .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.repo_list # In YAML format salt \(aq*\(aq helm.repo_list kvflags=\(dq{\(aqoutput\(aq: \(aqyaml\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.repo_manage(present=None, absent=None, prune=False, namespace=None, flags=None, kvflags=None) Manage charts repository. Return the summery of all actions. .INDENT 7.0 .TP .B present (list) List of repository to be present. It\(aqs a list of dict: [{\(aqname\(aq: \(aqlocal_name\(aq, \(aqurl\(aq: \(aqrepository_url\(aq}] .TP .B absent (list) List of local name repository to be absent. .TP .B prune (boolean \- default: False) If True, all repository already present but not in the present list would be removed. .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.repo_manage present=\(dq[{\(aqname\(aq: \(aqLOCAL_NAME\(aq, \(aqurl\(aq: \(aqREPO_URL\(aq}]\(dq absent=\(dq[\(aqLOCAL_NAME\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.repo_remove(name, namespace=None, flags=None, kvflags=None) Remove a chart repository. Return True if succeed, else the error message. .INDENT 7.0 .TP .B name (string) The local name of the repository to remove. .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.repo_remove NAME .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.repo_update(namespace=None, flags=None, kvflags=None) Update all charts repository. Return True if succeed, else the error message. .INDENT 7.0 .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.repo_update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.rollback(release, revision, namespace=None, flags=None, kvflags=None) Rolls back a release to a previous revision. To see release revision number, execute the history module. Return True if succeed, else the error message. .INDENT 7.0 .TP .B release (string) The name of the release to managed. .TP .B revision (string) The revision number to roll back to. .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.rollback RELEASE REVISION # In dry\-run mode. salt \(aq*\(aq helm.rollback RELEASE REVISION flags=[\(aqdry\-run\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.search_hub(keyword, flags=None, kvflags=None) Search the Helm Hub or an instance of Monocular for Helm charts. Return the research result if succeed, else the error message. .INDENT 7.0 .TP .B keyword (string) The keyword to search in the hub. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.search_hub KEYWORD # In YAML format salt \(aq*\(aq helm.search_hub KEYWORD kvflags=\(dq{\(aqoutput\(aq: \(aqyaml\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.search_repo(keyword, flags=None, kvflags=None) Search reads through all of the repositories configured on the system, and looks for matches. Search of these repositories uses the metadata stored on the system. Return the research result if succeed, else the error message. .INDENT 7.0 .TP .B keyword (string) The keyword to search in the repo. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.search_hub KEYWORD # In YAML format salt \(aq*\(aq helm.search_hub KEYWORD kvflags=\(dq{\(aqoutput\(aq: \(aqyaml\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.show_all(chart, flags=None, kvflags=None) Inspects a chart (directory, file, or URL) and displays all its content (values.yaml, Charts.yaml, README). Return chart information if succeed, else the error message. .INDENT 7.0 .TP .B chart (string) The chart to inspect. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.show_all CHART .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.show_chart(chart, flags=None, kvflags=None) Inspects a chart (directory, file, or URL) and displays the contents of the Charts.yaml file. Return chart information if succeed, else the error message. .INDENT 7.0 .TP .B chart (string) The chart to inspect. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.show_chart CHART .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.show_readme(chart, flags=None, kvflags=None) Inspects a chart (directory, file, or URL) and displays the contents of the README file. Return chart information if succeed, else the error message. .INDENT 7.0 .TP .B chart (string) The chart to inspect. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.show_readme CHART .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.show_values(chart, flags=None, kvflags=None) Inspects a chart (directory, file, or URL) and displays the contents of the values.yaml file. Return chart information if succeed, else the error message. .INDENT 7.0 .TP .B chart (string) The chart to inspect. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.show_values CHART .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.status(release, namespace=None, flags=None, kvflags=None) Show the status of the release. Return the release status if succeed, else the error message. .INDENT 7.0 .TP .B release (string) The release to status. .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.status RELEASE # In YAML format salt \(aq*\(aq helm.status RELEASE kvflags=\(dq{\(aqoutput\(aq: \(aqyaml\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.template(name, chart, values=None, output_dir=None, set=None, flags=None, kvflags=None) Render chart templates locally and display the output. Return the chart renderer if succeed, else the error message. .INDENT 7.0 .TP .B name (string) The template name. .TP .B chart (string) The chart to template. .TP .B values (string) Absolute path to the values.yaml file. .TP .B output_dir (string) Absolute path to the output directory. .TP .B set (string or list) Set a values on the command line. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.template NAME CHART # With values file. salt \(aq*\(aq helm.template NAME CHART values=\(aq/path/to/values.yaml\(aq output_dir=\(aqpath/to/output/dir\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.test(release, flags=None, kvflags=None) Runs the tests for a release. Return the test result if succeed, else the error message. .INDENT 7.0 .TP .B release (string) The release name to test. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.test RELEASE .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.uninstall(release, namespace=None, flags=None, kvflags=None) Uninstall the release name. Return True if succeed, else the error message. .INDENT 7.0 .TP .B release (string) The name of the release to managed. .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.uninstall RELEASE # In dry\-run mode. salt \(aq*\(aq helm.uninstall RELEASE flags=[\(aqdry\-run\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.upgrade(release, chart, values=None, version=None, namespace=None, set=None, flags=None, kvflags=None) Upgrades a release to a new version of a chart. Return True if succeed, else the error message. .INDENT 7.0 .TP .B release (string) The name of the release to managed. .TP .B chart (string) The chart to managed. .TP .B values (string) Absolute path to the values.yaml file. .TP .B version (string) The exact chart version to install. If this is not specified, the latest version is installed. .TP .B namespace (string) The namespace scope for this request. .TP .B set (string or list) Set a values on the command line. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.upgrade RELEASE CHART # In dry\-run mode. salt \(aq*\(aq helm.upgrade RELEASE CHART flags=[\(aqdry\-run\(aq] # With values file. salt \(aq*\(aq helm.upgrade RELEASE CHART values=\(aq/path/to/values.yaml\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.verify(path, flags=None, kvflags=None) Verify that the given chart has a valid provenance file. Return True if succeed, else the error message. .INDENT 7.0 .TP .B path (string) The path to the chart file. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.verify PATH .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.helm.version(flags=None, kvflags=None) Show the version for Helm. Return version information if succeed, else the error message. .INDENT 7.0 .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq helm.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.hg .sp Support for the Mercurial SCM .INDENT 0.0 .TP .B salt.modules.hg.archive(cwd, output, rev=\(aqtip\(aq, fmt=None, prefix=None, user=None) Export a tarball from the repository .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .TP .B output The path to the archive tarball .TP .B rev: tip The revision to create an archive from .TP .B fmt: None Format of the resulting archive. Mercurial supports: tar, tbz2, tgz, zip, uzip, and files formats. .TP .B prefix None Prepend <prefix>/ to every filename in the archive .TP .B user None Run hg as a user other than what the minion runs as .UNINDENT .sp If \fBprefix\fP is not specified it defaults to the basename of the repo directory. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hg.archive /path/to/repo output=/tmp/archive.tgz fmt=tgz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hg.clone(cwd, repository, opts=None, user=None, identity=None) Clone a new repository .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .TP .B repository The hg URI of the repository .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 .TP .B identity None Private SSH key on the minion server for authentication (\fI\%ssh://\fP) .sp New in version 2015.5.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hg.clone /path/to/repo https://bitbucket.org/birkenfeld/sphinx .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hg.describe(cwd, rev=\(aqtip\(aq, user=None) Mimic git describe and return an identifier for the given revision .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .TP .B rev: tip The path to the archive tarball .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 .sp .nf .ft C salt \(aq*\(aq hg.describe /path/to/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hg.pull(cwd, opts=None, user=None, identity=None, repository=None) Perform a pull on the given repository .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .TP .B repository None Perform pull from the repository different from .hg/hgrc:[paths]:default .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 .TP .B identity None Private SSH key on the minion server for authentication (\fI\%ssh://\fP) .sp New in version 2015.5.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hg.pull /path/to/repo opts=\-u .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hg.revision(cwd, rev=\(aqtip\(aq, short=False, user=None) Returns the long hash of a given identifier (hash, branch, tag, HEAD, etc) .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .TP .B rev: tip The revision .TP .B short: False Return an abbreviated commit hash .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 .sp .nf .ft C salt \(aq*\(aq hg.revision /path/to/repo mybranch .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hg.status(cwd, opts=None, user=None) Show changed files of the given repository .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .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 .sp .nf .ft C salt \(aq*\(aq hg.status /path/to/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hg.update(cwd, rev, force=False, user=None) Update to a given revision .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .TP .B rev The revision to update to .TP .B force False Force an update .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 .sp .nf .ft C salt devserver1 hg.update /path/to/repo somebranch .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.highstate_doc .sp This module renders highstate configuration into a more human readable format. .sp How it works: .sp \fIhighstate or lowstate\fP data is parsed with a \fIprocessor\fP this defaults to \fIhighstate_doc.processor_markdown\fP\&. The processed data is passed to a \fIjinja\fP template that builds up the document content. .sp configuration: Pillar .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # the following defaults can be overridden highstate_doc.config: # list of regex of state names to ignore in \(gahighstate_doc.process_lowstates\(ga filter_id_regex: \- \(aq.*!doc_skip$\(aq # list of regex of state functions to ignore in \(gahighstate_doc.process_lowstates\(ga filter_state_function_regex: \- \(aqfile.accumulated\(aq # dict of regex to replace text after \(gahighstate_doc.render\(ga. (remove passwords) text_replace_regex: \(aqpassword:.*^\(aq: \(aq[PASSWORD]\(aq # limit size of files that can be included in doc (10000 bytes) max_render_file_size: 10000 # advanced option to set a custom lowstate processor processor: highstate_doc.processor_markdown .ft P .fi .UNINDENT .UNINDENT .sp State example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{sls}} note: highstate_doc.note: \- name: example \- order: 0 \- contents: | example \(gahighstate_doc.note\(ga \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- This state does not do anything to the system! It is only used by a \(gaprocessor\(ga you can use \(garequisites\(ga and \(gaorder\(ga to move your docs around the rendered file. {{sls}} a file we don\(aqt want in the doc !doc_skip: file.managed: \- name: /root/passwords \- contents: \(aqpassword: sadefgq34y45h56q\(aq # also could use \(gahighstate_doc.config: text_replace_regex\(ga to replace # password string. \(gapassword:.*^\(aq: \(aq[PASSWORD]\(ga .ft P .fi .UNINDENT .UNINDENT .sp To create the help document build a State that uses \fIhighstate_doc.render\fP\&. For performance it\(aqs advised to not included this state in your \fItop.sls\fP file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # example \(gasalt://makereadme.sls\(ga make helpfile: file.managed: \- name: /root/README.md \- contents: {{salt.highstate_doc.render()|json}} \- show_diff: {{opts[\(aqtest\(aq]}} \- mode: \(aq0640\(aq \- order: last .ft P .fi .UNINDENT .UNINDENT .sp Run our \fImakereadme.sls\fP state to create \fI/root/README.md\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # first ensure \(gahighstate\(ga return without errors or changes salt\-call state.highstate salt\-call state.apply makereadme # or if you don\(aqt want the extra \(gamake helpfile\(ga state salt\-call \-\-out=newline_values_only salt.highstate_doc.render > /root/README.md ; chmod 0600 /root/README.md .ft P .fi .UNINDENT .UNINDENT .SS Creating a document collection .sp From the master we can run the following script to creates a collection of all your minion documents. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply makereadme .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!/bin/python import os import salt.client s = salt.client.LocalClient() # NOTE: because of issues with \(gacp.push\(ga use \(gahighstate_doc.read_file\(ga o = s.cmd(\(aq*\(aq, \(aqhighstate_doc.read_file\(aq, [\(aq/root/README.md\(aq]) for m in o: d = o.get(m) if d and not d.endswith(\(aqis not available.\(aq): # mkdir m #directory = os.path.dirname(file_path) if not os.path.exists(m): os.makedirs(m) with open(m + \(aq/README.md\(aq,\(aqwb\(aq) as f: f.write(d) print(\(aqADDED: \(aq + m + \(aq/README.md\(aq) .ft P .fi .UNINDENT .UNINDENT .sp Once the master has a collection of all the README files. You can use pandoc to create HTML versions of the markdown. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # process all the readme.md files to readme.html if which pandoc; then echo \(dqFound pandoc\(dq; else echo \(dq** Missing pandoc\(dq; exit 1; fi if which gs; then echo \(dqFound gs\(dq; else echo \(dq** Missing gs(ghostscript)\(dq; exit 1; fi readme_files=$(find $dest \-type f \-path \(dq*/README.md\(dq \-print) for f in $readme_files ; do ff=${f#$dest/} minion=${ff%%/*} echo \(dqprocess: $dest/${minion}/$(basename $f)\(dq cat $dest/${minion}/$(basename $f) | pandoc \-\-standalone \-\-from markdown_github \-\-to html \-\-include\-in\-header $dest/style.html > $dest/${minion}/$(basename $f).html done .ft P .fi .UNINDENT .UNINDENT .sp It is also nice to put the help files in source control. .INDENT 0.0 .INDENT 3.5 # git init git add \-A git commit \-am \(aqupdated docs\(aq git push \-f .UNINDENT .UNINDENT .SS Other hints .sp If you wish to customize the document format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # you could also create a new \(gaprocessor\(ga for perhaps reStructuredText # highstate_doc.config: # processor: doc_custom.processor_rst # example \(gasalt://makereadme.jinja\(ga \(dq\(dq\(dq {{opts[\(aqid\(aq]}} ========================================== {# lowstates is set from highstate_doc.render() #} {# if lowstates is missing use salt.highstate_doc.process_lowstates() #} {% for s in lowstates %} {{s.id}} \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- {{s.function}} {{s.markdown.requisite}} {{s.markdown.details}} {%\- endfor %} \(dq\(dq\(dq # example \(gasalt://makereadme.sls\(ga {% import_text \(dqmakereadme.jinja\(dq as makereadme %} {{sls}} or: file.managed: \- name: /root/README_other.md \- contents: {{salt.highstate_doc.render(jinja_template_text=makereadme)|json}} \- mode: \(aq0640\(aq .ft P .fi .UNINDENT .UNINDENT .sp Some \fIreplace_text_regex\fP values that might be helpful: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C CERTS \-\-\-\-\- \(ga\(ga\(aq\-\-\-\-\-BEGIN RSA PRIVATE KEY\-\-\-\-\-[\er\en\et\ef\eS]{0,2200}\(aq: \(aqXXXXXXX\(aq\(ga\(ga \(ga\(ga\(aq\-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\-[\er\en\et\ef\eS]{0,2200}\(aq: \(aqXXXXXXX\(aq\(ga\(ga \(ga\(ga\(aq\-\-\-\-\-BEGIN DH PARAMETERS\-\-\-\-\-[\er\en\et\ef\eS]{0,2200}\(aq: \(aqXXXXXXX\(aq\(ga\(ga \(ga\(ga\(aq\-\-\-\-\-BEGIN PRIVATE KEY\-\-\-\-\-[\er\en\et\ef\eS]{0,2200}\(aq: \(aqXXXXXXX\(aq\(ga\(ga \(ga\(ga\(aq\-\-\-\-\-BEGIN OPENSSH PRIVATE KEY\-\-\-\-\-[\er\en\et\ef\eS]{0,2200}\(aq: \(aqXXXXXXX\(aq\(ga\(ga \(ga\(ga\(aqssh\-rsa .* \(aq: \(aqssh\-rsa XXXXXXX \(aq\(ga\(ga \(ga\(ga\(aqssh\-dss .* \(aq: \(aqssh\-dss XXXXXXX \(aq\(ga\(ga DB \-\- \(ga\(ga\(aqDB_PASS.*\(aq: \(aqDB_PASS = XXXXXXX\(aq\(ga\(ga \(ga\(ga\(aq5432:*:*:.*\(aq: \(aq5432:*:XXXXXXX\(aq\(ga\(ga \(ga\(ga\(dq\(aqPASSWORD\(aq: .*\(dq: \(dq\(aqPASSWORD\(aq: \(aqXXXXXXX\(aq,\(dq\(ga\(ga \(ga\(ga\(dq PASSWORD \(aq.*\(aq\(dq: \(dq PASSWORD \(aqXXXXXXX\(aq\(dq\(ga\(ga \(ga\(ga\(aqPGPASSWORD=.* \(aq: \(aqPGPASSWORD=XXXXXXX\(aq\(ga\(ga \(ga\(ga\(dq_replication password \(aq.*\(aq\(dq: \(dq_replication password \(aqXXXXXXX\(aq\(dq\(ga\(ga OTHER \-\-\-\-\- \(ga\(ga\(aqEMAIL_HOST_PASSWORD =.*\(aq: \(aqEMAIL_HOST_PASSWORD =XXXXXXX\(aq\(ga\(ga \(ga\(ga\(dqnet ads join \-U \(aq.*@MFCFADS.MATH.EXAMPLE.CA.* \(dq: \(dqnet ads join \-U \(aq.*@MFCFADS.MATH.EXAMPLE.CA%XXXXXXX \(dq\(ga\(ga \(ga\(ga\(dqnet ads join \-U \(aq.*@NEXUS.EXAMPLE.CA.* \(dq: \(dqnet ads join \-U \(aq.*@NEXUS.EXAMPLE.CA%XXXXXXX \(dq\(ga\(ga \(ga\(ga\(aqinstall\-uptrack .* \-\-autoinstall\(aq: \(aqinstall\-uptrack XXXXXXX \-\-autoinstall\(aq\(ga\(ga \(ga\(ga\(aqaccesskey = .*\(aq: \(aqaccesskey = XXXXXXX\(aq\(ga\(ga \(ga\(ga\(aqauth_pass .*\(aq: \(aqauth_pass XXXXXXX\(aq\(ga\(ga \(ga\(ga\(aqPSK \(dq0x.*\(aq: \(aqPSK \(dq0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\(aq\(ga\(ga \(ga\(ga\(aqSECRET_KEY.*\(aq: \(aqSECRET_KEY = XXXXXXX\(aq\(ga\(ga \(ga\(ga\(dqpassword=.*\(dq: \(dqpassword=XXXXXXX\(dq\(ga\(ga \(ga\(ga\(aq<password>.*</password>\(aq: \(aq<password>XXXXXXX</password>\(aq\(ga\(ga \(ga\(ga\(aq<salt>.*</salt>\(aq: \(aq<salt>XXXXXXX</salt>\(aq\(ga\(ga \(ga\(ga\(aqapplication.secret = \(dq.*\(dq\(aq: \(aqapplication.secret = \(dqXXXXXXX\(dq\(aq\(ga\(ga \(ga\(ga\(aqurl = \(dqpostgres://.*\(dq\(aq: \(aqurl = \(dqpostgres://XXXXXXX\(dq\(aq\(ga\(ga \(ga\(ga\(aqPASS_.*_PASS\(aq: \(aqPASS_XXXXXXX_PASS\(aq\(ga\(ga HTACCESS \-\-\-\-\-\-\-\- \(ga\(ga\(aq:{PLAIN}.*\(aq: \(aq:{PLAIN}XXXXXXX\(aq\(ga\(ga .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.highstate_doc.markdown_basic_jinja_template(**kwargs) Return text for a simple markdown jinja template .sp This function can be used from the \fIhighstate_doc.render\fP modules \fIjinja_template_function\fP option. .UNINDENT .INDENT 0.0 .TP .B salt.modules.highstate_doc.markdown_default_jinja_template(**kwargs) Return text for a markdown jinja template that included a header .sp This function can be used from the \fIhighstate_doc.render\fP modules \fIjinja_template_function\fP option. .UNINDENT .INDENT 0.0 .TP .B salt.modules.highstate_doc.markdown_full_jinja_template(**kwargs) Return text for an advanced markdown jinja template .sp This function can be used from the \fIhighstate_doc.render\fP modules \fIjinja_template_function\fP option. .UNINDENT .INDENT 0.0 .TP .B salt.modules.highstate_doc.process_lowstates(**kwargs) return processed lowstate data that was not blacklisted .sp render_module_function is used to provide your own. defaults to from_lowstate .UNINDENT .INDENT 0.0 .TP .B salt.modules.highstate_doc.processor_markdown(lowstate_item, config, **kwargs) Takes low state data and returns a dict of processed data that is by default used in a jinja template when rendering a markdown highstate_doc. .sp This \fIlowstate_item_markdown\fP given a lowstate item, returns a dict like: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C vars: # the raw lowstate_item that was processed id: # the \(aqid\(aq of the state. id_full: # combo of the state type and id \(dqstate: id\(dq state: # name of the salt state module function: # name of the state function name: # value of \(aqname:\(aq passed to the salt state module state_function: # the state name and function name markdown: # text data to describe a state requisites: # requisite like [watch_in, require_in] details: # state name, parameters and other details like file contents .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.highstate_doc.read_file(name) output the contents of a file: .sp this is a workaround if the cp.push module does not work. \fI\%https://github.com/saltstack/salt/issues/37133\fP .sp help the master output the contents of a document that might be saved on the minions filesystem. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C #!/bin/python import os import salt.client s = salt.client.LocalClient() o = s.cmd(\(aq*\(aq, \(aqhighstate_doc.read_file\(aq, [\(aq/root/README.md\(aq]) for m in o: d = o.get(m) if d and not d.endswith(\(aqis not available.\(aq): # mkdir m #directory = os.path.dirname(file_path) if not os.path.exists(m): os.makedirs(m) with open(m + \(aq/README.md\(aq,\(aqwb\(aq) as fin: fin.write(d) print(\(aqADDED: \(aq + m + \(aq/README.md\(aq) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.highstate_doc.render(jinja_template_text=None, jinja_template_function=\(aqhighstate_doc.markdown_default_jinja_template\(aq, **kwargs) Render highstate to a text format (default Markdown) .sp if \fIjinja_template_text\fP is not set, \fIjinja_template_function\fP is used. .sp jinja_template_text: jinja text that the render uses to create the document. jinja_template_function: a salt module call that returns template text. .INDENT 7.0 .TP .B Options highstate_doc.markdown_basic_jinja_template highstate_doc.markdown_default_jinja_template highstate_doc.markdown_full_jinja_template .UNINDENT .UNINDENT .SS salt.modules.hosts .sp Manage the information in the hosts file .INDENT 0.0 .TP .B salt.modules.hosts.add_host(ip, alias) Add a host to an existing entry, if the entry is not in place then create it with the given host .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hosts.add_host <ip> <alias> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.get_alias(ip) Return the list of aliases associated with an ip .sp Aliases (host names) are returned in the order in which they appear in the hosts file. If there are no aliases associated with the IP, an empty list is returned. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hosts.get_alias <ip addr> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.get_ip(host) Return the ip associated with the named host .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hosts.get_ip <hostname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.has_pair(ip, alias) Return true if the alias is set .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hosts.has_pair <ip> <alias> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.list_hosts() Return the hosts found in the hosts file in this format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<ip addr>\(aq: [\(aqalias1\(aq, \(aqalias2\(aq, ...]} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hosts.list_hosts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.rm_host(ip, alias) Remove a host entry from the hosts file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hosts.rm_host <ip> <alias> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.set_comment(ip, comment) Set the comment for a host to an existing entry, if the entry is not in place then return False .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hosts.set_comment <ip> <comment> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.set_host(ip, alias, comment=None) Set the host entry in the hosts file for the given ip, this will overwrite any previous entry for the given ip .sp Changed in version 2016.3.0: If \fBalias\fP does not include any host names (it is the empty string or contains only whitespace), all entries for the given IP address are removed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hosts.set_host <ip> <alias> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.http .sp Module for making various web calls. Primarily designed for webhooks and the like, but also useful for basic http testing. .sp New in version 2015.5.0. .INDENT 0.0 .TP .B salt.modules.http.query(url, **kwargs) New in version 2015.5.0. .sp Query a resource, and decode the return data .sp Passes through all the parameters described in the \fI\%utils.http.query function\fP: .INDENT 7.0 .TP .B salt.utils.http.query(url, method=\(aqGET\(aq, params=None, data=None, data_file=None, header_dict=None, header_list=None, header_file=None, username=None, password=None, auth=None, decode=False, decode_type=\(aqauto\(aq, status=False, headers=False, text=False, cookies=None, cookie_jar=None, cookie_format=\(aqlwp\(aq, persist_session=False, session_cookie_jar=None, data_render=False, data_renderer=None, header_render=False, header_renderer=None, template_dict=None, test=False, test_url=None, node=\(aqminion\(aq, port=80, opts=None, backend=None, ca_bundle=None, verify_ssl=None, cert=None, text_out=None, headers_out=None, decode_out=None, stream=False, streaming_callback=None, header_callback=None, handle=False, agent=\(aqSalt/3007.1\(aq, hide_fields=None, raise_error=True, formdata=False, formdata_fieldname=None, formdata_filename=None, decode_body=True, **kwargs) Query a resource, and decode the return data .UNINDENT .INDENT 7.0 .TP .B raise_error True If \fBFalse\fP, and if a connection cannot be made, the error will be suppressed and the body of the return will simply be \fBNone\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq http.query http://somelink.com/ salt \(aq*\(aq http.query http://somelink.com/ method=POST params=\(aq{\(dqkey1\(dq: \(dqval1\(dq, \(dqkey2\(dq: \(dqval2\(dq}\(aq salt \(aq*\(aq http.query http://somelink.com/ method=POST data=\(aq<xml>somecontent</xml>\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.http.update_ca_bundle(target=None, source=None, merge_files=None) Update the local CA bundle file from a URL .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq http.update_ca_bundle salt \(aq*\(aq http.update_ca_bundle target=/path/to/cacerts.pem salt \(aq*\(aq http.update_ca_bundle source=https://example.com/cacerts.pem .ft P .fi .UNINDENT .UNINDENT .sp If the \fBtarget\fP is not specified, it will be pulled from the \fBca_cert\fP configuration variable available to the minion. If it cannot be found there, it will be placed at \fB<<FILE_ROOTS>>/cacerts.pem\fP\&. .sp If the \fBsource\fP is not specified, it will be pulled from the \fBca_cert_url\fP configuration variable available to the minion. If it cannot be found, it will be downloaded from the cURL website, using an http (not https) URL. USING THE DEFAULT URL SHOULD BE AVOIDED! .sp \fBmerge_files\fP may also be specified, which includes a string or list of strings representing a file or files to be appended to the end of the CA bundle, once it is downloaded. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq http.update_ca_bundle merge_files=/path/to/mycert.pem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.http.wait_for_successful_query(url, wait_for=300, **kwargs) Query a resource until a successful response, and decode the return data .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq http.wait_for_successful_query http://somelink.com/ wait_for=160 request_interval=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.icinga2 .sp Module to provide icinga2 compatibility to salt. .sp New in version 2017.7.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 icinga2 server .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.icinga2.generate_cert(domain) Generate an icinga2 client certificate and key. .INDENT 7.0 .TP .B Returns:: icinga2 pki new\-cert \-\-cn domain.tld \-\-key /etc/icinga2/pki/domain.tld.key \-\-cert /etc/icinga2/pki/domain.tld.crt .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq icinga2.generate_cert domain.tld .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.icinga2.generate_ticket(domain) Generate and save an icinga2 ticket. .INDENT 7.0 .TP .B Returns:: icinga2 pki ticket \-\-cn domain.tld .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq icinga2.generate_ticket domain.tld .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.icinga2.node_setup(domain, master, ticket) Setup the icinga2 node. .INDENT 7.0 .TP .B Returns:: icinga2 node setup \-\-ticket TICKET_ID \-\-endpoint master.domain.tld \-\-zone domain.tld \-\-master_host master.domain.tld \-\-trustedcert /etc/icinga2/pki/trusted\-master.crt .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq icinga2.node_setup domain.tld master.domain.tld TICKET_ID .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.icinga2.request_cert(domain, master, ticket, port) Request CA cert from master icinga2 node. .INDENT 7.0 .TP .B Returns:: icinga2 pki request \-\-host master.domain.tld \-\-port 5665 \-\-ticket TICKET_ID \-\-key /etc/icinga2/pki/domain.tld.key \-\-cert /etc/icinga2/pki/domain.tld.crt \-\-trustedcert /etc/icinga2/pki/trusted\-master.crt \-\-ca /etc/icinga2/pki/ca.crt .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq icinga2.request_cert domain.tld master.domain.tld TICKET_ID .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.icinga2.save_cert(domain, master) Save the certificate for master icinga2 node. .INDENT 7.0 .TP .B Returns:: icinga2 pki save\-cert \-\-key /etc/icinga2/pki/domain.tld.key \-\-cert /etc/icinga2/pki/domain.tld.crt \-\-trustedcert /etc/icinga2/pki/trusted\-master.crt \-\-host master.domain.tld .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq icinga2.save_cert domain.tld master.domain.tld .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.idem .SS Idem Support .sp This module provides access to idem execution modules .sp New in version 3002. .INDENT 0.0 .TP .B salt.modules.idem.exec_(path, acct_file=None, acct_key=None, acct_profile=None, *args, **kwargs) Call an idem execution module .INDENT 7.0 .TP .B path The idem path of the idem execution module to run .TP .B acct_file Path to the acct file used in generating idem ctx parameters. Defaults to the value in the ACCT_FILE environment variable. .TP .B acct_key Key used to decrypt the acct file. Defaults to the value in the ACCT_KEY environment variable. .TP .B acct_profile Name of the profile to add to idem\(aqs ctx.acct parameter. Defaults to the value in the ACCT_PROFILE environment variable. .TP .B args Any positional arguments to pass to the idem exec function .TP .B kwargs Any keyword arguments to pass to the idem exec function .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq idem.exec test.ping .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Maturity new .TP .B Depends acct, pop, pop\-config, idem .TP .B Platform all .UNINDENT .UNINDENT .SS salt.modules.ifttt .sp Support for IFTTT .sp New in version 2015.8.0. .sp Requires an \fBapi_key\fP in \fB/etc/salt/minion\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ifttt: secret_key: \(aq280d4699\-a817\-4719\-ba6f\-ca56e573e44f\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ifttt.trigger_event(event=None, **kwargs) Trigger a configured event in IFTTT. .INDENT 7.0 .TP .B Parameters \fBevent\fP \-\- The name of the event to trigger. .TP .B Returns A dictionary with status, text, and error if result was failure. .UNINDENT .UNINDENT .SS salt.modules.ilo .sp Manage HP ILO .INDENT 0.0 .TP .B depends hponcfg (SmartStart Scripting Toolkit Linux Edition) .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.change_password(username, password) Reset a users password .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.change_password damianMyerscough .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.change_username(old_username, new_username) Change a username .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.change_username damian diana .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.configure_network(ip, netmask, gateway) Configure Network Interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.configure_network [IP ADDRESS] [NETMASK] [GATEWAY] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.configure_snmp(community, snmp_port=161, snmp_trapport=161) Configure SNMP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.configure_snmp [COMMUNITY STRING] [SNMP PORT] [SNMP TRAP PORT] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.create_user(name, password, *privileges) Create user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.create_user damian secretagent VIRTUAL_MEDIA_PRIV .ft P .fi .UNINDENT .UNINDENT .sp If no permissions are specify the user will only have a read\-only account. .sp Supported privelges: .INDENT 7.0 .IP \(bu 2 ADMIN_PRIV Enables the user to administer user accounts. .IP \(bu 2 REMOTE_CONS_PRIV Enables the user to access the Remote Console functionality. .IP \(bu 2 RESET_SERVER_PRIV Enables the user to remotely manipulate the server power setting. .IP \(bu 2 VIRTUAL_MEDIA_PRIV Enables the user permission to access the virtual media functionality. .IP \(bu 2 CONFIG_ILO_PRIV Enables the user to configure iLO settings. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.delete_ssh_key(username) Delete a users SSH key from the ILO .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.delete_user_sshkey damian .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.delete_user(username) Delete a user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.delete_user damian .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.disable_dhcp() Disable DHCP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.disable_dhcp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.disable_ssh() Disable the SSH daemon .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.disable_ssh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.enable_dhcp() Enable DHCP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.enable_dhcp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.enable_ssh() Enable the SSH daemon .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.enable_ssh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.get_user(username) Returns local user information, excluding the password .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.get_user damian .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.global_settings() Show global settings .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.global_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.list_users() List all users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.list_users_info() List all users in detail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.list_users_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.network() Grab the current network settings .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.network .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.set_http_port(port=80) Configure the port HTTP should listen on .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.set_http_port 8080 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.set_https_port(port=443) Configure the port HTTPS should listen on .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.set_https_port 4334 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.set_ssh_key(public_key) Configure SSH public keys for specific users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.set_ssh_key \(dqssh\-dss AAAAB3NzaC1kc3MAAACBA... damian\(dq .ft P .fi .UNINDENT .UNINDENT .sp The SSH public key needs to be DSA and the last argument in the key needs to be the username (case\-senstive) of the ILO username. .UNINDENT .INDENT 0.0 .TP .B salt.modules.ilo.set_ssh_port(port=22) Enable SSH on a user defined port .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ilo.set_ssh_port 2222 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.incron .sp Work with incron .INDENT 0.0 .TP .B salt.modules.incron.list_tab(user) Return the contents of the specified user\(aqs incrontab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq incron.list_tab root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.incron.ls(user) This function is an alias of \fBlist_tab\fP\&. .INDENT 7.0 .INDENT 3.5 Return the contents of the specified user\(aqs incrontab .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq incron.list_tab root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.incron.raw_incron(user) Return the contents of the user\(aqs incrontab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq incron.raw_incron root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.incron.raw_system_incron() Return the contents of the system wide incrontab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq incron.raw_system_incron .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.incron.rm(user, path, mask, cmd) This function is an alias of \fBrm_job\fP\&. .INDENT 7.0 .INDENT 3.5 Remove a incron job for a specified user. If any of the day/time params are specified, the job will only be removed if the specified params match. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq incron.rm_job root /path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.incron.rm_job(user, path, mask, cmd) Remove a incron job for a specified user. If any of the day/time params are specified, the job will only be removed if the specified params match. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq incron.rm_job root /path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.incron.set_job(user, path, mask, cmd) Sets an incron job up for a specified user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq incron.set_job root \(aq/root\(aq \(aqIN_MODIFY\(aq \(aqecho \(dq$$ $@ $# $% $&\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.incron.write_incron_file(user, path) Writes the contents of a file to a user\(aqs incrontab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq incron.write_incron_file root /tmp/new_incron .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.incron.write_incron_file_verbose(user, path) Writes the contents of a file to a user\(aqs incrontab and return error message on error .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq incron.write_incron_file_verbose root /tmp/new_incron .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.influxdb08mod .sp InfluxDB \- A distributed time series database .sp Module to provide InfluxDB compatibility to Salt (compatible with InfluxDB version 0.5\-0.8) .sp New in version 2014.7.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 influxdb Python module (>= 1.0.0) .UNINDENT .TP .B configuration This module accepts connection configuration details either as parameters or as configuration settings in /etc/salt/minion on the relevant minions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C influxdb08.host: \(aqlocalhost\(aq influxdb08.port: 8086 influxdb08.user: \(aqroot\(aq influxdb08.password: \(aqroot\(aq .ft P .fi .UNINDENT .UNINDENT .sp This data can also be passed into pillar. Options passed into opts will overwrite options passed into pillar. .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.db_create(name, user=None, password=None, host=None, port=None) Create a database .INDENT 7.0 .TP .B name Database name to create .TP .B user The user to connect as .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.db_create <name> salt \(aq*\(aq influxdb08.db_create <name> <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.db_exists(name, user=None, password=None, host=None, port=None) Checks if a database exists in Influxdb .INDENT 7.0 .TP .B name Database name to create .TP .B user The user to connect as .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.db_exists <name> salt \(aq*\(aq influxdb08.db_exists <name> <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.db_list(user=None, password=None, host=None, port=None) List all InfluxDB databases .INDENT 7.0 .TP .B user The user to connect as .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.db_list salt \(aq*\(aq influxdb08.db_list <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.db_remove(name, user=None, password=None, host=None, port=None) Remove a database .INDENT 7.0 .TP .B name Database name to remove .TP .B user The user to connect as .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.db_remove <name> salt \(aq*\(aq influxdb08.db_remove <name> <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.login_test(name, password, database=None, host=None, port=None) Checks if a credential pair can log in at all. .sp If a database is specified: it will check for database user existence. If a database is not specified: it will check for cluster admin existence. .INDENT 7.0 .TP .B name The user to connect as .TP .B password The password of the user .TP .B database The database to try to log in to .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.login_test <name> salt \(aq*\(aq influxdb08.login_test <name> <database> salt \(aq*\(aq influxdb08.login_test <name> <database> <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.query(database, query, time_precision=\(aqs\(aq, chunked=False, user=None, password=None, host=None, port=None) Querying data .INDENT 7.0 .TP .B database The database to query .TP .B query Query to be executed .TP .B time_precision Time precision to use (\(aqs\(aq, \(aqm\(aq, or \(aqu\(aq) .TP .B chunked Whether is chunked or not .TP .B user The user to connect as .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.query <database> <query> salt \(aq*\(aq influxdb08.query <database> <query> <time_precision> <chunked> <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.retention_policy_add(database, name, duration, replication, default=False, user=None, password=None, host=None, port=None) Add a retention policy. .INDENT 7.0 .TP .B database The database to operate on. .TP .B name Name of the policy to modify. .TP .B duration How long InfluxDB keeps the data. .TP .B replication How many copies of the data are stored in the cluster. .TP .B default Whether this policy should be the default or not. Default is False. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.retention_policy_add metrics default 1d 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.retention_policy_alter(database, name, duration, replication, default=False, user=None, password=None, host=None, port=None) Modify an existing retention policy. .INDENT 7.0 .TP .B database The database to operate on. .TP .B name Name of the policy to modify. .TP .B duration How long InfluxDB keeps the data. .TP .B replication How many copies of the data are stored in the cluster. .TP .B default Whether this policy should be the default or not. Default is False. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.retention_policy_modify metrics default 1d 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.retention_policy_exists(database, name, user=None, password=None, host=None, port=None) Check if a retention policy exists. .INDENT 7.0 .TP .B database The database to operate on. .TP .B name Name of the policy to modify. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.retention_policy_exists metrics default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.retention_policy_get(database, name, user=None, password=None, host=None, port=None) Get an existing retention policy. .INDENT 7.0 .TP .B database The database to operate on. .TP .B name Name of the policy to modify. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.retention_policy_get metrics default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.user_chpass(name, passwd, database=None, user=None, password=None, host=None, port=None) Change password for a cluster admin or a database user. .sp If a database is specified: it will update database user password. If a database is not specified: it will update cluster admin password. .INDENT 7.0 .TP .B name User name for whom to change the password .TP .B passwd New password .TP .B database The database on which to operate .TP .B user The user to connect as .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.user_chpass <name> <passwd> salt \(aq*\(aq influxdb08.user_chpass <name> <passwd> <database> salt \(aq*\(aq influxdb08.user_chpass <name> <passwd> <database> <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.user_create(name, passwd, database=None, user=None, password=None, host=None, port=None) Create a cluster admin or a database user. .sp If a database is specified: it will create database user. If a database is not specified: it will create a cluster admin. .INDENT 7.0 .TP .B name User name for the new user to create .TP .B passwd Password for the new user to create .TP .B database The database to create the user in .TP .B user The user to connect as .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.user_create <name> <passwd> salt \(aq*\(aq influxdb08.user_create <name> <passwd> <database> salt \(aq*\(aq influxdb08.user_create <name> <passwd> <database> <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.user_exists(name, database=None, user=None, password=None, host=None, port=None) Checks if a cluster admin or database user exists. .sp If a database is specified: it will check for database user existence. If a database is not specified: it will check for cluster admin existence. .INDENT 7.0 .TP .B name User name .TP .B database The database to check for the user to exist .TP .B user The user to connect as .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.user_exists <name> salt \(aq*\(aq influxdb08.user_exists <name> <database> salt \(aq*\(aq influxdb08.user_exists <name> <database> <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.user_list(database=None, user=None, password=None, host=None, port=None) List cluster admins or database users. .sp If a database is specified: it will return database users list. If a database is not specified: it will return cluster admins list. .INDENT 7.0 .TP .B database The database to list the users from .TP .B user The user to connect as .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.user_list salt \(aq*\(aq influxdb08.user_list <database> salt \(aq*\(aq influxdb08.user_list <database> <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdb08mod.user_remove(name, database=None, user=None, password=None, host=None, port=None) Remove a cluster admin or a database user. .sp If a database is specified: it will remove the database user. If a database is not specified: it will remove the cluster admin. .INDENT 7.0 .TP .B name User name to remove .TP .B database The database to remove the user from .TP .B user User name for the new user to delete .TP .B user The user to connect as .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb08.user_remove <name> salt \(aq*\(aq influxdb08.user_remove <name> <database> salt \(aq*\(aq influxdb08.user_remove <name> <database> <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.influxdbmod .sp InfluxDB \- A distributed time series database .sp Module to provide InfluxDB compatibility to Salt (compatible with InfluxDB version 0.9+) .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 influxdb Python module (>= 3.0.0) .UNINDENT .TP .B configuration This module accepts connection configuration details either as parameters or as configuration settings in /etc/salt/minion on the relevant minions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C influxdb.host: \(aqlocalhost\(aq influxdb.port: 8086 influxdb.user: \(aqroot\(aq influxdb.password: \(aqroot\(aq .ft P .fi .UNINDENT .UNINDENT .sp This data can also be passed into pillar. Options passed into opts will overwrite options passed into pillar. .sp Most functions in this module allow you to override or provide some or all of these settings via keyword arguments: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.foo_function influxdb_user=\(aqinfluxadmin\(aq influxdb_password=\(aqs3cr1t\(aq .ft P .fi .UNINDENT .UNINDENT .sp would override \fBuser\fP and \fBpassword\fP while still using the defaults for \fBhost\fP and \fBport\fP\&. .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.alter_retention_policy(database, name, duration, replication, default=False, **client_args) Modify an existing retention policy. .INDENT 7.0 .TP .B name Name of the retention policy to modify. .TP .B database Name of the database for which the retention policy was defined. .TP .B duration New duration of given retention policy. .sp Durations such as 1h, 90m, 12h, 7d, and 4w, are all supported and mean 1 hour, 90 minutes, 12 hours, 7 day, and 4 weeks, respectively. For infinite retention – meaning the data will never be deleted – use \(aqINF\(aq for duration. The minimum retention period is 1 hour. .TP .B replication New replication of given retention policy. .sp This determines how many independent copies of each data point are stored in a cluster. .TP .B default False Whether or not to set the modified policy as default. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.alter_retention_policy metrics default 1d 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.continuous_query_exists(database, name, **client_args) Check if continuous query with given name exists on the database. .INDENT 7.0 .TP .B database Name of the database for which the continuous query was defined. .TP .B name Name of the continuous query to check. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.continuous_query_exists metrics default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.create_continuous_query(database, name, query, resample_time=None, coverage_period=None, **client_args) Create a continuous query. .INDENT 7.0 .TP .B database Name of the database for which the continuous query will be created on. .TP .B name Name of the continuous query to create. .TP .B query The continuous query string. .TP .B resample_time None Duration between continuous query resampling. .TP .B coverage_period None Duration specifying time period per sample. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.create_continuous_query mydb cq_month \(aqSELECT mean(*) INTO mydb.a_month.:MEASUREMENT FROM mydb.a_week./.*/ GROUP BY time(5m), *\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.create_db(name, **client_args) Create a database. .INDENT 7.0 .TP .B name Name of the database to create. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.create_db <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.create_retention_policy(database, name, duration, replication, default=False, **client_args) Create a retention policy. .INDENT 7.0 .TP .B database Name of the database for which the retention policy will be created. .TP .B name Name of the new retention policy. .TP .B duration Duration of the new retention policy. .sp Durations such as 1h, 90m, 12h, 7d, and 4w, are all supported and mean 1 hour, 90 minutes, 12 hours, 7 day, and 4 weeks, respectively. For infinite retention – meaning the data will never be deleted – use \(aqINF\(aq for duration. The minimum retention period is 1 hour. .TP .B replication Replication factor of the retention policy. .sp This determines how many independent copies of each data point are stored in a cluster. .TP .B default False Whether or not the policy as default will be set as default. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.create_retention_policy metrics default 1d 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.create_user(name, passwd, admin=False, **client_args) Create a user. .INDENT 7.0 .TP .B name Name of the user to create. .TP .B passwd Password of the new user. .TP .B admin False Whether the user should have cluster administration privileges or not. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.create_user <name> <password> salt \(aq*\(aq influxdb.create_user <name> <password> admin=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.db_exists(name, **client_args) Checks if a database exists in InfluxDB. .INDENT 7.0 .TP .B name Name of the database to check. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.db_exists <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.drop_continuous_query(database, name, **client_args) Drop a continuous query. .INDENT 7.0 .TP .B database Name of the database for which the continuous query will be drop from. .TP .B name Name of the continuous query to drop. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.drop_continuous_query mydb my_cq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.drop_db(name, **client_args) Drop a database. .INDENT 7.0 .TP .B name Name of the database to drop. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.drop_db <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.drop_retention_policy(database, name, **client_args) Drop a retention policy. .INDENT 7.0 .TP .B database Name of the database for which the retention policy will be dropped. .TP .B name Name of the retention policy to drop. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.drop_retention_policy mydb mypr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.get_continuous_query(database, name, **client_args) Get an existing continuous query. .INDENT 7.0 .TP .B database Name of the database for which the continuous query was defined. .TP .B name Name of the continuous query to get. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.get_continuous_query mydb cq_month .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.get_retention_policy(database, name, **client_args) Get an existing retention policy. .INDENT 7.0 .TP .B database Name of the database for which the retention policy was defined. .TP .B name Name of the retention policy. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.get_retention_policy metrics default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.grant_admin_privileges(name, **client_args) Grant cluster administration privileges to a user. .INDENT 7.0 .TP .B name Name of the user to whom admin privileges will be granted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.grant_admin_privileges <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.grant_privilege(database, privilege, username, **client_args) Grant a privilege on a database to a user. .INDENT 7.0 .TP .B database Name of the database to grant the privilege on. .TP .B privilege Privilege to grant. Can be one of \(aqread\(aq, \(aqwrite\(aq or \(aqall\(aq. .TP .B username Name of the user to grant the privilege to. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.list_dbs(**client_args) List all InfluxDB databases. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.list_dbs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.list_privileges(name, **client_args) List privileges from a user. .INDENT 7.0 .TP .B name Name of the user from whom privileges will be listed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.list_privileges <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.list_users(**client_args) List all users. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.query(database, query, **client_args) Execute a query. .INDENT 7.0 .TP .B database Name of the database to query on. .TP .B query InfluxQL query string. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.remove_user(name, **client_args) Remove a user. .INDENT 7.0 .TP .B name Name of the user to remove .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.remove_user <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.retention_policy_exists(database, name, **client_args) Check if retention policy with given name exists. .INDENT 7.0 .TP .B database Name of the database for which the retention policy was defined. .TP .B name Name of the retention policy to check. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.retention_policy_exists metrics default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.revoke_admin_privileges(name, **client_args) Revoke cluster administration privileges from a user. .INDENT 7.0 .TP .B name Name of the user from whom admin privileges will be revoked. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.revoke_admin_privileges <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.revoke_privilege(database, privilege, username, **client_args) Revoke a privilege on a database from a user. .INDENT 7.0 .TP .B database Name of the database to grant the privilege on. .TP .B privilege Privilege to grant. Can be one of \(aqread\(aq, \(aqwrite\(aq or \(aqall\(aq. .TP .B username Name of the user to grant the privilege to. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.set_user_password(name, passwd, **client_args) Change password of a user. .INDENT 7.0 .TP .B name Name of the user for whom to set the password. .TP .B passwd New password of the user. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.set_user_password <name> <password> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.user_exists(name, **client_args) Check if a user exists. .INDENT 7.0 .TP .B name Name of the user to check. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.user_exists <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.influxdbmod.user_info(name, **client_args) Get information about given user. .INDENT 7.0 .TP .B name Name of the user for which to get information. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq influxdb.user_info <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.infoblox .sp This module have been tested on infoblox API v1.2.1, other versions of the API are likly workable. .INDENT 0.0 .TP .B depends libinfoblox, \fI\%https://github.com/steverweber/libinfoblox\fP .sp libinfoblox can be installed using \fIpip install libinfoblox\fP .UNINDENT .sp API documents can be found on your infoblox server at: .INDENT 0.0 .INDENT 3.5 \fI\%https://INFOBLOX/wapidoc\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B configuration The following configuration defaults can be defined (pillar or config files \(aq/etc/salt/master.d/infoblox.conf\(aq): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C infoblox.config: api_sslverify: True api_url: \(aqhttps://INFOBLOX/wapi/v1.2.1\(aq api_user: \(aqusername\(aq api_key: \(aqpassword\(aq .ft P .fi .UNINDENT .UNINDENT .sp Many of the functions accept \fIapi_opts\fP to override the API config. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_host name=my.host.com api_url: \(aqhttps://INFOBLOX/wapi/v1.2.1\(aq api_user=admin api_key=passs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.create_a(data, **api_opts) Create A record. .sp This is a helper function to \fIcreate_object\fP\&. See your infoblox API for full \fIdata\fP format. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.create_a data = name: \(aqfastlinux.math.example.ca\(aq ipv4addr: \(aq127.0.0.1\(aq view: External .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.create_cname(data, **api_opts) Create a cname record. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.create_cname data={ \(dqcomment\(dq: \(dqcname to example server\(dq, \(dqname\(dq: \(dqexample.example.com\(dq, \(dqzone\(dq: \(dqexample.com\(dq, \(dqview\(dq: \(dqInternal\(dq, \(dqcanonical\(dq: \(dqexample\-ha\-0.example.com\(dq } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.create_host(data, **api_opts) Add host record .sp Avoid race conditions, use func:nextavailableip for ipv[4,6]addrs: .INDENT 7.0 .IP \(bu 2 func:nextavailableip:network/ZG54dfgsrDFEFfsfsLzA:10.0.0.0/8/default .IP \(bu 2 func:nextavailableip:10.0.0.0/8 .IP \(bu 2 func:nextavailableip:10.0.0.0/8,external .IP \(bu 2 func:nextavailableip:10.0.0.3\-10.0.0.10 .UNINDENT .sp See your infoblox API for full \fIdata\fP format. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.create_host data = {\(aqname\(aq: \(aqhostname.example.ca\(aq, \(aqaliases\(aq: [\(aqhostname.math.example.ca\(aq], \(aqextattrs\(aq: [{\(aqBusiness Contact\(aq: {\(aqvalue\(aq: \(aqexample@example.ca\(aq}}, {\(aqPol8 Classification\(aq: {\(aqvalue\(aq: \(aqRestricted\(aq}}, {\(aqPrimary OU\(aq: {\(aqvalue\(aq: \(aqCS\(aq}}, {\(aqTechnical Contact\(aq: {\(aqvalue\(aq: \(aqexample@example.ca\(aq}}], \(aqipv4addrs\(aq: [{\(aqconfigure_for_dhcp\(aq: True, \(aqipv4addr\(aq: \(aqfunc:nextavailableip:129.97.139.0/24\(aq, \(aqmac\(aq: \(aq00:50:56:84:6e:ae\(aq}], \(aqipv6addrs\(aq: [], } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.create_ipv4_range(data, **api_opts) Create a ipv4 range .sp This is a helper function to \fIcreate_object\fP See your infoblox API for full \fIdata\fP format. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.create_ipv4_range data={ start_addr: \(aq129.97.150.160\(aq, end_addr: \(aq129.97.150.170\(aq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.create_object(object_type, data, **api_opts) Create raw infoblox object. This is a low level api call. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.update_object object_type=record:host data={} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.delete_a(name=None, ipv4addr=None, allow_array=False, **api_opts) Delete A record .sp If the A record is used as a round robin you can set \fBallow_array=True\fP to delete all records for the hostname. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.delete_a name=abc.example.com salt\-call infoblox.delete_a ipv4addr=192.168.3.5 salt\-call infoblox.delete_a name=acname.example.com allow_array=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.delete_cname(name=None, canonical=None, **api_opts) Delete CNAME. This is a helper call to delete_object. .sp If record is not found, return True .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.delete_cname name=example.example.com salt\-call infoblox.delete_cname canonical=example\-ha\-0.example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.delete_host(name=None, mac=None, ipv4addr=None, **api_opts) Delete host .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.delete_host name=example.domain.com salt\-call infoblox.delete_host ipv4addr=123.123.122.12 salt\-call infoblox.delete_host ipv4addr=123.123.122.12 mac=00:50:56:84:6e:ae .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.delete_ipv4_range(start_addr=None, end_addr=None, **api_opts) Delete ip range. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.delete_ipv4_range start_addr=123.123.122.12 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.delete_object(objref, **api_opts) Delete infoblox object. This is a low level api call. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.delete_object objref=[ref_of_object] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.diff_objects(obja, objb) Diff two complex infoblox objects. This is used from salt states to detect changes in objects. .sp Using \fBfunc:nextavailableip\fP will not cause a diff if the ipaddress is in range .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_a(name=None, ipv4addr=None, allow_array=True, **api_opts) Get A record .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_a name=abc.example.com salt\-call infoblox.get_a ipv4addr=192.168.3.5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_cname(name=None, canonical=None, return_fields=None, **api_opts) Get CNAME information. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_cname name=example.example.com salt\-call infoblox.get_cname canonical=example\-ha\-0.example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_host(name=None, ipv4addr=None, mac=None, return_fields=None, **api_opts) Get host information .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_host hostname.domain.ca salt\-call infoblox.get_host ipv4addr=123.123.122.12 salt\-call infoblox.get_host mac=00:50:56:84:6e:ae .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_host_advanced(name=None, ipv4addr=None, mac=None, **api_opts) Get all host information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_host_advanced hostname.domain.ca .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_host_domainname(name, domains=None, **api_opts) Get host domain name .sp If no domains are passed, the hostname is checked for a zone in infoblox, if no zone split on first dot. .sp If domains are provided, the best match out of the list is returned. .sp If none are found the return is None .sp dots at end of names are ignored. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call uwl.get_host_domainname name=localhost.t.domain.com domains=[\(aqdomain.com\(aq, \(aqt.domain.com.\(aq] # returns: t.domain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_host_hostname(name, domains=None, **api_opts) Get hostname .sp If no domains are passed, the hostname is checked for a zone in infoblox, if no zone split on first dot. .sp If domains are provided, the best match out of the list is truncated from the fqdn leaving the hostname. .sp If no matching domains are found the fqdn is returned. .sp dots at end of names are ignored. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_host_hostname fqdn=localhost.xxx.t.domain.com domains=\(dq[\(aqdomain.com\(aq, \(aqt.domain.com\(aq]\(dq #returns: localhost.xxx salt\-call infoblox.get_host_hostname fqdn=localhost.xxx.t.domain.com #returns: localhost .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_host_ipv4(name=None, mac=None, allow_array=False, **api_opts) Get ipv4 address from host record. .sp Use \fIallow_array\fP to return possible multiple values. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_host_ipv4 host=localhost.domain.com salt\-call infoblox.get_host_ipv4 mac=00:50:56:84:6e:ae .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_host_ipv4addr_info(ipv4addr=None, mac=None, discovered_data=None, return_fields=None, **api_opts) Get host ipv4addr information .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_ipv4addr ipv4addr=123.123.122.12 salt\-call infoblox.get_ipv4addr mac=00:50:56:84:6e:ae salt\-call infoblox.get_ipv4addr mac=00:50:56:84:6e:ae return_fields=host return_fields=\(aqmac,host,configure_for_dhcp,ipv4addr\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_host_ipv6addr_info(ipv6addr=None, mac=None, discovered_data=None, return_fields=None, **api_opts) Get host ipv6addr information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_host_ipv6addr_info ipv6addr=2001:db8:85a3:8d3:1349:8a2e:370:7348 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_host_mac(name=None, allow_array=False, **api_opts) Get mac address from host record. .sp Use \fIallow_array\fP to return possible multiple values. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_host_mac host=localhost.domain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_ipv4_range(start_addr=None, end_addr=None, return_fields=None, **api_opts) Get ip range .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_ipv4_range start_addr=123.123.122.12 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_network(ipv4addr=None, network=None, return_fields=None, **api_opts) Get list of all networks. This is helpful when looking up subnets to use with func:nextavailableip .sp This call is offen slow and not cached! .sp some return_fields comment,network,network_view,ddns_domainname,disable,enable_ddns .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_network .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.get_object(objref, data=None, return_fields=None, max_results=None, ensure_none_or_one_result=False, **api_opts) Get raw infoblox object. This is a low level api call. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.get_object objref=[_ref of object] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.is_ipaddr_in_ipfunc_range(ipaddr, ipfunc) Return true if the ipaddress is in the range of the nextavailableip function .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.is_ipaddr_in_ipfunc_range ipaddr=\(dq10.0.2.2\(dq ipfunc=\(dqfunc:nextavailableip:10.0.0.0/8\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.update_cname(name, data, **api_opts) Update CNAME. This is a helper call to update_object. .sp Find a CNAME \fB_ref\fP then call update_object with the record data. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.update_cname name=example.example.com data=\(dq{ \(aqcanonical\(aq:\(aqexample\-ha\-0.example.com\(aq, \(aquse_ttl\(aq:true, \(aqttl\(aq:200, \(aqcomment\(aq:\(aqSalt managed CNAME\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.update_host(name, data, **api_opts) Update host record. This is a helper call to update_object. .sp Find a hosts \fB_ref\fP then call update_object with the record data. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.update_host name=fqdn data={} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.infoblox.update_object(objref, data, **api_opts) Update raw infoblox object. This is a low level api call. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call infoblox.update_object objref=[ref_of_object] data={} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ini_manage .sp Edit ini files .INDENT 0.0 .TP .B maintainer <\fI\%akilesh1597@gmail.com\fP> .TP .B maturity new .TP .B depends re .TP .B platform all .UNINDENT .sp (for example /etc/sysctl.conf) .INDENT 0.0 .TP .B salt.modules.ini_manage.get_ini(file_name, separator=\(aq=\(aq, encoding=None) Retrieve the whole structure from an ini file and return it as a dictionary. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfile_name\fP (\fI\%str\fP) \-\- The full path to the ini file. .IP \(bu 2 \fBseparator\fP (\fI\%str\fP) \-\- .sp The character used to separate keys and values. Standard ini files use the \(dq=\(dq character. The default is \fB=\fP\&. .sp New in version 2016.11.0. .IP \(bu 2 \fBencoding\fP (\fI\%str\fP) \-\- .sp A string value representing encoding of the target ini file. If \fBNone\fP is passed, it uses the system default which is likely \fButf\-8\fP\&. Default is \fBNone\fP .sp New in version 3006.6. .UNINDENT .TP .B Returns .INDENT 7.0 .TP .B A dictionary containing the sections along with the values and names contained in each section .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp API Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C import salt.client with salt.client.get_local_client() as sc: sc.cmd(\(aqtarget\(aq, \(aqini.get_ini\(aq, [path_to_ini_file]) .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ini.get_ini /path/to/ini .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ini_manage.get_option(file_name, section, option, separator=\(aq=\(aq, encoding=None) Get value of a key from a section in an ini file. Returns \fBNone\fP if no matching key was found. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfile_name\fP (\fI\%str\fP) \-\- The full path to the ini file. .IP \(bu 2 \fBsection\fP (\fI\%str\fP) \-\- A string value representing the section of the ini that the option is in. If the option is not in a section, leave this empty. .IP \(bu 2 \fBoption\fP (\fI\%str\fP) \-\- A string value representing the option to search for. .IP \(bu 2 \fBseparator\fP (\fI\%str\fP) \-\- .sp The character used to separate keys and values. Standard ini files use the \(dq=\(dq character. The default is \fB=\fP\&. .sp New in version 2016.11.0. .IP \(bu 2 \fBencoding\fP (\fI\%str\fP) \-\- .sp A string value representing encoding of the target ini file. If \fBNone\fP is passed, it uses the system default which is likely \fButf\-8\fP\&. Default is \fBNone\fP .sp New in version 3006.6. .UNINDENT .TP .B Returns .INDENT 7.0 .TP .B The value as defined in the ini file, or \fBNone\fP if empty or not found .UNINDENT .TP .B Return type \fI\%str\fP .UNINDENT .sp API Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C import salt.client with salt.client.get_local_client() as sc: sc.cmd(\(aqtarget\(aq, \(aqini.get_option\(aq, [path_to_ini_file, section_name, option]) .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ini.get_option /path/to/ini section_name option_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ini_manage.get_section(file_name, section, separator=\(aq=\(aq, encoding=None) Retrieve a section from an ini file. Returns the section as a dictionary. If the section is not found, an empty dictionary is returned. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfile_name\fP (\fI\%str\fP) \-\- The full path to the ini file. .IP \(bu 2 \fBsection\fP (\fI\%str\fP) \-\- A string value representing name of the section to search for. .IP \(bu 2 \fBseparator\fP (\fI\%str\fP) \-\- .sp The character used to separate keys and values. Standard ini files use the \(dq=\(dq character. The default is \fB=\fP\&. .sp New in version 2016.11.0. .IP \(bu 2 \fBencoding\fP (\fI\%str\fP) \-\- .sp A string value representing encoding of the target ini file. If \fBNone\fP is passed, it uses the system default which is likely \fButf\-8\fP\&. Default is \fBNone\fP .sp New in version 3006.6. .UNINDENT .TP .B Returns .INDENT 7.0 .TP .B A dictionary containing the names and values of all items in the section of the ini file. If the section is not found, an empty dictionary is returned .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp API Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C import salt.client with salt.client.get_local_client() as sc: sc.cmd(\(aqtarget\(aq, \(aqini.get_section\(aq, [path_to_ini_file, section_name]) .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ini.get_section /path/to/ini section_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ini_manage.remove_option(file_name, section, option, separator=\(aq=\(aq, encoding=None) Remove a key/value pair from a section in an ini file. Returns the value of the removed key, or \fBNone\fP if nothing was removed. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfile_name\fP (\fI\%str\fP) \-\- The full path to the ini file. .IP \(bu 2 \fBsection\fP (\fI\%str\fP) \-\- A string value representing the section of the ini that the option is in. If the option is not in a section, leave this empty. .IP \(bu 2 \fBoption\fP (\fI\%str\fP) \-\- A string value representing the option to search for. .IP \(bu 2 \fBseparator\fP (\fI\%str\fP) \-\- .sp The character used to separate keys and values. Standard ini files use the \(dq=\(dq character. The default is \fB=\fP\&. .sp New in version 2016.11.0. .IP \(bu 2 \fBencoding\fP (\fI\%str\fP) \-\- .sp A string value representing encoding of the target ini file. If \fBNone\fP is passed, it uses the system default which is likely \fButf\-8\fP\&. Default is \fBNone\fP .sp New in version 3006.6. .UNINDENT .TP .B Returns .INDENT 7.0 .TP .B A string value representing the option that was removed or \fBNone\fP if nothing was removed .UNINDENT .TP .B Return type \fI\%str\fP .UNINDENT .sp API Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C import salt sc = salt.client.get_local_client() sc.cmd(\(aqtarget\(aq, \(aqini.remove_option\(aq, [path_to_ini_file, section_name, option]) .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ini.remove_option /path/to/ini section_name option_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ini_manage.remove_section(file_name, section, separator=\(aq=\(aq, encoding=None) Remove a section in an ini file. Returns the removed section as a dictionary, or \fBNone\fP if nothing is removed. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfile_name\fP (\fI\%str\fP) \-\- The full path to the ini file. .IP \(bu 2 \fBsection\fP (\fI\%str\fP) \-\- A string value representing the name of the section search for. .IP \(bu 2 \fBseparator\fP (\fI\%str\fP) \-\- .sp The character used to separate keys and values. Standard ini files use the \(dq=\(dq character. The default is \fB=\fP\&. .sp New in version 2016.11.0. .IP \(bu 2 \fBencoding\fP (\fI\%str\fP) \-\- .sp A string value representing encoding of the target ini file. If \fBNone\fP is passed, it uses the system default which is likely \fButf\-8\fP\&. Default is \fBNone\fP .sp New in version 3006.6. .UNINDENT .TP .B Returns .INDENT 7.0 .TP .B A dictionary containing the names and values of all items in the section that was removed or \fBNone\fP if nothing was removed .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp API Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C import salt.client with salt.client.get_local_client() as sc: sc.cmd(\(aqtarget\(aq, \(aqini.remove_section\(aq, [path_to_ini_file, section_name]) .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ini.remove_section /path/to/ini section_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ini_manage.set_option(file_name, sections=None, separator=\(aq=\(aq, encoding=None) Edit an ini file, replacing one or more sections. Returns a dictionary containing the changes made. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfile_name\fP (\fI\%str\fP) \-\- The full path to the ini file. .IP \(bu 2 \fBsections\fP (\fI\%dict\fP) \-\- A dictionary representing the sections to be edited in the ini file. The keys are the section names and the values are a dictionary containing the options. If the ini file does not contain sections the keys and values represent the options. The default is \fBNone\fP\&. .IP \(bu 2 \fBseparator\fP (\fI\%str\fP) \-\- .sp The character used to separate keys and values. Standard ini files use the \(dq=\(dq character. The default is \fB=\fP\&. .sp New in version 2016.11.0. .IP \(bu 2 \fBencoding\fP (\fI\%str\fP) \-\- .sp A string value representing encoding of the target ini file. If \fBNone\fP is passed, it uses the system default which is likely \fButf\-8\fP\&. Default is \fBNone\fP .sp New in version 3006.6. .UNINDENT .TP .B Returns A dictionary representing the changes made to the ini file .TP .B Return type \fI\%dict\fP .UNINDENT .sp API Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C import salt.client with salt.client.get_local_client() as sc: sc.cmd( \(aqtarget\(aq, \(aqini.set_option\(aq, [\(aqpath_to_ini_file\(aq, \(aq{\(dqsection_to_change\(dq: {\(dqkey\(dq: \(dqvalue\(dq}}\(aq] ) .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ini.set_option /path/to/ini \(aq{section_foo: {key: value}}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.inspectlib package .SS Submodules .SS salt.modules.inspectlib.collector .INDENT 0.0 .TP .B class salt.modules.inspectlib.collector.Inspector(cachedir=None, piddir=None, pidfilename=None) .INDENT 7.0 .TP .B DEFAULT_MINION_CONFIG_PATH = \(aq/etc/salt/minion\(aq .UNINDENT .INDENT 7.0 .TP .B IGNORE_FS_TYPES = [\(aqautofs\(aq, \(aqcifs\(aq, \(aqnfs\(aq, \(aqnfs4\(aq] .UNINDENT .INDENT 7.0 .TP .B IGNORE_MOUNTS = [\(aqproc\(aq, \(aqsysfs\(aq, \(aqdevtmpfs\(aq, \(aqtmpfs\(aq, \(aqfuse.gvfs\-fuse\-daemon\(aq] .UNINDENT .INDENT 7.0 .TP .B IGNORE_PATHS = [\(aq/tmp\(aq, \(aq/var/tmp\(aq, \(aq/lost+found\(aq, \(aq/var/run\(aq, \(aq/var/lib/rpm\(aq, \(aq/.snapshots\(aq, \(aq/.zfs\(aq, \(aq/etc/ssh\(aq, \(aq/root\(aq, \(aq/home\(aq] .UNINDENT .INDENT 7.0 .TP .B MODE = [\(aqconfiguration\(aq, \(aqpayload\(aq, \(aqall\(aq] .UNINDENT .INDENT 7.0 .TP .B build(format=\(aqqcow2\(aq, path=\(aq/tmp\(aq) Build an image using Kiwi. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBformat\fP \-\- .IP \(bu 2 \fBpath\fP \-\- .UNINDENT .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B create_snapshot() Open new snapshot. .INDENT 7.0 .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B export(description, local=False, path=\(aq/tmp\(aq, format=\(aqqcow2\(aq) Export description for Kiwi. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBlocal\fP \-\- .IP \(bu 2 \fBpath\fP \-\- .UNINDENT .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B request_snapshot(mode, priority=19, **kwargs) Take a snapshot of the system. .UNINDENT .INDENT 7.0 .TP .B reuse_snapshot() Open an existing, latest snapshot. .INDENT 7.0 .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B snapshot(mode) Take a snapshot of the system. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.inspectlib.collector.is_alive(pidfile) Check if PID is still alive. .UNINDENT .INDENT 0.0 .TP .B salt.modules.inspectlib.collector.main(dbfile, pidfile, mode) Main analyzer routine. .UNINDENT .SS salt.modules.inspectlib.dbhandle .INDENT 0.0 .TP .B class salt.modules.inspectlib.dbhandle.DBHandle(*args, **kwargs) .UNINDENT .INDENT 0.0 .TP .B class salt.modules.inspectlib.dbhandle.DBHandleBase(path) Handle for the \fIvolatile\fP database, which serves the purpose of caching the inspected data. This database can be destroyed or corrupted, so it should be simply re\-created from scratch. .INDENT 7.0 .TP .B close() Close the database connection. .UNINDENT .INDENT 7.0 .TP .B flush(table) Flush the table. .UNINDENT .INDENT 7.0 .TP .B open(new=False) Init the database, if required. .UNINDENT .INDENT 7.0 .TP .B purge() Purge whole database. .UNINDENT .UNINDENT .SS salt.modules.inspectlib.exceptions .INDENT 0.0 .TP .B exception salt.modules.inspectlib.exceptions.InspectorKiwiProcessorException Kiwi builder/exporter exception. .UNINDENT .INDENT 0.0 .TP .B exception salt.modules.inspectlib.exceptions.InspectorQueryException Exception that is only for the inspector query. .UNINDENT .INDENT 0.0 .TP .B exception salt.modules.inspectlib.exceptions.InspectorSnapshotException Snapshot exception. .UNINDENT .INDENT 0.0 .TP .B exception salt.modules.inspectlib.exceptions.SIException System information exception. .UNINDENT .SS salt.modules.inspectlib.query .INDENT 0.0 .TP .B class salt.modules.inspectlib.query.Query(scope, cachedir=None) Query the system. This class is actually puts all Salt features together, so there would be no need to pick it from various places. .INDENT 7.0 .TP .B SCOPES = [\(aqchanges\(aq, \(aqconfiguration\(aq, \(aqidentity\(aq, \(aqsystem\(aq, \(aqsoftware\(aq, \(aqservices\(aq, \(aqpayload\(aq, \(aqall\(aq] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.inspectlib.query.SysInfo(systype) System information. .UNINDENT .SS Module contents .INDENT 0.0 .TP .B class salt.modules.inspectlib.EnvLoader(cachedir=None, piddir=None, pidfilename=None) Load environment. .INDENT 7.0 .TP .B DB_FILE = \(aq_minion_collector.db\(aq .UNINDENT .INDENT 7.0 .TP .B DEFAULT_CACHE_PATH = \(aq/var/cache/salt\(aq .UNINDENT .INDENT 7.0 .TP .B DEFAULT_PID_PATH = \(aq/var/run\(aq .UNINDENT .INDENT 7.0 .TP .B PID_FILE = \(aq_minion_collector.pid\(aq .UNINDENT .UNINDENT .SS salt.modules.inspectlib.entities .INDENT 0.0 .TP .B class salt.modules.inspectlib.entities.AllowedDir Allowed directories .UNINDENT .INDENT 0.0 .TP .B class salt.modules.inspectlib.entities.IgnoredDir Ignored directories .UNINDENT .INDENT 0.0 .TP .B class salt.modules.inspectlib.entities.Package Package. .UNINDENT .INDENT 0.0 .TP .B class salt.modules.inspectlib.entities.PackageCfgFile Config file, belongs to the package .UNINDENT .INDENT 0.0 .TP .B class salt.modules.inspectlib.entities.PayloadFile Payload file. .UNINDENT .SS salt.modules.inspectlib.fsdb .INDENT 0.0 .TP .B codeauthor Bo Maryniuk <\fI\%bo@suse.de\fP> .UNINDENT .INDENT 0.0 .TP .B class salt.modules.inspectlib.fsdb.CsvDB(path) File\-based CSV database. This database is in\-memory operating relatively small plain text csv files. .INDENT 7.0 .TP .B close() Close the database. .INDENT 7.0 .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B create_table_from_object(obj) Create a table from the object. NOTE: This method doesn\(aqt stores anything. .INDENT 7.0 .TP .B Parameters \fBobj\fP \-\- .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B delete(obj, matches=None, mt=None, lt=None, eq=None) Delete object from the database. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- .IP \(bu 2 \fBmatches\fP \-\- .IP \(bu 2 \fBmt\fP \-\- .IP \(bu 2 \fBlt\fP \-\- .IP \(bu 2 \fBeq\fP \-\- .UNINDENT .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B flush(table) Flush table. .INDENT 7.0 .TP .B Parameters \fBtable\fP \-\- .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get(obj, matches=None, mt=None, lt=None, eq=None) Get objects from the table. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable_name\fP \-\- .IP \(bu 2 \fBmatches\fP \-\- Regexp. .IP \(bu 2 \fBmt\fP \-\- More than. .IP \(bu 2 \fBlt\fP \-\- Less than. .IP \(bu 2 \fBeq\fP \-\- Equals. .UNINDENT .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B is_closed() Return if the database is closed. .INDENT 7.0 .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B list() List all the databases on the given path. .INDENT 7.0 .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B list_tables() Load existing tables and their descriptions. .INDENT 7.0 .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B new() Create a new database and opens it. .INDENT 7.0 .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B open(dbname=None) Open database from the path with the name or latest. If there are no yet databases, create a new implicitly. .INDENT 7.0 .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B purge(dbid) Purge the database. .INDENT 7.0 .TP .B Parameters \fBdbid\fP \-\- .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B store(obj, distinct=False) Store an object in the table. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- An object to store .IP \(bu 2 \fBdistinct\fP \-\- Store object only if there is none identical of such. If at least one field is different, store it. .UNINDENT .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B update(obj, matches=None, mt=None, lt=None, eq=None) Update object(s) in the database. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- .IP \(bu 2 \fBmatches\fP \-\- .IP \(bu 2 \fBmt\fP \-\- .IP \(bu 2 \fBlt\fP \-\- .IP \(bu 2 \fBeq\fP \-\- .UNINDENT .TP .B Returns .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.inspectlib.fsdb.CsvDBEntity Serializable object for the table. .UNINDENT .SS salt.modules.inspectlib.kiwiproc .INDENT 0.0 .TP .B class salt.modules.inspectlib.kiwiproc.KiwiExporter(grains, format) Exports system description as Kiwi configuration. .INDENT 7.0 .TP .B export(name) Export to the Kiwi config.xml as text. .INDENT 7.0 .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B load(**descr) Load data by keys. .INDENT 7.0 .TP .B Parameters \fBdata\fP \-\- .TP .B Returns .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.inspector .sp Module for full system inspection. .INDENT 0.0 .TP .B salt.modules.inspector.build(format=\(aqqcow2\(aq, path=\(aq/tmp/\(aq) Build an image from a current system description. The image is a system image can be output in bootable ISO or QCOW2 formats. .sp Node uses the image building library Kiwi to perform the actual build. .sp Parameters: .INDENT 7.0 .IP \(bu 2 \fBformat\fP: Specifies output format: \(dqqcow2\(dq or \(dqiso. Default: \fIqcow2\fP\&. .IP \(bu 2 \fBpath\fP: Specifies output path where to store built image. Default: \fI/tmp\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion inspector.build salt myminion inspector.build format=iso path=/opt/builds/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.inspector.delete(all=False, *databases) Remove description snapshots from the system. .sp ::parameter: all. Default: False. Remove all snapshots, if set to True. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion inspector.delete <ID> <ID1> <ID2>.. salt myminion inspector.delete all=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.inspector.export(local=False, path=\(aq/tmp\(aq, format=\(aqqcow2\(aq) Export an image description for Kiwi. .sp Parameters: .INDENT 7.0 .IP \(bu 2 \fBlocal\fP: Specifies True or False if the export has to be in the local file. Default: False. .IP \(bu 2 .INDENT 2.0 .TP \fBpath\fP: If \fIlocal=True\fP, then specifies the path where file with the Kiwi description is written. Default: \fI/tmp\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion inspector.export salt myminion inspector.export format=iso path=/opt/builds/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.inspector.inspect(mode=\(aqall\(aq, priority=19, **kwargs) Start node inspection and save the data to the database for further query. .sp Parameters: .INDENT 7.0 .IP \(bu 2 \fBmode\fP: Clarify inspection mode: configuration, payload, all (default) .INDENT 2.0 .TP .B payload .INDENT 7.0 .IP \(bu 2 \fBfilter\fP: Comma\-separated directories to track payload. .UNINDENT .UNINDENT .IP \(bu 2 \fBpriority\fP: (advanced) Set priority of the inspection. Default is low priority. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq inspector.inspect salt \(aq*\(aq inspector.inspect configuration salt \(aq*\(aq inspector.inspect payload filter=/opt,/ext/oracle .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.inspector.query(*args, **kwargs) Query the node for specific information. .sp Parameters: .INDENT 7.0 .IP \(bu 2 \fBscope\fP: Specify scope of the query. .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBSystem\fP: Return system data. .IP \(bu 2 \fBSoftware\fP: Return software information. .IP \(bu 2 \fBServices\fP: Return known services. .IP \(bu 2 .INDENT 2.0 .TP \fBIdentity\fP: Return user accounts information for this system. .INDENT 7.0 .TP .B accounts Can be either \(aqlocal\(aq, \(aqremote\(aq or \(aqall\(aq (equal to \(dqlocal,remote\(dq). Remote accounts cannot be resolved on all systems, but only those, which supports \(aqpasswd \-S \-a\(aq. .TP .B disabled True (or False, default) to return only disabled accounts. .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP \fBpayload\fP: Payload scope parameters: .INDENT 7.0 .TP .B filter Include only results which path starts from the filter string. .TP .B time Display time in Unix ticks or format according to the configured TZ (default) Values: ticks, tz (default) .TP .B size Format size. Values: B, KB, MB, GB .TP .B type Include payload type. Values (comma\-separated): directory (or dir), link, file (default) Example (returns everything): type=directory,link,file .TP .B owners Resolve UID/GID to an actual names or leave them numeric (default). Values: name (default), id .TP .B brief Return just a list of payload elements, if True. Default: False. .UNINDENT .UNINDENT .IP \(bu 2 \fBall\fP: Return all information (default). .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq inspector.query scope=system salt \(aq*\(aq inspector.query scope=payload type=file,link filter=/etc size=Kb brief=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.inspector.snapshots() List current description snapshots. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion inspector.snapshots .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.introspect .sp Functions to perform introspection on a minion, and return data in a format usable by Salt States .INDENT 0.0 .TP .B salt.modules.introspect.enabled_service_owners() Return which packages own each of the services that are currently enabled. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion introspect.enabled_service_owners .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.introspect.running_service_owners(exclude=(\(aq/dev\(aq, \(aq/home\(aq, \(aq/media\(aq, \(aq/proc\(aq, \(aq/run\(aq, \(aq/sys/\(aq, \(aq/tmp\(aq, \(aq/var\(aq)) Determine which packages own the currently running services. By default, excludes files whose full path starts with \fB/dev\fP, \fB/home\fP, \fB/media\fP, \fB/proc\fP, \fB/run\fP, \fB/sys\fP, \fB/tmp\fP and \fB/var\fP\&. This can be overridden by passing in a new list to \fBexclude\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion introspect.running_service_owners .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.introspect.service_highstate(requires=True) Return running and enabled services in a highstate structure. By default also returns package dependencies for those services, which means that package definitions must be created outside this function. To drop the package dependencies, set \fBrequires\fP to False. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion introspect.service_highstate salt myminion introspect.service_highstate requires=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.iosconfig .sp Cisco IOS configuration manipulation helpers .sp New in version 2019.2.0. .sp This module provides a collection of helper functions for Cisco IOS style configuration manipulation. This module does not have external dependencies and can be used from any Proxy or regular Minion. .INDENT 0.0 .TP .B salt.modules.iosconfig.clean(config=None, path=None, saltenv=\(aqbase\(aq) Return a clean version of the config, without any special signs (such as \fB!\fP as an individual line) or empty lines, but just lines with significant value in the configuration of the network device. .INDENT 7.0 .TP .B config The configuration sent as text. This argument is ignored when \fBpath\fP is configured. .TP .B path Absolute or remote path from where to load the configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBpath\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iosconfig.clean path=salt://path/to/my/config.txt salt \(aq*\(aq iosconfig.clean path=https://bit.ly/2mAdq7z .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iosconfig.diff_text(candidate_config=None, candidate_path=None, running_config=None, running_path=None, saltenv=\(aqbase\(aq) Return the diff, as text, between the candidate and the running config. .INDENT 7.0 .TP .B candidate_config The candidate configuration sent as text. This argument is ignored when \fBcandidate_path\fP is set. .TP .B candidate_path Absolute or remote path from where to load the candidate configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B running_config The running configuration sent as text. This argument is ignored when \fBrunning_path\fP is set. .TP .B running_path Absolute or remote path from where to load the running configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBcandidate_path\fP or \fBrunning_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iosconfig.diff_text candidate_path=salt://path/to/candidate.cfg running_path=salt://path/to/running.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iosconfig.diff_tree(candidate_config=None, candidate_path=None, running_config=None, running_path=None, saltenv=\(aqbase\(aq) Return the diff, as Python dictionary, between the candidate and the running configuration. .INDENT 7.0 .TP .B candidate_config The candidate configuration sent as text. This argument is ignored when \fBcandidate_path\fP is set. .TP .B candidate_path Absolute or remote path from where to load the candidate configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B running_config The running configuration sent as text. This argument is ignored when \fBrunning_path\fP is set. .TP .B running_path Absolute or remote path from where to load the running configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBcandidate_path\fP or \fBrunning_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iosconfig.diff_tree candidate_path=salt://path/to/candidate.cfg running_path=salt://path/to/running.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iosconfig.merge_diff(initial_config=None, initial_path=None, merge_config=None, merge_path=None, saltenv=\(aqbase\(aq) Return the merge diff, as text, after merging the merge config into the initial config. .INDENT 7.0 .TP .B initial_config The initial configuration sent as text. This argument is ignored when \fBinitial_path\fP is set. .TP .B initial_path Absolute or remote path from where to load the initial configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B merge_config The config to be merged into the initial config, sent as text. This argument is ignored when \fBmerge_path\fP is set. .TP .B merge_path Absolute or remote path from where to load the merge configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBinitial_path\fP or \fBmerge_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iosconfig.merge_diff initial_path=salt://path/to/running.cfg merge_path=salt://path/to/merge.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iosconfig.merge_text(initial_config=None, initial_path=None, merge_config=None, merge_path=None, saltenv=\(aqbase\(aq) Return the merge result of the \fBinitial_config\fP with the \fBmerge_config\fP, as plain text. .INDENT 7.0 .TP .B initial_config The initial configuration sent as text. This argument is ignored when \fBinitial_path\fP is set. .TP .B initial_path Absolute or remote path from where to load the initial configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B merge_config The config to be merged into the initial config, sent as text. This argument is ignored when \fBmerge_path\fP is set. .TP .B merge_path Absolute or remote path from where to load the merge configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBinitial_path\fP or \fBmerge_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iosconfig.merge_text initial_path=salt://path/to/running.cfg merge_path=salt://path/to/merge.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iosconfig.merge_tree(initial_config=None, initial_path=None, merge_config=None, merge_path=None, saltenv=\(aqbase\(aq) Return the merge tree of the \fBinitial_config\fP with the \fBmerge_config\fP, as a Python dictionary. .INDENT 7.0 .TP .B initial_config The initial configuration sent as text. This argument is ignored when \fBinitial_path\fP is set. .TP .B initial_path Absolute or remote path from where to load the initial configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B merge_config The config to be merged into the initial config, sent as text. This argument is ignored when \fBmerge_path\fP is set. .TP .B merge_path Absolute or remote path from where to load the merge configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBinitial_path\fP or \fBmerge_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iosconfig.merge_tree initial_path=salt://path/to/running.cfg merge_path=salt://path/to/merge.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iosconfig.tree(config=None, path=None, with_tags=False, saltenv=\(aqbase\(aq) Transform Cisco IOS style configuration to structured Python dictionary. Depending on the value of the \fBwith_tags\fP argument, this function may provide different views, valuable in different situations. .INDENT 7.0 .TP .B config The configuration sent as text. This argument is ignored when \fBpath\fP is configured. .TP .B path Absolute or remote path from where to load the configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B with_tags: \fBFalse\fP Whether this function should return a detailed view, with tags. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBpath\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iosconfig.tree path=salt://path/to/my/config.txt salt \(aq*\(aq iosconfig.tree path=https://bit.ly/2mAdq7z .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ipmi .sp Support IPMI commands over LAN. This module does not talk to the local systems hardware through IPMI drivers. It uses a python module \fIpyghmi\fP\&. .INDENT 0.0 .TP .B depends Python module pyghmi. You can install pyghmi using pip: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pip install pyghmi .ft P .fi .UNINDENT .UNINDENT .TP .B configuration The following configuration defaults can be define (pillar or config files): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ipmi.config: api_host: 127.0.0.1 api_user: admin api_pass: apassword api_port: 623 api_kg: None .ft P .fi .UNINDENT .UNINDENT .sp Usage can override the config defaults: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.get_user api_host=myipmienabled.system api_user=admin api_pass=pass uid=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.create_user(uid, name, password, channel=14, callback=False, link_auth=True, ipmi_msg=True, privilege_level=\(aqadministrator\(aq, **kwargs) create/ensure a user is created with provided settings. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprivilege_level\fP \-\- User Privilege Limit. (Determines the maximum privilege level that the user is allowed to switch to on the specified channel.) * callback * user * operator * administrator * proprietary * no_access .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.create_user uid=2 name=steverweber api_host=172.168.0.7 api_pass=nevertell .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.fast_connect_test(**kwargs) Returns True if connection success. This uses an aggressive timeout value! .INDENT 7.0 .TP .B Parameters \fBkwargs\fP \-\- .INDENT 7.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.fast_connect_test api_host=172.168.0.9 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.get_bootdev(**kwargs) Get current boot device override information. .sp Provides the current requested boot device. Be aware that not all IPMI devices support this. Even in BMCs that claim to, occasionally the BIOS or UEFI fail to honor it. This is usually only applicable to the next reboot. .INDENT 7.0 .TP .B Parameters \fBkwargs\fP \-\- .INDENT 7.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.get_bootdev api_host=127.0.0.1 api_user=admin api_pass=pass .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.get_channel_access(channel=14, read_mode=\(aqnon_volatile\(aq, **kwargs) :param kwargs:api_host=\(aq127.0.0.1\(aq api_user=\(aqadmin\(aq api_pass=\(aqexample\(aq api_port=623 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBchannel\fP \-\- number [1:7] .IP \(bu 2 \fBread_mode\fP \-\- .INDENT 2.0 .IP \(bu 2 non_volatile = get non\-volatile Channel Access .IP \(bu 2 volatile = get present volatile (active) setting of Channel Access .UNINDENT .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .sp Return Data .INDENT 7.0 .INDENT 3.5 A Python dict with the following keys/values: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { alerting: per_msg_auth: user_level_auth: access_mode:{ (ONE OF) 0: \(aqdisabled\(aq, 1: \(aqpre_boot\(aq, 2: \(aqalways\(aq, 3: \(aqshared\(aq } privilege_level: { (ONE OF) 1: \(aqcallback\(aq, 2: \(aquser\(aq, 3: \(aqoperator\(aq, 4: \(aqadministrator\(aq, 5: \(aqproprietary\(aq, } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.get_channel_access channel=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.get_channel_info(channel=14, **kwargs) Get channel info .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBchannel\fP \-\- number [1:7] .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Return Data channel session supports .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- no_session: channel is session\-less \- single: channel is single\-session \- multi: channel is multi\-session \- auto: channel is session\-based (channel could alternate between single\- and multi\-session operation, as can occur with a serial/modem channel that supports connection mode auto\-detect) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.get_channel_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.get_channel_max_user_count(channel=14, **kwargs) Get max users in channel .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBchannel\fP \-\- number [1:7] .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .TP .B Returns int \-\- often 16 .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.get_channel_max_user_count .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.get_health(**kwargs) Get Summarize health .sp This provides a summary of the health of the managed system. It additionally provides an iterable list of reasons for warning, critical, or failed assessments. .sp good health: {\(aqbadreadings\(aq: [], \(aqhealth\(aq: 0} .INDENT 7.0 .TP .B Parameters \fBkwargs\fP \-\- .INDENT 7.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.get_health api_host=127.0.0.1 api_user=admin api_pass=pass .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.get_power(**kwargs) Get current power state .sp The response, if successful, should contain \(aqpowerstate\(aq key and either \(aqon\(aq or \(aqoff\(aq to indicate current state. .INDENT 7.0 .TP .B Parameters \fBkwargs\fP \-\- .INDENT 7.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.get_power api_host=127.0.0.1 api_user=admin api_pass=pass .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.get_sensor_data(**kwargs) Get sensor readings .sp Iterates sensor reading objects .INDENT 7.0 .TP .B Parameters \fBkwargs\fP \-\- .INDENT 7.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.get_sensor_data api_host=127.0.0.1 api_user=admin api_pass=pass .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.get_user(uid, channel=14, **kwargs) Get user from uid and access on channel .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuid\fP \-\- user number [1:16] .IP \(bu 2 \fBchannel\fP \-\- number [1:7] .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .sp Return Data .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C name: (str) uid: (int) channel: (int) access: \- callback (bool) \- link_auth (bool) \- ipmi_msg (bool) \- privilege_level: (str)[callback, user, operatorm administrator, proprietary, no_access] .ft P .fi .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.get_user uid=2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.get_user_access(uid, channel=14, **kwargs) Get user access .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuid\fP \-\- user number [1:16] .IP \(bu 2 \fBchannel\fP \-\- number [1:7] .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .sp Return Data .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C channel_info: \- max_user_count = maximum number of user IDs on this channel \- enabled_users = count of User ID slots presently in use \- users_with_fixed_names = count of user IDs with fixed names access: \- callback \- link_auth \- ipmi_msg \- privilege_level: [reserved, callback, user, operator administrator, proprietary, no_access] .ft P .fi .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.get_user_access uid=2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.get_user_name(uid, return_none_on_error=True, **kwargs) Get user name .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuid\fP \-\- user number [1:16] .IP \(bu 2 \fBreturn_none_on_error\fP \-\- return None on error .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.get_user_name uid=2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.get_users(channel=14, **kwargs) get list of users and access information .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBchannel\fP \-\- number [1:7] .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .TP .B Returns .INDENT 7.0 .IP \(bu 2 name: (str) .IP \(bu 2 uid: (int) .IP \(bu 2 channel: (int) .IP \(bu 2 .INDENT 2.0 .TP .B access: .INDENT 7.0 .IP \(bu 2 callback (bool) .IP \(bu 2 link_auth (bool) .IP \(bu 2 ipmi_msg (bool) .IP \(bu 2 privilege_level: (str)[callback, user, operatorm administrator, proprietary, no_access] .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.get_users api_host=172.168.0.7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.raw_command(netfn, command, bridge_request=None, data=(), retry=True, delay_xmit=None, **kwargs) Send raw ipmi command .sp This allows arbitrary IPMI bytes to be issued. This is commonly used for certain vendor specific commands. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnetfn\fP \-\- Net function number .IP \(bu 2 \fBcommand\fP \-\- Command value .IP \(bu 2 \fBbridge_request\fP \-\- The target slave address and channel number for the bridge request. .IP \(bu 2 \fBdata\fP \-\- Command data as a tuple or list .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .TP .B Returns dict \-\- The response from IPMI device .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.raw_command netfn=0x06 command=0x46 data=[0x02] # this will return the name of the user with id 2 in bytes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.set_bootdev(bootdev=\(aqdefault\(aq, persist=False, uefiboot=False, **kwargs) Set boot device to use on next reboot .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbootdev\fP \-\- .INDENT 2.0 .IP \(bu 2 network: Request network boot .IP \(bu 2 hd: Boot from hard drive .IP \(bu 2 safe: Boot from hard drive, requesting \(aqsafe mode\(aq .IP \(bu 2 optical: boot from CD/DVD/BD drive .IP \(bu 2 setup: Boot into setup utility .IP \(bu 2 default: remove any IPMI directed boot device request .UNINDENT .IP \(bu 2 \fBpersist\fP \-\- If true, ask that system firmware use this device beyond next boot. Be aware many systems do not honor this .IP \(bu 2 \fBuefiboot\fP \-\- If true, request UEFI boot explicitly. Strictly speaking, the spec suggests that if not set, the system should BIOS boot and offers no \(dqdon\(aqt care\(dq option. In practice, this flag not being set does not preclude UEFI boot on any system I\(aqve encountered. .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .TP .B Returns dict or True \-\- If callback is not provided, the response .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.set_bootdev bootdev=network persist=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.set_channel_access(channel=14, access_update_mode=\(aqnon_volatile\(aq, alerting=False, per_msg_auth=False, user_level_auth=False, access_mode=\(aqalways\(aq, privilege_update_mode=\(aqnon_volatile\(aq, privilege_level=\(aqadministrator\(aq, **kwargs) Set channel access .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBchannel\fP \-\- number [1:7] .IP \(bu 2 \fBaccess_update_mode\fP \-\- .INDENT 2.0 .IP \(bu 2 \(aqdont_change\(aq = don\(aqt set or change Channel Access .IP \(bu 2 \(aqnon_volatile\(aq = set non\-volatile Channel Access .IP \(bu 2 \(aqvolatile\(aq = set volatile (active) setting of Channel Access .UNINDENT .IP \(bu 2 \fBalerting\fP \-\- .sp PEF Alerting Enable/Disable .INDENT 2.0 .IP \(bu 2 True = enable PEF Alerting .IP \(bu 2 False = disable PEF Alerting on this channel (Alert Immediate command can still be used to generate alerts) .UNINDENT .IP \(bu 2 \fBper_msg_auth\fP \-\- .sp Per\-message Authentication .INDENT 2.0 .IP \(bu 2 True = enable .IP \(bu 2 False = disable Per\-message Authentication. [Authentication required to activate any session on this channel, but authentication not used on subsequent packets for the session.] .UNINDENT .IP \(bu 2 \fBuser_level_auth\fP \-\- .sp User Level Authentication Enable/Disable .INDENT 2.0 .IP \(bu 2 True = enable User Level Authentication. All User Level commands are to be authenticated per the Authentication Type that was negotiated when the session was activated. .IP \(bu 2 False = disable User Level Authentication. Allow User Level commands to be executed without being authenticated. If the option to disable User Level Command authentication is accepted, the BMC will accept packets with Authentication Type set to None if they contain user level commands. For outgoing packets, the BMC returns responses with the same Authentication Type that was used for the request. .UNINDENT .IP \(bu 2 \fBaccess_mode\fP \-\- .sp Access Mode for IPMI messaging (PEF Alerting is enabled/disabled separately from IPMI messaging) .INDENT 2.0 .IP \(bu 2 disabled = disabled for IPMI messaging .IP \(bu 2 pre_boot = pre\-boot only channel only available when system is in a powered down state or in BIOS prior to start of boot. .IP \(bu 2 always = channel always available regardless of system mode. BIOS typically dedicates the serial connection to the BMC. .IP \(bu 2 shared = same as always available, but BIOS typically leaves the serial port available for software use. .UNINDENT .IP \(bu 2 \fBprivilege_update_mode\fP \-\- .sp Channel Privilege Level Limit. This value sets the maximum privilege level that can be accepted on the specified channel. .INDENT 2.0 .IP \(bu 2 dont_change = don\(aqt set or change channel Privilege Level Limit .IP \(bu 2 non_volatile = non\-volatile Privilege Level Limit according .IP \(bu 2 volatile = volatile setting of Privilege Level Limit .UNINDENT .IP \(bu 2 \fBprivilege_level\fP \-\- .sp Channel Privilege Level Limit .INDENT 2.0 .IP \(bu 2 reserved = unused .IP \(bu 2 callback .IP \(bu 2 user .IP \(bu 2 operator .IP \(bu 2 administrator .IP \(bu 2 proprietary = used by OEM .UNINDENT .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.set_channel_access privilege_level=\(aqadministrator\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.set_identify(on=True, duration=600, **kwargs) Request identify light .sp Request the identify light to turn off, on for a duration, or on indefinitely. Other than error exceptions, .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBon\fP \-\- Set to True to force on or False to force off .IP \(bu 2 \fBduration\fP \-\- Set if wanting to request turn on for a duration in seconds, None = indefinitely. .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.set_identify .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.set_power(state=\(aqpower_on\(aq, wait=True, **kwargs) Request power state change .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- .INDENT 2.0 .IP \(bu 2 power_on \-\- system turn on .IP \(bu 2 power_off \-\- system turn off (without waiting for OS) .IP \(bu 2 shutdown \-\- request OS proper shutdown .IP \(bu 2 reset \-\- reset (without waiting for OS) .IP \(bu 2 boot \-\- If system is off, then \(aqon\(aq, else \(aqreset\(aq .UNINDENT .IP \(bu 2 \fBensure\fP \-\- If (bool True), do not return until system actually completes requested state change for 300 seconds. If a non\-zero (int), adjust the wait time to the requested number of seconds .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .TP .B Returns dict \-\- A dict describing the response retrieved .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.set_power state=shutdown wait=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.set_user_access(uid, channel=14, callback=True, link_auth=True, ipmi_msg=True, privilege_level=\(aqadministrator\(aq, **kwargs) Set user access .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuid\fP \-\- user number [1:16] .IP \(bu 2 \fBchannel\fP \-\- number [1:7] .IP \(bu 2 \fBcallback\fP \-\- .sp User Restricted to Callback .INDENT 2.0 .IP \(bu 2 False = User Privilege Limit is determined by the User Privilege Limit parameter, below, for both callback and non\-callback connections. .IP \(bu 2 True = User Privilege Limit is determined by the User Privilege Limit parameter for callback connections, but is restricted to Callback level for non\-callback connections. Thus, a user can only initiate a Callback when they \(aqcall in\(aq to the BMC, but once the callback connection has been made, the user could potentially establish a session as an Operator. .UNINDENT .IP \(bu 2 \fBlink_auth\fP \-\- User Link authentication enable/disable (used to enable whether this user\(aqs name and password information will be used for link authentication, e.g. PPP CHAP) for the given channel. Link authentication itself is a global setting for the channel and is enabled/disabled via the serial/modem configuration parameters. .IP \(bu 2 \fBipmi_msg\fP \-\- User IPMI Messaging: (used to enable/disable whether this user\(aqs name and password information will be used for IPMI Messaging. In this case, \(aqIPMI Messaging\(aq refers to the ability to execute generic IPMI commands that are not associated with a particular payload type. For example, if IPMI Messaging is disabled for a user, but that user is enabled for activating the SOL payload type, then IPMI commands associated with SOL and session management, such as Get SOL Configuration Parameters and Close Session are available, but generic IPMI commands such as Get SEL Time are unavailable.) .IP \(bu 2 \fBprivilege_level\fP \-\- .sp User Privilege Limit. (Determines the maximum privilege level that the user is allowed to switch to on the specified channel.) .INDENT 2.0 .IP \(bu 2 callback .IP \(bu 2 user .IP \(bu 2 operator .IP \(bu 2 administrator .IP \(bu 2 proprietary .IP \(bu 2 no_access .UNINDENT .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.set_user_access uid=2 privilege_level=\(aqoperator\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.set_user_name(uid, name, **kwargs) Set user name .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuid\fP \-\- user number [1:16] .IP \(bu 2 \fBname\fP \-\- username (limit of 16bytes) .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.set_user_name uid=2 name=\(aqsteverweber\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.set_user_password(uid, mode=\(aqset_password\(aq, password=None, **kwargs) Set user password and (modes) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuid\fP \-\- id number of user. see: get_names_uid()[\(aqname\(aq] .IP \(bu 2 \fBmode\fP \-\- .INDENT 2.0 .IP \(bu 2 disable = disable user connections .IP \(bu 2 enable = enable user connections .IP \(bu 2 set_password = set or ensure password .IP \(bu 2 test_password = test password is correct .UNINDENT .IP \(bu 2 \fBpassword\fP \-\- max 16 char string (optional when mode is [disable or enable]) .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .TP .B Returns True on success when mode = test_password, return False on bad password .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.set_user_password api_host=127.0.0.1 api_user=admin api_pass=pass uid=1 password=newPass salt\-call ipmi.set_user_password uid=1 mode=enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipmi.user_delete(uid, channel=14, **kwargs) Delete user (helper) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuid\fP \-\- user number [1:16] .IP \(bu 2 \fBchannel\fP \-\- number [1:7] .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 api_host=127.0.0.1 .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass=example .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call ipmi.user_delete uid=2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ipset .sp Support for ipset .INDENT 0.0 .TP .B salt.modules.ipset.add(name=None, entry=None, family=\(aqipv4\(aq, **kwargs) Append an entry to the specified set. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ipset.add name 192.168.1.26 salt \(aq*\(aq ipset.add name 192.168.0.3,AA:BB:CC:DD:EE:FF .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipset.check(name=None, entry=None, family=\(aqipv4\(aq) Check that an entry exists in the specified set. .INDENT 7.0 .TP .B name The ipset name .TP .B entry An entry in the ipset. This parameter can be a single IP address, a range of IP addresses, or a subnet block. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C 192.168.0.1 192.168.0.2\-192.168.0.19 192.168.0.0/25 .ft P .fi .UNINDENT .UNINDENT .TP .B family IP protocol version: ipv4 or ipv6 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ipset.check name \(aq192.168.0.1 comment \(dqHello\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipset.check_set(name=None, family=\(aqipv4\(aq) Check that given ipset set exists. .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ipset.check_set name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipset.delete(name=None, entry=None, family=\(aqipv4\(aq, **kwargs) Delete an entry from the specified set. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ipset.delete name 192.168.0.3,AA:BB:CC:DD:EE:FF .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipset.delete_set(name=None, family=\(aqipv4\(aq) New in version 2014.7.0. .sp Delete ipset set. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ipset.delete_set custom_set IPv6: salt \(aq*\(aq ipset.delete_set custom_set family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipset.flush(name=None, family=\(aqipv4\(aq) Flush entries in the specified set, Flush all sets if set is not specified. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ipset.flush salt \(aq*\(aq ipset.flush set IPv6: salt \(aq*\(aq ipset.flush salt \(aq*\(aq ipset.flush set .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipset.list_sets(family=\(aqipv4\(aq) New in version 2014.7.0. .sp List all ipset sets. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ipset.list_sets .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipset.new_set(name=None, set_type=None, family=\(aqipv4\(aq, comment=False, **kwargs) New in version 2014.7.0. .sp Create new custom set .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ipset.new_set custom_set list:set salt \(aq*\(aq ipset.new_set custom_set list:set comment=True IPv6: salt \(aq*\(aq ipset.new_set custom_set list:set family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipset.rename_set(name=None, new_set=None, family=\(aqipv4\(aq) New in version 2014.7.0. .sp Delete ipset set. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ipset.rename_set custom_set new_set=new_set_name IPv6: salt \(aq*\(aq ipset.rename_set custom_set new_set=new_set_name family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipset.test(name=None, entry=None, family=\(aqipv4\(aq, **kwargs) Test if an entry is in the specified set. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ipset.test name 192.168.0.2 IPv6: salt \(aq*\(aq ipset.test name fd81:fc56:9ac7::/48 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ipset.version() Return version from ipset \-\-version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ipset.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.iptables .sp Support for iptables .SS Configuration Options .sp The following options can be set in the minion config, grains, pillar, or master config. The configuration is read using \fI\%config.get\fP\&. .INDENT 0.0 .IP \(bu 2 \fBiptables.save_filters\fP: List of REGEX strings to FILTER OUT matching lines .sp This is useful for filtering out chains, rules, etc that you do not wish to persist, such as ephemeral Docker rules. .sp The default is to not filter out anything. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C iptables.save_filters: \- \(dq\-j CATTLE_PREROUTING\(dq \- \(dq\-j DOCKER\(dq \- \(dq\-A POSTROUTING\(dq \- \(dq\-A CATTLE_POSTROUTING\(dq \- \(dq\-A FORWARD\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.append(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq) Append a rule to the specified table/chain. .INDENT 7.0 .TP .B This function accepts a rule in a standard iptables command format, starting with the chain. Trying to force users to adapt to a new method of creating rules would be irritating at best, and we already have a parser that can handle it. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.append filter INPUT \e rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq IPv6: salt \(aq*\(aq iptables.append filter INPUT \e rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq \e family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.build_rule(table=\(aqfilter\(aq, chain=None, command=None, position=\(aq\(aq, full=None, family=\(aqipv4\(aq, **kwargs) Build a well\-formatted iptables rule based on kwargs. A \fItable\fP and \fIchain\fP are not required, unless \fIfull\fP is True. .sp If \fIfull\fP is \fITrue\fP, then \fItable\fP, \fIchain\fP and \fIcommand\fP are required. \fIcommand\fP may be specified as either a short option (\(aqI\(aq) or a long option (\fI\-\-insert\fP). This will return the iptables command, exactly as it would be used from the command line. .sp If a position is required (as with \fI\-I\fP or \fI\-D\fP), it may be specified as \fIposition\fP\&. This will only be useful if \fIfull\fP is True. .sp If \fIstate\fP is passed, it will be ignored, use \fIconnstate\fP\&. If \fIconnstate\fP is passed in, it will automatically be changed to \fIstate\fP\&. .sp To pass in jump options that doesn\(aqt take arguments, pass in an empty string. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Whereas iptables will accept \fB\-p\fP, \fB\-\-proto[c[o[l]]]\fP as synonyms of \fB\-\-protocol\fP, if \fB\-\-proto\fP appears in an iptables command after the appearance of \fB\-m policy\fP, it is interpreted as the \fB\-\-proto\fP option of the policy extension (see the iptables\-extensions(8) man page). .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.build_rule match=state \e connstate=RELATED,ESTABLISHED jump=ACCEPT salt \(aq*\(aq iptables.build_rule filter INPUT command=I position=3 \e full=True match=state connstate=RELATED,ESTABLISHED jump=ACCEPT salt \(aq*\(aq iptables.build_rule filter INPUT command=A \e full=True match=state connstate=RELATED,ESTABLISHED \e source=\(aq127.0.0.1\(aq jump=ACCEPT \&.. Invert Rules salt \(aq*\(aq iptables.build_rule filter INPUT command=A \e full=True match=state connstate=RELATED,ESTABLISHED \e source=\(aq!127.0.0.1\(aq jump=ACCEPT salt \(aq*\(aq iptables.build_rule filter INPUT command=A \e full=True match=state connstate=RELATED,ESTABLISHED \e destination=\(aqnot 127.0.0.1\(aq jump=ACCEPT IPv6: salt \(aq*\(aq iptables.build_rule match=state \e connstate=RELATED,ESTABLISHED jump=ACCEPT \e family=ipv6 salt \(aq*\(aq iptables.build_rule filter INPUT command=I position=3 \e full=True match=state connstate=RELATED,ESTABLISHED jump=ACCEPT \e family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.check(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq) Check for the existence of a rule in the table and chain .INDENT 7.0 .TP .B This function accepts a rule in a standard iptables command format, starting with the chain. Trying to force users to adapt to a new method of creating rules would be irritating at best, and we already have a parser that can handle it. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.check filter INPUT \e rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq IPv6: salt \(aq*\(aq iptables.check filter INPUT \e rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq \e family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.check_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) New in version 2014.1.0. .sp Check for the existence of a chain in the table .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.check_chain filter INPUT IPv6: salt \(aq*\(aq iptables.check_chain filter INPUT family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.delete(table, chain=None, position=None, rule=None, family=\(aqipv4\(aq) .INDENT 7.0 .TP .B Delete a rule from the specified table/chain, specifying either the rule in its entirety, or the rule\(aqs position in the chain. .TP .B This function accepts a rule in a standard iptables command format, starting with the chain. Trying to force users to adapt to a new method of creating rules would be irritating at best, and we already have a parser that can handle it. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.delete filter INPUT position=3 salt \(aq*\(aq iptables.delete filter INPUT \e rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq IPv6: salt \(aq*\(aq iptables.delete filter INPUT position=3 family=ipv6 salt \(aq*\(aq iptables.delete filter INPUT \e rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq \e family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.delete_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) New in version 2014.1.0. .sp Delete custom chain to the specified table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.delete_chain filter CUSTOM_CHAIN IPv6: salt \(aq*\(aq iptables.delete_chain filter CUSTOM_CHAIN family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.flush(table=\(aqfilter\(aq, chain=\(aq\(aq, family=\(aqipv4\(aq) Flush the chain in the specified table, flush all chains in the specified table if not specified chain. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.flush filter INPUT IPv6: salt \(aq*\(aq iptables.flush filter INPUT family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.get_policy(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) Return the current policy for the specified table/chain .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.get_policy filter INPUT IPv6: salt \(aq*\(aq iptables.get_policy filter INPUT family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.get_rules(family=\(aqipv4\(aq) Return a data structure of the current, in\-memory rules .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.get_rules IPv6: salt \(aq*\(aq iptables.get_rules family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.get_saved_policy(table=\(aqfilter\(aq, chain=None, conf_file=None, family=\(aqipv4\(aq) Return the current policy for the specified table/chain .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.get_saved_policy filter INPUT salt \(aq*\(aq iptables.get_saved_policy filter INPUT \e conf_file=/etc/iptables.saved IPv6: salt \(aq*\(aq iptables.get_saved_policy filter INPUT family=ipv6 salt \(aq*\(aq iptables.get_saved_policy filter INPUT \e conf_file=/etc/iptables.saved family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.get_saved_rules(conf_file=None, family=\(aqipv4\(aq) Return a data structure of the rules in the conf file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.get_saved_rules IPv6: salt \(aq*\(aq iptables.get_saved_rules family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.insert(table=\(aqfilter\(aq, chain=None, position=None, rule=None, family=\(aqipv4\(aq) Insert a rule into the specified table/chain, at the specified position. .INDENT 7.0 .TP .B This function accepts a rule in a standard iptables command format, starting with the chain. Trying to force users to adapt to a new method of creating rules would be irritating at best, and we already have a parser that can handle it. .TP .B If the position specified is a negative number, then the insert will be performed counting from the end of the list. For instance, a position of \-1 will insert the rule as the second to last rule. To insert a rule in the last position, use the append function instead. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.insert filter INPUT position=3 \e rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq IPv6: salt \(aq*\(aq iptables.insert filter INPUT position=3 \e rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq \e family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.new_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) New in version 2014.1.0. .sp Create new custom chain to the specified table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.new_chain filter CUSTOM_CHAIN IPv6: salt \(aq*\(aq iptables.new_chain filter CUSTOM_CHAIN family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.save(filename=None, family=\(aqipv4\(aq) Save the current in\-memory rules to disk .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.save /etc/sysconfig/iptables IPv6: salt \(aq*\(aq iptables.save /etc/sysconfig/iptables family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.set_policy(table=\(aqfilter\(aq, chain=None, policy=None, family=\(aqipv4\(aq) Set the current policy for the specified table/chain .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.set_policy filter INPUT ACCEPT IPv6: salt \(aq*\(aq iptables.set_policy filter INPUT ACCEPT family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iptables.version(family=\(aqipv4\(aq) Return version from iptables \-\-version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq iptables.version IPv6: salt \(aq*\(aq iptables.version family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.iwtools .sp Support for Wireless Tools for Linux .INDENT 0.0 .TP .B salt.modules.iwtools.list_interfaces(style=None) List all of the wireless interfaces .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion iwtools.list_interfaces .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iwtools.scan(iface, style=None) List networks on a wireless interface .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion iwtools.scan wlp3s0 salt minion iwtools.scan wlp3s0 list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.iwtools.set_mode(iface, mode) List networks on a wireless interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion iwtools.set_mode wlp3s0 Managed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.jboss7 .sp Module for managing JBoss AS 7 through the CLI interface. .sp New in version 2015.5.0. .INDENT 0.0 .TP .B In order to run each function, jboss_config dictionary with the following properties must be passed: .INDENT 7.0 .IP \(bu 2 cli_path: the path to jboss\-cli script, for example: \(aq/opt/jboss/jboss\-7.0/bin/jboss\-cli.sh\(aq .IP \(bu 2 controller: the IP address and port of controller, for example: 10.11.12.13:9999 .IP \(bu 2 cli_user: username to connect to jboss administration console if necessary .IP \(bu 2 cli_password: password to connect to jboss administration console if necessary .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C jboss_config: cli_path: \(aq/opt/jboss/jboss\-7.0/bin/jboss\-cli.sh\(aq controller: 10.11.12.13:9999 cli_user: \(aqjbossadm\(aq cli_password: \(aqjbossadm\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.create_datasource(jboss_config, name, datasource_properties, profile=None) Create datasource in running jboss instance .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B name Datasource name .TP .B datasource_properties .INDENT 7.0 .TP .B A dictionary of datasource properties to be created: .INDENT 7.0 .IP \(bu 2 driver\-name: mysql .IP \(bu 2 connection\-url: \(aq\fI\%jdbc:mysql://localhost:3306/sampleDatabase\fP\(aq .IP \(bu 2 jndi\-name: \(aqjava:jboss/datasources/sampleDS\(aq .IP \(bu 2 user\-name: sampleuser .IP \(bu 2 password: secret .IP \(bu 2 min\-pool\-size: 3 .IP \(bu 2 use\-java\-context: True .UNINDENT .UNINDENT .TP .B profile The profile name (JBoss domain mode only) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7.create_datasource \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq \(aqmy_datasource\(aq \(aq{\(dqdriver\-name\(dq: \(dqmysql\(dq, \(dqconnection\-url\(dq: \(dqjdbc:mysql://localhost:3306/sampleDatabase\(dq, \(dqjndi\-name\(dq: \(dqjava:jboss/datasources/sampleDS\(dq, \(dquser\-name\(dq: \(dqsampleuser\(dq, \(dqpassword\(dq: \(dqsecret\(dq, \(dqmin\-pool\-size\(dq: 3, \(dquse\-java\-context\(dq: True}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.create_simple_binding(jboss_config, binding_name, value, profile=None) Create a simple jndi binding in the running jboss instance .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B binding_name Binding name to be created .TP .B value Binding value .TP .B profile The profile name (JBoss domain mode only) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7.create_simple_binding \e \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \e \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq \e my_binding_name my_binding_value .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.deploy(jboss_config, source_file) Deploy the application on the jboss instance from the local file system where minion is running. .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B source_file Source file to deploy from .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7.deploy \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq /opt/deploy_files/my_deploy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.list_deployments(jboss_config) List all deployments on the jboss instance .INDENT 7.0 .TP .B jboss_config .INDENT 7.0 .INDENT 3.5 Configuration dictionary with properties specified above. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7.list_deployments \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.read_datasource(jboss_config, name, profile=None) Read datasource properties in the running jboss instance. .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B name Datasource name .TP .B profile Profile name (JBoss domain mode only) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7.read_datasource \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.read_simple_binding(jboss_config, binding_name, profile=None) Read jndi binding in the running jboss instance .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B binding_name Binding name to be created .TP .B profile The profile name (JBoss domain mode only) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .sp salt \(aq*\(aq jboss7.read_simple_binding \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq my_binding_name .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.reload_(jboss_config, host=None) Reload running jboss instance .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B host The name of the host. JBoss domain mode only \- and required if running in domain mode. The host name is the \(dqname\(dq attribute of the \(dqhost\(dq element in host.xml .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7.reload \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.remove_datasource(jboss_config, name, profile=None) Remove an existing datasource from the running jboss instance. .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B name Datasource name .TP .B profile The profile (JBoss domain mode only) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7.remove_datasource \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq my_datasource_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.status(jboss_config, host=None, server_config=None) Get status of running jboss instance. .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B host The name of the host. JBoss domain mode only \- and required if running in domain mode. The host name is the \(dqname\(dq attribute of the \(dqhost\(dq element in host.xml .TP .B server_config The name of the Server Configuration. JBoss Domain mode only \- and required if running in domain mode. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7.status \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.stop_server(jboss_config, host=None) Stop running jboss instance .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B host The name of the host. JBoss domain mode only \- and required if running in domain mode. The host name is the \(dqname\(dq attribute of the \(dqhost\(dq element in host.xml .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7.stop_server \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.undeploy(jboss_config, deployment) Undeploy the application from jboss instance .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B deployment Deployment name to undeploy .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7.undeploy \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq my_deployment .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.update_datasource(jboss_config, name, new_properties, profile=None) Update an existing datasource in running jboss instance. If the property doesn\(aqt exist if will be created, if it does, it will be updated with the new value .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B name Datasource name .TP .B new_properties .INDENT 7.0 .TP .B A dictionary of datasource properties to be updated. For example: .INDENT 7.0 .IP \(bu 2 driver\-name: mysql .IP \(bu 2 connection\-url: \(aq\fI\%jdbc:mysql://localhost:3306/sampleDatabase\fP\(aq .IP \(bu 2 jndi\-name: \(aqjava:jboss/datasources/sampleDS\(aq .IP \(bu 2 user\-name: sampleuser .IP \(bu 2 password: secret .IP \(bu 2 min\-pool\-size: 3 .IP \(bu 2 use\-java\-context: True .UNINDENT .UNINDENT .TP .B profile The profile name (JBoss domain mode only) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7.update_datasource \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq \(aqmy_datasource\(aq \(aq{\(dqdriver\-name\(dq: \(dqmysql\(dq, \(dqconnection\-url\(dq: \(dqjdbc:mysql://localhost:3306/sampleDatabase\(dq, \(dqjndi\-name\(dq: \(dqjava:jboss/datasources/sampleDS\(dq, \(dquser\-name\(dq: \(dqsampleuser\(dq, \(dqpassword\(dq: \(dqsecret\(dq, \(dqmin\-pool\-size\(dq: 3, \(dquse\-java\-context\(dq: True}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7.update_simple_binding(jboss_config, binding_name, value, profile=None) Update the simple jndi binding in the running jboss instance .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B binding_name Binding name to be updated .TP .B value New binding value .TP .B profile The profile name (JBoss domain mode only) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7.update_simple_binding \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq my_binding_name my_binding_value .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.jboss7_cli .sp Module for low\-level interaction with JbossAS7 through CLI. .sp This module exposes two ways of interaction with the CLI, either through commands or operations. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Following JBoss documentation (\fI\%https://developer.jboss.org/wiki/CommandLineInterface\fP): \(dqOperations are considered a low level but comprehensive way to manage the AS controller, i.e. if it can\(aqt be done with operations it can\(aqt be done in any other way. Commands, on the other hand, are more user\-friendly in syntax, although most of them still translate into operation requests and some of them even into a few composite operation requests, i.e. commands also simplify some management operations from the user\(aqs point of view.\(dq .UNINDENT .UNINDENT .sp The difference between calling a command or operation is in handling the result. Commands return a zero return code if operation is successful or return non\-zero return code and print an error to standard output in plain text, in case of an error. .sp Operations return a json\-like structure, that contain more information about the result. In case of a failure, they also return a specific return code. This module parses the output from the operations and returns it as a dictionary so that an execution of an operation can then be verified against specific errors. .INDENT 0.0 .TP .B In order to run each function, jboss_config dictionary with the following properties must be passed: .INDENT 7.0 .IP \(bu 2 cli_path: the path to jboss\-cli script, for example: \(aq/opt/jboss/jboss\-7.0/bin/jboss\-cli.sh\(aq .IP \(bu 2 controller: the IP address and port of controller, for example: 10.11.12.13:9999 .IP \(bu 2 cli_user: username to connect to jboss administration console if necessary .IP \(bu 2 cli_password: password to connect to jboss administration console if necessary .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C jboss_config: cli_path: \(aq/opt/jboss/jboss\-7.0/bin/jboss\-cli.sh\(aq controller: 10.11.12.13:9999 cli_user: \(aqjbossadm\(aq cli_password: \(aqjbossadm\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7_cli.run_command(jboss_config, command, fail_on_error=True) Execute a command against jboss instance through the CLI interface. .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B command Command to execute against jboss instance .TP .B fail_on_error (default=True) Is true, raise CommandExecutionError exception if execution fails. If false, \(aqsuccess\(aq property of the returned dictionary is set to False .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7_cli.run_command \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq my_command .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jboss7_cli.run_operation(jboss_config, operation, fail_on_error=True, retries=1) Execute an operation against jboss instance through the CLI interface. .INDENT 7.0 .TP .B jboss_config Configuration dictionary with properties specified above. .TP .B operation An operation to execute against jboss instance .TP .B fail_on_error (default=True) Is true, raise CommandExecutionError exception if execution fails. If false, \(aqsuccess\(aq property of the returned dictionary is set to False .TP .B retries: Number of retries in case of \(dqJBAS012144: Could not connect to remote\(dq error. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jboss7_cli.run_operation \(aq{\(dqcli_path\(dq: \(dqintegration.modules.sysmod.SysModuleTest.test_valid_docs\(dq, \(dqcontroller\(dq: \(dq10.11.12.13:9999\(dq, \(dqcli_user\(dq: \(dqjbossadm\(dq, \(dqcli_password\(dq: \(dqjbossadm\(dq}\(aq my_operation .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.jenkinsmod .sp Module for controlling Jenkins .INDENT 0.0 .TP .B depends python\-jenkins .UNINDENT .sp New in version 2016.3.0. .INDENT 0.0 .TP .B depends \fI\%python\-jenkins\fP Python module (not to be confused with \fI\%jenkins\fP) .UNINDENT .INDENT 0.0 .TP .B configuration This module can be used by either passing an api key and version directly or by specifying both in a configuration profile in the salt master/minion config. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C jenkins: api_key: peWcBiMOS9HrZG15peWcBiMOS9HrZG15 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.build_job(name=None, parameters=None) Initiate a build for the provided job. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the job is check if it exists. .IP \(bu 2 \fBparameters\fP \-\- Parameters to send to the job. .UNINDENT .TP .B Returns True is successful, otherwise raise an exception. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.build_job jobname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.create_job(name=None, config_xml=None, saltenv=\(aqbase\(aq) Return the configuration file. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the job is check if it exists. .IP \(bu 2 \fBconfig_xml\fP \-\- The configuration file to use to create the job. .IP \(bu 2 \fBsaltenv\fP \-\- The environment to look for the file in. .UNINDENT .TP .B Returns The configuration file used for the job. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.create_job jobname salt \(aq*\(aq jenkins.create_job jobname config_xml=\(aqsalt://jenkins/config.xml\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.delete_job(name=None) Return true is job is deleted successfully. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the job to delete. .TP .B Returns Return true if job is deleted successfully. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.delete_job jobname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.disable_job(name=None) Return true is job is disabled successfully. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the job to disable. .TP .B Returns Return true if job is disabled successfully. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.disable_job jobname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.enable_job(name=None) Return true is job is enabled successfully. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the job to enable. .TP .B Returns Return true if job is enabled successfully. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.enable_job jobname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.get_job_config(name=None) Return the current job configuration for the provided job. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the job to return the configuration for. .TP .B Returns The configuration for the job specified. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.get_job_config jobname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.get_job_info(name=None) Return information about the Jenkins job. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the job is check if it exists. .TP .B Returns Information about the Jenkins job. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.get_job_info jobname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.get_jobs() Return the currently configured jobs. .INDENT 7.0 .TP .B Returns The currently configured jobs. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.get_jobs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.get_version() Return version of Jenkins .INDENT 7.0 .TP .B Returns The version of Jenkins .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.get_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.job_exists(name=None) Check whether the job exists in configured Jenkins jobs. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the job is check if it exists. .TP .B Returns True if job exists, False if job does not exist. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.job_exists jobname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.job_status(name=None) Return the current status, enabled or disabled, of the job. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the job to return status for .TP .B Returns Return true if enabled or false if disabled. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.job_status jobname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.plugin_installed(name) New in version 2016.11.0. .sp Return if the plugin is installed for the provided plugin name. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the parameter to confirm installation. .TP .B Returns True if plugin exists, False if plugin does not exist. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.plugin_installed pluginName .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.run(script) New in version 2017.7.0. .sp Execute a script on the jenkins master .INDENT 7.0 .TP .B Parameters \fBscript\fP \-\- The script .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.run \(aqJenkins.instance.doSafeRestart()\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jenkinsmod.update_job(name=None, config_xml=None, saltenv=\(aqbase\(aq) Return the updated configuration file. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the job is check if it exists. .IP \(bu 2 \fBconfig_xml\fP \-\- The configuration file to use to create the job. .IP \(bu 2 \fBsaltenv\fP \-\- The environment to look for the file in. .UNINDENT .TP .B Returns The configuration file used for the job. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jenkins.update_job jobname salt \(aq*\(aq jenkins.update_job jobname config_xml=\(aqsalt://jenkins/config.xml\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.jinja .sp Module for checking jinja maps and verifying the result of loading JSON/YAML files .sp New in version 3000. .INDENT 0.0 .TP .B salt.modules.jinja.import_json(path) Loads JSON data from the specified path .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion jinja.import_JSON myformula/foo.json .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jinja.import_yaml(path) Loads YAML data from the specified path .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion jinja.import_yaml myformula/foo.yaml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jinja.load_map(path, value) Loads the map at the specified path, and returns the specified value from that map. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Assuming the map is loaded in your formula SLS as follows: # # {% from \(dqmyformula/map.jinja\(dq import myformula with context %} # # the following syntax can be used to load the map and check the # results: salt myminion jinja.load_map myformula/map.jinja myformula .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.jira_mod .SS JIRA Execution module .sp New in version 2019.2.0. .sp Execution module to manipulate JIRA tickets via Salt. .sp This module requires the \fBjira\fP Python library to be installed. .sp Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C jira: server: https://jira.atlassian.org username: salt password: pass .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jira_mod.add_comment(issue_key, comment, visibility=None, is_internal=False, server=None, username=None, password=None) Add a comment to an existing ticket. Return \fBTrue\fP when it successfully added the comment. .INDENT 7.0 .TP .B issue_key The issue ID to add the comment to. .TP .B comment The body of the comment to be added. .TP .B visibility: \fBNone\fP A dictionary having two keys: .INDENT 7.0 .IP \(bu 2 \fBtype\fP: is \fBrole\fP (or \fBgroup\fP if the JIRA server has configured comment visibility for groups). .IP \(bu 2 \fBvalue\fP: the name of the role (or group) to which viewing of this comment will be restricted. .UNINDENT .TP .B is_internal: \fBFalse\fP Whether a comment has to be marked as \fBInternal\fP in Jira Service Desk. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jira.add_comment NE\-123 \(aqThis is a comment\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jira_mod.assign_issue(issue_key, assignee, server=None, username=None, password=None) Assign the issue to an existing user. Return \fBTrue\fP when the issue has been properly assigned. .INDENT 7.0 .TP .B issue_key The JIRA ID of the ticket to manipulate. .TP .B assignee The name of the user to assign the ticket to. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jira.assign_issue NET\-123 example_user .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jira_mod.create_issue(project, summary, description, template_engine=\(aqjinja\(aq, context=None, defaults=None, saltenv=\(aqbase\(aq, issuetype=\(aqBug\(aq, priority=\(aqNormal\(aq, labels=None, assignee=None, server=None, username=None, password=None, **kwargs) Create a JIRA issue using the named settings. Return the JIRA ticket ID. .INDENT 7.0 .TP .B project The name of the project to attach the JIRA ticket to. .TP .B summary The summary (title) of the JIRA ticket. When the \fBtemplate_engine\fP argument is set to a proper value of an existing Salt template engine (e.g., \fBjinja\fP, \fBmako\fP, etc.) it will render the \fBsummary\fP before creating the ticket. .TP .B description The full body description of the JIRA ticket. When the \fBtemplate_engine\fP argument is set to a proper value of an existing Salt template engine (e.g., \fBjinja\fP, \fBmako\fP, etc.) it will render the \fBdescription\fP before creating the ticket. .TP .B template_engine: \fBjinja\fP The name of the template engine to be used to render the values of the \fBsummary\fP and \fBdescription\fP arguments. Default: \fBjinja\fP\&. .TP .B context: \fBNone\fP The context to pass when rendering the \fBsummary\fP and \fBdescription\fP\&. This argument is ignored when \fBtemplate_engine\fP is set as \fBNone\fP .TP .B defaults: \fBNone\fP Default values to pass to the Salt rendering pipeline for the \fBsummary\fP and \fBdescription\fP arguments. This argument is ignored when \fBtemplate_engine\fP is set as \fBNone\fP\&. .TP .B saltenv: \fBbase\fP The Salt environment name (for the rendering system). .TP .B issuetype: \fBBug\fP The type of the JIRA ticket. Default: \fBBug\fP\&. .TP .B priority: \fBNormal\fP The priority of the JIRA ticket. Default: \fBNormal\fP\&. .TP .B labels: \fBNone\fP A list of labels to add to the ticket. .TP .B assignee: \fBNone\fP The name of the person to assign the ticket to. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jira.create_issue NET \(aqTicket title\(aq \(aqTicket description\(aq salt \(aq*\(aq jira.create_issue NET \(aqIssue on {{ opts.id }}\(aq \(aqError detected on {{ opts.id }}\(aq template_engine=jinja .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.jira_mod.issue_closed(issue_key, server=None, username=None, password=None) Check if the issue is closed. .INDENT 7.0 .TP .B issue_key The JIRA iD of the ticket to close. .UNINDENT .sp Returns: .INDENT 7.0 .IP \(bu 2 \fBTrue\fP: the ticket exists and it is closed. .IP \(bu 2 \fBFalse\fP: the ticket exists and it has not been closed. .IP \(bu 2 \fBNone\fP: the ticket does not exist. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jira.issue_closed NE\-123 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.junos .sp Module to interact with Junos devices. .INDENT 0.0 .TP .B maturity new .TP .B dependencies junos\-eznc, jxmlease .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Those who wish to use junos\-eznc (PyEZ) version >= 2.1.0, must use the latest salt code from github until the next release. .UNINDENT .UNINDENT .sp Refer to \fI\%junos\fP for information on connecting to junos proxy. .INDENT 0.0 .TP .B class salt.modules.junos.HandleFileCopy(path, **kwargs) To figure out proper path either from proxy local file system or proxy cache or on master. If required, then only copy from master to proxy .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.cli(command=None, **kwargs) Executes the CLI commands and returns the output in specified format. (default is text) The output can also be stored in a file. .INDENT 7.0 .TP .B command (required) The command to execute on the Junos CLI .TP .B format text Format in which to get the CLI output (either \fBtext\fP or \fBxml\fP) .TP .B dev_timeout 30 The NETCONF RPC timeout (in seconds) .TP .B dest Destination file where the RPC output is stored. Note that the file will be stored on the proxy minion. To push the files to the master use \fI\%cp.push\fP\&. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.cli \(aqshow system commit\(aq salt \(aqdevice_name\(aq junos.cli \(aqshow system alarms\(aq format=xml dest=/home/user/cli_output.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.commit(**kwargs) To commit the changes loaded in the candidate configuration. .INDENT 7.0 .TP .B dev_timeout 30 The NETCONF RPC timeout (in seconds) .TP .B comment Provide a comment for the commit .TP .B confirm Provide time in minutes for commit confirmation. If this option is specified, the commit will be rolled back in the specified amount of time unless the commit is confirmed. .TP .B sync False When \fBTrue\fP, on dual control plane systems, requests that the candidate configuration on one control plane be copied to the other control plane, checked for correct syntax, and committed on both Routing Engines. .TP .B force_sync False When \fBTrue\fP, on dual control plane systems, force the candidate configuration on one control plane to be copied to the other control plane. .TP .B full When \fBTrue\fP, requires all the daemons to check and evaluate the new configuration. .TP .B detail When \fBTrue\fP, return commit detail .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.commit comment=\(aqCommiting via saltstack\(aq detail=True salt \(aqdevice_name\(aq junos.commit dev_timeout=60 confirm=10 salt \(aqdevice_name\(aq junos.commit sync=True dev_timeout=90 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.commit_check() Perform a commit check on the configuration .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.commit_check .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.diff(**kwargs) Returns the difference between the candidate and the current configuration .INDENT 7.0 .TP .B id 0 The rollback ID value (0\-49) .TP .B d_id 0 The rollback ID value (0\-49) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.diff d_id=3 .ft P .fi .UNINDENT .UNINDENT .sp NOTE: Because of historical reasons and the internals of the Salt state compiler, there are three possible sources of the rollback ID\-\-the positional argument, and the \fIid\fP and \fId_id\fP kwargs. The precedence of the arguments are \fIid\fP (positional), \fIid\fP (kwarg), \fId_id\fP (kwarg). In other words, if all three are passed, only the positional argument will be used. A warning is logged if more than one is passed. .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.dir_copy(source, dest, force=False, **kwargs) Copy a directory and recursively its contents from source to dest. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function only works on the Juniper native minion .UNINDENT .UNINDENT .sp Parameters: .sp source : Directory to use as the source .sp dest : Directory in which to place the source and its contents. .sp force : This function will not copy identical files unless \fIforce\fP is \fITrue\fP .sp New in version 3003. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.dir_copy /etc/salt/pki re1:/ .ft P .fi .UNINDENT .UNINDENT .sp This will take the \fIpki\fP directory, its absolute path and copy it and its contents to routing engine 1 root directory. The result will be \fIre1:/etc/salt/pki/<files and dirs in /etc/salt/pki\fP\&. .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.facts() Displays the facts gathered during the connection. These facts are also stored in Salt grains. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.facts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.facts_refresh() Reload the facts dictionary from the device. Usually only needed if, the device configuration is changed by some other actor. This function will also refresh the facts stored in the salt grains. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.facts_refresh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.file_compare(file1, file2, **kwargs) Compare two files and return a dictionary indicating if they are different. .sp Dictionary includes \fIsuccess\fP key. If False, one or more files do not exist or some other error occurred. .sp Under the hood, this uses the junos CLI command \fIfile compare files ...\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function only works on Juniper native minions .UNINDENT .UNINDENT .sp New in version 3003. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt junos\-router junos.file_compare /var/tmp/backup1/cmt.script /var/tmp/backup2/cmt.script junos\-router: identical: False success: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.file_copy(src, dest) Copies the file from the local device to the junos device .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function does not work on Juniper native minions .UNINDENT .UNINDENT .INDENT 7.0 .TP .B src The source path where the file is kept. .TP .B dest The destination path on the where the file will be copied .UNINDENT .sp New in version 3001. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.file_copy /home/m2/info.txt info_copy.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.fsentry_exists(dir, **kwargs) Returns a dictionary indicating if \fIdir\fP refers to a file or a non\-file (generally a directory) in the file system, or if there is no file by that name. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function only works on Juniper native minions .UNINDENT .UNINDENT .sp New in version 3003. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt junos\-router junos.fsentry_exists /var/log junos\-router: is_dir: True exists: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.get_table(table, table_file, path=None, target=None, key=None, key_items=None, filters=None, table_args=None) New in version 3001. .sp Retrieve data from a Junos device using Tables/Views .INDENT 7.0 .TP .B table (required) Name of PyEZ Table .TP .B table_file (required) YAML file that has the table specified in table parameter .TP .B path: Path of location of the YAML file. defaults to op directory in jnpr.junos.op .TP .B target: if command need to run on FPC, can specify fpc target .TP .B key: To overwrite key provided in YAML .TP .B key_items: To select only given key items .TP .B filters: To select only filter for the dictionary from columns .TP .B table_args: key/value pair which should render Jinja template command or are passed as args to rpc call in op table .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.get_table RouteTable routes.yml salt \(aqdevice_name\(aq junos.get_table EthPortTable ethport.yml table_args=\(aq{\(dqinterface_name\(dq: \(dqge\-3/2/2\(dq}\(aq salt \(aqdevice_name\(aq junos.get_table EthPortTable ethport.yml salt://tables .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.install_config(path=None, **kwargs) Installs the given configuration file into the candidate configuration. Commits the changes if the commit checks or throws an error. .INDENT 7.0 .TP .B path (required) Path where the configuration/template file is present. If the file has a \fB\&.conf\fP extension, the content is treated as text format. If the file has a \fB\&.xml\fP extension, the content is treated as XML format. If the file has a \fB\&.set\fP extension, the content is treated as Junos OS \fBset\fP commands. .TP .B mode exclusive The mode in which the configuration is locked. Can be one of \fBprivate\fP, \fBdynamic\fP, \fBbatch\fP, \fBexclusive\fP, \fBephemeral\fP .TP .B dev_timeout 30 Set NETCONF RPC timeout. Can be used for commands which take a while to execute. .TP .B overwrite False Set to \fBTrue\fP if you want this file is to completely replace the configuration file. Sets action to override .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option cannot be used if \fBformat\fP is \(dqset\(dq. .UNINDENT .UNINDENT .TP .B replace False Specify whether the configuration file uses \fBreplace:\fP statements. If \fBTrue\fP, only those statements under the \fBreplace\fP tag will be changed. .TP .B merge False If set to \fBTrue\fP will set the load\-config action to merge. the default load\-config action is \(aqreplace\(aq for xml/json/text config .TP .B format Determines the format of the contents .TP .B update False Compare a complete loaded configuration against the candidate configuration. For each hierarchy level or configuration object that is different in the two configurations, the version in the loaded configuration replaces the version in the candidate configuration. When the configuration is later committed, only system processes that are affected by the changed configuration elements parse the new configuration. This action is supported from PyEZ 2.1. .TP .B comment Provide a comment for the commit .TP .B confirm Provide time in minutes for commit confirmation. If this option is specified, the commit will be rolled back in the specified amount of time unless the commit is confirmed. .TP .B diffs_file Path to the file where the diff (difference in old configuration and the committed configuration) will be stored. Note that the file will be stored on the proxy minion. To push the files to the master use: .INDENT 7.0 .INDENT 3.5 py:func:\fIcp.push <salt.modules.cp.push>\fP\&. .UNINDENT .UNINDENT .TP .B template_vars Variables to be passed into the template processing engine in addition to those present in pillar, the minion configuration, grains, etc. You may reference these variables in your template like so: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {{ template_vars[\(dqvar_name\(dq] }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.install_config \(aqsalt://production/network/routers/config.set\(aq salt \(aqdevice_name\(aq junos.install_config \(aqsalt://templates/replace_config.conf\(aq replace=True comment=\(aqCommitted via SaltStack\(aq salt \(aqdevice_name\(aq junos.install_config \(aqsalt://my_new_configuration.conf\(aq dev_timeout=300 diffs_file=\(aq/salt/confs/old_config.conf\(aq overwrite=True salt \(aqdevice_name\(aq junos.install_config \(aqsalt://syslog_template.conf\(aq template_vars=\(aq{\(dqsyslog_host\(dq: \(dq10.180.222.7\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.install_os(path=None, **kwargs) Installs the given image on the device. After the installation is complete the device is rebooted, if reboot=True is given as a keyworded argument. .INDENT 7.0 .TP .B path (required) Path where the image file is present on the proxy minion .TP .B remote_path /var/tmp If the value of path is a file path on the local (Salt host\(aqs) filesystem, then the image is copied from the local filesystem to the :remote_path: directory on the target Junos device. The default is \fB/var/tmp\fP\&. If the value of :path: or is a URL, then the value of :remote_path: is unused. .TP .B dev_timeout 1800 The NETCONF RPC timeout (in seconds). This argument was added since most of the time the \(dqpackage add\(dq RPC takes a significant amount of time. So this :timeout: value will be used in the context of the SW installation process. Defaults to 30 minutes (30*60=1800 seconds) .TP .B timeout 1800 Alias to dev_timeout for backward compatibility .TP .B reboot False Whether to reboot after installation .TP .B no_copy False If \fBTrue\fP the software package will not be SCP’d to the device .TP .B bool validate: When \fBTrue\fP this method will perform a config validation against the new image .TP .B bool issu: False When \fBTrue\fP allows unified in\-service software upgrade (ISSU) feature enables you to upgrade between two different Junos OS releases with no disruption on the control plane and with minimal disruption of traffic. .TP .B bool nssu: False When \fBTrue\fP allows nonstop software upgrade (NSSU) enables you to upgrade the software running on a Juniper Networks EX Series Virtual Chassis or a Juniper Networks EX Series Ethernet Switch with redundant Routing Engines with a single command and minimal disruption to network traffic. .TP .B bool all_re: True When True (default), executes the software install on all Routing Engines of the Junos device. When False, execute the software install only on the current Routing Engine. .sp New in version 3001. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Any additional keyword arguments specified are passed down to PyEZ sw.install() as is. Please refer to below URl for PyEZ sw.install() documentation: \fI\%https://pyez.readthedocs.io/en/latest/jnpr.junos.utils.html#jnpr.junos.utils.sw.SW.install\fP .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.install_os \(aqsalt://images/junos_image.tgz\(aq reboot=True salt \(aqdevice_name\(aq junos.install_os \(aqsalt://junos_16_1.tgz\(aq dev_timeout=300 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.load(path=None, **kwargs) Loads the configuration from the file provided onto the device. .INDENT 7.0 .TP .B path (required) Path where the configuration/template file is present. If the file has a \fB\&.conf\fP extension, the content is treated as text format. If the file has a \fB\&.xml\fP extension, the content is treated as XML format. If the file has a \fB\&.set\fP extension, the content is treated as Junos OS \fBset\fP commands. .TP .B overwrite False Set to \fBTrue\fP if you want this file is to completely replace the configuration file. Sets action to override .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option cannot be used if \fBformat\fP is \(dqset\(dq. .UNINDENT .UNINDENT .TP .B replace False Specify whether the configuration file uses \fBreplace:\fP statements. If \fBTrue\fP, only those statements under the \fBreplace\fP tag will be changed. .TP .B merge False If set to \fBTrue\fP will set the load\-config action to merge. the default load\-config action is \(aqreplace\(aq for xml/json/text config .TP .B update False Compare a complete loaded configuration against the candidate configuration. For each hierarchy level or configuration object that is different in the two configurations, the version in the loaded configuration replaces the version in the candidate configuration. When the configuration is later committed, only system processes that are affected by the changed configuration elements parse the new configuration. This action is supported from PyEZ 2.1. .TP .B format Determines the format of the contents .TP .B template_vars Variables to be passed into the template processing engine in addition to those present in pillar, the minion configuration, grains, etc. You may reference these variables in your template like so: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {{ template_vars[\(dqvar_name\(dq] }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.load \(aqsalt://production/network/routers/config.set\(aq salt \(aqdevice_name\(aq junos.load \(aqsalt://templates/replace_config.conf\(aq replace=True salt \(aqdevice_name\(aq junos.load \(aqsalt://my_new_configuration.conf\(aq overwrite=True salt \(aqdevice_name\(aq junos.load \(aqsalt://syslog_template.conf\(aq template_vars=\(aq{\(dqsyslog_host\(dq: \(dq10.180.222.7\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.lock() Attempts an exclusive lock on the candidate configuration. This is a non\-blocking call. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When locking, it is important to remember to call \fI\%junos.unlock\fP once finished. If locking during orchestration, remember to include a step in the orchestration job to unlock. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.lock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.ping(dest_ip=None, **kwargs) Send a ping RPC to a device .INDENT 7.0 .TP .B dest_ip The IP of the device to ping .TP .B dev_timeout 30 The NETCONF RPC timeout (in seconds) .TP .B rapid False When \fBTrue\fP, executes ping at 100pps instead of 1pps .TP .B ttl Maximum number of IP routers (IP hops) allowed between source and destination .TP .B routing_instance Name of the routing instance to use to send the ping .TP .B interface Interface used to send traffic .TP .B count 5 Number of packets to send .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.ping \(aq8.8.8.8\(aq count=5 salt \(aqdevice_name\(aq junos.ping \(aq8.8.8.8\(aq ttl=1 rapid=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.rollback(**kwargs) Roll back the last committed configuration changes and commit .INDENT 7.0 .TP .B id 0 The rollback ID value (0\-49) .TP .B d_id 0 The rollback ID value (0\-49) .TP .B dev_timeout 30 The NETCONF RPC timeout (in seconds) .TP .B comment Provide a comment for the commit .TP .B confirm Provide time in minutes for commit confirmation. If this option is specified, the commit will be rolled back in the specified amount of time unless the commit is confirmed. .TP .B diffs_file Path to the file where the diff (difference in old configuration and the committed configuration) will be stored. Note that the file will be stored on the proxy minion. To push the files to the master use \fI\%cp.push\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.rollback 10 .ft P .fi .UNINDENT .UNINDENT .sp NOTE: Because of historical reasons and the internals of the Salt state compiler, there are three possible sources of the rollback ID\-\-the positional argument, and the \fIid\fP and \fId_id\fP kwargs. The precedence of the arguments are \fIid\fP (positional), \fIid\fP (kwarg), \fId_id\fP (kwarg). In other words, if all three are passed, only the positional argument will be used. A warning is logged if more than one is passed. .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.routing_engine(**kwargs) Returns a dictionary containing the routing engines on the device and their status (Master, Disabled, Backup). .sp Under the hood parses the result of \fIshow chassis routing\-engine\fP .sp New in version 3003. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt junos\-router junos.routing_engine junos\-router: backup: \- re1: master: re0: success: True .ft P .fi .UNINDENT .UNINDENT .sp Returns \fIsuccess: False\fP if the device does not appear to have multiple routing engines. .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.rpc(cmd=None, dest=None, **kwargs) This function executes the RPC provided as arguments on the junos device. The returned data can be stored in a file. .INDENT 7.0 .TP .B cmd The RPC to be executed .TP .B dest Destination file where the RPC output is stored. Note that the file will be stored on the proxy minion. To push the files to the master use \fI\%cp.push\fP\&. .TP .B format xml The format in which the RPC reply is received from the device .TP .B dev_timeout 30 The NETCONF RPC timeout (in seconds) .TP .B filter Used with the \fBget\-config\fP RPC to get specific configuration .TP .B terse False Amount of information you want .TP .B interface_name Name of the interface to query .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice\(aq junos.rpc get_config dest=/var/log/config.txt format=text filter=\(aq<configuration><system/></configuration>\(aq salt \(aqdevice\(aq junos.rpc get\-interface\-information dest=/home/user/interface.xml interface_name=\(aqlo0\(aq terse=True salt \(aqdevice\(aq junos.rpc get\-chassis\-inventory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.rpc_file_list(path, **kwargs) Use the Junos RPC interface to get a list of files and return them as a structure dictionary. .sp New in version 3003. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt junos\-router junos.rpc_file_list /var/local/salt/etc junos\-router: files: directory: directory\-name: /var/local/salt/etc file\-information: |_ file\-directory: file\-name: pki |_ file\-name: proxy |_ file\-directory: file\-name: proxy.d total\-file\-blocks: 10 total\-files: 1 success: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.set_hostname(hostname=None, **kwargs) Set the device\(aqs hostname .INDENT 7.0 .TP .B hostname The name to be set .TP .B comment Provide a comment to the commit .TP .B dev_timeout 30 The NETCONF RPC timeout (in seconds) .TP .B confirm Provide time in minutes for commit confirmation. If this option is specified, the commit will be rolled back in the specified amount of time unless the commit is confirmed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.set_hostname salt\-device .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.shutdown(**kwargs) Shut down (power off) or reboot a device running Junos OS. This includes all Routing Engines in a Virtual Chassis or a dual Routing Engine system. .INDENT 7.0 .INDENT 3.5 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 One of \fBshutdown\fP or \fBreboot\fP must be set to \fBTrue\fP or no action will be taken. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B shutdown False Set this to \fBTrue\fP if you want to shutdown the machine. This is a safety mechanism so that the user does not accidentally shutdown the junos device. .TP .B reboot False If \fBTrue\fP, reboot instead of shutting down .TP .B at Used when rebooting, to specify the date and time the reboot should take place. The value of this option must match the JunOS CLI reboot syntax. .TP .B in_min Used when shutting down. Specify the delay (in minutes) before the device will be shut down. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.shutdown reboot=True salt \(aqdevice_name\(aq junos.shutdown shutdown=True in_min=10 salt \(aqdevice_name\(aq junos.shutdown shutdown=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.unlock() Unlocks the candidate configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.unlock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.junos.zeroize() Resets the device to default factory settings .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 In case of non\-root user, proxy_reconnect will not be able to re\-connect to the device as zeroize will delete the local user\(aqs configuration. For more details on zeroize functionality, please refer \fI\%https://www.juniper.net/documentation/en_US/junos/topics/reference/command\-summary/request\-system\-zeroize.html\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice_name\(aq junos.zeroize .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.k8s .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%kubernetes Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Salt module to manage Kubernetes cluster .sp New in version 2016.3.0. .sp Roadmap: .INDENT 0.0 .IP \(bu 2 Add creation of K8S objects (pod, rc, service, ...) .IP \(bu 2 Add replace of K8S objects (pod, rc, service, ...) .IP \(bu 2 Add deletion of K8S objects (pod, rc, service, ...) .IP \(bu 2 Add rolling update .IP \(bu 2 Add (auto)scalling .UNINDENT .INDENT 0.0 .TP .B salt.modules.k8s.create_namespace(name, apiserver_url=None) New in version 2016.3.0. .sp Create kubernetes namespace from the name, similar to the functionality added to kubectl since v.1.2.0: \&.. code\-block:: bash .INDENT 7.0 .INDENT 3.5 kubectl create namespaces namespace\-name .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq k8s.create_namespace namespace_name salt \(aq*\(aq k8s.create_namespace namespace_name http://kube\-master.cluster.local .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.k8s.create_secret(namespace, name, sources, apiserver_url=None, force=False, update=False, saltenv=\(aqbase\(aq) New in version 2016.3.0. .sp Create k8s secrets in the defined namespace from the list of files .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq k8s.create_secret namespace_name secret_name sources salt \(aq*\(aq k8s.create_secret namespace_name secret_name sources http://kube\-master.cluster.local .ft P .fi .UNINDENT .UNINDENT .sp sources are either dictionary of {name: path, name1: path} pairs or array of strings defining paths. .sp Example of paths array: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .sp [\(aq/full/path/filename\(aq, \(dq\fI\%file:///full/path/filename\fP\(dq, \(dqsalt://secret/storage/file.txt\(dq, \(dqhttp://user:password@securesite.com/secret\-file.json\(dq] .sp Example of dictionaries: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .sp {\(dqnameit\(dq: \(aq/full/path/fiename\(aq, name2: \(dqsalt://secret/storage/file.txt\(dq} .sp optional parameters accepted: .sp update=[false] default value is false if set to false, and secret is already present on the cluster \- warning will be returned and no changes to the secret will be done. In case it is set to \(dqtrue\(dq and secret is present but data is differ \- secret will be updated. .sp force=[true] default value is true if the to False, secret will not be created in case one of the files is not valid kubernetes secret. e.g. capital letters in secret name or _ in case force is set to True, wrong files will be skipped but secret will be created any way. .sp saltenv=[\(aqbase\(aq] default value is base in case \(aqsalt://\(aq path is used, this parameter can change the visibility of files .UNINDENT .INDENT 0.0 .TP .B salt.modules.k8s.delete_secret(namespace, name, apiserver_url=None, force=True) New in version 2016.3.0. .sp Delete kubernetes secret in the defined namespace. Namespace is the mandatory parameter as well as name. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq k8s.delete_secret namespace_name secret_name salt \(aq*\(aq k8s.delete_secret namespace_name secret_name http://kube\-master.cluster.local .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.k8s.get_labels(node=None, apiserver_url=None) New in version 2016.3.0. .sp Get labels from the current node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq k8s.get_labels salt \(aq*\(aq k8s.get_labels kube\-node.cluster.local http://kube\-master.cluster.local .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.k8s.get_namespaces(namespace=\(aq\(aq, apiserver_url=None) New in version 2016.3.0. .sp Get one or all kubernetes namespaces. .sp If namespace parameter is omitted, all namespaces will be returned back to user, similar to following kubectl example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C kubectl get namespaces \-o json .ft P .fi .UNINDENT .UNINDENT .sp In case namespace is set by user, the output will be similar to the one from kubectl: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C kubectl get namespaces namespace_name \-o json .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq k8s.get_namespaces salt \(aq*\(aq k8s.get_namespaces namespace_name http://kube\-master.cluster.local .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.k8s.get_secrets(namespace, name=\(aq\(aq, apiserver_url=None, decode=False, brief=False) Get k8s namespaces .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq k8s.get_secrets namespace_name salt \(aq*\(aq k8s.get_secrets namespace_name secret_name http://kube\-master.cluster.local .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.k8s.label_absent(name, node=None, apiserver_url=None) New in version 2016.3.0. .sp Delete label to the current node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq k8s.label_absent hw/disktype salt \(aq*\(aq k8s.label_absent hw/disktype kube\-node.cluster.local http://kube\-master.cluster.local .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.k8s.label_folder_absent(name, node=None, apiserver_url=None) New in version 2016.3.0. .sp Delete label folder to the current node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq k8s.label_folder_absent hw salt \(aq*\(aq k8s.label_folder_absent hw/ kube\-node.cluster.local http://kube\-master.cluster.local .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.k8s.label_present(name, value, node=None, apiserver_url=None) New in version 2016.3.0. .sp Set label to the current node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq k8s.label_present hw/disktype ssd salt \(aq*\(aq k8s.label_present hw/disktype ssd kube\-node.cluster.local http://kube\-master.cluster.local .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.k8s.update_secret(namespace, name, sources, apiserver_url=None, force=True, saltenv=\(aqbase\(aq) New in version 2016.3.0. .sp alias to k8s.create_secret with update=true .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq k8s.update_secret namespace_name secret_name sources [apiserver_url] [force=true] [update=false] [saltenv=\(aqbase\(aq] .ft P .fi .UNINDENT .UNINDENT .sp sources are either dictionary of {name: path, name1: path} pairs or array of strings defining paths. .sp Example of paths array: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .sp [\(aq/full/path/filename\(aq, \(dq\fI\%file:///full/path/filename\fP\(dq, \(dqsalt://secret/storage/file.txt\(dq, \(dqhttp://user:password@securesite.com/secret\-file.json\(dq] .sp Example of dictionaries: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .sp {\(dqnameit\(dq: \(aq/full/path/fiename\(aq, name2: \(dqsalt://secret/storage/file.txt\(dq} .sp optional parameters accepted: .sp force=[true] default value is true if the to False, secret will not be created in case one of the files is not valid kubernetes secret. e.g. capital letters in secret name or _ in case force is set to True, wrong files will be skipped but secret will be created any way. .sp saltenv=[\(aqbase\(aq] default value is base in case \(aqsalt://\(aq path is used, this parameter can change the visibility of files .UNINDENT .SS salt.modules.kapacitor .sp Kapacitor execution module. .INDENT 0.0 .TP .B configuration This module accepts connection configuration details either as parameters or as configuration settings in /etc/salt/minion on the relevant minions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C kapacitor.host: \(aqlocalhost\(aq kapacitor.port: 9092 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .sp Also protocol and SSL settings could be configured: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C kapacitor.unsafe_ssl: \(aqfalse\(aq kapacitor.protocol: \(aqhttp\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp This data can also be passed into pillar. Options passed into opts will overwrite options passed into pillar. .UNINDENT .INDENT 0.0 .TP .B salt.modules.kapacitor.define_task(name, tick_script, task_type=\(aqstream\(aq, database=None, retention_policy=\(aqdefault\(aq, dbrps=None) Define a task. Serves as both create/update. .INDENT 7.0 .TP .B name Name of the task. .TP .B tick_script Path to the TICK script for the task. Can be a salt:// source. .TP .B task_type Task type. Defaults to \(aqstream\(aq .TP .B dbrps A list of databases and retention policies in \(dqdbname\(dq.\(dqrpname\(dq format to fetch data from. For backward compatibility, the value of \(aqdatabase\(aq and \(aqretention_policy\(aq will be merged as part of dbrps. .sp New in version 2019.2.0. .TP .B database Which database to fetch data from. .TP .B retention_policy Which retention policy to fetch data from. Defaults to \(aqdefault\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kapacitor.define_task cpu salt://kapacitor/cpu.tick database=telegraf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kapacitor.delete_task(name) Delete a kapacitor task. .INDENT 7.0 .TP .B name Name of the task to delete. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kapacitor.delete_task cpu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kapacitor.disable_task(name) Disable a kapacitor task. .INDENT 7.0 .TP .B name Name of the task to disable. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kapacitor.disable_task cpu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kapacitor.enable_task(name) Enable a kapacitor task. .INDENT 7.0 .TP .B name Name of the task to enable. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kapacitor.enable_task cpu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kapacitor.get_task(name) Get a dict of data on a task. .INDENT 7.0 .TP .B name Name of the task to get information about. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kapacitor.get_task cpu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kapacitor.version() Get the kapacitor version. .UNINDENT .SS salt.modules.kerberos .sp Manage Kerberos KDC .INDENT 0.0 .TP .B configuration In order to manage your KDC you will need to generate a keytab that can authenticate without requiring a password. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # ktadd \-k /root/secure.keytab kadmin/admin kadmin/changepw .ft P .fi .UNINDENT .UNINDENT .sp On the KDC minion you will need to add the following to the minion configuration file so Salt knows what keytab to use and what principal to authenticate as. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth_keytab: /root/auth.keytab auth_principal: kadmin/admin .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kerberos.create_keytab(name, keytab, enctypes=None) Create keytab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqkdc.example.com\(aq kerberos.create_keytab host/host1.example.com host1.example.com.keytab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kerberos.create_principal(name, enctypes=None) Create Principal .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqkdc.example.com\(aq kerberos.create_principal host/example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kerberos.delete_principal(name) Delete Principal .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqkdc.example.com\(aq kerberos.delete_principal host/example.com@EXAMPLE.COM .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kerberos.get_policy(name) Get policy details .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqkdc.example.com\(aq kerberos.get_policy my_policy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kerberos.get_principal(name) Get princial details .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqkdc.example.com\(aq kerberos.get_principal root/admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kerberos.get_privs() Current privileges .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqkdc.example.com\(aq kerberos.get_privs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kerberos.list_policies() List policies .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqkdc.example.com\(aq kerberos.list_policies .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kerberos.list_principals() Get all principals .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqkde.example.com\(aq kerberos.list_principals .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.kernelpkg_linux_apt .sp Manage Linux kernel packages on APT\-based systems .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_apt.active() Return the version of the running kernel. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.active .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_apt.cleanup(keep_latest=True) Remove all unused kernel packages from the system. .INDENT 7.0 .TP .B keep_latest True In the event that the active kernel is not the latest one installed, setting this to True will retain the latest kernel package, in addition to the active one. If False, all kernel packages other than the active one will be removed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.cleanup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_apt.latest_available() Return the version of the latest kernel from the package repositories. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.latest_available .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_apt.latest_installed() Return the version of the latest installed kernel. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.latest_installed .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function may not return the same value as \fI\%active()\fP if a new kernel has been installed and the system has not yet been rebooted. The \fI\%needs_reboot()\fP function exists to detect this condition. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_apt.list_installed() Return a list of all installed kernels. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.list_installed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_apt.needs_reboot() Detect if a new kernel version has been installed but is not running. Returns True if a new kernel is installed, False otherwise. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.needs_reboot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_apt.remove(release) Remove a specific version of the kernel. .INDENT 7.0 .TP .B release The release number of an installed kernel. This must be the entire release number as returned by \fI\%list_installed()\fP, not the package name. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.remove 4.4.0\-70\-generic .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_apt.upgrade(reboot=False, at_time=None) Upgrade the kernel and optionally reboot the system. .INDENT 7.0 .TP .B reboot False Request a reboot if a new kernel is available. .TP .B at_time immediate Schedule the reboot at some point in the future. This argument is ignored if \fBreboot=False\fP\&. See \fI\%reboot()\fP for more details on this argument. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.upgrade salt \(aq*\(aq kernelpkg.upgrade reboot=True at_time=1 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 An immediate reboot often shuts down the system before the minion has a chance to return, resulting in errors. A minimal delay (1 minute) is useful to ensure the result is delivered to the master. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_apt.upgrade_available() Detect if a new kernel version is available in the repositories. Returns True if a new kernel is available, False otherwise. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.upgrade_available .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.kernelpkg_linux_yum .sp Manage Linux kernel packages on YUM\-based systems .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_yum.active() Return the version of the running kernel. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.active .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_yum.cleanup(keep_latest=True) Remove all unused kernel packages from the system. .INDENT 7.0 .TP .B keep_latest True In the event that the active kernel is not the latest one installed, setting this to True will retain the latest kernel package, in addition to the active one. If False, all kernel packages other than the active one will be removed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.cleanup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_yum.latest_available() Return the version of the latest kernel from the package repositories. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.latest_available .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_yum.latest_installed() Return the version of the latest installed kernel. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.latest_installed .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function may not return the same value as \fI\%active()\fP if a new kernel has been installed and the system has not yet been rebooted. The \fI\%needs_reboot()\fP function exists to detect this condition. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_yum.list_installed() Return a list of all installed kernels. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.list_installed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_yum.needs_reboot() Detect if a new kernel version has been installed but is not running. Returns True if a new kernel is installed, False otherwise. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.needs_reboot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_yum.remove(release) Remove a specific version of the kernel. .INDENT 7.0 .TP .B release The release number of an installed kernel. This must be the entire release number as returned by \fI\%list_installed()\fP, not the package name. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.remove 3.10.0\-327.el7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_yum.upgrade(reboot=False, at_time=None) Upgrade the kernel and optionally reboot the system. .INDENT 7.0 .TP .B reboot False Request a reboot if a new kernel is available. .TP .B at_time immediate Schedule the reboot at some point in the future. This argument is ignored if \fBreboot=False\fP\&. See \fI\%reboot()\fP for more details on this argument. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.upgrade salt \(aq*\(aq kernelpkg.upgrade reboot=True at_time=1 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 An immediate reboot often shuts down the system before the minion has a chance to return, resulting in errors. A minimal delay (1 minute) is useful to ensure the result is delivered to the master. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kernelpkg_linux_yum.upgrade_available() Detect if a new kernel version is available in the repositories. Returns True if a new kernel is available, False otherwise. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kernelpkg.upgrade_available .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.key .sp Functions to view the minion\(aqs public key information .INDENT 0.0 .TP .B salt.modules.key.finger(hash_type=None) Return the minion\(aqs public key fingerprint .INDENT 7.0 .TP .B hash_type The hash algorithm used to calculate the fingerprint .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq key.finger .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.key.finger_master(hash_type=None) Return the fingerprint of the master\(aqs public key on the minion. .INDENT 7.0 .TP .B hash_type The hash algorithm used to calculate the fingerprint .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq key.finger_master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.keyboard .sp Module for managing keyboards on supported POSIX\-like systems using systemd, or such as Redhat, Debian and Gentoo. .INDENT 0.0 .TP .B salt.modules.keyboard.get_sys() Get current system keyboard setting .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keyboard.get_sys .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keyboard.get_x() Get current X keyboard setting .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keyboard.get_x .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keyboard.set_sys(layout) Set current system keyboard setting .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keyboard.set_sys dvorak .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keyboard.set_x(layout) Set current X keyboard setting .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keyboard.set_x dvorak .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.keystone .sp Module for handling openstack keystone calls. .INDENT 0.0 .TP .B optdepends .INDENT 7.0 .IP \(bu 2 keystoneclient Python adapter .UNINDENT .TP .B configuration This module is not usable until the following are specified either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C keystone.user: admin keystone.password: verybadpass keystone.tenant: admin keystone.tenant_id: f80919baedab48ec8931f200c65a50df keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq keystone.verify_ssl: True .ft P .fi .UNINDENT .UNINDENT .sp OR (for token based authentication) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C keystone.token: \(aqADMIN\(aq keystone.endpoint: \(aqhttp://127.0.0.1:35357/v2.0\(aq .ft P .fi .UNINDENT .UNINDENT .sp If configuration for multiple openstack accounts is required, they can be set up as different configuration profiles. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C openstack1: keystone.user: admin keystone.password: verybadpass keystone.tenant: admin keystone.tenant_id: f80919baedab48ec8931f200c65a50df keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq keystone.verify_ssl: True openstack2: keystone.user: admin keystone.password: verybadpass keystone.tenant: admin keystone.tenant_id: f80919baedab48ec8931f200c65a50df keystone.auth_url: \(aqhttp://127.0.0.2:5000/v2.0/\(aq keystone.verify_ssl: True .ft P .fi .UNINDENT .UNINDENT .sp With this configuration in place, any of the keystone functions can make use of a configuration profile by declaring it explicitly. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.tenant_list profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.api_version(profile=None, **connection_args) Returns the API version derived from endpoint\(aqs response. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.api_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.auth(profile=None, **connection_args) Set up keystone credentials. Only intended to be used within Keystone\-enabled modules. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.auth .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.ec2_credentials_create(user_id=None, name=None, tenant_id=None, tenant=None, profile=None, **connection_args) Create EC2\-compatible credentials for user per tenant .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.ec2_credentials_create name=admin tenant=admin salt \(aq*\(aq keystone.ec2_credentials_create user_id=c965f79c4f864eaaa9c3b41904e67082 tenant_id=722787eb540849158668370dc627ec5f .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.ec2_credentials_delete(user_id=None, name=None, access_key=None, profile=None, **connection_args) Delete EC2\-compatible credentials .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.ec2_credentials_delete 860f8c2c38ca4fab989f9bc56a061a64 access_key=5f66d2f24f604b8bb9cd28886106f442 salt \(aq*\(aq keystone.ec2_credentials_delete name=admin access_key=5f66d2f24f604b8bb9cd28886106f442 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.ec2_credentials_get(user_id=None, name=None, access=None, profile=None, **connection_args) Return ec2_credentials for a user (keystone ec2\-credentials\-get) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.ec2_credentials_get c965f79c4f864eaaa9c3b41904e67082 access=722787eb540849158668370 salt \(aq*\(aq keystone.ec2_credentials_get user_id=c965f79c4f864eaaa9c3b41904e67082 access=722787eb540849158668370 salt \(aq*\(aq keystone.ec2_credentials_get name=nova access=722787eb540849158668370dc627ec5f .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.ec2_credentials_list(user_id=None, name=None, profile=None, **connection_args) Return a list of ec2_credentials for a specific user (keystone ec2\-credentials\-list) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.ec2_credentials_list 298ce377245c4ec9b70e1c639c89e654 salt \(aq*\(aq keystone.ec2_credentials_list user_id=298ce377245c4ec9b70e1c639c89e654 salt \(aq*\(aq keystone.ec2_credentials_list name=jack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.endpoint_create(service, publicurl=None, internalurl=None, adminurl=None, region=None, profile=None, url=None, interface=None, **connection_args) Create an endpoint for an Openstack service .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqv2\(aq keystone.endpoint_create nova \(aqhttp://public/url\(aq \(aqhttp://internal/url\(aq \(aqhttp://adminurl/url\(aq region salt \(aqv3\(aq keystone.endpoint_create nova url=\(aqhttp://public/url\(aq interface=\(aqpublic\(aq region=\(aqRegionOne\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.endpoint_delete(service, region=None, profile=None, interface=None, **connection_args) Delete endpoints of an Openstack service .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqv2\(aq keystone.endpoint_delete nova [region=RegionOne] salt \(aqv3\(aq keystone.endpoint_delete nova interface=admin [region=RegionOne] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.endpoint_get(service, region=None, profile=None, interface=None, **connection_args) Return a specific endpoint (keystone endpoint\-get) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqv2\(aq keystone.endpoint_get nova [region=RegionOne] salt \(aqv3\(aq keystone.endpoint_get nova interface=admin [region=RegionOne] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.endpoint_list(profile=None, **connection_args) Return a list of available endpoints (keystone endpoints\-list) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.endpoint_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.project_create(name, domain, description=None, enabled=True, profile=None, **connection_args) Create a keystone project. Overrides keystone tenant_create form api V2. For keystone api V3. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B name The project name, which must be unique within the owning domain. .TP .B domain The domain name. .TP .B description The project description. .TP .B enabled Enables or disables the project. .TP .B profile Configuration profile \- if configuration for multiple openstack accounts required. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.project_create nova default description=\(aqNova Compute Project\(aq salt \(aq*\(aq keystone.project_create test default enabled=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.project_delete(project_id=None, name=None, profile=None, **connection_args) Delete a project (keystone project\-delete). Overrides keystone tenant\-delete form api V2. For keystone api V3 only. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B project_id The project id. .TP .B name The project name. .TP .B profile Configuration profile \- if configuration for multiple openstack accounts required. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.project_delete c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.project_delete project_id=c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.project_delete name=demo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.project_get(project_id=None, name=None, profile=None, **connection_args) Return a specific projects (keystone project\-get) Overrides keystone tenant\-get form api V2. For keystone api V3 only. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B project_id The project id. .TP .B name The project name. .TP .B profile Configuration profile \- if configuration for multiple openstack accounts required. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.project_get c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.project_get project_id=c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.project_get name=nova .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.project_list(profile=None, **connection_args) Return a list of available projects (keystone projects\-list). Overrides keystone tenants\-list form api V2. For keystone api V3 only. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B profile Configuration profile \- if configuration for multiple openstack accounts required. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.project_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.project_update(project_id=None, name=None, description=None, enabled=None, profile=None, **connection_args) Update a tenant\(aqs information (keystone project\-update) The following fields may be updated: name, description, enabled. Can only update name if targeting by ID .sp Overrides keystone tenant_update form api V2. For keystone api V3 only. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B project_id The project id. .TP .B name The project name, which must be unique within the owning domain. .TP .B description The project description. .TP .B enabled Enables or disables the project. .TP .B profile Configuration profile \- if configuration for multiple openstack accounts required. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.project_update name=admin enabled=True salt \(aq*\(aq keystone.project_update c965f79c4f864eaaa9c3b41904e67082 name=admin email=admin@domain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.role_create(name, profile=None, **connection_args) Create a named role. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.role_create admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.role_delete(role_id=None, name=None, profile=None, **connection_args) Delete a role (keystone role\-delete) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.role_delete c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.role_delete role_id=c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.role_delete name=admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.role_get(role_id=None, name=None, profile=None, **connection_args) Return a specific roles (keystone role\-get) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.role_get c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.role_get role_id=c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.role_get name=nova .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.role_list(profile=None, **connection_args) Return a list of available roles (keystone role\-list) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.role_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.service_create(name, service_type, description=None, profile=None, **connection_args) Add service to Keystone service catalog .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.service_create nova compute \(aqOpenStack Compute Service\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.service_delete(service_id=None, name=None, profile=None, **connection_args) Delete a service from Keystone service catalog .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.service_delete c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.service_delete name=nova .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.service_get(service_id=None, name=None, profile=None, **connection_args) Return a specific services (keystone service\-get) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.service_get c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.service_get service_id=c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.service_get name=nova .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.service_list(profile=None, **connection_args) Return a list of available services (keystone services\-list) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.service_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.tenant_create(name, description=None, enabled=True, profile=None, **connection_args) Create a keystone tenant .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.tenant_create nova description=\(aqnova tenant\(aq salt \(aq*\(aq keystone.tenant_create test enabled=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.tenant_delete(tenant_id=None, name=None, profile=None, **connection_args) Delete a tenant (keystone tenant\-delete) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.tenant_delete c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.tenant_delete tenant_id=c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.tenant_delete name=demo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.tenant_get(tenant_id=None, name=None, profile=None, **connection_args) Return a specific tenants (keystone tenant\-get) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.tenant_get c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.tenant_get tenant_id=c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.tenant_get name=nova .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.tenant_list(profile=None, **connection_args) Return a list of available tenants (keystone tenants\-list) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.tenant_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.tenant_update(tenant_id=None, name=None, description=None, enabled=None, profile=None, **connection_args) Update a tenant\(aqs information (keystone tenant\-update) The following fields may be updated: name, description, enabled. Can only update name if targeting by ID .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.tenant_update name=admin enabled=True salt \(aq*\(aq keystone.tenant_update c965f79c4f864eaaa9c3b41904e67082 name=admin email=admin@domain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.token_get(profile=None, **connection_args) Return the configured tokens (keystone token\-get) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.token_get c965f79c4f864eaaa9c3b41904e67082 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.user_create(name, password, email, tenant_id=None, enabled=True, profile=None, project_id=None, description=None, **connection_args) Create a user (keystone user\-create) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.user_create name=jack password=zero email=jack@halloweentown.org tenant_id=a28a7b5a999a455f84b1f5210264375e enabled=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.user_delete(user_id=None, name=None, profile=None, **connection_args) Delete a user (keystone user\-delete) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.user_delete c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.user_delete user_id=c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.user_delete name=nova .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.user_get(user_id=None, name=None, profile=None, **connection_args) Return a specific users (keystone user\-get) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.user_get c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.user_get user_id=c965f79c4f864eaaa9c3b41904e67082 salt \(aq*\(aq keystone.user_get name=nova .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.user_list(profile=None, **connection_args) Return a list of available users (keystone user\-list) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.user_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.user_password_update(user_id=None, name=None, password=None, profile=None, **connection_args) Update a user\(aqs password (keystone user\-password\-update) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.user_password_update c965f79c4f864eaaa9c3b41904e67082 password=12345 salt \(aq*\(aq keystone.user_password_update user_id=c965f79c4f864eaaa9c3b41904e67082 password=12345 salt \(aq*\(aq keystone.user_password_update name=nova password=12345 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.user_role_add(user_id=None, user=None, tenant_id=None, tenant=None, role_id=None, role=None, profile=None, project_id=None, project_name=None, **connection_args) Add role for user in tenant (keystone user\-role\-add) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.user_role_add user_id=298ce377245c4ec9b70e1c639c89e654 tenant_id=7167a092ece84bae8cead4bf9d15bb3b role_id=ce377245c4ec9b70e1c639c89e8cead4 salt \(aq*\(aq keystone.user_role_add user=admin tenant=admin role=admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.user_role_list(user_id=None, tenant_id=None, user_name=None, tenant_name=None, profile=None, project_id=None, project_name=None, **connection_args) Return a list of available user_roles (keystone user\-roles\-list) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.user_role_list user_id=298ce377245c4ec9b70e1c639c89e654 tenant_id=7167a092ece84bae8cead4bf9d15bb3b salt \(aq*\(aq keystone.user_role_list user_name=admin tenant_name=admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.user_role_remove(user_id=None, user=None, tenant_id=None, tenant=None, role_id=None, role=None, profile=None, project_id=None, project_name=None, **connection_args) Remove role for user in tenant (keystone user\-role\-remove) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.user_role_remove user_id=298ce377245c4ec9b70e1c639c89e654 tenant_id=7167a092ece84bae8cead4bf9d15bb3b role_id=ce377245c4ec9b70e1c639c89e8cead4 salt \(aq*\(aq keystone.user_role_remove user=admin tenant=admin role=admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.user_update(user_id=None, name=None, email=None, enabled=None, tenant=None, profile=None, project=None, description=None, **connection_args) Update a user\(aqs information (keystone user\-update) The following fields may be updated: name, email, enabled, tenant. Because the name is one of the fields, a valid user id is required. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.user_update user_id=c965f79c4f864eaaa9c3b41904e67082 name=newname salt \(aq*\(aq keystone.user_update c965f79c4f864eaaa9c3b41904e67082 name=newname email=newemail@domain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystone.user_verify_password(user_id=None, name=None, password=None, profile=None, **connection_args) Verify a user\(aqs password .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystone.user_verify_password name=test password=foobar salt \(aq*\(aq keystone.user_verify_password user_id=c965f79c4f864eaaa9c3b41904e67082 password=foobar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.keystoneng .sp Keystone module for interacting with OpenStack Keystone .sp New in version 2018.3.0. .sp :depends:shade .sp Example configuration .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keystone: cloud: default .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keystone: auth: username: admin password: password123 user_domain_name: mydomain project_name: myproject project_domain_name: myproject auth_url: https://example.org:5000/v3 identity_api_version: 3 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.compare_changes(obj, **kwargs) Compare two dicts returning only keys that exist in the first dict and are different in the second one .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.domain_create(auth=None, **kwargs) Create a domain .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.domain_create name=domain1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.domain_delete(auth=None, **kwargs) Delete a domain .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.domain_delete name=domain1 salt \(aq*\(aq keystoneng.domain_delete name=b62e76fbeeff4e8fb77073f591cf211e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.domain_get(auth=None, **kwargs) Get a single domain .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.domain_get name=domain1 salt \(aq*\(aq keystoneng.domain_get name=b62e76fbeeff4e8fb77073f591cf211e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.domain_list(auth=None, **kwargs) List domains .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.domain_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.domain_search(auth=None, **kwargs) Search domains .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.domain_search salt \(aq*\(aq keystoneng.domain_search name=domain1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.domain_update(auth=None, **kwargs) Update a domain .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.domain_update name=domain1 new_name=newdomain salt \(aq*\(aq keystoneng.domain_update name=domain1 enabled=True description=\(aqnew description\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.endpoint_create(auth=None, **kwargs) Create an endpoint .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.endpoint_create interface=admin service=glance url=https://example.org:9292 salt \(aq*\(aq keystoneng.endpoint_create interface=public service=glance region=RegionOne url=https://example.org:9292 salt \(aq*\(aq keystoneng.endpoint_create interface=admin service=glance url=https://example.org:9292 enabled=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.endpoint_delete(auth=None, **kwargs) Delete an endpoint .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.endpoint_delete id=3bee4bd8c2b040ee966adfda1f0bfca9 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.endpoint_get(auth=None, **kwargs) Get a single endpoint .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.endpoint_get id=02cffaa173b2460f98e40eda3748dae5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.endpoint_list(auth=None, **kwargs) List endpoints .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.endpoint_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.endpoint_search(auth=None, **kwargs) Search endpoints .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.endpoint_search salt \(aq*\(aq keystoneng.endpoint_search id=02cffaa173b2460f98e40eda3748dae5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.endpoint_update(auth=None, **kwargs) Update an endpoint .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.endpoint_update endpoint_id=4f961ad09d2d48948896bbe7c6a79717 interface=public enabled=False salt \(aq*\(aq keystoneng.endpoint_update endpoint_id=4f961ad09d2d48948896bbe7c6a79717 region=newregion salt \(aq*\(aq keystoneng.endpoint_update endpoint_id=4f961ad09d2d48948896bbe7c6a79717 service_name_or_id=glance url=https://example.org:9292 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.get_entity(ent_type, **kwargs) Attempt to query Keystone for more information about an entity .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.get_openstack_cloud(auth=None) Return an openstack_cloud .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.get_operator_cloud(auth=None) Return an operator_cloud .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.group_create(auth=None, **kwargs) Create a group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.group_create name=group1 salt \(aq*\(aq keystoneng.group_create name=group2 domain=domain1 description=\(aqmy group2\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.group_delete(auth=None, **kwargs) Delete a group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.group_delete name=group1 salt \(aq*\(aq keystoneng.group_delete name=group2 domain_id=b62e76fbeeff4e8fb77073f591cf211e salt \(aq*\(aq keystoneng.group_delete name=0e4febc2a5ab4f2c8f374b054162506d .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.group_get(auth=None, **kwargs) Get a single group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.group_get name=group1 salt \(aq*\(aq keystoneng.group_get name=group2 domain_id=b62e76fbeeff4e8fb77073f591cf211e salt \(aq*\(aq keystoneng.group_get name=0e4febc2a5ab4f2c8f374b054162506d .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.group_list(auth=None, **kwargs) List groups .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.group_list salt \(aq*\(aq keystoneng.group_list domain_id=b62e76fbeeff4e8fb77073f591cf211e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.group_search(auth=None, **kwargs) Search for groups .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.group_search name=group1 salt \(aq*\(aq keystoneng.group_search domain_id=b62e76fbeeff4e8fb77073f591cf211e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.group_update(auth=None, **kwargs) Update a group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.group_update name=group1 description=\(aqnew description\(aq salt \(aq*\(aq keystoneng.group_create name=group2 domain_id=b62e76fbeeff4e8fb77073f591cf211e new_name=newgroupname salt \(aq*\(aq keystoneng.group_create name=0e4febc2a5ab4f2c8f374b054162506d new_name=newgroupname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.project_create(auth=None, **kwargs) Create a project .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.project_create name=project1 salt \(aq*\(aq keystoneng.project_create name=project2 domain_id=b62e76fbeeff4e8fb77073f591cf211e salt \(aq*\(aq keystoneng.project_create name=project3 enabled=False description=\(aqmy project3\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.project_delete(auth=None, **kwargs) Delete a project .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.project_delete name=project1 salt \(aq*\(aq keystoneng.project_delete name=project2 domain_id=b62e76fbeeff4e8fb77073f591cf211e salt \(aq*\(aq keystoneng.project_delete name=f315afcf12f24ad88c92b936c38f2d5a .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.project_get(auth=None, **kwargs) Get a single project .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.project_get name=project1 salt \(aq*\(aq keystoneng.project_get name=project2 domain_id=b62e76fbeeff4e8fb77073f591cf211e salt \(aq*\(aq keystoneng.project_get name=f315afcf12f24ad88c92b936c38f2d5a .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.project_list(auth=None, **kwargs) List projects .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.project_list salt \(aq*\(aq keystoneng.project_list domain_id=b62e76fbeeff4e8fb77073f591cf211e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.project_search(auth=None, **kwargs) Search projects .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.project_search salt \(aq*\(aq keystoneng.project_search name=project1 salt \(aq*\(aq keystoneng.project_search domain_id=b62e76fbeeff4e8fb77073f591cf211e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.project_update(auth=None, **kwargs) Update a project .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.project_update name=project1 new_name=newproject salt \(aq*\(aq keystoneng.project_update name=project2 enabled=False description=\(aqnew description\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.role_assignment_list(auth=None, **kwargs) List role assignments .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.role_assignment_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.role_create(auth=None, **kwargs) Create a role .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.role_create name=role1 salt \(aq*\(aq keystoneng.role_create name=role1 domain_id=b62e76fbeeff4e8fb77073f591cf211e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.role_delete(auth=None, **kwargs) Delete a role .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.role_delete name=role1 domain_id=b62e76fbeeff4e8fb77073f591cf211e salt \(aq*\(aq keystoneng.role_delete name=1eb6edd5525e4ac39af571adee673559 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.role_get(auth=None, **kwargs) Get a single role .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.role_get name=role1 salt \(aq*\(aq keystoneng.role_get name=role1 domain_id=b62e76fbeeff4e8fb77073f591cf211e salt \(aq*\(aq keystoneng.role_get name=1eb6edd5525e4ac39af571adee673559 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.role_grant(auth=None, **kwargs) Grant a role in a project/domain to a user/group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.role_grant name=role1 user=user1 project=project1 salt \(aq*\(aq keystoneng.role_grant name=ddbe3e0ed74e4c7f8027bad4af03339d group=user1 project=project1 domain=domain1 salt \(aq*\(aq keystoneng.role_grant name=ddbe3e0ed74e4c7f8027bad4af03339d group=19573afd5e4241d8b65c42215bae9704 project=1dcac318a83b4610b7a7f7ba01465548 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.role_list(auth=None, **kwargs) List roles .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.role_list salt \(aq*\(aq keystoneng.role_list domain_id=b62e76fbeeff4e8fb77073f591cf211e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.role_revoke(auth=None, **kwargs) Grant a role in a project/domain to a user/group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.role_revoke name=role1 user=user1 project=project1 salt \(aq*\(aq keystoneng.role_revoke name=ddbe3e0ed74e4c7f8027bad4af03339d group=user1 project=project1 domain=domain1 salt \(aq*\(aq keystoneng.role_revoke name=ddbe3e0ed74e4c7f8027bad4af03339d group=19573afd5e4241d8b65c42215bae9704 project=1dcac318a83b4610b7a7f7ba01465548 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.role_search(auth=None, **kwargs) Search roles .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.role_search salt \(aq*\(aq keystoneng.role_search name=role1 salt \(aq*\(aq keystoneng.role_search domain_id=b62e76fbeeff4e8fb77073f591cf211e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.role_update(auth=None, **kwargs) Update a role .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.role_update name=role1 new_name=newrole salt \(aq*\(aq keystoneng.role_update name=1eb6edd5525e4ac39af571adee673559 new_name=newrole .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.service_create(auth=None, **kwargs) Create a service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.service_create name=glance type=image salt \(aq*\(aq keystoneng.service_create name=glance type=image description=\(dqImage\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.service_delete(auth=None, **kwargs) Delete a service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.service_delete name=glance salt \(aq*\(aq keystoneng.service_delete name=39cc1327cdf744ab815331554430e8ec .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.service_get(auth=None, **kwargs) Get a single service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.service_get name=glance salt \(aq*\(aq keystoneng.service_get name=75a5804638944b3ab54f7fbfcec2305a .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.service_list(auth=None, **kwargs) List services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.service_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.service_search(auth=None, **kwargs) Search services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.service_search salt \(aq*\(aq keystoneng.service_search name=glance salt \(aq*\(aq keystoneng.service_search name=135f0403f8e544dc9008c6739ecda860 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.service_update(auth=None, **kwargs) Update a service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.service_update name=cinder type=volumev2 salt \(aq*\(aq keystoneng.service_update name=cinder description=\(aqnew description\(aq salt \(aq*\(aq keystoneng.service_update name=ab4d35e269f147b3ae2d849f77f5c88f enabled=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.setup_clouds(auth=None) Call functions to create Shade cloud objects in __context__ to take advantage of Shade\(aqs in\-memory caching across several states .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.user_create(auth=None, **kwargs) Create a user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.user_create name=user1 salt \(aq*\(aq keystoneng.user_create name=user2 password=1234 enabled=False salt \(aq*\(aq keystoneng.user_create name=user3 domain_id=b62e76fbeeff4e8fb77073f591cf211e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.user_delete(auth=None, **kwargs) Delete a user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.user_delete name=user1 salt \(aq*\(aq keystoneng.user_delete name=user2 domain_id=b62e76fbeeff4e8fb77073f591cf211e salt \(aq*\(aq keystoneng.user_delete name=a42cbbfa1e894e839fd0f584d22e321f .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.user_get(auth=None, **kwargs) Get a single user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.user_get name=user1 salt \(aq*\(aq keystoneng.user_get name=user1 domain_id=b62e76fbeeff4e8fb77073f591cf211e salt \(aq*\(aq keystoneng.user_get name=02cffaa173b2460f98e40eda3748dae5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.user_list(auth=None, **kwargs) List users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.user_list salt \(aq*\(aq keystoneng.user_list domain_id=b62e76fbeeff4e8fb77073f591cf211e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.user_search(auth=None, **kwargs) List users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.user_list salt \(aq*\(aq keystoneng.user_list domain_id=b62e76fbeeff4e8fb77073f591cf211e .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystoneng.user_update(auth=None, **kwargs) Update a user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystoneng.user_update name=user1 enabled=False description=\(aqnew description\(aq salt \(aq*\(aq keystoneng.user_update name=user1 new_name=newuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.keystore .sp Module to interact with keystores .INDENT 0.0 .TP .B salt.modules.keystore.add(name, keystore, passphrase, certificate, private_key=None) Adds certificates to an existing keystore or creates a new one if necesssary. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- alias for the certificate .IP \(bu 2 \fBkeystore\fP \-\- The path to the keystore file to query .IP \(bu 2 \fBpassphrase\fP \-\- The passphrase to use to decode the keystore .IP \(bu 2 \fBcertificate\fP \-\- The PEM public certificate to add to keystore. Can be a string for file. .IP \(bu 2 \fBprivate_key\fP \-\- (Optional for TrustedCert) The PEM private key to add to the keystore .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystore.add aliasname /tmp/test.store changeit /tmp/testcert.crt salt \(aq*\(aq keystore.add aliasname /tmp/test.store changeit certificate=\(dq\-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\-SIb...BM=\-\-\-\-\-END CERTIFICATE\-\-\-\-\-\(dq salt \(aq*\(aq keystore.add keyname /tmp/test.store changeit /tmp/512.cert private_key=/tmp/512.key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystore.get_sha1(certificate) Returns the SHA1 sum of a ASN1/PEM certificate .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- ASN1/PEM certificate .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystore.get_sha1 \(dq(certificate_content_string)\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystore.list(keystore, passphrase, alias=None, return_cert=False) Lists certificates in a keytool managed keystore. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkeystore\fP \-\- The path to the keystore file to query .IP \(bu 2 \fBpassphrase\fP \-\- The passphrase to use to decode the keystore .IP \(bu 2 \fBalias\fP \-\- (Optional) If found, displays details on only this key .IP \(bu 2 \fBreturn_certs\fP \-\- (Optional) Also return certificate PEM. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 There are security implications for using return_cert to return decrypted certificates. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystore.list /usr/lib/jvm/java\-8/jre/lib/security/cacerts changeit salt \(aq*\(aq keystore.list /usr/lib/jvm/java\-8/jre/lib/security/cacerts changeit debian:verisign_\-_g5.pem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.keystore.remove(name, keystore, passphrase) Removes a certificate from an existing keystore. Returns True if remove was successful, otherwise False .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- alias for the certificate .IP \(bu 2 \fBkeystore\fP \-\- The path to the keystore file to query .IP \(bu 2 \fBpassphrase\fP \-\- The passphrase to use to decode the keystore .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keystore.remove aliasname /tmp/test.store changeit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.kmod .sp Module to manage Linux kernel modules .INDENT 0.0 .TP .B salt.modules.kmod.available() Return a list of all available kernel modules .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.available .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kmod.check_available(mod) Check to see if the specified kernel module is available .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.check_available kvm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kmod.is_loaded(mod) Check to see if the specified kernel module is loaded .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.is_loaded kvm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kmod.load(mod, persist=False) Load the specified kernel module .INDENT 7.0 .TP .B mod Name of module to add .TP .B persist Write module to /etc/modules to make it load on system reboot .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.load kvm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kmod.lsmod() Return a dict containing information about currently loaded modules .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.lsmod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kmod.mod_list(only_persist=False) Return a list of the loaded module names .INDENT 7.0 .TP .B only_persist Only return the list of loaded persistent modules .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.mod_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kmod.remove(mod, persist=False, comment=True) Remove the specified kernel module .INDENT 7.0 .TP .B mod Name of module to remove .TP .B persist Also remove module from /etc/modules .TP .B comment If persist is set don\(aqt remove line from /etc/modules but only comment it .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.remove kvm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.kubeadm .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%kubernetes Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Module for kubeadm :maintainer: Alberto Planas <\fI\%aplanas@suse.com\fP> :maturity: new :depends: None :platform: Linux .INDENT 0.0 .TP .B salt.modules.kubeadm.alpha_certs_renew(rootfs=None) New in version 3001. .sp Renews certificates for a Kubernetes cluster .INDENT 7.0 .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.alpha_certs_renew .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.alpha_kubeconfig_user(client_name, apiserver_advertise_address=None, apiserver_bind_port=None, cert_dir=None, org=None, token=None, rootfs=None) New in version 3001. .sp Outputs a kubeconfig file for an additional user .INDENT 7.0 .TP .B client_name The name of the user. It will be used as the CN if client certificates are created .TP .B apiserver_advertise_address The IP address the API server is accessible on .TP .B apiserver_bind_port The port the API server is accessible on (default 6443) .TP .B cert_dir The path where certificates are stored (default \(dq/etc/kubernetes/pki\(dq) .TP .B org The organization of the client certificate .TP .B token The token that show be used as the authentication mechanism for this kubeconfig, instead of client certificates .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.alpha_kubeconfig_user client_name=user .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.alpha_kubelet_config_download(kubeconfig=None, kubelet_version=None, rootfs=None) New in version 3001. .sp Downloads the kubelet configuration from the cluster ConfigMap kubelet\-config\-1.X .INDENT 7.0 .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B kubelet_version The desired version for the kubelet .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.alpha_kubelet_config_download salt \(aq*\(aq kubeadm.alpha_kubelet_config_download kubelet_version=\(aq1.14.0\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.alpha_kubelet_config_enable_dynamic(node_name, kubeconfig=None, kubelet_version=None, rootfs=None) New in version 3001. .sp Enables or updates dynamic kubelet configuration for a node .INDENT 7.0 .TP .B node_name Name of the node that should enable the dynamic kubelet configuration .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B kubelet_version The desired version for the kubelet .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.alpha_kubelet_config_enable_dynamic node\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.alpha_selfhosting_pivot(cert_dir=None, config=None, kubeconfig=None, store_certs_in_secrets=False, rootfs=None) New in version 3001. .sp Converts a static Pod\-hosted control plane into a selt\-hosted one .INDENT 7.0 .TP .B cert_dir The path where certificates are stored (default \(dq/etc/kubernetes/pki\(dq) .TP .B config Path to kubeadm configuration file .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B store_certs_in_secrets Enable storing certs in secrets .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.alpha_selfhost_pivot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.config_images_list(config=None, feature_gates=None, kubernetes_version=None, kubeconfig=None, rootfs=None) New in version 3001. .sp Print a list of images kubeadm will use .INDENT 7.0 .TP .B config Path to kubeadm configuration file .TP .B feature_gates A set of key=value pairs that describe feature gates for various features .TP .B kubernetes_version Choose a specifig Kubernetes version for the control plane (default \(dqstable\-1\(dq) .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.config_images_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.config_images_pull(config=None, cri_socket=None, feature_gates=None, kubernetes_version=None, kubeconfig=None, rootfs=None) New in version 3001. .sp Pull images used by kubeadm .INDENT 7.0 .TP .B config Path to kubeadm configuration file .TP .B cri_socket Path to the CRI socket to connect .TP .B feature_gates A set of key=value pairs that describe feature gates for various features .TP .B kubernetes_version Choose a specifig Kubernetes version for the control plane (default \(dqstable\-1\(dq) .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.config_images_pull .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.config_migrate(old_config, new_config=None, kubeconfig=None, rootfs=None) New in version 3001. .sp Read an older version of the kubeadm configuration API types from a file, and output the similar config object for the newer version .INDENT 7.0 .TP .B old_config Path to the kubeadm config file that is usin the old API version and should be converted .TP .B new_config Path to the resulting equivalent kubeadm config file using the new API version. If not specified the output will be returned .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.config_migrate /oldconfig.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.config_print_init_defaults(component_configs=None, kubeconfig=None, rootfs=None) New in version 3001. .sp Return default init configuration, that can be used for \(aqkubeadm init\(aq .INDENT 7.0 .TP .B component_config A comma\-separated list for component config API object to print the default values for (valid values: KubeProxyConfiguration, KubeletConfiguration) .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.config_print_init_defaults .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.config_print_join_defaults(component_configs=None, kubeconfig=None, rootfs=None) New in version 3001. .sp Return default join configuration, that can be used for \(aqkubeadm join\(aq .INDENT 7.0 .TP .B component_config A comma\-separated list for component config API object to print the default values for (valid values: KubeProxyConfiguration, KubeletConfiguration) .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.config_print_join_defaults .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.config_upload_from_file(config, kubeconfig=None, rootfs=None) New in version 3001. .sp Upload a configuration file to the in\-cluster ConfigMap for kubeadm configuration .INDENT 7.0 .TP .B config Path to a kubeadm configuration file .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.config_upload_from_file /config.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.config_upload_from_flags(apiserver_advertise_address=None, apiserver_bind_port=None, apiserver_cert_extra_sans=None, cert_dir=None, cri_socket=None, feature_gates=None, kubernetes_version=None, node_name=None, pod_network_cidr=None, service_cidr=None, service_dns_domain=None, kubeconfig=None, rootfs=None) New in version 3001. .sp Create the in\-cluster configuration file for the first time using flags .INDENT 7.0 .TP .B apiserver_advertise_address The IP address the API server will advertise it\(aqs listening on .TP .B apiserver_bind_port The port the API server is accessible on (default 6443) .TP .B apiserver_cert_extra_sans Optional extra Subject Alternative Names (SANs) to use for the API Server serving certificate .TP .B cert_dir The path where to save and store the certificates (default \(dq/etc/kubernetes/pki\(dq) .TP .B cri_socket Path to the CRI socket to connect .TP .B feature_gates A set of key=value pairs that describe feature gates for various features .TP .B kubernetes_version Choose a specifig Kubernetes version for the control plane (default \(dqstable\-1\(dq) .TP .B node_name Specify the node name .TP .B pod_network_cidr Specify range of IP addresses for the pod network .TP .B service_cidr Use alternative range of IP address for service VIPs (default \(dq10.96.0.0/12\(dq) .TP .B service_dns_domain Use alternative domain for services (default \(dqcluster.local\(dq) .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.config_upload_from_flags .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.config_view(kubeconfig=None, rootfs=None) New in version 3001. .sp View the kubeadm configuration stored inside the cluster .INDENT 7.0 .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.config_view .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.init(apiserver_advertise_address=None, apiserver_bind_port=None, apiserver_cert_extra_sans=None, cert_dir=None, certificate_key=None, control_plane_endpoint=None, config=None, cri_socket=None, experimental_upload_certs=False, upload_certs=False, feature_gates=None, ignore_preflight_errors=None, image_repository=None, kubernetes_version=None, node_name=None, pod_network_cidr=None, service_cidr=None, service_dns_domain=None, skip_certificate_key_print=False, skip_phases=None, skip_token_print=False, token=None, token_ttl=None, rootfs=None) New in version 3001. .sp Command to set up the Kubernetes control plane .INDENT 7.0 .TP .B apiserver_advertise_address The IP address the API server will advertise it\(aqs listening on .TP .B apiserver_bind_port The port the API server is accessible on (default 6443) .TP .B apiserver_cert_extra_sans Optional extra Subject Alternative Names (SANs) to use for the API Server serving certificate .TP .B cert_dir The path where to save and store the certificates (default \(dq/etc/kubernetes/pki\(dq) .TP .B certificate_key Key used to encrypt the control\-plane certificates in the kubeadm\-certs Secret .TP .B config Path to a kubeadm configuration file .TP .B control_plane_endpoint Specify a stable IP address or DNS name for the control plane .TP .B cri_socket Path to the CRI socket to connect .TP .B experimental_upload_certs Upload control\-plane certificate to the kubeadm\-certs Secret. ( kubeadm version =< 1.16 ) .TP .B upload_certs Upload control\-plane certificate to the kubeadm\-certs Secret. ( kubeadm version > 1.16 ) .TP .B feature_gates A set of key=value pairs that describe feature gates for various features .TP .B ignore_preflight_errors A list of checks whose errors will be shown as warnings .TP .B image_repository Choose a container registry to pull control plane images from .TP .B kubernetes_version Choose a specifig Kubernetes version for the control plane (default \(dqstable\-1\(dq) .TP .B node_name Specify the node name .TP .B pod_network_cidr Specify range of IP addresses for the pod network .TP .B service_cidr Use alternative range of IP address for service VIPs (default \(dq10.96.0.0/12\(dq) .TP .B service_dns_domain Use alternative domain for services (default \(dqcluster.local\(dq) .TP .B skip_certificate_key_print Don\(aqt print the key used to encrypt the control\-plane certificates .TP .B skip_phases List of phases to be skipped .TP .B skip_token_print Skip printing of the default bootstrap token generated by \(aqkubeadm init\(aq .TP .B token The token to use for establishing bidirectional trust between nodes and control\-plane nodes. The token must match a regular expression, that by default is [a\-z0\-9]{6}.[a\-z0\-9]{16} .TP .B token_ttl The duration defore the token is automatically deleted (1s, 2m, 3h). If set to \(aq0\(aq the token will never expire. Default value is 24h0m0s .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.init pod_network_cidr=\(aq10.244.0.0/16\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.join(api_server_endpoint=None, apiserver_advertise_address=None, apiserver_bind_port=None, certificate_key=None, config=None, cri_socket=None, discovery_file=None, discovery_token=None, discovery_token_ca_cert_hash=None, discovery_token_unsafe_skip_ca_verification=False, experimental_control_plane=False, control_plane=False, ignore_preflight_errors=None, node_name=None, skip_phases=None, tls_bootstrap_token=None, token=None, rootfs=None) New in version 3001. .sp Command to join to an existing cluster .INDENT 7.0 .TP .B api_server_endpoint IP address or domain name and port of the API Server .TP .B apiserver_advertise_address If the node should host a new control plane instance, the IP address the API Server will advertise it\(aqs listening on .TP .B apiserver_bind_port If the node should host a new control plane instance, the port the API Server to bind to (default 6443) .TP .B certificate_key Use this key to decrypt the certificate secrets uploaded by init .TP .B config Path to a kubeadm configuration file .TP .B cri_socket Path to the CRI socket to connect .TP .B discovery_file For file\-based discovery, a file or URL from which to load cluster information .TP .B discovery_token For token\-based discovery, the token used to validate cluster information fetched from the API Server .TP .B discovery_token_ca_cert_hash For token\-based discovery, validate that the root CA public key matches this hash (format: \(dq<type>:<value>\(dq) .TP .B discovery_token_unsafe_skip_ca_verification For token\-based discovery, allow joining without \(aqdiscovery\-token\-ca\-cert\-hash\(aq pinning .TP .B experimental_control_plane Create a new control plane instance on this node (kubeadm version =< 1.16) .TP .B control_plane Create a new control plane instance on this node (kubeadm version > 1.16) .TP .B ignore_preflight_errors A list of checks whose errors will be shown as warnings .TP .B node_name Specify the node name .TP .B skip_phases List of phases to be skipped .TP .B tls_bootstrap_token Specify the token used to temporarily authenticate with the Kubernetes Control Plane while joining the node .TP .B token Use this token for both discovery\-token and tls\-bootstrap\-token when those values are not provided .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.join 10.160.65.165:6443 token=\(aqtoken\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.join_params(create_if_needed=False) New in version 3001. .sp Return the parameters required for joining into the cluster .INDENT 7.0 .TP .B create_if_needed If the token bucket is empty and this parameter is True, a new token will be created. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.join_params salt \(aq*\(aq kubeadm.join_params create_if_needed=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.reset(cert_dir=None, cri_socket=None, ignore_preflight_errors=None, kubeconfig=None, rootfs=None) New in version 3001. .sp Revert any changes made to this host by \(aqkubeadm init\(aq or \(aqkubeadm join\(aq .INDENT 7.0 .TP .B cert_dir The path to the directory where the certificates are stored (default \(dq/etc/kubernetes/pki\(dq) .TP .B cri_socket Path to the CRI socket to connect .TP .B ignore_preflight_errors A list of checks whose errors will be shown as warnings .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.join 10.160.65.165:6443 token=\(aqtoken\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.token_create(token=None, config=None, description=None, groups=None, ttl=None, usages=None, kubeconfig=None, rootfs=None) New in version 3001. .sp Create bootstrap tokens on the server .INDENT 7.0 .TP .B token Token to write, if None one will be generated. The token must match a regular expression, that by default is [a\-z0\-9]{6}.[a\-z0\-9]{16} .TP .B config Path to kubeadm configuration file .TP .B description A human friendly description of how this token is used .TP .B groups List of extra groups that this token will authenticate, default to [\(aqsystem:bootstrappers:kubeadm:default\-node\-token\(aq] .TP .B ttl The duration defore the token is automatically deleted (1s, 2m, 3h). If set to \(aq0\(aq the token will never expire. Default value is 24h0m0s .TP .B usages Describes the ways in which this token can be used. The default value is [\(aqsigning\(aq, \(aqauthentication\(aq] .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.token_create salt \(aq*\(aq kubeadm.token_create a1b2c.0123456789abcdef salt \(aq*\(aq kubeadm.token_create ttl=\(aq6h\(aq salt \(aq*\(aq kubeadm.token_create usages=\(dq[\(aqsigning\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.token_delete(token, kubeconfig=None, rootfs=None) New in version 3001. .sp Delete bootstrap tokens on the server .INDENT 7.0 .TP .B token Token to write, if None one will be generated. The token must match a regular expression, that by default is [a\-z0\-9]{6}.[a\-z0\-9]{16} .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.token_delete a1b2c salt \(aq*\(aq kubeadm.token_create a1b2c.0123456789abcdef .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.token_generate(kubeconfig=None, rootfs=None) New in version 3001. .sp Generate and return a bootstrap token, but do not create it on the server .INDENT 7.0 .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.token_generate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.token_list(kubeconfig=None, rootfs=None) New in version 3001. .sp List bootstrap tokens on the server .INDENT 7.0 .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.token_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubeadm.version(kubeconfig=None, rootfs=None) New in version 3001. .sp Return the version of kubeadm .INDENT 7.0 .TP .B kubeconfig The kubeconfig file to use when talking to the cluster. The default values in /etc/kubernetes/admin.conf .TP .B rootfs The path to the real host root filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubeadm.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.kubernetesmod .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%kubernetes Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Module for handling kubernetes calls. .INDENT 0.0 .TP .B optdepends .INDENT 7.0 .IP \(bu 2 kubernetes Python client < 4.0 .IP \(bu 2 PyYAML < 6.0 .UNINDENT .TP .B configuration The k8s API settings are provided either in a pillar, in the minion\(aqs config file, or in master\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C kubernetes.kubeconfig: \(aq/path/to/kubeconfig\(aq kubernetes.kubeconfig\-data: \(aq<base64 encoded kubeconfig content\(aq kubernetes.context: \(aqcontext\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp These settings can be overridden by adding \fIcontext and \(gakubeconfig\fP or \fIkubeconfig_data\fP parameters when calling a function. .sp The data format for \fIkubernetes.kubeconfig\-data\fP value is the content of \fIkubeconfig\fP base64 encoded in one line. .sp Only \fIkubeconfig\fP or \fIkubeconfig\-data\fP should be provided. In case both are provided \fIkubeconfig\fP entry is preferred. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.nodes kubeconfig=/etc/salt/k8s/kubeconfig context=minikube .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.0. .sp Changed in version 2019.2.0. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Configuration options changed in 2019.2.0. The following configuration options have been removed: .INDENT 0.0 .IP \(bu 2 kubernetes.user .IP \(bu 2 kubernetes.password .IP \(bu 2 kubernetes.api_url .IP \(bu 2 kubernetes.certificate\-authority\-data/file .IP \(bu 2 kubernetes.client\-certificate\-data/file .IP \(bu 2 kubernetes.client\-key\-data/file .UNINDENT .sp Please use now: .INDENT 0.0 .IP \(bu 2 kubernetes.kubeconfig or kubernetes.kubeconfig\-data .IP \(bu 2 kubernetes.context .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.configmaps(namespace=\(aqdefault\(aq, **kwargs) Return a list of kubernetes configmaps defined in the namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.configmaps salt \(aq*\(aq kubernetes.configmaps namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.create_configmap(name, namespace, data, source=None, template=None, saltenv=\(aqbase\(aq, **kwargs) Creates the kubernetes configmap as defined by the user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq kubernetes.create_configmap settings default \(aq{\(dqexample.conf\(dq: \(dq# example file\(dq}\(aq salt \(aqminion2\(aq kubernetes.create_configmap name=settings namespace=default data=\(aq{\(dqexample.conf\(dq: \(dq# example file\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.create_deployment(name, namespace, metadata, spec, source, template, saltenv, **kwargs) Creates the kubernetes deployment as defined by the user. .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.create_namespace(name, **kwargs) Creates a namespace with the specified name. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.create_namespace salt salt \(aq*\(aq kubernetes.create_namespace name=salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.create_pod(name, namespace, metadata, spec, source, template, saltenv, **kwargs) Creates the kubernetes deployment as defined by the user. .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.create_secret(name, namespace=\(aqdefault\(aq, data=None, source=None, template=None, saltenv=\(aqbase\(aq, **kwargs) Creates the kubernetes secret as defined by the user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq kubernetes.create_secret passwords default \(aq{\(dqdb\(dq: \(dqletmein\(dq}\(aq salt \(aqminion2\(aq kubernetes.create_secret name=passwords namespace=default data=\(aq{\(dqdb\(dq: \(dqletmein\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.create_service(name, namespace, metadata, spec, source, template, saltenv, **kwargs) Creates the kubernetes service as defined by the user. .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.delete_configmap(name, namespace=\(aqdefault\(aq, **kwargs) Deletes the kubernetes configmap defined by name and namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.delete_configmap settings default salt \(aq*\(aq kubernetes.delete_configmap name=settings namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.delete_deployment(name, namespace=\(aqdefault\(aq, **kwargs) Deletes the kubernetes deployment defined by name and namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.delete_deployment my\-nginx salt \(aq*\(aq kubernetes.delete_deployment name=my\-nginx namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.delete_namespace(name, **kwargs) Deletes the kubernetes namespace defined by name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.delete_namespace salt salt \(aq*\(aq kubernetes.delete_namespace name=salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.delete_pod(name, namespace=\(aqdefault\(aq, **kwargs) Deletes the kubernetes pod defined by name and namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.delete_pod guestbook\-708336848\-5nl8c default salt \(aq*\(aq kubernetes.delete_pod name=guestbook\-708336848\-5nl8c namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.delete_secret(name, namespace=\(aqdefault\(aq, **kwargs) Deletes the kubernetes secret defined by name and namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.delete_secret confidential default salt \(aq*\(aq kubernetes.delete_secret name=confidential namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.delete_service(name, namespace=\(aqdefault\(aq, **kwargs) Deletes the kubernetes service defined by name and namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.delete_service my\-nginx default salt \(aq*\(aq kubernetes.delete_service name=my\-nginx namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.deployments(namespace=\(aqdefault\(aq, **kwargs) Return a list of kubernetes deployments defined in the namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.deployments salt \(aq*\(aq kubernetes.deployments namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.namespaces(**kwargs) Return the names of the available namespaces .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.namespaces salt \(aq*\(aq kubernetes.namespaces kubeconfig=/etc/salt/k8s/kubeconfig context=minikube .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.node(name, **kwargs) Return the details of the node identified by the specified name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.node name=\(aqminikube\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.node_add_label(node_name, label_name, label_value, **kwargs) Set the value of the label identified by \fIlabel_name\fP to \fIlabel_value\fP on the node identified by the name \fInode_name\fP\&. Creates the label if not present. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.node_add_label node_name=\(dqminikube\(dq label_name=\(dqfoo\(dq label_value=\(dqbar\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.node_labels(name, **kwargs) Return the labels of the node identified by the specified name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.node_labels name=\(dqminikube\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.node_remove_label(node_name, label_name, **kwargs) Removes the label identified by \fIlabel_name\fP from the node identified by the name \fInode_name\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.node_remove_label node_name=\(dqminikube\(dq label_name=\(dqfoo\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.nodes(**kwargs) Return the names of the nodes composing the kubernetes cluster .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.nodes salt \(aq*\(aq kubernetes.nodes kubeconfig=/etc/salt/k8s/kubeconfig context=minikube .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.ping(**kwargs) Checks connections with the kubernetes API server. Returns True if the connection can be established, False otherwise. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.pods(namespace=\(aqdefault\(aq, **kwargs) Return a list of kubernetes pods defined in the namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.pods salt \(aq*\(aq kubernetes.pods namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.replace_configmap(name, data, source=None, template=None, saltenv=\(aqbase\(aq, namespace=\(aqdefault\(aq, **kwargs) Replaces an existing configmap with a new one defined by name and namespace with the specified data. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq kubernetes.replace_configmap settings default \(aq{\(dqexample.conf\(dq: \(dq# example file\(dq}\(aq salt \(aqminion2\(aq kubernetes.replace_configmap name=settings namespace=default data=\(aq{\(dqexample.conf\(dq: \(dq# example file\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.replace_deployment(name, metadata, spec, source, template, saltenv, namespace=\(aqdefault\(aq, **kwargs) Replaces an existing deployment with a new one defined by name and namespace, having the specificed metadata and spec. .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.replace_secret(name, data, source=None, template=None, saltenv=\(aqbase\(aq, namespace=\(aqdefault\(aq, **kwargs) Replaces an existing secret with a new one defined by name and namespace, having the specificed data. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion1\(aq kubernetes.replace_secret name=passwords data=\(aq{\(dqdb\(dq: \(dqletmein\(dq}\(aq salt \(aqminion2\(aq kubernetes.replace_secret name=passwords namespace=saltstack data=\(aq{\(dqdb\(dq: \(dqpassw0rd\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.replace_service(name, metadata, spec, source, template, old_service, saltenv, namespace=\(aqdefault\(aq, **kwargs) Replaces an existing service with a new one defined by name and namespace, having the specificed metadata and spec. .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.secrets(namespace=\(aqdefault\(aq, **kwargs) Return a list of kubernetes secrets defined in the namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.secrets salt \(aq*\(aq kubernetes.secrets namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.services(namespace=\(aqdefault\(aq, **kwargs) Return a list of kubernetes services defined in the namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.services salt \(aq*\(aq kubernetes.services namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.show_configmap(name, namespace=\(aqdefault\(aq, **kwargs) Return the kubernetes configmap defined by name and namespace. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.show_configmap game\-config default salt \(aq*\(aq kubernetes.show_configmap name=game\-config namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.show_deployment(name, namespace=\(aqdefault\(aq, **kwargs) Return the kubernetes deployment defined by name and namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.show_deployment my\-nginx default salt \(aq*\(aq kubernetes.show_deployment name=my\-nginx namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.show_namespace(name, **kwargs) Return information for a given namespace defined by the specified name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.show_namespace kube\-system .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.show_pod(name, namespace=\(aqdefault\(aq, **kwargs) Return POD information for a given pod name defined in the namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.show_pod guestbook\-708336848\-fqr2x salt \(aq*\(aq kubernetes.show_pod guestbook\-708336848\-fqr2x namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.show_secret(name, namespace=\(aqdefault\(aq, decode=False, **kwargs) Return the kubernetes secret defined by name and namespace. The secrets can be decoded if specified by the user. Warning: this has security implications. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.show_secret confidential default salt \(aq*\(aq kubernetes.show_secret name=confidential namespace=default salt \(aq*\(aq kubernetes.show_secret name=confidential decode=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kubernetesmod.show_service(name, namespace=\(aqdefault\(aq, **kwargs) Return the kubernetes service defined by name and namespace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kubernetes.show_service my\-nginx default salt \(aq*\(aq kubernetes.show_service name=my\-nginx namespace=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.launchctl_service .sp Module for the management of MacOS systems that use launchd/launchctl .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage services on a minion, and it is using a different module (or gives an error similar to \fI\(aqservice.start\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 plistlib Python module .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.launchctl_service.available(job_label) Check that the given service is available. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available com.openssh.sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.launchctl_service.disabled(job_label, runas=None) Return True if the named service is disabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service label> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.launchctl_service.enabled(job_label, runas=None) Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service label> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.launchctl_service.get_all() Return all installed services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.launchctl_service.missing(job_label) The inverse of service.available Check that the given service is not available. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing com.openssh.sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.launchctl_service.restart(job_label, runas=None) Restart the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service label> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.launchctl_service.start(job_label, runas=None) Start the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service label> salt \(aq*\(aq service.start org.ntp.ntpd salt \(aq*\(aq service.start /System/Library/LaunchDaemons/org.ntp.ntpd.plist .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.launchctl_service.status(name, runas=None) Return the status for a service via systemd. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.launchctl_service.stop(job_label, runas=None) Stop the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service label> salt \(aq*\(aq service.stop org.ntp.ntpd salt \(aq*\(aq service.stop /System/Library/LaunchDaemons/org.ntp.ntpd.plist .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.layman .sp Support for Layman .INDENT 0.0 .TP .B salt.modules.layman.add(overlay) Add the given overlay from the cached remote list to your locally installed overlays. Specify \(aqALL\(aq to add all overlays from the remote list. .sp Return a list of the new overlay(s) added: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq layman.add <overlay name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.layman.delete(overlay) Remove the given overlay from the your locally installed overlays. Specify \(aqALL\(aq to remove all overlays. .sp Return a list of the overlays(s) that were removed: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq layman.delete <overlay name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.layman.list_all() List all overlays, including remote ones. .sp Return a list of available overlays: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq layman.list_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.layman.list_local() List the locally installed overlays. .sp Return a list of installed overlays: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq layman.list_local .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.layman.sync(overlay=\(aqALL\(aq) Update the specified overlay. Use \(aqALL\(aq to synchronize all overlays. This is the default if no overlay is specified. .INDENT 7.0 .TP .B overlay Name of the overlay to sync. (Defaults to \(aqALL\(aq) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq layman.sync .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ldap3 .SS Query and modify an LDAP database (alternative interface) .sp New in version 2016.3.0. .sp This is an alternative to the \fBldap\fP interface provided by the \fI\%ldapmod\fP execution module. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 \fBldap\fP Python module .UNINDENT .UNINDENT .INDENT 0.0 .TP .B exception salt.modules.ldap3.LDAPError(message, cause=None) Base class of all LDAP exceptions raised by backends. .sp This is only used for errors encountered while interacting with the LDAP server; usage errors (e.g., invalid backend name) will have a different type. .INDENT 7.0 .TP .B Variables \fBcause\fP \-\- backend exception object, if applicable .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ldap3.add(connect_spec, dn, attributes) Add an entry to an LDAP database. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnect_spec\fP \-\- See the documentation for the \fBconnect_spec\fP parameter for \fI\%connect()\fP\&. .IP \(bu 2 \fBdn\fP \-\- Distinguished name of the entry. .IP \(bu 2 \fBattributes\fP \-\- Non\-empty dict mapping each of the new entry\(aqs attributes to a non\-empty iterable of values. .UNINDENT .TP .B Returns \fBTrue\fP if successful, raises an exception otherwise. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ldap3.add \(dq{ \(aqurl\(aq: \(aqldaps://ldap.example.com/\(aq, \(aqbind\(aq: { \(aqmethod\(aq: \(aqsimple\(aq, \(aqpassword\(aq: \(aqsecret\(aq, }, }\(dq \(dqdn=\(aqdc=example,dc=com\(aq\(dq \(dqattributes={\(aqexample\(aq: \(aqvalues\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ldap3.change(connect_spec, dn, before, after) Modify an entry in an LDAP database. .sp This does the same thing as \fI\%modify()\fP, but with a simpler interface. Instead of taking a list of directives, it takes a before and after view of an entry, determines the differences between the two, computes the directives, and executes them. .sp Any attribute value present in \fBbefore\fP but missing in \fBafter\fP is deleted. Any attribute value present in \fBafter\fP but missing in \fBbefore\fP is added. Any attribute value in the database that is not mentioned in either \fBbefore\fP or \fBafter\fP is not altered. Any attribute value that is present in both \fBbefore\fP and \fBafter\fP is ignored, regardless of whether that attribute value exists in the database. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnect_spec\fP \-\- See the documentation for the \fBconnect_spec\fP parameter for \fI\%connect()\fP\&. .IP \(bu 2 \fBdn\fP \-\- Distinguished name of the entry. .IP \(bu 2 \fBbefore\fP \-\- The expected state of the entry before modification. This is a dict mapping each attribute name to an iterable of values. .IP \(bu 2 \fBafter\fP \-\- The desired state of the entry after modification. This is a dict mapping each attribute name to an iterable of values. .UNINDENT .TP .B Returns \fBTrue\fP if successful, raises an exception otherwise. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ldap3.change \(dq{ \(aqurl\(aq: \(aqldaps://ldap.example.com/\(aq, \(aqbind\(aq: { \(aqmethod\(aq: \(aqsimple\(aq, \(aqpassword\(aq: \(aqsecret\(aq} }\(dq dn=\(aqcn=admin,dc=example,dc=com\(aq before=\(dq{\(aqexample_value\(aq: \(aqbefore_val\(aq}\(dq after=\(dq{\(aqexample_value\(aq: \(aqafter_val\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ldap3.connect(connect_spec=None) Connect and optionally bind to an LDAP server. .INDENT 7.0 .TP .B Parameters \fBconnect_spec\fP \-\- .sp This can be an LDAP connection object returned by a previous call to \fI\%connect()\fP (in which case the argument is simply returned), \fBNone\fP (in which case an empty dict is used), or a dict with the following keys: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqbackend\(aq\fP Optional; default depends on which Python LDAP modules are installed. Name of the Python LDAP module to use. Only \fB\(aqldap\(aq\fP is supported at the moment. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqurl\(aq\fP Optional; defaults to \fB\(aqldapi:///\(aq\fP\&. URL to the LDAP server. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqbind\(aq\fP Optional; defaults to \fBNone\fP\&. Describes how to bind an identity to the LDAP connection. If \fBNone\fP, an anonymous connection is made. Valid keys: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqmethod\(aq\fP Optional; defaults to \fBNone\fP\&. The authentication method to use. Valid values include but are not necessarily limited to \fB\(aqsimple\(aq\fP, \fB\(aqsasl\(aq\fP, and \fBNone\fP\&. If \fBNone\fP, an anonymous connection is made. Available methods depend on the chosen backend. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqmechanism\(aq\fP Optional; defaults to \fB\(aqEXTERNAL\(aq\fP\&. The SASL mechanism to use. Ignored unless the method is \fB\(aqsasl\(aq\fP\&. Available methods depend on the chosen backend and the server\(aqs capabilities. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqcredentials\(aq\fP Optional; defaults to \fBNone\fP\&. An object specific to the chosen SASL mechanism and backend that represents the authentication credentials. Ignored unless the method is \fB\(aqsasl\(aq\fP\&. .sp For the \fB\(aqldap\(aq\fP backend, this is a dictionary. If \fBNone\fP, an empty dict is used. Keys: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqargs\(aq\fP Optional; defaults to an empty list. A list of arguments to pass to the SASL mechanism constructor. See the SASL mechanism constructor documentation in the \fBldap.sasl\fP Python module. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqkwargs\(aq\fP Optional; defaults to an empty dict. A dict of keyword arguments to pass to the SASL mechanism constructor. See the SASL mechanism constructor documentation in the \fBldap.sasl\fP Python module. .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqdn\(aq\fP Optional; defaults to an empty string. The distinguished name to bind. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqpassword\(aq\fP Optional; defaults to an empty string. Password for binding. Ignored if the method is \fB\(aqsasl\(aq\fP\&. .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqtls\(aq\fP Optional; defaults to \fBNone\fP\&. A backend\-specific object containing settings to override default TLS behavior. .sp For the \fB\(aqldap\(aq\fP backend, this is a dictionary. Not all settings in this dictionary are supported by all versions of \fBpython\-ldap\fP or the underlying TLS library. If \fBNone\fP, an empty dict is used. Possible keys: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqstarttls\(aq\fP If present, initiate a TLS connection using StartTLS. (The value associated with this key is ignored.) .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqcacertdir\(aq\fP Set the path of the directory containing CA certificates. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqcacertfile\(aq\fP Set the pathname of the CA certificate file. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqcertfile\(aq\fP Set the pathname of the certificate file. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqcipher_suite\(aq\fP Set the allowed cipher suite. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqcrlcheck\(aq\fP Set the CRL evaluation strategy. Valid values are \fB\(aqnone\(aq\fP, \fB\(aqpeer\(aq\fP, and \fB\(aqall\(aq\fP\&. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqcrlfile\(aq\fP Set the pathname of the CRL file. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqdhfile\(aq\fP Set the pathname of the file containing the parameters for Diffie\-Hellman ephemeral key exchange. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqkeyfile\(aq\fP Set the pathname of the certificate key file. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqnewctx\(aq\fP If present, instruct the underlying TLS library to create a new TLS context. (The value associated with this key is ignored.) .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqprotocol_min\(aq\fP Set the minimum protocol version. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqrandom_file\(aq\fP Set the pathname of the random file when \fB/dev/random\fP and \fB/dev/urandom\fP are not available. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqrequire_cert\(aq\fP Set the certificate validation policy. Valid values are \fB\(aqnever\(aq\fP, \fB\(aqhard\(aq\fP, \fB\(aqdemand\(aq\fP, \fB\(aqallow\(aq\fP, and \fB\(aqtry\(aq\fP\&. .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqopts\(aq\fP Optional; defaults to \fBNone\fP\&. A backend\-specific object containing options for the backend. .sp For the \fB\(aqldap\(aq\fP backend, this is a dictionary of OpenLDAP options to set. If \fBNone\fP, an empty dict is used. Each key is a the name of an OpenLDAP option constant without the \fB\(aqLDAP_OPT_\(aq\fP prefix, then converted to lower case. .UNINDENT .UNINDENT .TP .B Returns an object representing an LDAP connection that can be used as the \fBconnect_spec\fP argument to any of the functions in this module (to avoid the overhead of making and terminating multiple connections). .sp This object should be used as a context manager. It is safe to nest \fBwith\fP statements. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ldap3.connect \(dq{ \(aqurl\(aq: \(aqldaps://ldap.example.com/\(aq, \(aqbind\(aq: { \(aqmethod\(aq: \(aqsimple\(aq, \(aqdn\(aq: \(aqcn=admin,dc=example,dc=com\(aq, \(aqpassword\(aq: \(aqsecret\(aq} }\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ldap3.delete(connect_spec, dn) Delete an entry from an LDAP database. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnect_spec\fP \-\- See the documentation for the \fBconnect_spec\fP parameter for \fI\%connect()\fP\&. .IP \(bu 2 \fBdn\fP \-\- Distinguished name of the entry. .UNINDENT .TP .B Returns \fBTrue\fP if successful, raises an exception otherwise. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ldap3.delete \(dq{ \(aqurl\(aq: \(aqldaps://ldap.example.com/\(aq, \(aqbind\(aq: { \(aqmethod\(aq: \(aqsimple\(aq, \(aqpassword\(aq: \(aqsecret\(aq} }\(dq dn=\(aqcn=admin,dc=example,dc=com\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ldap3.modify(connect_spec, dn, directives) Modify an entry in an LDAP database. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnect_spec\fP \-\- See the documentation for the \fBconnect_spec\fP parameter for \fI\%connect()\fP\&. .IP \(bu 2 \fBdn\fP \-\- Distinguished name of the entry. .IP \(bu 2 \fBdirectives\fP \-\- .sp Iterable of directives that indicate how to modify the entry. Each directive is a tuple of the form \fB(op, attr, vals)\fP, where: .INDENT 2.0 .IP \(bu 2 \fBop\fP identifies the modification operation to perform. One of: .INDENT 2.0 .IP \(bu 2 \fB\(aqadd\(aq\fP to add one or more values to the attribute .IP \(bu 2 \fB\(aqdelete\(aq\fP to delete some or all of the values from the attribute. If no values are specified with this operation, all of the attribute\(aqs values are deleted. Otherwise, only the named values are deleted. .IP \(bu 2 \fB\(aqreplace\(aq\fP to replace all of the attribute\(aqs values with zero or more new values .UNINDENT .IP \(bu 2 \fBattr\fP names the attribute to modify .IP \(bu 2 \fBvals\fP is an iterable of values to add or delete .UNINDENT .UNINDENT .TP .B Returns \fBTrue\fP if successful, raises an exception otherwise. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ldap3.modify \(dq{ \(aqurl\(aq: \(aqldaps://ldap.example.com/\(aq, \(aqbind\(aq: { \(aqmethod\(aq: \(aqsimple\(aq, \(aqpassword\(aq: \(aqsecret\(aq} }\(dq dn=\(aqcn=admin,dc=example,dc=com\(aq directives=\(dq(\(aqadd\(aq, \(aqexample\(aq, [\(aqexample_val\(aq])\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ldap3.search(connect_spec, base, scope=\(aqsubtree\(aq, filterstr=\(aq(objectClass=*)\(aq, attrlist=None, attrsonly=0) Search an LDAP database. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnect_spec\fP \-\- See the documentation for the \fBconnect_spec\fP parameter for \fI\%connect()\fP\&. .IP \(bu 2 \fBbase\fP \-\- Distinguished name of the entry at which to start the search. .IP \(bu 2 \fBscope\fP \-\- .sp One of the following: .INDENT 2.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqsubtree\(aq\fP Search the base and all of its descendants. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqbase\(aq\fP Search only the base itself. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqonelevel\(aq\fP Search only the base\(aqs immediate children. .UNINDENT .UNINDENT .IP \(bu 2 \fBfilterstr\fP \-\- String representation of the filter to apply in the search. .IP \(bu 2 \fBattrlist\fP \-\- Limit the returned attributes to those in the specified list. If \fBNone\fP, all attributes of each entry are returned. .IP \(bu 2 \fBattrsonly\fP \-\- If non\-zero, don\(aqt return any attribute values. .UNINDENT .TP .B Returns a dict of results. The dict is empty if there are no results. The dict maps each returned entry\(aqs distinguished name to a dict that maps each of the matching attribute names to a list of its values. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ldap3.search \(dq{ \(aqurl\(aq: \(aqldaps://ldap.example.com/\(aq, \(aqbind\(aq: { \(aqmethod\(aq: \(aqsimple\(aq, \(aqdn\(aq: \(aqcn=admin,dc=example,dc=com\(aq, \(aqpassword\(aq: \(aqsecret\(aq, }, }\(dq \(dqbase=\(aqdc=example,dc=com\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ldapmod .sp Salt interface to LDAP commands .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 ldap Python module .UNINDENT .TP .B configuration In order to connect to LDAP, certain configuration is required in the minion config on the LDAP server. The minimum configuration items that must be set are: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ldap.basedn: dc=acme,dc=com (example values, adjust to suit) .ft P .fi .UNINDENT .UNINDENT .sp If your LDAP server requires authentication then you must also set: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ldap.anonymous: False ldap.binddn: admin ldap.bindpw: password .ft P .fi .UNINDENT .UNINDENT .sp In addition, the following optional values may be set: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ldap.server: localhost (default=localhost, see warning below) ldap.port: 389 (default=389, standard port) ldap.tls: False (default=False, no TLS) ldap.no_verify: False (default=False, verify TLS) ldap.anonymous: True (default=True, bind anonymous) ldap.scope: 2 (default=2, ldap.SCOPE_SUBTREE) ldap.attrs: [saltAttr] (default=None, return all attributes) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 At the moment this module only recommends connection to LDAP services listening on \fBlocalhost\fP\&. This is deliberate to avoid the potentially dangerous situation of multiple minions sending identical update commands to the same LDAP server. It\(aqs easy enough to override this behavior, but badness may ensue \- you have been warned. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ldapmod.search(filter, dn=None, scope=None, attrs=None, **kwargs) Run an arbitrary LDAP query and return the results. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqldaphost\(aq ldap.search \(dqfilter=cn=myhost\(dq .ft P .fi .UNINDENT .UNINDENT .sp Return data: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqmyhost\(aq: {\(aqcount\(aq: 1, \(aqresults\(aq: [[\(aqcn=myhost,ou=hosts,o=acme,c=gb\(aq, {\(aqsaltKeyValue\(aq: [\(aqntpserver=ntp.acme.local\(aq, \(aqfoo=myfoo\(aq], \(aqsaltState\(aq: [\(aqfoo\(aq, \(aqbar\(aq]}]], \(aqtime\(aq: {\(aqhuman\(aq: \(aq1.2ms\(aq, \(aqraw\(aq: \(aq0.00123\(aq}}} .ft P .fi .UNINDENT .UNINDENT .sp Search and connection options can be overridden by specifying the relevant option as key=value pairs, for example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqldaphost\(aq ldap.search filter=cn=myhost dn=ou=hosts,o=acme,c=gb scope=1 attrs=\(aq\(aq server=\(aqlocalhost\(aq port=\(aq7393\(aq tls=True bindpw=\(aqssh\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.libcloud_compute .SS Apache Libcloud Compute Management .sp Connection module for Apache Libcloud Compute management for a full list of supported clouds, see \fI\%http://libcloud.readthedocs.io/en/latest/compute/supported_providers.html\fP .sp Clouds include Amazon EC2, Azure, Google GCE, VMware, OpenStack Nova .sp New in version 2018.3.0. .INDENT 0.0 .TP .B configuration This module uses a configuration profile for one or multiple cloud providers .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C libcloud_compute: profile_test1: driver: google key: service\-account@googlecloud.net secret: /path/to.key.json profile_test2: driver: arm key: 12345 secret: mysecret .ft P .fi .UNINDENT .UNINDENT .TP .B depends apache\-libcloud .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.attach_volume(node_id, volume_id, profile, device=None, **libcloud_kwargs) Attaches volume to node. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnode_id\fP (\fBstr\fP) \-\- Node ID to target .IP \(bu 2 \fBvolume_id\fP (\fBstr\fP) \-\- Volume ID from which to attach .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBdevice\fP (\fBstr\fP) \-\- Where the device is exposed, e.g. \(aq/dev/sdb\(aq .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs attach_volume method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.detach_volume vol1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.copy_image(source_region, image_id, name, profile, description=None, **libcloud_kwargs) Copies an image from a source region to the current region. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsource_region\fP (\fBstr\fP) \-\- Region to copy the node from. .IP \(bu 2 \fBimage_id\fP (\fBstr\fP) \-\- Image to copy. .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- name for new image. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBdescription\fP \-\- description for new image. .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs copy_image method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.copy_image us\-east1 image1 \(aqnew image\(aq profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.create_image(node_id, name, profile, description=None, **libcloud_kwargs) Create an image from a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnode_id\fP (\fBstr\fP) \-\- Node to run the task on. .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- name for new image. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBdescription\fP (\fBdescription\fP) \-\- description for new image. .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs create_image method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.create_image server1 my_image profile1 salt myminion libcloud_compute.create_image server1 my_image profile1 description=\(aqtest image\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.create_key_pair(name, profile, **libcloud_kwargs) Create a single key pair by name .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Name of the key pair to create. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs create_key_pair method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.create_key_pair pair1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.create_volume(size, name, profile, location_id=None, **libcloud_kwargs) Create a storage volume .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsize\fP (\fBint\fP) \-\- Size of volume in gigabytes (required) .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Name of the volume to be created .IP \(bu 2 \fBlocation_id\fP (\fBstr\fP) \-\- Which data center to create a volume in. If empty, undefined behavior will be selected. (optional) .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_volumes method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.create_volume 1000 vol1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.create_volume_snapshot(volume_id, profile, name=None, **libcloud_kwargs) Create a storage volume snapshot .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvolume_id\fP (\fBstr\fP) \-\- Volume ID from which to create the new snapshot. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Name of the snapshot to be created (optional) .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs create_volume_snapshot method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.create_volume_snapshot vol1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.delete_image(image_id, profile, **libcloud_kwargs) Delete an image of a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBimage_id\fP (\fBstr\fP) \-\- Image to delete .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs delete_image method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.delete_image image1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.delete_key_pair(name, profile, **libcloud_kwargs) Delete a key pair .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Key pair name. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs import_key_pair_from_xxx method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.delete_key_pair pair1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.destroy_node(node_id, profile, **libcloud_kwargs) Destroy a node in the cloud .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnode_id\fP (\fBstr\fP) \-\- Unique ID of the node to destroy .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs destroy_node method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.destry_node as\-2346 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.destroy_volume(volume_id, profile, **libcloud_kwargs) Destroy a volume. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvolume_id\fP (\fBstr\fP) \-\- Volume ID from which to destroy .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs destroy_volume method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.destroy_volume vol1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.destroy_volume_snapshot(volume_id, snapshot_id, profile, **libcloud_kwargs) Destroy a volume snapshot. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvolume_id\fP (\fBstr\fP) \-\- Volume ID from which the snapshot belongs .IP \(bu 2 \fBsnapshot_id\fP (\fBstr\fP) \-\- Volume Snapshot ID from which to destroy .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs destroy_volume_snapshot method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.destroy_volume_snapshot snap1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.detach_volume(volume_id, profile, **libcloud_kwargs) Detaches a volume from a node. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvolume_id\fP (\fBstr\fP) \-\- Volume ID from which to detach .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs detach_volume method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.detach_volume vol1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.extra(method, profile, **libcloud_kwargs) Call an extended method on the driver .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmethod\fP (\fBstr\fP) \-\- Driver\(aqs method name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.extra ex_get_permissions google container_name=my_container object_name=me.jpg \-\-out=yaml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.get_image(image_id, profile, **libcloud_kwargs) Get an image of a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBimage_id\fP (\fBstr\fP) \-\- Image to fetch .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs delete_image method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.get_image image1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.get_key_pair(name, profile, **libcloud_kwargs) Get a single key pair by name .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Name of the key pair to retrieve. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs get_key_pair method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.get_key_pair pair1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.import_key_pair(name, key, profile, key_type=None, **libcloud_kwargs) Import a new public key from string or a file path .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Key pair name. .IP \(bu 2 \fBkey\fP (\fBstr\fP or path \fBstr\fP) \-\- Public key material, the string or a path to a file .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBkey_type\fP (\fBstr\fP) \-\- The key pair type, either \fIFILE\fP or \fISTRING\fP\&. Will detect if not provided and assume that if the string is a path to an existing path it is a FILE, else STRING. .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs import_key_pair_from_xxx method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.import_key_pair pair1 key_value_data123 profile1 salt myminion libcloud_compute.import_key_pair pair1 /path/to/key profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.list_images(profile, location_id=None, **libcloud_kwargs) Return a list of images for this cloud .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlocation_id\fP (\fBstr\fP) \-\- The location key, from list_locations .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_images method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.list_images profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.list_key_pairs(profile, **libcloud_kwargs) List all the available key pair objects. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_key_pairs method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.list_key_pairs profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.list_locations(profile, **libcloud_kwargs) Return a list of locations for this cloud .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_locations method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.list_locations profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.list_nodes(profile, **libcloud_kwargs) Return a list of nodes .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_nodes method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.list_nodes profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.list_sizes(profile, location_id=None, **libcloud_kwargs) Return a list of node sizes .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlocation_id\fP (\fBstr\fP) \-\- The location key, from list_locations .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_sizes method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.list_sizes profile1 salt myminion libcloud_compute.list_sizes profile1 us\-east1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.list_volume_snapshots(volume_id, profile, **libcloud_kwargs) Return a list of storage volumes snapshots for this cloud .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvolume_id\fP (\fBstr\fP) \-\- The volume identifier .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_volume_snapshots method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.list_volume_snapshots vol1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.list_volumes(profile, **libcloud_kwargs) Return a list of storage volumes for this cloud .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_volumes method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.list_volumes profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_compute.reboot_node(node_id, profile, **libcloud_kwargs) Reboot a node in the cloud .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnode_id\fP (\fBstr\fP) \-\- Unique ID of the node to reboot .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs reboot_node method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_compute.reboot_node as\-2346 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.libcloud_dns .SS Apache Libcloud DNS Management .sp Connection module for Apache Libcloud DNS management .sp New in version 2016.11.0. .INDENT 0.0 .TP .B configuration This module uses a configuration profile for one or multiple DNS providers .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C libcloud_dns: profile_test1: driver: cloudflare key: 12345 secret: mysecret profile_test2: driver: godaddy key: 12345 secret: mysecret shopper_id: 12345 .ft P .fi .UNINDENT .UNINDENT .TP .B depends apache\-libcloud .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_dns.create_record(name, zone_id, type, data, profile) Create a new record. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Record name without the domain name (e.g. www). Note: If you want to create a record for a base domain name, you should specify empty string (\(aq\(aq) for this argument. .IP \(bu 2 \fBzone_id\fP (\fBstr\fP) \-\- Zone where the requested record is created. .IP \(bu 2 \fBtype\fP (\fBstr\fP) \-\- DNS record type (A, AAAA, ...). .IP \(bu 2 \fBdata\fP (\fBstr\fP) \-\- Data for the record (depends on the record type). .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_dns.create_record www google.com A 12.32.12.2 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_dns.create_zone(domain, profile, type=\(aqmaster\(aq, ttl=None) Create a new zone. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain\fP (\fBstr\fP) \-\- Zone domain name (e.g. example.com) .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBtype\fP (\fBstr\fP) \-\- Zone type (master / slave). .IP \(bu 2 \fBttl\fP (\fBint\fP) \-\- TTL for new records. (optional) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_dns.create_zone google.com profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_dns.delete_record(zone_id, record_id, profile) Delete a record. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBzone_id\fP (\fBstr\fP) \-\- Zone to delete. .IP \(bu 2 \fBrecord_id\fP (\fBstr\fP) \-\- Record to delete. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .TP .B Return type \fBbool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_dns.delete_record google.com www profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_dns.delete_zone(zone_id, profile) Delete a zone. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBzone_id\fP (\fBstr\fP) \-\- Zone to delete. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .TP .B Return type \fBbool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_dns.delete_zone google.com profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_dns.extra(method, profile, **libcloud_kwargs) Call an extended method on the driver .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmethod\fP (\fBstr\fP) \-\- Driver\(aqs method name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs delete_container method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_dns.extra ex_get_permissions google container_name=my_container object_name=me.jpg \-\-out=yaml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_dns.get_bind_data(zone_id, profile) Export Zone to the BIND compatible format. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBzone_id\fP (\fBstr\fP) \-\- Zone to export. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .TP .B Returns Zone data in BIND compatible format. .TP .B Return type \fBstr\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_dns.get_bind_data google.com profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_dns.get_record(zone_id, record_id, profile) Get record information for the given zone_id on the given profile .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBzone_id\fP (\fBstr\fP) \-\- Zone to export. .IP \(bu 2 \fBrecord_id\fP (\fBstr\fP) \-\- Record to delete. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_dns.get_record google.com www profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_dns.get_zone(zone_id, profile) Get zone information for the given zone_id on the given profile .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBzone_id\fP (\fBstr\fP) \-\- Zone to export. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_dns.get_zone google.com profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_dns.list_record_types(profile) List available record types for the given profile, e.g. A, AAAA .INDENT 7.0 .TP .B Parameters \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_dns.list_record_types profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_dns.list_records(zone_id, profile, type=None) List records for the given zone_id on the given profile .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBzone_id\fP (\fBstr\fP) \-\- Zone to export. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBtype\fP (\fBstr\fP) \-\- The record type, e.g. A, NS .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_dns.list_records google.com profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_dns.list_zones(profile) List zones for the given profile .INDENT 7.0 .TP .B Parameters \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_dns.list_zones profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_dns.update_zone(zone_id, domain, profile, type=\(aqmaster\(aq, ttl=None) Update an existing zone. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBzone_id\fP (\fBstr\fP) \-\- Zone ID to update. .IP \(bu 2 \fBdomain\fP (\fBstr\fP) \-\- Zone domain name (e.g. example.com) .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBtype\fP (\fBstr\fP) \-\- Zone type (master / slave). .IP \(bu 2 \fBttl\fP (\fBint\fP) \-\- TTL for new records. (optional) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_dns.update_zone google.com google.com profile1 type=slave .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.libcloud_loadbalancer .SS Apache Libcloud Load Balancer Management .sp Connection module for Apache Libcloud Storage load balancer management for a full list of supported clouds, see \fI\%http://libcloud.readthedocs.io/en/latest/loadbalancer/supported_providers.html\fP .sp Clouds include Amazon ELB, ALB, Google, Aliyun, CloudStack, Softlayer .sp New in version 2018.3.0. .INDENT 0.0 .TP .B configuration This module uses a configuration profile for one or multiple Storage providers .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C libcloud_loadbalancer: profile_test1: driver: gce key: GOOG0123456789ABCXYZ secret: mysecret profile_test2: driver: alb key: 12345 secret: mysecret .ft P .fi .UNINDENT .UNINDENT .TP .B depends apache\-libcloud .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_loadbalancer.balancer_attach_member(balancer_id, ip, port, profile, extra=None, **libcloud_kwargs) Add a new member to the load balancer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbalancer_id\fP (\fBstr\fP) \-\- id of a load balancer you want to fetch .IP \(bu 2 \fBip\fP (\fBstr\fP) \-\- IP address for the new member .IP \(bu 2 \fBport\fP (\fBint\fP) \-\- Port for the new member .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs balancer_attach_member method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.balancer_attach_member balancer123 1.2.3.4 80 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_loadbalancer.balancer_detach_member(balancer_id, member_id, profile, **libcloud_kwargs) Add a new member to the load balancer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbalancer_id\fP (\fBstr\fP) \-\- id of a load balancer you want to fetch .IP \(bu 2 \fBip\fP (\fBstr\fP) \-\- IP address for the new member .IP \(bu 2 \fBport\fP (\fBint\fP) \-\- Port for the new member .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs balancer_detach_member method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.balancer_detach_member balancer123 member123 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_loadbalancer.create_balancer(name, port, protocol, profile, algorithm=None, members=None, **libcloud_kwargs) Create a new load balancer instance .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Name of the new load balancer (required) .IP \(bu 2 \fBport\fP (\fBstr\fP) \-\- Port the load balancer should listen on, defaults to 80 .IP \(bu 2 \fBprotocol\fP (\fBstr\fP) \-\- Loadbalancer protocol, defaults to http. .IP \(bu 2 \fBalgorithm\fP (\fBstr\fP) \-\- Load balancing algorithm, defaults to ROUND_ROBIN. See Algorithm type in Libcloud documentation for a full listing. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs create_balancer method .UNINDENT .TP .B Returns The details of the new balancer .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.create_balancer my_balancer 80 http profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_loadbalancer.destroy_balancer(balancer_id, profile, **libcloud_kwargs) Destroy a load balancer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbalancer_id\fP (\fBstr\fP) \-\- LoadBalancer ID which should be used .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs destroy_balancer method .UNINDENT .TP .B Returns \fBTrue\fP if the destroy was successful, otherwise \fBFalse\fP\&. .TP .B Return type \fBbool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.destroy_balancer balancer_1 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_loadbalancer.extra(method, profile, **libcloud_kwargs) Call an extended method on the driver .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmethod\fP (\fBstr\fP) \-\- Driver\(aqs method name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_loadbalancer.extra ex_get_permissions google container_name=my_container object_name=me.jpg \-\-out=yaml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_loadbalancer.get_balancer(balancer_id, profile, **libcloud_kwargs) Get the details for a load balancer by ID .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbalancer_id\fP (\fBstr\fP) \-\- id of a load balancer you want to fetch .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs get_balancer method .UNINDENT .TP .B Returns the load balancer details .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.get_balancer balancer123 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_loadbalancer.get_balancer_by_name(name, profile, **libcloud_kwargs) Get the details for a load balancer by name .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Name of a load balancer you want to fetch .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_balancers method .UNINDENT .TP .B Returns the load balancer details .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.get_balancer_by_name my_balancer profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_loadbalancer.list_balancer_members(balancer_id, profile, **libcloud_kwargs) List the members of a load balancer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbalancer_id\fP (\fBstr\fP) \-\- id of a load balancer you want to fetch .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_balancer_members method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.list_balancer_members balancer123 profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_loadbalancer.list_balancers(profile, **libcloud_kwargs) Return a list of load balancers. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_balancers method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.list_balancers profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_loadbalancer.list_protocols(profile, **libcloud_kwargs) Return a list of supported protocols. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_protocols method .UNINDENT .TP .B Returns a list of supported protocols .TP .B Return type \fBlist\fP of \fBstr\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.list_protocols profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_loadbalancer.list_supported_algorithms(profile, **libcloud_kwargs) Get the supported algorithms for a profile .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_supported_algorithms method .UNINDENT .TP .B Returns The supported algorithms .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.list_supported_algorithms profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.libcloud_storage .SS Apache Libcloud Storage Management .sp Connection module for Apache Libcloud Storage (object/blob) management for a full list of supported clouds, see \fI\%http://libcloud.readthedocs.io/en/latest/storage/supported_providers.html\fP .sp Clouds include Amazon S3, Google Storage, Aliyun, Azure Blobs, Ceph, OpenStack swift .sp New in version 2018.3.0. .INDENT 0.0 .TP .B configuration This module uses a configuration profile for one or multiple Storage providers .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C libcloud_storage: profile_test1: driver: google_storage key: GOOG0123456789ABCXYZ secret: mysecret profile_test2: driver: s3 key: 12345 secret: mysecret .ft P .fi .UNINDENT .UNINDENT .TP .B depends apache\-libcloud .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_storage.create_container(container_name, profile, **libcloud_kwargs) Create a container in the cloud .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontainer_name\fP (\fBstr\fP) \-\- Container name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs create_container method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.create_container MyFolder profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_storage.delete_container(container_name, profile, **libcloud_kwargs) Delete an object container in the cloud .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontainer_name\fP (\fBstr\fP) \-\- Container name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs delete_container method .UNINDENT .TP .B Returns True if an object container has been successfully deleted, False otherwise. .TP .B Return type \fBbool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.delete_container MyFolder profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_storage.delete_object(container_name, object_name, profile, **libcloud_kwargs) Delete an object in the cloud .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontainer_name\fP (\fBstr\fP) \-\- Container name .IP \(bu 2 \fBobject_name\fP (\fBstr\fP) \-\- Object name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs delete_object method .UNINDENT .TP .B Returns True if an object has been successfully deleted, False otherwise. .TP .B Return type \fBbool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.delete_object MyFolder me.jpg profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_storage.download_object(container_name, object_name, destination_path, profile, overwrite_existing=False, delete_on_failure=True, **libcloud_kwargs) Download an object to the specified destination path. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontainer_name\fP (\fBstr\fP) \-\- Container name .IP \(bu 2 \fBobject_name\fP (\fBstr\fP) \-\- Object name .IP \(bu 2 \fBdestination_path\fP (\fBstr\fP) \-\- Full path to a file or a directory where the incoming file will be saved. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBoverwrite_existing\fP (\fBbool\fP) \-\- True to overwrite an existing file, defaults to False. .IP \(bu 2 \fBdelete_on_failure\fP (\fBbool\fP) \-\- True to delete a partially downloaded file if the download was not successful (hash mismatch / file size). .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs download_object method .UNINDENT .TP .B Returns True if an object has been successfully downloaded, False otherwise. .TP .B Return type \fBbool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.download_object MyFolder me.jpg /tmp/me.jpg profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_storage.extra(method, profile, **libcloud_kwargs) Call an extended method on the driver .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmethod\fP (\fBstr\fP) \-\- Driver\(aqs method name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs delete_container method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_storage.get_container(container_name, profile, **libcloud_kwargs) List container details for the given container_name on the given profile .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontainer_name\fP (\fBstr\fP) \-\- Container name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs get_container method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.get_container MyFolder profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_storage.get_container_object(container_name, object_name, profile, **libcloud_kwargs) Get the details for a container object (file or object in the cloud) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontainer_name\fP (\fBstr\fP) \-\- Container name .IP \(bu 2 \fBobject_name\fP (\fBstr\fP) \-\- Object name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs get_container_object method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.get_container_object MyFolder MyFile.xyz profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_storage.list_container_objects(container_name, profile, **libcloud_kwargs) List container objects (e.g. files) for the given container_id on the given profile .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontainer_name\fP (\fBstr\fP) \-\- Container name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_container_objects method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.list_container_objects MyFolder profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_storage.list_containers(profile, **libcloud_kwargs) Return a list of containers. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs list_containers method .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.list_containers profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.libcloud_storage.upload_object(file_path, container_name, object_name, profile, extra=None, verify_hash=True, headers=None, **libcloud_kwargs) Upload an object currently located on a disk. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfile_path\fP (\fBstr\fP) \-\- Path to the object on disk. .IP \(bu 2 \fBcontainer_name\fP (\fBstr\fP) \-\- Destination container. .IP \(bu 2 \fBobject_name\fP (\fBstr\fP) \-\- Object name. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBverify_hash\fP (\fBbool\fP) \-\- Verify hash .IP \(bu 2 \fBextra\fP (\fBdict\fP) \-\- Extra attributes (driver specific). (optional) .IP \(bu 2 \fBheaders\fP (\fBdict\fP) \-\- (optional) Additional request headers, such as CORS headers. For example: headers = {\(aqAccess\-Control\-Allow\-Origin\(aq: \(aq\fI\%http://mozilla.com\fP\(aq} .IP \(bu 2 \fBlibcloud_kwargs\fP (\fBdict\fP) \-\- Extra arguments for the driver\(aqs upload_object method .UNINDENT .TP .B Returns The object name in the cloud .TP .B Return type \fBstr\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion libcloud_storage.upload_object /file/to/me.jpg MyFolder me.jpg profile1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.linux_acl .sp Support for Linux File Access Control Lists .sp The Linux ACL module requires the \fIgetfacl\fP and \fIsetfacl\fP binaries. .INDENT 0.0 .TP .B salt.modules.linux_acl.delfacl(acl_type, acl_name=\(aq\(aq, *args, **kwargs) Remove specific FACL from the specified file(s) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq acl.delfacl user myuser /tmp/house/kitchen salt \(aq*\(aq acl.delfacl default:group mygroup /tmp/house/kitchen salt \(aq*\(aq acl.delfacl d:u myuser /tmp/house/kitchen salt \(aq*\(aq acl.delfacl g myuser /tmp/house/kitchen /tmp/house/livingroom salt \(aq*\(aq acl.delfacl user myuser /tmp/house/kitchen recursive=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_acl.getfacl(*args, **kwargs) Return (extremely verbose) map of FACLs on specified file(s) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq acl.getfacl /tmp/house/kitchen salt \(aq*\(aq acl.getfacl /tmp/house/kitchen /tmp/house/livingroom salt \(aq*\(aq acl.getfacl /tmp/house/kitchen /tmp/house/livingroom recursive=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_acl.modfacl(acl_type, acl_name=\(aq\(aq, perms=\(aq\(aq, *args, **kwargs) Add or modify a FACL for the specified file(s) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq acl.modfacl user myuser rwx /tmp/house/kitchen salt \(aq*\(aq acl.modfacl default:group mygroup rx /tmp/house/kitchen salt \(aq*\(aq acl.modfacl d:u myuser 7 /tmp/house/kitchen salt \(aq*\(aq acl.modfacl g mygroup 0 /tmp/house/kitchen /tmp/house/livingroom salt \(aq*\(aq acl.modfacl user myuser rwx /tmp/house/kitchen recursive=True salt \(aq*\(aq acl.modfacl user myuser rwx /tmp/house/kitchen raise_err=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_acl.version() Return facl version from getfacl \-\-version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq acl.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_acl.wipefacls(*args, **kwargs) Remove all FACLs from the specified file(s) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq acl.wipefacls /tmp/house/kitchen salt \(aq*\(aq acl.wipefacls /tmp/house/kitchen /tmp/house/livingroom salt \(aq*\(aq acl.wipefacls /tmp/house/kitchen /tmp/house/livingroom recursive=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.linux_ip .sp The networking module for Non\-RH/Deb Linux distros .INDENT 0.0 .TP .B salt.modules.linux_ip.down(iface, iface_type=None) Shutdown a network interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.down eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_ip.get_interface(iface) Return the contents of an interface script .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_interface eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_ip.get_routes(iface=None) Return the current routing table .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_routes salt \(aq*\(aq ip.get_routes eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_ip.up(iface, iface_type=None) Start up a network interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.up eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.linux_lvm .sp Support for Linux LVM2 .INDENT 0.0 .TP .B salt.modules.linux_lvm.fullversion() Return all version info from lvm version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvm.fullversion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.lvcreate(lvname, vgname, size=None, extents=None, snapshot=None, pv=None, thinvolume=False, thinpool=False, force=False, **kwargs) Create a new logical volume, with option for which physical volume to be used .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvm.lvcreate new_volume_name vg_name size=10G salt \(aq*\(aq lvm.lvcreate new_volume_name vg_name extents=100 pv=/dev/sdb salt \(aq*\(aq lvm.lvcreate new_snapshot vg_name snapshot=volume_name size=3G .ft P .fi .UNINDENT .UNINDENT .sp New in version 0.12.0. .sp Support for thin pools and thin volumes .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvm.lvcreate new_thinpool_name vg_name size=20G thinpool=True salt \(aq*\(aq lvm.lvcreate new_thinvolume_name vg_name/thinpool_name size=10G thinvolume=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.lvdisplay(lvname=\(aq\(aq, quiet=False) Return information about the logical volume(s) .INDENT 7.0 .TP .B lvname logical device name .TP .B quiet if the logical volume is not present, do not show any error .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvm.lvdisplay salt \(aq*\(aq lvm.lvdisplay /dev/vg_myserver/root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.lvextend(size=None, lvpath=None, extents=None, force=False, resizefs=False) Increase a logical volume to specific size. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvm.lvextend +12M /dev/mapper/vg1\-test salt \(aq*\(aq lvm.lvextend lvpath=/dev/mapper/vg1\-test extents=+100%FREE .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.lvremove(lvname, vgname, force=True) Remove a given existing logical volume from a named existing volume group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvm.lvremove lvname vgname force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.lvresize(size=None, lvpath=None, extents=None, force=False, resizefs=False) Resize a logical volume to specific size. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvm.lvresize +12M /dev/mapper/vg1\-test salt \(aq*\(aq lvm.lvresize lvpath=/dev/mapper/vg1\-test extents=+100%FREE .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.pvcreate(devices, override=True, force=True, **kwargs) Set a physical device to be used as an LVM physical volume .INDENT 7.0 .TP .B override Skip devices, if they are already LVM physical volumes .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt mymachine lvm.pvcreate /dev/sdb1,/dev/sdb2 salt mymachine lvm.pvcreate /dev/sdb1 dataalignmentoffset=7s .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.pvdisplay(pvname=\(aq\(aq, real=False, quiet=False) Return information about the physical volume(s) .INDENT 7.0 .TP .B pvname physical device name .TP .B real dereference any symlinks and report the real device .sp New in version 2015.8.7. .TP .B quiet if the physical volume is not present, do not show any error .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvm.pvdisplay salt \(aq*\(aq lvm.pvdisplay /dev/md0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.pvremove(devices, override=True, force=True) Remove a physical device being used as an LVM physical volume .INDENT 7.0 .TP .B override Skip devices, if they are already not used as LVM physical volumes .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt mymachine lvm.pvremove /dev/sdb1,/dev/sdb2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.pvresize(devices, override=True, force=True) Resize a LVM physical volume to the physical device size .INDENT 7.0 .TP .B override Skip devices, if they are already not used as LVM physical volumes .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt mymachine lvm.pvresize /dev/sdb1,/dev/sdb2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.version() Return LVM version from lvm version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvm.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.vgcreate(vgname, devices, force=False, **kwargs) Create an LVM volume group .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt mymachine lvm.vgcreate my_vg /dev/sdb1,/dev/sdb2 salt mymachine lvm.vgcreate my_vg /dev/sdb1 clustered=y .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.vgdisplay(vgname=\(aq\(aq, quiet=False) Return information about the volume group(s) .INDENT 7.0 .TP .B vgname volume group name .TP .B quiet if the volume group is not present, do not show any error .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvm.vgdisplay salt \(aq*\(aq lvm.vgdisplay nova\-volumes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.vgextend(vgname, devices, force=False) Add physical volumes to an LVM volume group .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt mymachine lvm.vgextend my_vg /dev/sdb1,/dev/sdb2 salt mymachine lvm.vgextend my_vg /dev/sdb1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_lvm.vgremove(vgname, force=True) Remove an LVM volume group .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt mymachine lvm.vgremove vgname salt mymachine lvm.vgremove vgname force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.linux_service .sp 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. .INDENT 0.0 .TP .B salt.modules.linux_service.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_service.get_all() Return a list of all available services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_service.missing(name) The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_service.reload_(name) Refreshes config files by calling service reload. Does not perform a full restart. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_service.restart(name) Restart the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_service.run(name, action) Run the specified service with an action. .sp New in version 2015.8.1. .INDENT 7.0 .TP .B name Service name. .TP .B action Action name (like start, stop, reload, restart). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.run apache2 reload salt \(aq*\(aq service.run postgresql initdb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_service.start(name) Start the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_service.status(name, sig=None) Return the status for a service. If the name contains globbing, a dict mapping service name to PID or empty string is returned. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Signature to use to find the service via ps .UNINDENT .TP .B Returns PID if running, empty otherwise dict: Maps service name to PID if running, empty string otherwise .TP .B Return type string .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> [service signature] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_service.stop(name) Stop the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.linux_shadow .sp Manage the shadow file on Linux systems .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage passwords on a minion, and it is using a different module (or gives an error similar to \fI\(aqshadow.info\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.default_hash() Returns the default hash used for unset passwords .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.default_hash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.del_password(name, root=None) New in version 2014.7.0. .sp Delete the password from name user .INDENT 7.0 .TP .B name User to delete .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.del_password username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.gen_password(password, crypt_salt=None, algorithm=\(aqsha512\(aq) New in version 2014.7.0. .sp Generate hashed password .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When called this function is called directly via remote\-execution, the password argument may be displayed in the system\(aqs process list. This may be a security risk on certain systems. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B password Plaintext password to be hashed. .TP .B crypt_salt Crpytographic salt. If not given, a random 8\-character salt will be generated. .TP .B algorithm The following hash algorithms are supported: .INDENT 7.0 .IP \(bu 2 md5 .IP \(bu 2 blowfish (not in mainline glibc, only available in distros that add it) .IP \(bu 2 sha256 .IP \(bu 2 sha512 (default) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.gen_password \(aqI_am_password\(aq salt \(aq*\(aq shadow.gen_password \(aqI_am_password\(aq crypt_salt=\(aqI_am_salt\(aq algorithm=sha256 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.info(name, root=None) Return information for the specified user .INDENT 7.0 .TP .B name User to get the information for .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.info root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.list_users(root=None) New in version 2018.3.0. .sp Return a list of all shadow users .INDENT 7.0 .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.lock_password(name, root=None) New in version 2016.11.0. .sp Lock the password from specified user .INDENT 7.0 .TP .B name User to lock .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.lock_password username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.set_date(name, date, root=None) Sets the value for the date the password was last changed to days since the epoch (January 1, 1970). See man chage. .INDENT 7.0 .TP .B name User to modify .TP .B date Date the password was last changed .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_date username 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.set_expire(name, expire, root=None) Changed in version 2014.7.0. .sp Sets the value for the date the account expires as days since the epoch (January 1, 1970). Using a value of \-1 will clear expiration. See man chage. .INDENT 7.0 .TP .B name User to modify .TP .B date Date the account expires .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_expire username \-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.set_inactdays(name, inactdays, root=None) Set the number of days of inactivity after a password has expired before the account is locked. See man chage. .INDENT 7.0 .TP .B name User to modify .TP .B inactdays Set password inactive after this number of days .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_inactdays username 7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.set_maxdays(name, maxdays, root=None) Set the maximum number of days during which a password is valid. See man chage. .INDENT 7.0 .TP .B name User to modify .TP .B maxdays Maximum number of days during which a password is valid .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_maxdays username 90 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.set_mindays(name, mindays, root=None) Set the minimum number of days between password changes. See man chage. .INDENT 7.0 .TP .B name User to modify .TP .B mindays Minimum number of days between password changes .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_mindays username 7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.set_password(name, password, use_usermod=False, root=None) Set the password for a named user. The password must be a properly defined hash. A password hash can be generated with \fI\%gen_password()\fP\&. .INDENT 7.0 .TP .B name User to set the password .TP .B password Password already hashed .TP .B use_usermod Use usermod command to better compatibility .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_password root \(aq$1$UYCIxa628.9qXjpQCjM4a..\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.set_warndays(name, warndays, root=None) Set the number of days of warning before a password change is required. See man chage. .INDENT 7.0 .TP .B name User to modify .TP .B warndays Number of days of warning before a password change is required .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_warndays username 7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_shadow.unlock_password(name, root=None) New in version 2016.11.0. .sp Unlock the password from name user .INDENT 7.0 .TP .B name User to unlock .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.unlock_password username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.linux_sysctl .sp Module for viewing and modifying sysctl parameters .INDENT 0.0 .TP .B salt.modules.linux_sysctl.assign(name, value) Assign a single sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.assign net.ipv4.ip_forward 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_sysctl.default_config() Linux hosts using systemd 207 or later ignore \fB/etc/sysctl.conf\fP and only load from \fB/etc/sysctl.d/*.conf\fP\&. This function will do the proper checks and return a default config file which will be valid for the Minion. Hosts running systemd >= 207 will use \fB/etc/sysctl.d/99\-salt.conf\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqkernel:Linux\(aq sysctl.default_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_sysctl.get(name) Return a single sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.get net.ipv4.ip_forward .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_sysctl.persist(name, value, config=None) Assign and persist a simple sysctl parameter for this minion. If \fBconfig\fP is not specified, a sensible default will be chosen using \fI\%sysctl.default_config\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.persist net.ipv4.ip_forward 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_sysctl.show(config_file=False) Return a list of sysctl parameters for this minion .INDENT 7.0 .TP .B config: Pull the data from the system configuration file instead of the live data. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.show .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.localemod .sp Module for managing locales on POSIX\-like systems. .INDENT 0.0 .TP .B salt.modules.localemod.avail(locale) Check if a locale is available. .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq locale.avail \(aqen_US.UTF\-8\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.localemod.gen_locale(locale, **kwargs) Generate a locale. Options: .sp New in version 2014.7.0. .INDENT 7.0 .TP .B Parameters \fBlocale\fP \-\- Any locale listed in /usr/share/i18n/locales or /usr/share/i18n/SUPPORTED for Debian and Gentoo based distributions, which require the charmap to be specified as part of the locale when generating it. .UNINDENT .INDENT 7.0 .TP .B verbose Show extra warnings about errors that are normally ignored. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq locale.gen_locale en_US.UTF\-8 salt \(aq*\(aq locale.gen_locale \(aqen_IE.UTF\-8 UTF\-8\(aq # Debian/Gentoo only .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.localemod.get_locale() Get the current system locale .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq locale.get_locale .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.localemod.list_avail() Lists available (compiled) locales .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq locale.list_avail .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.localemod.set_locale(locale) Sets the current system locale .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq locale.set_locale \(aqen_US.UTF\-8\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.locate .sp Module for using the locate utilities .INDENT 0.0 .TP .B salt.modules.locate.locate(pattern, database=\(aq\(aq, limit=0, **kwargs) Performs a file lookup. Valid options (and their defaults) are: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C basename=False count=False existing=False follow=True ignore=False nofollow=False wholename=True regex=False database=<locate\(aqs default database> limit=<integer, not set by default> .ft P .fi .UNINDENT .UNINDENT .sp See the manpage for \fBlocate(1)\fP for further explanation of these options. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq locate.locate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.locate.stats() Returns statistics about the locate database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq locate.stats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.locate.updatedb() Updates the locate database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq locate.updatedb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.locate.version() Returns the version of locate .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq locate.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.logadm .sp Module for managing Solaris logadm based log rotations. .INDENT 0.0 .TP .B salt.modules.logadm.list_conf(conf_file=\(aq/etc/logadm.conf\(aq, log_file=None, include_unset=False) Show parsed configuration .sp New in version 2018.3.0. .INDENT 7.0 .TP .B conf_file string path to logadm.conf, defaults to /etc/logadm.conf .TP .B log_file string optional show only one log file .TP .B include_unset boolean include unset flags in output .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq logadm.list_conf salt \(aq*\(aq logadm.list_conf log=/var/log/syslog salt \(aq*\(aq logadm.list_conf include_unset=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.logadm.remove(name, conf_file=\(aq/etc/logadm.conf\(aq) Remove log pattern from logadm .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq logadm.remove myapplog .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.logadm.rotate(name, pattern=None, conf_file=\(aq/etc/logadm.conf\(aq, **kwargs) Set up pattern for logging. .INDENT 7.0 .TP .B name string alias for entryname .TP .B pattern string alias for log_file .TP .B conf_file string optional path to alternative configuration file .TP .B kwargs boolean|string|int optional additional flags and parameters .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBname\fP and \fBpattern\fP were kept for backwards compatibility reasons. .sp \fBname\fP is an alias for the \fBentryname\fP argument, \fBpattern\fP is an alias for \fBlog_file\fP\&. These aliases will only be used if the \fBentryname\fP and \fBlog_file\fP arguments are not passed. .sp For a full list of arguments see \fB\(galogadm.show_args\(ga\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq logadm.rotate myapplog pattern=\(aq/var/log/myapp/*.log\(aq count=7 salt \(aq*\(aq logadm.rotate myapplog log_file=\(aq/var/log/myapp/*.log\(aq count=4 owner=myappd mode=\(aq0700\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.logadm.show_args() Show which arguments map to which flags and options. .sp New in version 2018.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq logadm.show_args .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.logadm.show_conf(conf_file=\(aq/etc/logadm.conf\(aq, name=None) Show configuration .INDENT 7.0 .TP .B conf_file string path to logadm.conf, defaults to /etc/logadm.conf .TP .B name string optional show only a single entry .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq logadm.show_conf salt \(aq*\(aq logadm.show_conf name=/var/log/syslog .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.logmod .SS On\-demand logging .sp New in version 2017.7.0. .sp The sole purpose of this module is logging messages in the (proxy) minion. It comes very handy when debugging complex Jinja templates, for example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {%\- for var in range(10) %} {%\- do salt[\(dqlog.info\(dq](var) \-%} {%\- endfor %} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq log.error \(dqPlease don\(aqt do that, this module is not for CLI use!\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.logmod.critical(message) Log message at level CRITICAL. .UNINDENT .INDENT 0.0 .TP .B salt.modules.logmod.debug(message) Log message at level DEBUG. .UNINDENT .INDENT 0.0 .TP .B salt.modules.logmod.error(message) Log message at level ERROR. .UNINDENT .INDENT 0.0 .TP .B salt.modules.logmod.exception(message) Log message at level EXCEPTION. .UNINDENT .INDENT 0.0 .TP .B salt.modules.logmod.info(message) Log message at level INFO. .UNINDENT .INDENT 0.0 .TP .B salt.modules.logmod.warning(message) Log message at level WARNING. .UNINDENT .SS salt.modules.logrotate .sp Module for managing logrotate. .INDENT 0.0 .TP .B salt.modules.logrotate.get(key, value=None, conf_file=\(aq/etc/logrotate.conf\(aq) Get the value for a specific configuration line. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The command or stanza block to configure. .IP \(bu 2 \fBvalue\fP (\fI\%str\fP) \-\- The command value or command of the block specified by the key parameter. .IP \(bu 2 \fBconf_file\fP (\fI\%str\fP) \-\- The logrotate configuration file. .UNINDENT .TP .B Returns The value for a specific configuration line. .TP .B Return type \fI\%bool\fP|\fI\%int\fP|\fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq logrotate.get rotate salt \(aq*\(aq logrotate.get /var/log/wtmp rotate /etc/logrotate.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.logrotate.set_(key, value, setting=None, conf_file=\(aq/etc/logrotate.conf\(aq) Set a new value for a specific configuration line. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The command or block to configure. .IP \(bu 2 \fBvalue\fP (\fI\%str\fP) \-\- The command value or command of the block specified by the key parameter. .IP \(bu 2 \fBsetting\fP (\fI\%str\fP) \-\- The command value for the command specified by the value parameter. .IP \(bu 2 \fBconf_file\fP (\fI\%str\fP) \-\- The logrotate configuration file. .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 logrotate.set rotate 2 .ft P .fi .UNINDENT .UNINDENT .sp Can also be used to set a single value inside a multiline configuration block. For instance, to change rotate in the following block: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /var/log/wtmp { monthly create 0664 root root rotate 1 } .ft P .fi .UNINDENT .UNINDENT .sp Use the following command: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq logrotate.set /var/log/wtmp rotate 2 .ft P .fi .UNINDENT .UNINDENT .sp This module also has the ability to scan files inside an include directory, and make changes in the appropriate file. .UNINDENT .INDENT 0.0 .TP .B salt.modules.logrotate.show_conf(conf_file=\(aq/etc/logrotate.conf\(aq) Show parsed configuration .INDENT 7.0 .TP .B Parameters \fBconf_file\fP (\fI\%str\fP) \-\- The logrotate configuration file. .TP .B Returns The parsed configuration. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq logrotate.show_conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.lvs .sp Support for LVS (Linux Virtual Server) .INDENT 0.0 .TP .B salt.modules.lvs.add_server(protocol=None, service_address=None, server_address=None, packet_forward_method=\(aqdr\(aq, weight=1, **kwargs) Add a real server to a virtual service. .INDENT 7.0 .TP .B protocol The service protocol(only support \fBtcp\fP, \fBudp\fP and \fBfwmark\fP service). .TP .B service_address The LVS service address. .TP .B server_address The real server address. .TP .B packet_forward_method The LVS packet forwarding method(\fBdr\fP for direct routing, \fBtunnel\fP for tunneling, \fBnat\fP for network access translation). .TP .B weight The capacity of a server relative to the others in the pool. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvs.add_server tcp 1.1.1.1:80 192.168.0.11:8080 nat 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lvs.add_service(protocol=None, service_address=None, scheduler=\(aqwlc\(aq) Add a virtual service. .INDENT 7.0 .TP .B protocol The service protocol(only support tcp, udp and fwmark service). .TP .B service_address The LVS service address. .TP .B scheduler Algorithm for allocating TCP connections and UDP datagrams to real servers. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvs.add_service tcp 1.1.1.1:80 rr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lvs.check_server(protocol=None, service_address=None, server_address=None, **kwargs) Check the real server exists in the specified service. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvs.check_server tcp 1.1.1.1:80 192.168.0.11:8080 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lvs.check_service(protocol=None, service_address=None, **kwargs) Check the virtual service exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvs.check_service tcp 1.1.1.1:80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lvs.clear() Clear the virtual server table .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvs.clear .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lvs.delete_server(protocol=None, service_address=None, server_address=None) Delete the realserver from the virtual service. .INDENT 7.0 .TP .B protocol The service protocol(only support \fBtcp\fP, \fBudp\fP and \fBfwmark\fP service). .TP .B service_address The LVS service address. .TP .B server_address The real server address. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvs.delete_server tcp 1.1.1.1:80 192.168.0.11:8080 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lvs.delete_service(protocol=None, service_address=None) Delete the virtual service. .INDENT 7.0 .TP .B protocol The service protocol(only support tcp, udp and fwmark service). .TP .B service_address The LVS service address. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvs.delete_service tcp 1.1.1.1:80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lvs.edit_server(protocol=None, service_address=None, server_address=None, packet_forward_method=None, weight=None, **kwargs) Edit a real server to a virtual service. .INDENT 7.0 .TP .B protocol The service protocol(only support \fBtcp\fP, \fBudp\fP and \fBfwmark\fP service). .TP .B service_address The LVS service address. .TP .B server_address The real server address. .TP .B packet_forward_method The LVS packet forwarding method(\fBdr\fP for direct routing, \fBtunnel\fP for tunneling, \fBnat\fP for network access translation). .TP .B weight The capacity of a server relative to the others in the pool. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvs.edit_server tcp 1.1.1.1:80 192.168.0.11:8080 nat 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lvs.edit_service(protocol=None, service_address=None, scheduler=None) Edit the virtual service. .INDENT 7.0 .TP .B protocol The service protocol(only support tcp, udp and fwmark service). .TP .B service_address The LVS service address. .TP .B scheduler Algorithm for allocating TCP connections and UDP datagrams to real servers. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvs.edit_service tcp 1.1.1.1:80 rr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lvs.get_rules() Get the virtual server rules .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvs.get_rules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lvs.list_(protocol=None, service_address=None) List the virtual server table if service_address is not specified. If a service_address is selected, list this service only. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvs.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lvs.zero(protocol=None, service_address=None) Zero the packet, byte and rate counters in a service or all services. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lvs.zero .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.lxc .sp Control Linux Containers via Salt .INDENT 0.0 .TP .B depends lxc package for distribution .UNINDENT .sp lxc >= 1.0 (even beta alpha) is required .INDENT 0.0 .TP .B salt.modules.lxc.add_veth(name, interface_name, bridge=None, path=None) Add a veth to a container. Note : this function doesn\(aqt update the container config, just add the interface at runtime .INDENT 7.0 .TP .B name Name of the container .TP .B interface_name Name of the interface in the container .TP .B bridge Name of the bridge to attach the interface to (facultative) .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.add_veth container_name eth1 br1 salt \(aq*\(aq lxc.add_veth container_name eth1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.apply_network_profile(name, network_profile, nic_opts=None, path=None) New in version 2015.5.0. .sp Apply a network profile to a container .INDENT 7.0 .TP .B network_profile profile name or default values (dict) .TP .B nic_opts values to override in defaults (dict) indexed by nic card names .TP .B path path to the container parent .sp New in version 2015.8.0. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq lxc.apply_network_profile web1 centos salt \(aqminion\(aq lxc.apply_network_profile web1 centos \e nic_opts=\(dq{\(aqeth0\(aq: {\(aqmac\(aq: \(aqxx:xx:xx:xx:xx:xx\(aq}}\(dq salt \(aqminion\(aq lxc.apply_network_profile web1 \e \(dq{\(aqeth0\(aq: {\(aqmac\(aq: \(aqxx:xx:xx:xx:xx:yy\(aq}}\(dq nic_opts=\(dq{\(aqeth0\(aq: {\(aqmac\(aq: \(aqxx:xx:xx:xx:xx:xx\(aq}}\(dq .ft P .fi .UNINDENT .UNINDENT .sp The special case to disable use of ethernet nics: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq lxc.apply_network_profile web1 centos \e \(dq{eth0: {disable: true}}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.attachable(name, path=None) Return True if the named container can be attached to via the lxc\-attach command .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq lxc.attachable ubuntu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.bootstrap(name, config=None, approve_key=True, install=True, pub_key=None, priv_key=None, bootstrap_url=None, force_install=False, unconditional_install=False, path=None, bootstrap_delay=None, bootstrap_args=None, bootstrap_shell=None) Install and configure salt in a container. .INDENT 7.0 .TP .B config Minion configuration options. By default, the \fBmaster\fP option is set to the target host\(aqs master. .TP .B approve_key Request a pre\-approval of the generated minion key. Requires that the salt\-master be configured to either auto\-accept all keys or expect a signing request from the target host. Default: \fBTrue\fP .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B pub_key Explicit public key to pressed the minion with (optional). This can be either a filepath or a string representing the key .TP .B priv_key Explicit private key to pressed the minion with (optional). This can be either a filepath or a string representing the key .TP .B bootstrap_delay Delay in seconds between end of container creation and bootstrapping. Useful when waiting for container to obtain a DHCP lease. .sp New in version 2015.5.0. .TP .B bootstrap_url url, content or filepath to the salt bootstrap script .TP .B bootstrap_args salt bootstrap script arguments .TP .B bootstrap_shell shell to execute the script into .TP .B install Whether to attempt a full installation of salt\-minion if needed. .TP .B force_install Force installation even if salt\-minion is detected, this is the way to run vendor bootstrap scripts even if a salt minion is already present in the container .TP .B unconditional_install Run the script even if the container seems seeded .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq lxc.bootstrap container_name [config=config_data] \e [approve_key=(True|False)] [install=(True|False)] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.clone(name, orig, profile=None, network_profile=None, nic_opts=None, **kwargs) Create a new container as a clone of another container .INDENT 7.0 .TP .B name Name of the container .TP .B orig Name of the original container to be cloned .TP .B profile Profile to use in container cloning (see \fI\%lxc.get_container_profile\fP). Values in a profile will be overridden by the \fBContainer Cloning Arguments\fP listed below. .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .UNINDENT .sp \fBContainer Cloning Arguments\fP .INDENT 7.0 .TP .B snapshot Use Copy On Write snapshots (LVM) .TP .B size 1G Size of the volume to create. Only applicable if \fBbacking=lvm\fP\&. .TP .B backing The type of storage to use. Set to \fBlvm\fP to use an LVM group. Defaults to filesystem within /var/lib/lxc. .TP .B network_profile Network profile to use for container .sp New in version 2015.8.0. .TP .B nic_opts give extra opts overriding network profile values .sp New in version 2015.8.0. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.clone myclone orig=orig_container salt \(aq*\(aq lxc.clone myclone orig=orig_container snapshot=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.cloud_init(name, vm_=None, **kwargs) Thin wrapper to lxc.init to be used from the saltcloud lxc driver .INDENT 7.0 .TP .B name Name of the container may be None and then guessed from saltcloud mapping .TP .B \fIvm_\fP saltcloud mapping defaults for the vm .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.cloud_init foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.cloud_init_interface(name, vm_=None, **kwargs) Interface between salt.cloud.lxc driver and lxc.init \fBvm_\fP is a mapping of vm opts in the salt.cloud format as documented for the lxc driver. .sp This can be used either: .INDENT 7.0 .IP \(bu 2 from the salt cloud driver .IP \(bu 2 because you find the argument to give easier here than using directly lxc.init .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 BE REALLY CAREFUL CHANGING DEFAULTS !!! IT\(aqS A RETRO COMPATIBLE INTERFACE WITH THE SALT CLOUD DRIVER (ask kiorky). .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name name of the lxc container to create .TP .B pub_key public key to preseed the minion with. Can be the keycontent or a filepath .TP .B priv_key private key to preseed the minion with. Can be the keycontent or a filepath .TP .B path path to the container parent directory (default: /var/lib/lxc) .sp New in version 2015.8.0. .TP .B profile \fI\%profile\fP selection .TP .B network_profile \fI\%network profile\fP selection .TP .B nic_opts per interface settings compatibles with network profile (ipv4/ipv6/link/gateway/mac/netmask) .sp eg: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- {\(aqeth0\(aq: {\(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 unconditional_install given to lxc.bootstrap (see relative doc) .TP .B force_install given to lxc.bootstrap (see relative doc) .TP .B config any extra argument for the salt minion config .TP .B dnsservers list of DNS servers to set inside the container .TP .B dns_via_dhcp do not set the dns servers, let them be set by the dhcp. .TP .B autostart autostart the container at boot time .TP .B password administrative password for the container .TP .B bootstrap_delay delay before launching bootstrap script at Container init .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Legacy but still supported options: .INDENT 0.0 .TP .B from_container which container we use as a template when running lxc.clone .TP .B image which template do we use when we are using lxc.create. This is the default mode unless you specify something in from_container .TP .B backing which backing store to use. Values can be: overlayfs, dir(default), lvm, zfs, brtfs .TP .B fstype When using a blockdevice level backing store, which filesystem to use on .TP .B size When using a blockdevice level backing store, which size for the filesystem to use on .TP .B snapshot Use snapshot when cloning the container source .TP .B vgname if using LVM: vgname .TP .B lvname if using LVM: lvname .TP .B thinpool: if using LVM: thinpool .TP .B ip ip for the primary nic .TP .B mac mac address for the primary nic .TP .B netmask netmask for the primary nic (24) = \fBvm_.get(\(aqnetmask\(aq, \(aq24\(aq)\fP .TP .B bridge bridge for the primary nic (lxcbr0) .TP .B gateway network gateway for the container .TP .B additional_ips additional ips which will be wired on the main bridge (br0) which is connected to internet. Be aware that you may use manual virtual mac addresses providen by you provider (online, ovh, etc). This is a list of mappings {ip: \(aq\(aq, mac: \(aq\(aq, netmask:\(aq\(aq} Set gateway to None and an interface with a gateway to escape from another interface that eth0. eg: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- {\(aqmac\(aq: \(aq00:16:3e:01:29:40\(aq, \(aqgateway\(aq: None, (default) \(aqlink\(aq: \(aqbr0\(aq, (default) \(aqnetmask\(aq: \(aq\(aq, (default) \(aqip\(aq: \(aq22.1.4.25\(aq} .ft P .fi .UNINDENT .UNINDENT .TP .B users administrative users for the container default: [root] and [root, ubuntu] on ubuntu .TP .B default_nic name of the first interface, you should really not override this .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.cloud_init_interface foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.copy_to(name, source, dest, overwrite=False, makedirs=False, path=None) Changed in version 2015.8.0: Function renamed from \fBlxc.cp\fP to \fBlxc.copy_to\fP for consistency with other container types. \fBlxc.cp\fP will continue to work, however. For versions 2015.2.x and earlier, use \fBlxc.cp\fP\&. .sp Copy a file or directory from the host into a container .INDENT 7.0 .TP .B name Container name .TP .B source File to be copied to the container .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B dest Destination on the container. Must be an absolute path. .sp Changed in version 2015.5.0: If the destination is a directory, the file will be copied into that directory. .TP .B overwrite False Unless this option is set to \fBTrue\fP, then if a file exists at the location specified by the \fBdest\fP argument, an error will be raised. .sp New in version 2015.8.0. .UNINDENT .sp makedirs : False .INDENT 7.0 .INDENT 3.5 Create the parent directory on the container if it does not already exist. .sp New in version 2015.5.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq lxc.copy_to /tmp/foo /root/foo salt \(aqminion\(aq lxc.cp /tmp/foo /root/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.cp(name, source, dest, overwrite=False, makedirs=False, path=None) This function is an alias of \fBcopy_to\fP\&. .INDENT 7.0 .INDENT 3.5 Changed in version 2015.8.0: Function renamed from \fBlxc.cp\fP to \fBlxc.copy_to\fP for consistency with other container types. \fBlxc.cp\fP will continue to work, however. For versions 2015.2.x and earlier, use \fBlxc.cp\fP\&. .sp Copy a file or directory from the host into a container .INDENT 0.0 .TP .B name Container name .TP .B source File to be copied to the container .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B dest Destination on the container. Must be an absolute path. .sp Changed in version 2015.5.0: If the destination is a directory, the file will be copied into that directory. .TP .B overwrite False Unless this option is set to \fBTrue\fP, then if a file exists at the location specified by the \fBdest\fP argument, an error will be raised. .sp New in version 2015.8.0. .UNINDENT .sp makedirs : False .INDENT 0.0 .INDENT 3.5 Create the parent directory on the container if it does not already exist. .sp New in version 2015.5.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq lxc.copy_to /tmp/foo /root/foo salt \(aqminion\(aq lxc.cp /tmp/foo /root/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.create(name, config=None, profile=None, network_profile=None, nic_opts=None, **kwargs) Create a new container. .INDENT 7.0 .TP .B name Name of the container .TP .B config The config file to use for the container. Defaults to system\-wide config (usually in /etc/lxc/lxc.conf). .TP .B profile Profile to use in container creation (see \fI\%lxc.get_container_profile\fP). Values in a profile will be overridden by the \fBContainer Creation Arguments\fP listed below. .TP .B network_profile Network profile to use for container .sp New in version 2015.5.0. .UNINDENT .sp \fBContainer Creation Arguments\fP .INDENT 7.0 .TP .B template The template to use. For example, \fBubuntu\fP or \fBfedora\fP\&. For a full list of available templates, check out the \fI\%lxc.templates\fP function. .sp Conflicts with the \fBimage\fP argument. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fBdownload\fP template requires the following three parameters to be defined in \fBoptions\fP: .INDENT 0.0 .IP \(bu 2 \fBdist\fP \- The name of the distribution .IP \(bu 2 \fBrelease\fP \- Release name/version .IP \(bu 2 \fBarch\fP \- Architecture of the container .UNINDENT .sp The available images can be listed using the \fI\%lxc.images\fP function. .UNINDENT .UNINDENT .TP .B options Template\-specific options to pass to the lxc\-create command. These correspond to the long options (ones beginning with two dashes) that the template script accepts. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C options=\(aq{\(dqdist\(dq: \(dqcentos\(dq, \(dqrelease\(dq: \(dq6\(dq, \(dqarch\(dq: \(dqamd64\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp For available template options, refer to the lxc template scripts which are usually located under \fB/usr/share/lxc/templates\fP, or run \fBlxc\-create \-t <template> \-h\fP\&. .TP .B image A tar archive to use as the rootfs for the container. Conflicts with the \fBtemplate\fP argument. .TP .B backing The type of storage to use. Set to \fBlvm\fP to use an LVM group. Defaults to filesystem within /var/lib/lxc. .TP .B fstype Filesystem type to use on LVM logical volume .TP .B size 1G Size of the volume to create. Only applicable if \fBbacking=lvm\fP\&. .TP .B vgname lxc Name of the LVM volume group in which to create the volume for this container. Only applicable if \fBbacking=lvm\fP\&. .TP .B lvname Name of the LVM logical volume in which to create the volume for this container. Only applicable if \fBbacking=lvm\fP\&. .TP .B thinpool Name of a pool volume that will be used for thin\-provisioning this container. Only applicable if \fBbacking=lvm\fP\&. .TP .B nic_opts give extra opts overriding network profile values .TP .B path parent path for the container creation (default: /var/lib/lxc) .TP .B zfsroot Name of the ZFS root in which to create the volume for this container. Only applicable if \fBbacking=zfs\fP\&. (default: tank/lxc) .sp New in version 2015.8.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.destroy(name, stop=False, path=None) Destroy the named container. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Destroys all data associated with the container. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path path to the container parent directory (default: /var/lib/lxc) .sp New in version 2015.8.0. .TP .B stop False If \fBTrue\fP, the container will be destroyed even if it is running/frozen. .sp Changed in version 2015.5.0: Default value changed to \fBFalse\fP\&. This more closely matches the behavior of \fBlxc\-destroy(1)\fP, and also makes it less likely that an accidental command will destroy a running container that was being used for important things. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.destroy foo salt \(aq*\(aq lxc.destroy foo stop=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.edit_conf(conf_file, out_format=\(aqsimple\(aq, read_only=False, lxc_config=None, **kwargs) Edit an LXC configuration file. If a setting is already present inside the file, its value will be replaced. If it does not exist, it will be appended to the end of the file. Comments and blank lines will be kept in\-tact if they already exist in the file. .INDENT 7.0 .TP .B out_format: Set to simple if you need backward compatibility (multiple items for a simple key is not supported) .TP .B read_only: return only the edited configuration without applying it to the underlying lxc configuration file .TP .B lxc_config: List of dict containning lxc configuration items For network configuration, you also need to add the device it belongs to, otherwise it will default to eth0. Also, any change to a network parameter will result in the whole network reconfiguration to avoid mismatchs, be aware of that ! .UNINDENT .sp After the file is edited, its contents will be returned. By default, it will be returned in \fBsimple\fP format, meaning an unordered dict (which may not represent the actual file order). Passing in an \fBout_format\fP of \fBcommented\fP will return a data structure which accurately represents the order and content of the file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq lxc.edit_conf /etc/lxc/mycontainer.conf \e out_format=commented lxc.network.type=veth salt \(aqminion\(aq lxc.edit_conf /etc/lxc/mycontainer.conf \e out_format=commented \e lxc_config=\(dq[{\(aqlxc.network.name\(aq: \(aqeth0\(aq, \e \(aqlxc.network.ipv4\(aq: \(aq1.2.3.4\(aq}, {\(aqlxc.network.name\(aq: \(aqeth2\(aq, \e \(aqlxc.network.ipv4\(aq: \(aq1.2.3.5\(aq,\e \(aqlxc.network.gateway\(aq: \(aq1.2.3.1\(aq}]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.exists(name, path=None) Returns whether the named container exists. .INDENT 7.0 .TP .B path path to the container parent directory (default: /var/lib/lxc) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.exists name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.freeze(name, **kwargs) Freeze the named container .INDENT 7.0 .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .TP .B start False If \fBTrue\fP and the container is stopped, the container will be started before attempting to freeze. .sp New in version 2015.5.0. .TP .B use_vt run the command through VT .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.freeze name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.get_container_profile(name=None, **kwargs) New in version 2015.5.0. .sp Gather a pre\-configured set of container configuration parameters. If no arguments are passed, an empty profile is returned. .sp Profiles can be defined in the minion or master config files, or in pillar or grains, and are loaded using \fI\%config.get\fP\&. The key under which LXC profiles must be configured is \fBlxc.container_profile.profile_name\fP\&. An example container profile would be as follows: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C lxc.container_profile: ubuntu: template: ubuntu backing: lvm vgname: lxc size: 1G .ft P .fi .UNINDENT .UNINDENT .sp Parameters set in a profile can be overridden by passing additional container creation arguments (such as the ones passed to \fI\%lxc.create\fP) to this function. .sp A profile can be defined either as the name of the profile, or a dictionary of variable names and values. See the \fI\%LXC Tutorial\fP for more information on how to use LXC profiles. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call lxc.get_container_profile centos salt\-call lxc.get_container_profile ubuntu template=ubuntu backing=overlayfs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.get_network_profile(name=None, **kwargs) New in version 2015.5.0. .sp Gather a pre\-configured set of network configuration parameters. If no arguments are passed, the following default profile is returned: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqeth0\(aq: {\(aqlink\(aq: \(aqbr0\(aq, \(aqtype\(aq: \(aqveth\(aq, \(aqflags\(aq: \(aqup\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp Profiles can be defined in the minion or master config files, or in pillar or grains, and are loaded using \fI\%config.get\fP\&. The key under which LXC profiles must be configured is \fBlxc.network_profile\fP\&. An example network profile would be as follows: .INDENT 7.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 To disable networking entirely: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C lxc.network_profile.centos: eth0: disable: true .ft P .fi .UNINDENT .UNINDENT .sp Parameters set in a profile can be overridden by passing additional arguments to this function. .sp A profile can be passed either as the name of the profile, or a dictionary of variable names and values. See the \fI\%LXC Tutorial\fP for more information on how to use network profiles. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The \fBipv4\fP, \fBipv6\fP, \fBgateway\fP, and \fBlink\fP (bridge) settings in network profiles will only work if the container doesn\(aqt redefine the network configuration (for example in \fB/etc/sysconfig/network\-scripts/ifcfg\-<interface_name>\fP on RHEL/CentOS, or \fB/etc/network/interfaces\fP on Debian/Ubuntu/etc.) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call lxc.get_network_profile default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.get_parameter(name, parameter, path=None) Returns the value of a cgroup parameter for a container .INDENT 7.0 .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.get_parameter container_name memory.limit_in_bytes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.get_pid(name, path=None) Returns a container pid. Throw an exception if the container isn\(aqt running. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.get_pid name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.get_root_path(path) Get the configured lxc root for containers .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.get_root_path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.images(dist=None) New in version 2015.5.0. .sp List the available images for LXC\(aqs \fBdownload\fP template. .INDENT 7.0 .TP .B dist None Filter results to a single Linux distribution .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.images salt myminion lxc.images dist=centos .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.info(name, path=None) Returns information about a container .INDENT 7.0 .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.info name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.init(name, config=None, cpuset=None, cpushare=None, memory=None, profile=None, network_profile=None, nic_opts=None, cpu=None, autostart=True, password=None, password_encrypted=None, users=None, dnsservers=None, searchdomains=None, bridge=None, gateway=None, pub_key=None, priv_key=None, force_install=False, unconditional_install=False, bootstrap_delay=None, bootstrap_args=None, bootstrap_shell=None, bootstrap_url=None, **kwargs) Initialize a new container. .sp This is a partial idempotent function as if it is already provisioned, we will reset a bit the lxc configuration file but much of the hard work will be escaped as markers will prevent re\-execution of harmful tasks. .INDENT 7.0 .TP .B name Name of the container .TP .B image A tar archive to use as the rootfs for the container. Conflicts with the \fBtemplate\fP argument. .TP .B cpus Select a random number of cpu cores and assign it to the cpuset, if the cpuset option is set then this option will be ignored .TP .B cpuset Explicitly define the cpus this container will be bound to .TP .B cpushare cgroups cpu shares .TP .B autostart autostart container on reboot .TP .B memory cgroups memory limit, in MB .sp Changed in version 2015.5.0: If no value is passed, no limit is set. In earlier Salt versions, not passing this value causes a 1024MB memory limit to be set, and it was necessary to pass \fBmemory=0\fP to set no limit. .TP .B gateway the ipv4 gateway to use the default does nothing more than lxcutils does .TP .B bridge the bridge to use the default does nothing more than lxcutils does .TP .B network_profile Network profile to use for the container .sp New in version 2015.5.0. .TP .B nic_opts Extra options for network interfaces, will override .sp \fB{\(dqeth0\(dq: {\(dqhwaddr\(dq: \(dqaa:bb:cc:dd:ee:ff\(dq, \(dqipv4\(dq: \(dq10.1.1.1\(dq, \(dqipv6\(dq: \(dq2001:db8::ff00:42:8329\(dq}}\fP .sp or .sp \fB{\(dqeth0\(dq: {\(dqhwaddr\(dq: \(dqaa:bb:cc:dd:ee:ff\(dq, \(dqipv4\(dq: \(dq10.1.1.1/24\(dq, \(dqipv6\(dq: \(dq2001:db8::ff00:42:8329\(dq}}\fP .TP .B users Users for which the password defined in the \fBpassword\fP param should be set. Can be passed as a comma separated list or a python list. Defaults to just the \fBroot\fP user. .TP .B password Set the initial password for the users defined in the \fBusers\fP parameter .TP .B password_encrypted False Set to \fBTrue\fP to denote a password hash instead of a plaintext password .sp New in version 2015.5.0. .TP .B profile A LXC profile (defined in config or pillar). This can be either a real profile mapping or a string to retrieve it in configuration .TP .B start Start the newly\-created container .TP .B dnsservers list of dns servers to set in the container, default [] (no setting) .TP .B seed Seed the container with the minion config. Default: \fBTrue\fP .TP .B install If salt\-minion is not already installed, install it. Default: \fBTrue\fP .TP .B config Optional config parameters. By default, the id is set to the name of the container. .TP .B master salt master (default to minion\(aqs master) .TP .B master_port salt master port (default to minion\(aqs master port) .TP .B pub_key Explicit public key to preseed the minion with (optional). This can be either a filepath or a string representing the key .TP .B priv_key Explicit private key to preseed the minion with (optional). This can be either a filepath or a string representing the key .TP .B approve_key If explicit preseeding is not used; Attempt to request key approval from the master. Default: \fBTrue\fP .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .TP .B clone_from Original from which to use a clone operation to create the container. Default: \fBNone\fP .TP .B bootstrap_delay Delay in seconds between end of container creation and bootstrapping. Useful when waiting for container to obtain a DHCP lease. .sp New in version 2015.5.0. .TP .B bootstrap_url See lxc.bootstrap .TP .B bootstrap_shell See lxc.bootstrap .TP .B bootstrap_args See lxc.bootstrap .TP .B force_install Force installation even if salt\-minion is detected, this is the way to run vendor bootstrap scripts even if a salt minion is already present in the container .TP .B unconditional_install Run the script even if the container seems seeded .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq lxc.init name [cpuset=cgroups_cpuset] \e [cpushare=cgroups_cpushare] [memory=cgroups_memory] \e [nic=nic_profile] [profile=lxc_profile] \e [nic_opts=nic_opts] [start=(True|False)] \e [seed=(True|False)] [install=(True|False)] \e [config=minion_config] [approve_key=(True|False) \e [clone_from=original] [autostart=True] \e [priv_key=/path_or_content] [pub_key=/path_or_content] \e [bridge=lxcbr0] [gateway=10.0.3.1] \e [dnsservers[dns1,dns2]] \e [users=[foo]] [password=\(aqsecret\(aq] \e [password_encrypted=(True|False)] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.list_(extra=False, limit=None, path=None) List containers classified by state .INDENT 7.0 .TP .B extra Also get per\-container specific info. This will change the return data. Instead of returning a list of containers, a dictionary of containers and each container\(aqs output from \fI\%lxc.info\fP\&. .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .TP .B limit Return output matching a specific state (\fBfrozen\fP, \fBrunning\fP, or \fBstopped\fP). .sp New in version 2015.5.0. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.list salt \(aq*\(aq lxc.list extra=True salt \(aq*\(aq lxc.list limit=running .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.ls_(active=None, cache=True, path=None) Return a list of the containers available on the minion .INDENT 7.0 .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .TP .B active If \fBTrue\fP, return only active (i.e. running) containers .sp New in version 2015.5.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.ls salt \(aq*\(aq lxc.ls active=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.read_conf(conf_file, out_format=\(aqsimple\(aq) Read in an LXC configuration file. By default returns a simple, unsorted dict, but can also return a more detailed structure including blank lines and comments. .INDENT 7.0 .TP .B out_format: set to \(aqsimple\(aq if you need the old and unsupported behavior. This won\(aqt support the multiple lxc values (eg: multiple network nics) .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq lxc.read_conf /etc/lxc/mycontainer.conf salt \(aqminion\(aq lxc.read_conf /etc/lxc/mycontainer.conf out_format=commented .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.reboot(name, path=None) Reboot a container. .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq lxc.reboot myvm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.reconfigure(name, cpu=None, cpuset=None, cpushare=None, memory=None, profile=None, network_profile=None, nic_opts=None, bridge=None, gateway=None, autostart=None, utsname=None, rootfs=None, path=None, **kwargs) Reconfigure a container. .sp This only applies to a few property .INDENT 7.0 .TP .B name Name of the container. .TP .B utsname utsname of the container. .sp New in version 2016.3.0. .TP .B rootfs rootfs of the container. .sp New in version 2016.3.0. .TP .B cpu Select a random number of cpu cores and assign it to the cpuset, if the cpuset option is set then this option will be ignored .TP .B cpuset Explicitly define the cpus this container will be bound to .TP .B cpushare cgroups cpu shares. .TP .B autostart autostart container on reboot .TP .B memory cgroups memory limit, in MB. (0 for nolimit, None for old default 1024MB) .TP .B gateway the ipv4 gateway to use the default does nothing more than lxcutils does .TP .B bridge the bridge to use the default does nothing more than lxcutils does .TP .B nic Network interfaces profile (defined in config or pillar). .TP .B nic_opts Extra options for network interfaces, will override .sp \fB{\(dqeth0\(dq: {\(dqmac\(dq: \(dqaa:bb:cc:dd:ee:ff\(dq, \(dqipv4\(dq: \(dq10.1.1.1\(dq, \(dqipv6\(dq: \(dq2001:db8::ff00:42:8329\(dq}}\fP .sp or .sp \fB{\(dqeth0\(dq: {\(dqmac\(dq: \(dqaa:bb:cc:dd:ee:ff\(dq, \(dqipv4\(dq: \(dq10.1.1.1/24\(dq, \(dqipv6\(dq: \(dq2001:db8::ff00:42:8329\(dq}}\fP .TP .B path path to the container parent .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-lall mc_lxc_fork.reconfigure foobar nic_opts=\(dq{\(aqeth1\(aq: {\(aqmac\(aq: \(aq00:16:3e:dd:ee:44\(aq}}\(dq memory=4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.remove(name, stop=False, path=None) This function is an alias of \fBdestroy\fP\&. .INDENT 7.0 .INDENT 3.5 Destroy the named container. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Destroys all data associated with the container. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B path path to the container parent directory (default: /var/lib/lxc) .sp New in version 2015.8.0. .TP .B stop False If \fBTrue\fP, the container will be destroyed even if it is running/frozen. .sp Changed in version 2015.5.0: Default value changed to \fBFalse\fP\&. This more closely matches the behavior of \fBlxc\-destroy(1)\fP, and also makes it less likely that an accidental command will destroy a running container that was being used for important things. .UNINDENT .sp CLI Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.destroy foo salt \(aq*\(aq lxc.destroy foo stop=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.restart(name, path=None, lxc_config=None, force=False) New in version 2015.5.0. .sp Restart the named container. If the container was not running, the container will merely be started. .INDENT 7.0 .TP .B name The name of the container .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .TP .B lxc_config path to a lxc config file config file will be guessed from container name otherwise .sp New in version 2015.8.0. .TP .B force False If \fBTrue\fP, the container will be force\-stopped instead of gracefully shut down .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.restart name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.retcode(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, path=None, ignore_retcode=False, chroot_fallback=False, keep_env=\(aqhttp_proxy,https_proxy,no_proxy\(aq) New in version 2015.5.0. .sp Run \fI\%cmd.retcode\fP within a container .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Many shell builtins do not work, failing with stderr similar to the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc_container: No such file or directory \- failed to exec \(aqcommand\(aq .ft P .fi .UNINDENT .UNINDENT .sp The same error will be displayed in stderr if the command being run does not exist. If the retcode is nonzero and not what was expected, try using \fI\%lxc.run_stderr\fP or \fI\%lxc.run_all\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the container in which to run the command .TP .B cmd Command to run .TP .B no_start False If the container is not running, don\(aqt start it .TP .B preserve_state True After running the command, return the container to its previous state .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console \fBoutput=all\fP\&. .TP .B keep_env http_proxy,https_proxy,no_proxy A list of env vars to preserve. May be passed as commma\-delimited list. .TP .B chroot_fallback if the container is not running, try to run the command using chroot default: false .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.retcode mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.run(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, path=None, ignore_retcode=False, chroot_fallback=False, keep_env=\(aqhttp_proxy,https_proxy,no_proxy\(aq) New in version 2015.8.0. .sp Run \fI\%cmd.run\fP within a container .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Many shell builtins do not work, failing with stderr similar to the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc_container: No such file or directory \- failed to exec \(aqcommand\(aq .ft P .fi .UNINDENT .UNINDENT .sp The same error will be displayed in stderr if the command being run does not exist. If no output is returned using this function, try using \fI\%lxc.run_stderr\fP or \fI\%lxc.run_all\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the container in which to run the command .TP .B cmd Command to run .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B no_start False If the container is not running, don\(aqt start it .TP .B preserve_state True After running the command, return the container to its previous state .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. Assumes \fBoutput=all\fP\&. .TP .B chroot_fallback if the container is not running, try to run the command using chroot default: false .TP .B keep_env http_proxy,https_proxy,no_proxy A list of env vars to preserve. May be passed as commma\-delimited list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.run mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.run_all(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, path=None, ignore_retcode=False, chroot_fallback=False, keep_env=\(aqhttp_proxy,https_proxy,no_proxy\(aq) New in version 2015.5.0. .sp Run \fI\%cmd.run_all\fP within a container .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 While the command is run within the container, it is initiated from the host. Therefore, the PID in the return dict is from the host, not from the container. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Many shell builtins do not work, failing with stderr similar to the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc_container: No such file or directory \- failed to exec \(aqcommand\(aq .ft P .fi .UNINDENT .UNINDENT .sp The same error will be displayed in stderr if the command being run does not exist. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the container in which to run the command .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B cmd Command to run .TP .B no_start False If the container is not running, don\(aqt start it .TP .B preserve_state True After running the command, return the container to its previous state .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console \fBoutput=all\fP\&. .TP .B keep_env http_proxy,https_proxy,no_proxy A list of env vars to preserve. May be passed as commma\-delimited list. .TP .B chroot_fallback if the container is not running, try to run the command using chroot default: false .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.run_all mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.run_stderr(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, path=None, ignore_retcode=False, chroot_fallback=False, keep_env=\(aqhttp_proxy,https_proxy,no_proxy\(aq) New in version 2015.5.0. .sp Run \fI\%cmd.run_stderr\fP within a container .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Many shell builtins do not work, failing with stderr similar to the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc_container: No such file or directory \- failed to exec \(aqcommand\(aq .ft P .fi .UNINDENT .UNINDENT .sp The same error will be displayed if the command being run does not exist. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the container in which to run the command .TP .B cmd Command to run .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B no_start False If the container is not running, don\(aqt start it .TP .B preserve_state True After running the command, return the container to its previous state .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console \fBoutput=all\fP\&. .TP .B keep_env http_proxy,https_proxy,no_proxy A list of env vars to preserve. May be passed as commma\-delimited list. .TP .B chroot_fallback if the container is not running, try to run the command using chroot default: false .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.run_stderr mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.run_stdout(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, path=None, ignore_retcode=False, chroot_fallback=False, keep_env=\(aqhttp_proxy,https_proxy,no_proxy\(aq) New in version 2015.5.0. .sp Run \fI\%cmd.run_stdout\fP within a container .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Many shell builtins do not work, failing with stderr similar to the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc_container: No such file or directory \- failed to exec \(aqcommand\(aq .ft P .fi .UNINDENT .UNINDENT .sp The same error will be displayed in stderr if the command being run does not exist. If no output is returned using this function, try using \fI\%lxc.run_stderr\fP or \fI\%lxc.run_all\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the container in which to run the command .TP .B cmd Command to run .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B no_start False If the container is not running, don\(aqt start it .TP .B preserve_state True After running the command, return the container to its previous state .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console \fBoutput=all\fP\&. .TP .B keep_env http_proxy,https_proxy,no_proxy A list of env vars to preserve. May be passed as commma\-delimited list. .TP .B chroot_fallback if the container is not running, try to run the command using chroot default: false .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.run_stdout mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.running_systemd(name, cache=True, path=None) Determine if systemD is running .INDENT 7.0 .TP .B path path to the container parent .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.running_systemd ubuntu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.search_lxc_bridge() Search the first bridge which is potentially available as LXC bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.search_lxc_bridge .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.search_lxc_bridges() Search which bridges are potentially available as LXC bridges .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.search_lxc_bridges .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.set_dns(name, dnsservers=None, searchdomains=None, path=None) Changed in version 2015.5.0: The \fBdnsservers\fP and \fBsearchdomains\fP parameters can now be passed as a comma\-separated list. .sp Update /etc/resolv.confo .sp path .INDENT 7.0 .INDENT 3.5 path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.set_dns ubuntu \(dq[\(aq8.8.8.8\(aq, \(aq4.4.4.4\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.set_parameter(name, parameter, value, path=None) Set the value of a cgroup parameter for a container. .INDENT 7.0 .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.set_parameter name parameter value .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.set_pass(name, users, password, encrypted=True, path=None) This function is an alias of \fBset_password\fP\&. .INDENT 7.0 .INDENT 3.5 Changed in version 2015.5.0: Function renamed from \fBset_pass\fP to \fBset_password\fP\&. Additionally, this function now supports (and defaults to using) a password hash instead of a plaintext password. .sp Set the password of one or more system users inside containers .INDENT 0.0 .TP .B users Comma\-separated list (or python list) of users to change password .TP .B password Password to set for the specified user(s) .TP .B encrypted True If true, \fBpassword\fP must be a password hash. Set to \fBFalse\fP to set a plaintext password (not recommended). .sp New in version 2015.5.0. .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.set_pass container\-name root \(aq$6$uJ2uAyLU$KoI67t8As/0fXtJOPcHKGXmUpcoYUcVR2K6x93walnShTCQvjRwq25yIkiCBOqgbfdKQSFnAo28/ek6716vEV1\(aq salt \(aq*\(aq lxc.set_pass container\-name root foo encrypted=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.set_password(name, users, password, encrypted=True, path=None) Changed in version 2015.5.0: Function renamed from \fBset_pass\fP to \fBset_password\fP\&. Additionally, this function now supports (and defaults to using) a password hash instead of a plaintext password. .sp Set the password of one or more system users inside containers .INDENT 7.0 .TP .B users Comma\-separated list (or python list) of users to change password .TP .B password Password to set for the specified user(s) .TP .B encrypted True If true, \fBpassword\fP must be a password hash. Set to \fBFalse\fP to set a plaintext password (not recommended). .sp New in version 2015.5.0. .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.set_pass container\-name root \(aq$6$uJ2uAyLU$KoI67t8As/0fXtJOPcHKGXmUpcoYUcVR2K6x93walnShTCQvjRwq25yIkiCBOqgbfdKQSFnAo28/ek6716vEV1\(aq salt \(aq*\(aq lxc.set_pass container\-name root foo encrypted=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.start(name, **kwargs) Start the named container .INDENT 7.0 .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .TP .B lxc_config path to a lxc config file config file will be guessed from container name otherwise .sp New in version 2015.8.0. .TP .B use_vt run the command through VT .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.start name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.state(name, path=None) Returns the state of a container. .INDENT 7.0 .TP .B path path to the container parent directory (default: /var/lib/lxc) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.state name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.stop(name, kill=False, path=None, use_vt=None) Stop the named container .INDENT 7.0 .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .TP .B kill: False Do not wait for the container to stop, kill all tasks in the container. Older LXC versions will stop containers like this irrespective of this argument. .sp Changed in version 2015.5.0: Default value changed to \fBFalse\fP .TP .B use_vt run the command through VT .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.stop name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.systemd_running_state(name, path=None) Get the operational state of a systemd based container .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.systemd_running_state ubuntu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.templates() New in version 2015.5.0. .sp List the available LXC template scripts installed on the minion .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.templates .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.test_bare_started_state(name, path=None) Test if a non systemd container is fully started For now, it consists only to test if the container is attachable .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.test_bare_started_state ubuntu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.test_sd_started_state(name, path=None) Test if a systemd container is fully started .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.test_sd_started_state ubuntu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.unfreeze(name, path=None, use_vt=None) Unfreeze the named container. .INDENT 7.0 .TP .B path path to the container parent directory default: /var/lib/lxc (system) .sp New in version 2015.8.0. .TP .B use_vt run the command through VT .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.unfreeze name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.update_lxc_conf(name, lxc_conf, lxc_conf_unset, path=None) Edit LXC configuration options .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.update_lxc_conf ubuntu \e lxc_conf=\(dq[{\(aqnetwork.ipv4.ip\(aq:\(aq10.0.3.5\(aq}]\(dq \e lxc_conf_unset=\(dq[\(aqlxc.utsname\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.version() Return the actual lxc client version .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxc.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.wait_started(name, path=None, timeout=300) Check that the system has fully inited .sp This is actually very important for systemD based containers .sp see \fI\%https://github.com/saltstack/salt/issues/23847\fP .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.wait_started ubuntu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxc.write_conf(conf_file, conf) Write out an LXC configuration file .sp This is normally only used internally. The format of the data structure must match that which is returned from \fBlxc.read_conf()\fP, with \fBout_format\fP set to \fBcommented\fP\&. .sp An example might look like: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ {\(aqlxc.utsname\(aq: \(aq$CONTAINER_NAME\(aq}, \(aq# This is a commented line\en\(aq, \(aq\en\(aq, {\(aqlxc.mount\(aq: \(aq$CONTAINER_FSTAB\(aq}, {\(aqlxc.rootfs\(aq: {\(aqcomment\(aq: \(aqThis is another test\(aq, \(aqvalue\(aq: \(aqThis is another test\(aq}}, \(aq\en\(aq, {\(aqlxc.network.type\(aq: \(aqveth\(aq}, {\(aqlxc.network.flags\(aq: \(aqup\(aq}, {\(aqlxc.network.link\(aq: \(aqbr0\(aq}, {\(aqlxc.network.mac\(aq: \(aq$CONTAINER_MACADDR\(aq}, {\(aqlxc.network.ipv4\(aq: \(aq$CONTAINER_IPADDR\(aq}, {\(aqlxc.network.name\(aq: \(aq$CONTAINER_DEVICENAME\(aq}, ] .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq lxc.write_conf /etc/lxc/mycontainer.conf \e out_format=commented .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.lxd .sp Module for managing the LXD daemon and its containers. .sp New in version 2019.2.0. .sp \fI\%LXD(1)\fP is a container \(dqhypervisor\(dq. This execution module provides several functions to help manage it and its containers. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%pylxd(2)\fP version >=2.2.5 is required to let this work, currently only available via pip. .INDENT 2.0 .INDENT 3.5 To install on Ubuntu: .sp $ apt\-get install libssl\-dev python\-pip $ pip install \-U pylxd .UNINDENT .UNINDENT .IP \(bu 2 you need lxd installed on the minion for the init() and version() methods. .IP \(bu 2 for the config_get() and config_get() methods you need to have lxd\-client installed. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B maintainer René Jochum <\fI\%rene@jochums.at\fP> .TP .B maturity new .TP .B depends python\-pylxd .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.authenticate(remote_addr, password, cert, key, verify_cert=True) Authenticate with a remote LXDaemon. .INDENT 7.0 .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP .UNINDENT .TP .B password : The password of the remote. .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.authenticate https://srv01:8443 <yourpass> ~/.config/lxc/client.crt ~/.config/lxc/client.key false .ft P .fi .UNINDENT .UNINDENT .sp See the \fI\%requests\-docs\fP for the SSL stuff. .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.config_get(key) Get an LXD daemon config option .INDENT 7.0 .TP .B key : The key of the config value to retrieve .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.config_get core.https_address .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.config_set(key, value) Set an LXD daemon config option .sp CLI Examples: .sp To listen on IPv4 and IPv6 port 8443, you can omit the :8443 its the default: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.config_set core.https_address [::]:8443 .ft P .fi .UNINDENT .UNINDENT .sp To set the server trust password: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.config_set core.trust_password blah .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_config_delete(name, config_key, remote_addr=None, cert=None, key=None, verify_cert=True) Delete a container config value .INDENT 7.0 .TP .B name : Name of the container .TP .B config_key : The config key to delete .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_config_get(name, config_key, remote_addr=None, cert=None, key=None, verify_cert=True) Get a container config value .INDENT 7.0 .TP .B name : Name of the container .TP .B config_key : The config key to retrieve .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_config_set(name, config_key, config_value, remote_addr=None, cert=None, key=None, verify_cert=True) Set a container config value .INDENT 7.0 .TP .B name : Name of the container .TP .B config_key : The config key to set .TP .B config_value : The config value to set .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_create(name, source, profiles=None, config=None, devices=None, architecture=\(aqx86_64\(aq, ephemeral=False, wait=True, remote_addr=None, cert=None, key=None, verify_cert=True, _raw=False) Create a container .INDENT 7.0 .TP .B name : The name of the container .TP .B source : .INDENT 7.0 .TP .B Can be either a string containing an image alias: \(dqxenial/amd64\(dq .TP .B or an dict with type \(dqimage\(dq with alias: .INDENT 7.0 .TP .B {\(dqtype\(dq: \(dqimage\(dq, \(dqalias\(dq: \(dqxenial/amd64\(dq} .UNINDENT .TP .B or image with \(dqfingerprint\(dq: .INDENT 7.0 .TP .B {\(dqtype\(dq: \(dqimage\(dq, \(dqfingerprint\(dq: \(dqSHA\-256\(dq} .UNINDENT .TP .B or image with \(dqproperties\(dq: .INDENT 7.0 .TP .B {\(dqtype\(dq: \(dqimage\(dq, .INDENT 7.0 .TP .B \(dqproperties\(dq: { \(dqos\(dq: \(dqubuntu\(dq, \(dqrelease\(dq: \(dq14.04\(dq, \(dqarchitecture\(dq: \(dqx86_64\(dq}} .UNINDENT .UNINDENT .TP .B or none: {\(dqtype\(dq: \(dqnone\(dq} .TP .B or copy: .INDENT 7.0 .TP .B {\(dqtype\(dq: \(dqcopy\(dq, \(dqsource\(dq: \(dqmy\-old\-container\(dq} .UNINDENT .UNINDENT .TP .B profiles [\(aqdefault\(aq] List of profiles to apply on this container .TP .B config : A config dict or None (None = unset). .INDENT 7.0 .TP .B Can also be a list: .INDENT 7.0 .TP .B [{\(aqkey\(aq: \(aqboot.autostart\(aq, \(aqvalue\(aq: 1}, {\(aqkey\(aq: \(aqsecurity.privileged\(aq, \(aqvalue\(aq: \(aq1\(aq}] .UNINDENT .UNINDENT .TP .B devices : A device dict or None (None = unset). .TP .B architecture \(aqx86_64\(aq.INDENT 7.0 .TP .B Can be one of the following: .INDENT 7.0 .IP \(bu 2 unknown .IP \(bu 2 i686 .IP \(bu 2 x86_64 .IP \(bu 2 armv7l .IP \(bu 2 aarch64 .IP \(bu 2 ppc .IP \(bu 2 ppc64 .IP \(bu 2 ppc64le .IP \(bu 2 s390x .UNINDENT .UNINDENT .TP .B ephemeral False Destroy this container after stop? .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .TP .B _raw False Return the raw pyxld object or a dict? .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.container_create test xenial/amd64 .ft P .fi .UNINDENT .UNINDENT .sp See also the \fI\%rest\-api\-docs\fP\&. .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_delete(name, remote_addr=None, cert=None, key=None, verify_cert=True) Delete a container .INDENT 7.0 .TP .B name : Name of the container to delete .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_device_add(name, device_name, device_type=\(aqdisk\(aq, remote_addr=None, cert=None, key=None, verify_cert=True, **kwargs) Add a container device .INDENT 7.0 .TP .B name : Name of the container .TP .B device_name : The device name to add .TP .B device_type : Type of the device .TP .B ** kwargs : Additional device args .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_device_delete(name, device_name, remote_addr=None, cert=None, key=None, verify_cert=True) Delete a container device .INDENT 7.0 .TP .B name : Name of the container .TP .B device_name : The device name to delete .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_device_get(name, device_name, remote_addr=None, cert=None, key=None, verify_cert=True) Get a container device .INDENT 7.0 .TP .B name : Name of the container .TP .B device_name : The device name to retrieve .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_execute(name, cmd, remote_addr=None, cert=None, key=None, verify_cert=True) Execute a command list on a container. .INDENT 7.0 .TP .B name : Name of the container .TP .B cmd : Command to be executed (as a list) .INDENT 7.0 .TP .B Example : \(aq[\(dqls\(dq, \(dq\-l\(dq]\(aq .UNINDENT .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.container_execute <container name> \(aq[\(dqls\(dq, \(dq\-l\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_file_get(name, src, dst, overwrite=False, mode=None, uid=None, gid=None, remote_addr=None, cert=None, key=None, verify_cert=True) Get a file from a container .INDENT 7.0 .TP .B name : Name of the container .TP .B src : The source file or directory .TP .B dst : The destination file or directory .TP .B mode : Set file mode to octal number .TP .B uid : Set file uid (owner) .TP .B gid : Set file gid (group) .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_file_put(name, src, dst, recursive=False, overwrite=False, mode=None, uid=None, gid=None, saltenv=\(aqbase\(aq, remote_addr=None, cert=None, key=None, verify_cert=True) Put a file into a container .INDENT 7.0 .TP .B name : Name of the container .TP .B src : The source file or directory .TP .B dst : The destination file or directory .TP .B recursive : Decent into src directory .TP .B overwrite : Replace destination if it exists .TP .B mode : Set file mode to octal number .TP .B uid : Set file uid (owner) .TP .B gid : Set file gid (group) .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.container_file_put <container name> /var/tmp/foo /var/tmp/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_freeze(name, remote_addr=None, cert=None, key=None, verify_cert=True) Freeze a container .INDENT 7.0 .TP .B name : Name of the container to freeze .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_get(name=None, remote_addr=None, cert=None, key=None, verify_cert=True, _raw=False) Gets a container from the LXD .INDENT 7.0 .TP .B name : The name of the container to get. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .TP .B _raw : Return the pylxd object, this is internal and by states in use. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_list(list_names=False, remote_addr=None, cert=None, key=None, verify_cert=True) Lists containers .INDENT 7.0 .TP .B list_names False Only return a list of names when True .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Examples: .sp Full dict with all available information: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.container_list .ft P .fi .UNINDENT .UNINDENT .sp For a list of names: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.container_list true .ft P .fi .UNINDENT .UNINDENT .sp See also \fI\%container\-attributes\fP\&. .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_migrate(name, stop_and_start=False, remote_addr=None, cert=None, key=None, verify_cert=True, src_remote_addr=None, src_cert=None, src_key=None, src_verify_cert=None) Migrate a container. .sp If the container is running, it either must be shut down first (use stop_and_start=True) or criu must be installed on the source and destination machines. .sp For this operation both certs need to be authenticated, use \fBlxd.authenticate <salt.modules.lxd.authenticate\fP to authenticate your cert(s). .INDENT 7.0 .TP .B name : Name of the container to migrate .TP .B stop_and_start : Stop the container on the source and start it on dest .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Authorize salt \(aq*\(aq lxd.authenticate https://srv01:8443 <yourpass> ~/.config/lxc/client.crt ~/.config/lxc/client.key false salt \(aq*\(aq lxd.authenticate https://srv02:8443 <yourpass> ~/.config/lxc/client.crt ~/.config/lxc/client.key false # Migrate phpmyadmin from srv01 to srv02 salt \(aq*\(aq lxd.container_migrate phpmyadmin stop_and_start=true remote_addr=https://srv02:8443 cert=~/.config/lxc/client.crt key=~/.config/lxc/client.key verify_cert=False src_remote_addr=https://srv01:8443 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_rename(name, newname, remote_addr=None, cert=None, key=None, verify_cert=True) Rename a container .INDENT 7.0 .TP .B name : Name of the container to Rename .TP .B newname : The new name of the container .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_restart(name, remote_addr=None, cert=None, key=None, verify_cert=True) Restart a container .INDENT 7.0 .TP .B name : Name of the container to restart .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_start(name, remote_addr=None, cert=None, key=None, verify_cert=True) Start a container .INDENT 7.0 .TP .B name : Name of the container to start .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_state(name=None, remote_addr=None, cert=None, key=None, verify_cert=True) Get container state .INDENT 7.0 .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_stop(name, timeout=30, force=True, remote_addr=None, cert=None, key=None, verify_cert=True) Stop a container .INDENT 7.0 .TP .B name : Name of the container to stop .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.container_unfreeze(name, remote_addr=None, cert=None, key=None, verify_cert=True) Unfreeze a container .INDENT 7.0 .TP .B name : Name of the container to unfreeze .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.image_alias_add(image, alias, description=\(aq\(aq, remote_addr=None, cert=None, key=None, verify_cert=True) Create an alias on the given image .INDENT 7.0 .TP .B image : An image alias, a fingerprint or a image object .TP .B alias : The alias to add .TP .B description : Description of the alias .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.image_alias_add xenial/amd64 x \(dqShort version of xenial/amd64\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.image_alias_delete(image, alias, remote_addr=None, cert=None, key=None, verify_cert=True) Delete an alias (this is currently not restricted to the image) .INDENT 7.0 .TP .B image : An image alias, a fingerprint or a image object .TP .B alias : The alias to delete .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.image_alias_add xenial/amd64 x \(dqShort version of xenial/amd64\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.image_copy_lxd(source, src_remote_addr, src_cert, src_key, src_verify_cert, remote_addr, cert, key, verify_cert=True, aliases=None, public=None, auto_update=None, _raw=False) Copy an image from another LXD instance .INDENT 7.0 .TP .B source : An alias or a fingerprint of the source. .TP .B src_remote_addr : An URL to the source remote daemon .INDENT 7.0 .TP .B Examples: \fI\%https://mysourceserver.lan:8443\fP .UNINDENT .TP .B src_cert : PEM Formatted SSL Certificate for the source .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B src_key : PEM Formatted SSL Key for the source .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B src_verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .TP .B remote_addr : Address of the destination daemon .INDENT 7.0 .TP .B Examples: \fI\%https://mydestserver.lan:8443\fP .UNINDENT .TP .B cert : PEM Formatted SSL Certificate for the destination .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key for the destination .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .TP .B aliases [] List of aliases to append to the copied image .TP .B public None Make this image public available, None = copy source .TP .B auto_update None Wherever to auto\-update from the original source, None = copy source .TP .B _raw False Return the raw pylxd object or a dict of the destination image? .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.image_copy_lxd xenial/amd64 https://srv01:8443 ~/.config/lxc/client.crt ~/.config/lxc/client.key false https://srv02:8443 ~/.config/lxc/client.crt ~/.config/lxc/client.key false aliases=\(dq[\(aqxenial/amd64\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.image_delete(image, remote_addr=None, cert=None, key=None, verify_cert=True) Delete an image by an alias or fingerprint .INDENT 7.0 .TP .B name : The alias or fingerprint of the image to delete, can be a obj for the states. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.image_delete xenial/amd64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.image_from_file(filename, remote_addr=None, cert=None, key=None, verify_cert=True, aliases=None, public=False, saltenv=\(aqbase\(aq, _raw=False) Create an image from a file .INDENT 7.0 .TP .B filename : The filename of the rootfs .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .TP .B aliases [] List of aliases to append to the copied image .TP .B public False Make this image public available .TP .B saltenv base The saltenv to use for salt:// copies .TP .B _raw False Return the raw pylxd object or a dict of the image? .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.image_from_file salt://lxd/files/busybox.tar.xz aliases=[\(dqbusybox\-amd64\(dq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.image_from_simplestreams(server, alias, remote_addr=None, cert=None, key=None, verify_cert=True, aliases=None, public=False, auto_update=False, _raw=False) Create an image from simplestreams .INDENT 7.0 .TP .B server : Simplestreams server URI .TP .B alias : The alias of the image to retrieve .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .TP .B aliases [] List of aliases to append to the copied image .TP .B public False Make this image public available .TP .B auto_update False Should LXD auto update that image? .TP .B _raw False Return the raw pylxd object or a dict of the image? .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.image_from_simplestreams \(dqhttps://cloud\-images.ubuntu.com/releases\(dq \(dqtrusty/amd64\(dq aliases=\(aq[\(dqt\(dq, \(dqtrusty/amd64\(dq]\(aq auto_update=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.image_from_url(url, remote_addr=None, cert=None, key=None, verify_cert=True, aliases=None, public=False, auto_update=False, _raw=False) Create an image from an url .INDENT 7.0 .TP .B url : The URL from where to download the image .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .TP .B aliases [] List of aliases to append to the copied image .TP .B public False Make this image public available .TP .B auto_update False Should LXD auto update that image? .TP .B _raw False Return the raw pylxd object or a dict of the image? .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.image_from_url https://dl.stgraber.org/lxd aliases=\(aq[\(dqbusybox\-amd64\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.image_get(fingerprint, remote_addr=None, cert=None, key=None, verify_cert=True, _raw=False) Get an image by its fingerprint .INDENT 7.0 .TP .B fingerprint : The fingerprint of the image to retrieve .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .TP .B _raw False Return the raw pylxd object or a dict of it? .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.image_get <fingerprint> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.image_get_by_alias(alias, remote_addr=None, cert=None, key=None, verify_cert=True, _raw=False) Get an image by an alias .INDENT 7.0 .TP .B alias : The alias of the image to retrieve .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .TP .B _raw False Return the raw pylxd object or a dict of it? .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.image_get_by_alias xenial/amd64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.image_list(list_aliases=False, remote_addr=None, cert=None, key=None, verify_cert=True) Lists all images from the LXD. .sp list_aliases : .INDENT 7.0 .INDENT 3.5 Return a dict with the fingerprint as key and a list of aliases as value instead. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.image_list true \-\-out=json salt \(aq*\(aq lxd.image_list \-\-out=json .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.init(storage_backend=\(aqdir\(aq, trust_password=None, network_address=None, network_port=None, storage_create_device=None, storage_create_loop=None, storage_pool=None) Calls lxd init \-\-auto \-\- opts .INDENT 7.0 .TP .B storage_backend : Storage backend to use (zfs or dir, default: dir) .TP .B trust_password : Password required to add new clients .TP .B network_address None Address to bind LXD to (default: none) .TP .B network_port None Port to bind LXD to (Default: 8443) .TP .B storage_create_device None Setup device based storage using this DEVICE .TP .B storage_create_loop None Setup loop based storage with this SIZE in GB .TP .B storage_pool None Storage pool to use or create .UNINDENT .sp CLI Examples: .sp To listen on all IPv4/IPv6 Addresses: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.init dir PaSsW0rD [::] .ft P .fi .UNINDENT .UNINDENT .sp To not listen on Network: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.init .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.normalize_input_values(config, devices) normalize config input so returns can be put into mongodb, which doesn\(aqt like \fI\&.\fP .sp This is not meant to be used on the commandline. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.normalize_input_values config={} devices={} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.profile_config_delete(name, config_key, remote_addr=None, cert=None, key=None, verify_cert=True) Delete a profile config item. .INDENT 7.0 .TP .B name : The name of the profile to delete the config item. .TP .B config_key : The config key for the value to retrieve. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.profile_config_delete autostart boot.autostart.delay .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.profile_config_get(name, config_key, remote_addr=None, cert=None, key=None, verify_cert=True) Get a profile config item. .INDENT 7.0 .TP .B name : The name of the profile to get the config item from. .TP .B config_key : The key for the item to retrieve. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.profile_config_get autostart boot.autostart .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.profile_config_set(name, config_key, config_value, remote_addr=None, cert=None, key=None, verify_cert=True) Set a profile config item. .INDENT 7.0 .TP .B name : The name of the profile to set the config item to. .TP .B config_key : The items key. .TP .B config_value : Its items value. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.profile_config_set autostart boot.autostart 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.profile_create(name, config=None, devices=None, description=None, remote_addr=None, cert=None, key=None, verify_cert=True) Creates a profile. .INDENT 7.0 .TP .B name : The name of the profile to get. .TP .B config : A config dict or None (None = unset). .INDENT 7.0 .TP .B Can also be a list: .INDENT 7.0 .TP .B [{\(aqkey\(aq: \(aqboot.autostart\(aq, \(aqvalue\(aq: 1}, {\(aqkey\(aq: \(aqsecurity.privileged\(aq, \(aqvalue\(aq: \(aq1\(aq}] .UNINDENT .UNINDENT .TP .B devices : A device dict or None (None = unset). .TP .B description : A description string or None (None = unset). .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.profile_create autostart config=\(dq{boot.autostart: 1, boot.autostart.delay: 2, boot.autostart.priority: 1}\(dq salt \(aq*\(aq lxd.profile_create shared_mounts devices=\(dq{shared_mount: {type: \(aqdisk\(aq, source: \(aq/home/shared\(aq, path: \(aq/home/shared\(aq}}\(dq .ft P .fi .UNINDENT .UNINDENT .sp See the \fI\%lxd\-docs\fP for the details about the config and devices dicts. .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.profile_delete(name, remote_addr=None, cert=None, key=None, verify_cert=True) Deletes a profile. .INDENT 7.0 .TP .B name : The name of the profile to delete. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.profile_delete shared_mounts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.profile_device_delete(name, device_name, remote_addr=None, cert=None, key=None, verify_cert=True) Delete a profile device. .INDENT 7.0 .TP .B name : The name of the profile to delete the device. .TP .B device_name : The name of the device to delete. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.profile_device_delete autostart eth1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.profile_device_get(name, device_name, remote_addr=None, cert=None, key=None, verify_cert=True) Get a profile device. .INDENT 7.0 .TP .B name : The name of the profile to get the device from. .TP .B device_name : The name of the device to retrieve. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.profile_device_get default eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.profile_device_set(name, device_name, device_type=\(aqdisk\(aq, remote_addr=None, cert=None, key=None, verify_cert=True, **kwargs) Set a profile device. .INDENT 7.0 .TP .B name : The name of the profile to set the device to. .TP .B device_name : The name of the device to set. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.profile_device_set autostart eth1 nic nictype=bridged parent=lxdbr0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.profile_get(name, remote_addr=None, cert=None, key=None, verify_cert=True, _raw=False) Gets a profile from the LXD .INDENT 7.0 .TP .B name : The name of the profile to get. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .TP .B _raw : Return the pylxd object, this is internal and by states in use. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.profile_get autostart .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.profile_list(list_names=False, remote_addr=None, cert=None, key=None, verify_cert=True) Lists all profiles from the LXD. .sp list_names : .INDENT 7.0 .INDENT 3.5 Return a list of names instead of full blown dicts. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.profile_list true \-\-out=json salt \(aq*\(aq lxd.profile_list \-\-out=json .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.pylxd_client_get(remote_addr=None, cert=None, key=None, verify_cert=True) Get an pyxld client, this is not meant to be run over the CLI. .INDENT 7.0 .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr and its a TCP Address! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp See the \fI\%requests\-docs\fP for the SSL stuff. .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.pylxd_save_object(obj) .INDENT 7.0 .TP .B Saves an object (profile/image/container) and translate its execpetion on failure .TP .B obj : The object to save .UNINDENT .sp This is an internal method, no CLI Example. .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.pylxd_version() Returns the actual pylxd version. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.pylxd_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.snapshots_all(container, remote_addr=None, cert=None, key=None, verify_cert=True) Get all snapshots for a container .INDENT 7.0 .TP .B container : The name of the container to get. .TP .B remote_addr : An URL to a remote server. The \(aqcert\(aq and \(aqkey\(aq fields must also be provided if \(aqremote_addr\(aq is defined. .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Verify the ssl certificate. Default: True .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.snapshots_all test\-container .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.snapshots_create(container, name=None, remote_addr=None, cert=None, key=None, verify_cert=True) Create a snapshot for a container .INDENT 7.0 .TP .B container : The name of the container to get. .TP .B name : The name of the snapshot. .TP .B remote_addr : An URL to a remote server. The \(aqcert\(aq and \(aqkey\(aq fields must also be provided if \(aqremote_addr\(aq is defined. .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Verify the ssl certificate. Default: True .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.snapshots_create test\-container test\-snapshot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.snapshots_delete(container, name, remote_addr=None, cert=None, key=None, verify_cert=True) Delete a snapshot for a container .INDENT 7.0 .TP .B container : The name of the container to get. .TP .B name : The name of the snapshot. .TP .B remote_addr : An URL to a remote server. The \(aqcert\(aq and \(aqkey\(aq fields must also be provided if \(aqremote_addr\(aq is defined. .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Verify the ssl certificate. Default: True .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.snapshots_delete test\-container test\-snapshot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.snapshots_get(container, name, remote_addr=None, cert=None, key=None, verify_cert=True) Get information about snapshot for a container .INDENT 7.0 .TP .B container : The name of the container to get. .TP .B name : The name of the snapshot. .TP .B remote_addr : An URL to a remote server. The \(aqcert\(aq and \(aqkey\(aq fields must also be provided if \(aqremote_addr\(aq is defined. .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Certificate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Verify the ssl certificate. Default: True .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.snapshots_get test\-container test\-snapshot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.sync_config_devices(obj, newconfig, newdevices, test=False) Syncs the given config and devices with the object (a profile or a container) returns a changes dict with all changes made. .INDENT 7.0 .TP .B obj : The object to sync with / or just test with. .TP .B newconfig: The new config to check with the obj. .TP .B newdevices: The new devices to check with the obj. .TP .B test: Wherever to not change anything and give \(dqWould change\(dq message. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.lxd.version() Returns the actual lxd version. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lxd.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_assistive .sp This module allows you to manage assistive access on macOS minions with 10.9+ .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq assistive.install /usr/bin/osascript .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.mac_assistive.TccDB(path=None) .INDENT 7.0 .TP .B disable(app_id) .UNINDENT .INDENT 7.0 .TP .B enable(app_id) .UNINDENT .INDENT 7.0 .TP .B enabled(app_id) .UNINDENT .INDENT 7.0 .TP .B install(app_id, enable=True) .UNINDENT .INDENT 7.0 .TP .B installed(app_id) .UNINDENT .INDENT 7.0 .TP .B remove(app_id) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_assistive.enable_(app_id, enabled=True) Enable or disable an existing assistive access application. .INDENT 7.0 .TP .B app_id The bundle ID or command to set assistive access status. .TP .B enabled Sets enabled or disabled status. Default is \fBTrue\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq assistive.enable /usr/bin/osascript salt \(aq*\(aq assistive.enable com.smileonmymac.textexpander enabled=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_assistive.enabled(app_id) Check if a bundle ID or command is listed in assistive access and enabled. .INDENT 7.0 .TP .B app_id The bundle ID or command to retrieve assistive access status. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq assistive.enabled /usr/bin/osascript salt \(aq*\(aq assistive.enabled com.smileonmymac.textexpander .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_assistive.install(app_id, enable=True, tries=3, wait=10) Install a bundle ID or command as being allowed to use assistive access. .INDENT 7.0 .TP .B app_id The bundle ID or command to install for assistive access. .TP .B enabled Sets enabled or disabled status. Default is \fBTrue\fP\&. .TP .B tries How many times to try and write to a read\-only tcc. Default is \fBTrue\fP\&. .TP .B wait Number of seconds to wait between tries. Default is \fB10\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq assistive.install /usr/bin/osascript salt \(aq*\(aq assistive.install com.smileonmymac.textexpander .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_assistive.installed(app_id) Check if a bundle ID or command is listed in assistive access. This will not check to see if it\(aqs enabled. .INDENT 7.0 .TP .B app_id The bundle ID or command to check installed status. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq assistive.installed /usr/bin/osascript salt \(aq*\(aq assistive.installed com.smileonmymac.textexpander .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_assistive.remove(app_id) Remove a bundle ID or command as being allowed to use assistive access. .INDENT 7.0 .TP .B app_id The bundle ID or command to remove from assistive access list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq assistive.remove /usr/bin/osascript salt \(aq*\(aq assistive.remove com.smileonmymac.textexpander .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_brew_pkg .sp Homebrew for macOS .sp It is recommended for the \fBsalt\-minion\fP to have the \fBHOMEBREW_PREFIX\fP environment variable set. .sp This will ensure that Salt uses the correct path for the \fBbrew\fP binary. .sp Typically, this is set to \fB/usr/local\fP for Intel Macs and \fB/opt/homebrew\fP for Apple Silicon Macs. .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.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 .sp Currently chooses stable versions, falling back to devel if that does not exist. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.hold(name=None, pkgs=None, sources=None, **kwargs) Set package in \(aqhold\(aq state, meaning it will not be upgraded. .sp New in version 3001. .INDENT 7.0 .TP .B name The name of the package, e.g., \(aqtmux\(aq .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.hold <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B pkgs A list of packages to hold. Must be passed as a python list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.hold pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.homebrew_prefix() Returns the full path to the homebrew prefix. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.homebrew_prefix .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.info_installed(*names, **kwargs) Return the information of the named package(s) installed on the system. .sp New in version 2016.3.1. .INDENT 7.0 .TP .B names The names of the packages for which to return information. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.info_installed <package1> salt \(aq*\(aq pkg.info_installed <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.install(name=None, pkgs=None, taps=None, options=None, **kwargs) Install the passed package(s) with \fBbrew install\fP .INDENT 7.0 .TP .B name The name of the formula to be installed. Note that this parameter is ignored if \(dqpkgs\(dq is passed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B taps Unofficial GitHub repos to use when updating and installing formulas. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> tap=\(aq<tap>\(aq salt \(aq*\(aq pkg.install zlib taps=\(aqhomebrew/dupes\(aq salt \(aq*\(aq pkg.install php54 taps=\(aq[\(dqjosegonzalez/php\(dq, \(dqhomebrew/dupes\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B options Options to pass to brew. Only applies to initial install. Due to how brew works, modifying chosen options requires a full uninstall followed by a fresh install. Note that if \(dqpkgs\(dq is used, all options will be passed to all packages. Unrecognized options for a package will be silently ignored by brew. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> tap=\(aq<tap>\(aq salt \(aq*\(aq pkg.install php54 taps=\(aq[\(dqjosegonzalez/php\(dq, \(dqhomebrew/dupes\(dq]\(aq options=\(aq[\(dq\-\-with\-fpm\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of formulas to install. Must be passed as a python list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq,\(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install \(aqpackage package package\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.latest_version(*names, **kwargs) Return the latest version of the named package available for upgrade or installation .sp Currently chooses stable versions, falling back to devel if that does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.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<package_name>\(aq: \(aq<version>\(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.mac_brew_pkg.list_upgrades(refresh=True, include_casks=False, **kwargs) Check whether or not an upgrade is available for all packages .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.pin(name=None, pkgs=None, sources=None, **kwargs) Set package in \(aqhold\(aq state, meaning it will not be upgraded. .sp New in version 3001. .INDENT 7.0 .TP .B name The name of the package, e.g., \(aqtmux\(aq .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.hold <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B pkgs A list of packages to hold. Must be passed as a python list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.hold pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.refresh_db(**kwargs) Update the homebrew package repository. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.remove(name=None, pkgs=None, **kwargs) Removes packages with \fBbrew uninstall\fP\&. .INDENT 7.0 .TP .B name The name of the package to be deleted. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to delete. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .UNINDENT .sp New in version 0.16.0. .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.unhold(name=None, pkgs=None, sources=None, **kwargs) Set package current in \(aqhold\(aq state to install state, meaning it will be upgraded. .sp New in version 3001. .INDENT 7.0 .TP .B name .INDENT 7.0 .INDENT 3.5 The name of the package, e.g., \(aqtmux\(aq .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unhold <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B pkgs A list of packages to unhold. Must be passed as a python list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unhold pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.unpin(name=None, pkgs=None, sources=None, **kwargs) Set package current in \(aqhold\(aq state to install state, meaning it will be upgraded. .sp New in version 3001. .INDENT 7.0 .TP .B name .INDENT 7.0 .INDENT 3.5 The name of the package, e.g., \(aqtmux\(aq .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unhold <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B pkgs A list of packages to unhold. Must be passed as a python list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unhold pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.upgrade(refresh=True, **kwargs) Upgrade outdated, unpinned brews. .INDENT 7.0 .TP .B refresh Fetch the newest version of Homebrew and all formulae from GitHub before installing. .UNINDENT .sp Returns a dictionary containing the changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.upgrade_available(pkg, **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 <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_brew_pkg.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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_desktop .sp macOS implementations of various commands in the \(dqdesktop\(dq interface .INDENT 0.0 .TP .B salt.modules.mac_desktop.get_output_volume() Get the output volume (range 0 to 100) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq desktop.get_output_volume .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_desktop.lock() Lock the desktop session .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq desktop.lock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_desktop.say(*words) Say some words. .INDENT 7.0 .TP .B words The words to execute the say command with. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq desktop.say <word0> <word1> ... <wordN> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_desktop.screensaver() Launch the screensaver. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq desktop.screensaver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_desktop.set_output_volume(volume) Set the volume of sound. .INDENT 7.0 .TP .B volume The level of volume. Can range from 0 to 100. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq desktop.set_output_volume <volume> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_group .sp Manage groups on Mac OS 10.7+ .INDENT 0.0 .TP .B salt.modules.mac_group.add(name, gid=None, **kwargs) Changed in version 3006.0. .sp Add the specified group .INDENT 7.0 .TP .B name Name of the new group .TP .B gid Use GID for the new group .UNINDENT .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.mac_group.adduser(group, name) 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.mac_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.mac_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.mac_group.deluser(group, name) Remove a user from the group .sp New in version 2016.3.0. .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.mac_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.mac_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.mac_group.members(name, members_list) Replaces members of the group with a provided list. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.members foo \(aquser1,user2,user3,...\(aq .ft P .fi .UNINDENT .UNINDENT .sp Replaces a membership list for a local group \(aqfoo\(aq. .UNINDENT .SS salt.modules.mac_keychain .sp Install certificates into the keychain on Mac OS .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.modules.mac_keychain.get_default_keychain(user=None, domain=\(aquser\(aq) Get the default keychain .INDENT 7.0 .TP .B user The user to check the default keychain of .TP .B domain The domain to use valid values are user|system|common|dynamic, the default is user .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keychain.get_default_keychain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_keychain.get_friendly_name(cert, password, legacy=False) Get the friendly name of the given certificate .INDENT 7.0 .TP .B cert The certificate to install .TP .B password The password for the certificate being installed formatted in the way described for openssl command in the PASS PHRASE ARGUMENTS section .sp Note: The password given here will show up as plaintext in the returned job info. .TP .B legacy Assume legacy format for certificate. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keychain.get_friendly_name /tmp/test.p12 test123 salt \(aq*\(aq keychain.get_friendly_name /tmp/test.p12 test123 legacy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_keychain.get_hash(name, password=None) Returns the hash of a certificate in the keychain. .INDENT 7.0 .TP .B name The name of the certificate (which you can get from keychain.get_friendly_name) or the location of a p12 file. .TP .B password The password that is used in the certificate. Only required if your passing a p12 file. Note: This will be outputted to logs .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keychain.get_hash /tmp/test.p12 test123 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_keychain.install(cert, password, keychain=\(aq/Library/Keychains/System.keychain\(aq, allow_any=False, keychain_password=None) Install a certificate .INDENT 7.0 .TP .B cert The certificate to install .TP .B password The password for the certificate being installed formatted in the way described for openssl command in the PASS PHRASE ARGUMENTS section. .sp Note: The password given here will show up as plaintext in the job returned info. .TP .B keychain The keychain to install the certificate to, this defaults to /Library/Keychains/System.keychain .TP .B allow_any Allow any application to access the imported certificate without warning .TP .B keychain_password If your keychain is likely to be locked pass the password and it will be unlocked before running the import .sp Note: The password given here will show up as plaintext in the returned job info. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keychain.install test.p12 test123 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_keychain.list_certs(keychain=\(aq/Library/Keychains/System.keychain\(aq) List all of the installed certificates .INDENT 7.0 .TP .B keychain The keychain to install the certificate to, this defaults to /Library/Keychains/System.keychain .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keychain.list_certs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_keychain.set_default_keychain(keychain, domain=\(aquser\(aq, user=None) Set the default keychain .INDENT 7.0 .TP .B keychain The location of the keychain to set as default .TP .B domain The domain to use valid values are user|system|common|dynamic, the default is user .TP .B user The user to set the default keychain as .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keychain.set_keychain /Users/fred/Library/Keychains/login.keychain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_keychain.uninstall(cert_name, keychain=\(aq/Library/Keychains/System.keychain\(aq, keychain_password=None) Uninstall a certificate from a keychain .INDENT 7.0 .TP .B cert_name The name of the certificate to remove .TP .B keychain The keychain to install the certificate to, this defaults to /Library/Keychains/System.keychain .TP .B keychain_password If your keychain is likely to be locked pass the password and it will be unlocked before running the import .sp Note: The password given here will show up as plaintext in the returned job info. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keychain.install test.p12 test123 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_keychain.unlock_keychain(keychain, password) Unlock the given keychain with the password .INDENT 7.0 .TP .B keychain The keychain to unlock .TP .B password The password to use to unlock the keychain. .sp Note: The password given here will show up as plaintext in the returned job info. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq keychain.unlock_keychain /tmp/test.p12 test123 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_pkgutil .sp Installer support for macOS. .sp Installer is the native .pkg/.mpkg package manager for macOS. .INDENT 0.0 .TP .B salt.modules.mac_pkgutil.forget(package_id) New in version 2016.3.0. .sp Remove the receipt data about the specified package. Does not remove files. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 DO NOT use this command to fix broken package design .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBpackage_id\fP (\fI\%str\fP) \-\- The name of the package to forget .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgutil.forget com.apple.pkg.gcc4.2Leo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_pkgutil.install(source, package_id) Install a .pkg from an URI or an absolute path. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- The path to a package. .IP \(bu 2 \fBpackage_id\fP (\fI\%str\fP) \-\- The package ID .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgutil.install source=/vagrant/build_essentials.pkg package_id=com.apple.pkg.gcc4.2Leo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_pkgutil.is_installed(package_id) Returns whether a given package id is installed. .INDENT 7.0 .TP .B Returns True if installed, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgutil.is_installed com.apple.pkg.gcc4.2Leo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_pkgutil.list_() List the installed packages. .INDENT 7.0 .TP .B Returns A list of installed packages .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgutil.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_portspkg .sp Support for MacPorts under macOS. .sp This module has some caveats. .sp 1. Updating the database of available ports is quite resource\-intensive. However, \fIrefresh=True\fP is the default for all operations that need an up\-to\-date copy of available ports. Consider \fIrefresh=False\fP when you are sure no db update is needed. .sp 2. In some cases MacPorts doesn\(aqt always realize when another copy of itself is running and will gleefully tromp all over the available ports database. This makes MacPorts behave in undefined ways until a fresh complete copy is retrieved. .sp Because of 1 and 2 it is possible to get the salt\-minion into a state where \fIsalt mac\-machine pkg./something/\fP won\(aqt want to return. Use .sp \fIsalt\-run jobs.active\fP .sp on the master to check for potentially long\-running calls to \fIport\fP\&. .sp Finally, ports database updates are always handled with \fIport selfupdate\fP as opposed to \fIport sync\fP\&. This makes sense in the MacPorts user community but may confuse experienced Linux admins as Linux package managers don\(aqt upgrade the packaging software when doing a package database update. In other words \fIsalt mac\-machine pkg.refresh_db\fP is more like \fIapt\-get update; apt\-get upgrade dpkg apt\-get\fP than simply \fIapt\-get update\fP\&. .INDENT 0.0 .TP .B salt.modules.mac_portspkg.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 .sp Options: .INDENT 0.0 .TP .B refresh Update ports with \fBport selfupdate\fP .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_portspkg.install(name=None, refresh=False, pkgs=None, **kwargs) Install the passed package(s) with \fBport install\fP .INDENT 7.0 .TP .B name The name of the formula to be installed. Note that this parameter is ignored if \(dqpkgs\(dq is passed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B version Specify a version to pkg to install. Ignored if pkgs is specified. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> salt \(aq*\(aq pkg.install git\-core version=\(aq1.8.5.5\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B variant Specify a variant to pkg to install. Ignored if pkgs is specified. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> salt \(aq*\(aq pkg.install git\-core version=\(aq1.8.5.5\(aq variant=\(aq+credential_osxkeychain+doc+pcre\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of formulas to install. Must be passed as a python list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq,\(dqbar\(dq]\(aq salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo@1.2\(dq,\(dqbar\(dq]\(aq salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo@1.2+ssl\(dq,\(dqbar@2.3\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install \(aqpackage package package\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_portspkg.latest_version(*names, **kwargs) Return the latest version of the named package available for upgrade or installation .sp Options: .INDENT 7.0 .TP .B refresh Update ports with \fBport selfupdate\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_portspkg.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<package_name>\(aq: \(aq<version>\(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.mac_portspkg.list_upgrades(refresh=True, **kwargs) Check whether or not an upgrade is available for all packages .sp Options: .INDENT 7.0 .TP .B refresh Update ports with \fBport selfupdate\fP .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.mac_portspkg.refresh_db(**kwargs) Update ports with \fBport selfupdate\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt mac pkg.refresh_db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_portspkg.remove(name=None, pkgs=None, **kwargs) Removes packages with \fBport uninstall\fP\&. .INDENT 7.0 .TP .B name The name of the package to be deleted. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to delete. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .UNINDENT .sp New in version 0.16.0. .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_portspkg.upgrade(refresh=True, **kwargs) Run a full upgrade using MacPorts \(aqport upgrade outdated\(aq .sp Options: .INDENT 7.0 .TP .B refresh Update ports with \fBport selfupdate\fP .UNINDENT .sp Returns a dictionary containing the changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_portspkg.upgrade_available(pkg, refresh=True, **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 <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_portspkg.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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_power .sp Module for editing power settings on macOS .INDENT 0.0 .INDENT 3.5 New in version 2016.3.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.get_computer_sleep() Display the amount of idle time until the computer sleeps. .INDENT 7.0 .TP .B Returns A string representing the sleep settings for the computer .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.get_computer_sleep .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.get_display_sleep() Display the amount of idle time until the display sleeps. .INDENT 7.0 .TP .B Returns A string representing the sleep settings for the displey .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.get_display_sleep .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.get_harddisk_sleep() Display the amount of idle time until the hard disk sleeps. .INDENT 7.0 .TP .B Returns A string representing the sleep settings for the hard disk .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.get_harddisk_sleep .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.get_restart_freeze() Displays whether \(aqrestart on freeze\(aq is on or off if supported .INDENT 7.0 .TP .B Returns A string value representing the \(dqrestart on freeze\(dq settings .TP .B Return type string .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.get_restart_freeze .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.get_restart_power_failure() Displays whether \(aqrestart on power failure\(aq is on or off if supported .INDENT 7.0 .TP .B Returns A string value representing the \(dqrestart on power failure\(dq settings .TP .B Return type string .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.get_restart_power_failure .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.get_sleep() Displays the amount of idle time until the machine sleeps. Settings for Computer, Display, and Hard Disk are displayed. .INDENT 7.0 .TP .B Returns A dictionary containing the sleep status for Computer, Display, and Hard Disk .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.get_sleep .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.get_sleep_on_power_button() Displays whether \(aqallow power button to sleep computer\(aq is on or off if supported .INDENT 7.0 .TP .B Returns A string value representing the \(dqallow power button to sleep computer\(dq settings .TP .B Return type string .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.get_sleep_on_power_button .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.get_wake_on_modem() Displays whether \(aqwake on modem\(aq is on or off if supported .INDENT 7.0 .TP .B Returns A string value representing the \(dqwake on modem\(dq settings .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.get_wake_on_modem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.get_wake_on_network() Displays whether \(aqwake on network\(aq is on or off if supported .INDENT 7.0 .TP .B Returns A string value representing the \(dqwake on network\(dq settings .TP .B Return type string .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.get_wake_on_network .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.set_computer_sleep(minutes) Set the amount of idle time until the computer sleeps. Pass \(dqNever\(dq of \(dqOff\(dq to never sleep. .INDENT 7.0 .TP .B Parameters \fBminutes\fP \-\- Can be an integer between 1 and 180 or \(dqNever\(dq or \(dqOff\(dq .TP .B Ptype int, str .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.set_computer_sleep 120 salt \(aq*\(aq power.set_computer_sleep off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.set_display_sleep(minutes) Set the amount of idle time until the display sleeps. Pass \(dqNever\(dq of \(dqOff\(dq to never sleep. .INDENT 7.0 .TP .B Parameters \fBminutes\fP \-\- Can be an integer between 1 and 180 or \(dqNever\(dq or \(dqOff\(dq .TP .B Ptype int, str .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.set_display_sleep 120 salt \(aq*\(aq power.set_display_sleep off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.set_harddisk_sleep(minutes) Set the amount of idle time until the harddisk sleeps. Pass \(dqNever\(dq of \(dqOff\(dq to never sleep. .INDENT 7.0 .TP .B Parameters \fBminutes\fP \-\- Can be an integer between 1 and 180 or \(dqNever\(dq or \(dqOff\(dq .TP .B Ptype int, str .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.set_harddisk_sleep 120 salt \(aq*\(aq power.set_harddisk_sleep off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.set_restart_freeze(enabled) Specifies whether the server restarts automatically after a system freeze. This setting doesn\(aqt seem to be editable. The command completes successfully but the setting isn\(aqt actually updated. This is probably a macOS. The functions remains in case they ever fix the bug. .INDENT 7.0 .TP .B Parameters \fBenabled\fP (\fI\%bool\fP) \-\- True to enable, False to disable. \(dqOn\(dq and \(dqOff\(dq are also acceptable values. Additionally you can pass 1 and 0 to represent True and False respectively .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.set_restart_freeze True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.set_restart_power_failure(enabled) Set whether or not the computer will automatically restart after a power failure. .INDENT 7.0 .TP .B Parameters \fBenabled\fP (\fI\%bool\fP) \-\- True to enable, False to disable. \(dqOn\(dq and \(dqOff\(dq are also acceptable values. Additionally you can pass 1 and 0 to represent True and False respectively .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.set_restart_power_failure True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.set_sleep(minutes) Sets the amount of idle time until the machine sleeps. Sets the same value for Computer, Display, and Hard Disk. Pass \(dqNever\(dq or \(dqOff\(dq for computers that should never sleep. .INDENT 7.0 .TP .B Parameters \fBminutes\fP \-\- Can be an integer between 1 and 180 or \(dqNever\(dq or \(dqOff\(dq .TP .B Ptype int, str .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.set_sleep 120 salt \(aq*\(aq power.set_sleep never .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.set_sleep_on_power_button(enabled) Set whether or not the power button can sleep the computer. .INDENT 7.0 .TP .B Parameters \fBenabled\fP (\fI\%bool\fP) \-\- True to enable, False to disable. \(dqOn\(dq and \(dqOff\(dq are also acceptable values. Additionally you can pass 1 and 0 to represent True and False respectively .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.set_sleep_on_power_button True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.set_wake_on_modem(enabled) Set whether or not the computer will wake from sleep when modem activity is detected. .INDENT 7.0 .TP .B Parameters \fBenabled\fP (\fI\%bool\fP) \-\- True to enable, False to disable. \(dqOn\(dq and \(dqOff\(dq are also acceptable values. Additionally you can pass 1 and 0 to represent True and False respectively .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.set_wake_on_modem True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_power.set_wake_on_network(enabled) Set whether or not the computer will wake from sleep when network activity is detected. .INDENT 7.0 .TP .B Parameters \fBenabled\fP (\fI\%bool\fP) \-\- True to enable, False to disable. \(dqOn\(dq and \(dqOff\(dq are also acceptable values. Additionally you can pass 1 and 0 to represent True and False respectively .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq power.set_wake_on_network True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_service .sp The service module for macOS .sp New in version 2016.3.0. .sp This module has support for services in the following locations. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /System/Library/LaunchDaemons/ /System/Library/LaunchAgents/ /Library/LaunchDaemons/ /Library/LaunchAgents/ # As of version \(dq2019.2.0\(dq support for user\-specific services were added. /Users/foo/Library/LaunchAgents/ .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As of the 2019.2.0 release, if a service is located in a \fBLaunchAgent\fP path and a \fBrunas\fP user is NOT specified, the current console user will be used to properly interact with the service. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As of the 3002 release, if a service name of \fBsalt\-minion\fP is passed this module will convert it over to it\(aqs macOS equivalent name, in this case to \fBcom.saltstack.salt.minion\fP\&. This is true for \fBsalt\-master\fP \fBsalt\-api\fP, and \fBsalt\-syndic\fP as well. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.available(name) Check that the given service is available. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the service .TP .B Returns True if the service is available, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available com.openssh.sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.disable(name, runas=None) Disable a launchd service. Raises an error if the service fails to be disabled .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Service label, file name, or full path .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands .UNINDENT .TP .B Returns \fBTrue\fP if successful or if the service is already disabled .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable org.cups.cupsd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.disabled(name, runas=None, domain=\(aqsystem\(aq) Check if the specified service is not enabled. This is the opposite of \fBservice.enabled\fP .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name to look up .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands .IP \(bu 2 \fBdomain\fP (\fI\%str\fP) \-\- domain to check for disabled services. Default is system. .UNINDENT .TP .B Returns True if the specified service is NOT enabled, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled org.cups.cupsd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.enable(name, runas=None) Enable a launchd service. Raises an error if the service fails to be enabled .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Service label, file name, or full path .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands .UNINDENT .TP .B Returns \fBTrue\fP if successful or if the service is already enabled .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable org.cups.cupsd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.enabled(name, runas=None) Check if the specified service is enabled (not disabled, capable of being loaded/bootstrapped). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Previously this function would see if the service is loaded via \fBlaunchctl list\fP to determine if the service is enabled. This was not an accurate way to do so. The new behavior checks to make sure its not disabled to determine the status. Please use \fBservice.loaded\fP for the previous behavior. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to look up. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands. .UNINDENT .TP .B Returns True if the specified service enabled, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled org.cups.cupsd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.get_all(runas=None) Return a list of services that are enabled or available. Can be used to find the name of a service. .INDENT 7.0 .TP .B Parameters \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands .TP .B Returns A list of all the services available or enabled .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.get_enabled(runas=None) Return a list of all services that are enabled. Can be used to find the name of a service. .INDENT 7.0 .TP .B Parameters \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands .TP .B Returns A list of all the services enabled on the system .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.launchctl(sub_cmd, *args, **kwargs) Run a launchctl command and raise an error if it fails .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsub_cmd\fP (\fI\%str\fP) \-\- Sub command supplied to launchctl .IP \(bu 2 \fBargs\fP (\fI\%tuple\fP) \-\- Tuple containing additional arguments to pass to launchctl .IP \(bu 2 \fBkwargs\fP (\fI\%dict\fP) \-\- Dictionary containing arguments to pass to \fBcmd.run_all\fP .IP \(bu 2 \fBreturn_stdout\fP (\fI\%bool\fP) \-\- A keyword argument. If true return the stdout of the launchctl command .UNINDENT .TP .B Returns \fBTrue\fP if successful, raise \fBCommandExecutionError\fP if not, or the stdout of the launchctl command if requested .TP .B Return type \fI\%bool\fP, \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.launchctl debug org.cups.cupsd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.list_(name=None, runas=None) Run launchctl list and return the output .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to list .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands .UNINDENT .TP .B Returns If a name is passed returns information about the named service, otherwise returns a list of all services and pids .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.list salt \(aq*\(aq service.list org.cups.cupsd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.loaded(name, runas=None) Check if the specified service is loaded. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to look up .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands .UNINDENT .TP .B Returns \fBTrue\fP if the specified service is loaded, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.loaded org.cups.cupsd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.missing(name) The inverse of service.available Check that the given service is not available. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the service .TP .B Returns True if the service is not available, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing com.openssh.sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.restart(name, runas=None) Unloads and reloads a launchd service. Raises an error if the service fails to reload .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Service label, file name, or full path .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands .UNINDENT .TP .B Returns \fBTrue\fP if successful .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart org.cups.cupsd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.show(name) Show properties of a launchctl service .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- Service label, file name, or full path .TP .B Returns The service information if the service is found .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.show org.cups.cupsd # service label salt \(aq*\(aq service.show org.cups.cupsd.plist # file name salt \(aq*\(aq service.show /System/Library/LaunchDaemons/org.cups.cupsd.plist # full path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.start(name, runas=None) Start a launchd service. Raises an error if the service fails to start .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To start a service in macOS the service must be enabled first. Use \fBservice.enable\fP to enable the service. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Service label, file name, or full path .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands .UNINDENT .TP .B Returns \fBTrue\fP if successful or if the service is already running .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start org.cups.cupsd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.status(name, sig=None, runas=None) Return the status for a service. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Previously this function would return a PID for a running service with a PID or \(aqloaded\(aq for a loaded service without a PID. This was changed to have better parity with other service modules that return True/False. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Used to find the service from launchctl. Can be the service Label, file name, or path to the service file. (normally a plist) .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Find the service with status.pid instead. Note that \fBname\fP must still be provided. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands. .UNINDENT .TP .B Returns True if running, otherwise False. .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status cups .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_service.stop(name, runas=None) Stop a launchd service. Raises an error if the service fails to stop .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Though \fBservice.stop\fP will unload a service in macOS, the service will start on next boot unless it is disabled. Use \fBservice.disable\fP to disable the service .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Service label, file name, or full path .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands .UNINDENT .TP .B Returns \fBTrue\fP if successful or if the service is already stopped .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop org.cups.cupsd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_shadow .sp Manage macOS local directory passwords and policies .sp New in version 2016.3.0. .sp Note that it is usually better to apply password policies through the creation of a configuration profile. .INDENT 0.0 .TP .B salt.modules.mac_shadow.del_password(name) Deletes the account password .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The user name of the account .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .TP .B Raises CommandExecutionError on user not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.del_password username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.get_account_created(name) Get the date/time the account was created .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The username of the account .TP .B Returns The date/time the account was created (yyyy\-mm\-dd hh:mm:ss) or 0 if the value is not defined .TP .B Return type \fI\%str\fP .TP .B Raises CommandExecutionError on user not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.get_account_created admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.get_change(name) Gets the date on which the password expires .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the user account .TP .B Returns The date the password will expire .TP .B Return type \fI\%str\fP .TP .B Raises CommandExecutionError on user not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.get_change username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.get_expire(name) Gets the date on which the account expires .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the user account .TP .B Returns The date the account expires .TP .B Return type \fI\%str\fP .TP .B Raises CommandExecutionError on user not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.get_expire username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.get_last_change(name) Get the date/time the account was changed .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The username of the account .TP .B Returns The date/time the account was modified (yyyy\-mm\-dd hh:mm:ss) or 0 if the value is not defined .TP .B Return type \fI\%str\fP .TP .B Raises CommandExecutionError on user not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.get_last_change admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.get_login_failed_count(name) Get the number of failed login attempts .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The username of the account .TP .B Returns The number of failed login attempts. 0 may mean there are no failed login attempts or the value is not defined .TP .B Return type \fI\%str\fP .TP .B Raises CommandExecutionError on user not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.get_login_failed_count admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.get_login_failed_last(name) Get the date/time of the last failed login attempt .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The username of the account .TP .B Returns The date/time of the last failed login attempt on this account (yyyy\-mm\-dd hh:mm:ss) or 0 if the value is not defined .TP .B Return type \fI\%str\fP .TP .B Raises CommandExecutionError on user not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.get_login_failed_last admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.get_maxdays(name) Get the maximum age of the password .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The username of the account .TP .B Returns The maximum age of the password in days .TP .B Return type \fI\%int\fP .TP .B Raises CommandExecutionError on user not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.get_maxdays admin 90 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.info(name) Return information for the specified user .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The username .TP .B Returns A dictionary containing the user\(aqs shadow information .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.info admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.set_change(name, date) Sets the date on which the password expires. The user will be required to change their password. Format is mm/dd/yyyy .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the user account .IP \(bu 2 \fBdate\fP (\fIdate\fP) \-\- The date the password will expire. Must be in mm/dd/yyyy format. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .TP .B Raises CommandExecutionError on user not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_change username 09/21/2016 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.set_expire(name, date) Sets the date on which the account expires. The user will not be able to login after this date. Date format is mm/dd/yyyy .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the user account .IP \(bu 2 \fBdate\fP (\fIdatetime\fP) \-\- The date the account will expire. Format must be mm/dd/yyyy. .UNINDENT .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .TP .B Raises CommandExecutionError on user not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_expire username 07/23/2015 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.set_inactdays(name, days) Set the number if inactive days before the account is locked. Not available in macOS .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The user name .IP \(bu 2 \fBdays\fP (\fI\%int\fP) \-\- The number of days .UNINDENT .TP .B Returns Will always return False until macOS supports this feature. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_inactdays admin 90 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.set_maxdays(name, days) Set the maximum age of the password in days .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The username of the account .IP \(bu 2 \fBdays\fP (\fI\%int\fP) \-\- The maximum age of the account in days .UNINDENT .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .TP .B Raises CommandExecutionError on user not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_maxdays admin 90 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.set_mindays(name, days) Set the minimum password age in days. Not available in macOS. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The user name .IP \(bu 2 \fBdays\fP (\fI\%int\fP) \-\- The number of days .UNINDENT .TP .B Returns Will always return False until macOS supports this feature. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_mindays admin 90 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.set_password(name, password) Set the password for a named user (insecure, the password will be in the process list while the command is running) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the local user, which is assumed to be in the local directory service .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The plaintext password to set .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .TP .B Raises CommandExecutionError on user not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mac_shadow.set_password macuser macpassword .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_shadow.set_warndays(name, days) Set the number of days before the password expires that the user will start to see a warning. Not available in macOS .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The user name .IP \(bu 2 \fBdays\fP (\fI\%int\fP) \-\- The number of days .UNINDENT .TP .B Returns Will always return False until macOS supports this feature. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_warndays admin 90 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_softwareupdate .sp Support for the softwareupdate command on MacOS. .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.download(name) Download a named update so that it can be installed later with the \fBupdate\fP or \fBupdate_all\fP functions .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The update to download. .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdate.download <update name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.download_all(recommended=False, restart=True) Download all available updates so that they can be installed later with the \fBupdate\fP or \fBupdate_all\fP functions. It returns a list of updates that are now downloaded. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrecommended\fP (\fI\%bool\fP) \-\- If set to True, only install the recommended updates. If set to False (default) all updates are installed. .IP \(bu 2 \fBrestart\fP (\fI\%bool\fP) \-\- Set this to False if you do not want to install updates that require a restart. Default is True .UNINDENT .TP .B Returns A list containing all downloaded updates on the system. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdate.download_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.get_catalog() New in version 2016.3.0. .sp Get the current catalog being used for update lookups. Will return a url if a custom catalog has been specified. Otherwise the word \(aqDefault\(aq will be returned .INDENT 7.0 .TP .B Returns The catalog being used for update lookups .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdates.get_catalog .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.ignore(name) Ignore a specific program update. When an update is ignored the \(aq\-\(aq and version number at the end will be omitted, so \(dqSecUpd2014\-001\-1.0\(dq becomes \(dqSecUpd2014\-001\(dq. It will be removed automatically if present. An update is successfully ignored when it no longer shows up after list_updates. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the update to add to the ignore list. .TP .B Ptype str .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdate.ignore <update\-name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.list_available(recommended=False, restart=False, shut_down=False) List all available updates. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrecommended\fP (\fI\%bool\fP) \-\- Show only recommended updates. .IP \(bu 2 \fBrestart\fP (\fI\%bool\fP) \-\- Show only updates that require a restart. .UNINDENT .TP .B Returns Returns a dictionary containing the updates .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdate.list_available .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.list_downloads() Return a list of all updates that have been downloaded locally. .INDENT 7.0 .TP .B Returns A list of updates that have been downloaded .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdate.list_downloads .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.list_ignored() List all updates that have been ignored. Ignored updates are shown without the \(aq\-\(aq and version number at the end, this is how the softwareupdate command works. .INDENT 7.0 .TP .B Returns The list of ignored updates .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdate.list_ignored .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.reset_catalog() New in version 2016.3.0. .sp Reset the Software Update Catalog to the default. .INDENT 7.0 .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdates.reset_catalog .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.reset_ignored() Make sure the ignored updates are not ignored anymore, returns a list of the updates that are no longer ignored. .INDENT 7.0 .TP .B Returns True if the list was reset, Otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdate.reset_ignored .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.schedule_enable(enable) Enable/disable automatic update scheduling. .INDENT 7.0 .TP .B Parameters \fBenable\fP \-\- True/On/Yes/1 to turn on automatic updates. False/No/Off/0 to turn off automatic updates. If this value is empty, the current status will be returned. .TP .B Type bool str .TP .B Returns True if scheduling is enabled, False if disabled .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdate.schedule_enable on|off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.schedule_enabled() Check the status of automatic update scheduling. .INDENT 7.0 .TP .B Returns True if scheduling is enabled, False if disabled .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdate.schedule_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.set_catalog(url) New in version 2016.3.0. .sp Set the Software Update Catalog to the URL specified .INDENT 7.0 .TP .B Parameters \fBurl\fP (\fI\%str\fP) \-\- The url to the update catalog .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdates.set_catalog http://swupd.local:8888/index.sucatalog .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.update(name) Install a named update. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the of the update to install. .TP .B Returns True if successfully updated, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdate.update <update\-name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.update_all(recommended=False, restart=True) Install all available updates. Returns a dictionary containing the name of the update and the status of its installation. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrecommended\fP (\fI\%bool\fP) \-\- If set to True, only install the recommended updates. If set to False (default) all updates are installed. .IP \(bu 2 \fBrestart\fP (\fI\%bool\fP) \-\- Set this to False if you do not want to install updates that require a restart. Default is True .UNINDENT .TP .B Returns A dictionary containing the updates that were installed and the status of its installation. If no updates were installed an empty dictionary is returned. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdate.update_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_softwareupdate.update_available(name) Check whether or not an update is available with a given name. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the update to look for .TP .B Returns True if available, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq softwareupdate.update_available <update\-name> salt \(aq*\(aq softwareupdate.update_available \(dq<update with whitespace>\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_sysctl .sp Module for viewing and modifying sysctl parameters .INDENT 0.0 .TP .B salt.modules.mac_sysctl.assign(name, value) Assign a single sysctl parameter for this minion .INDENT 7.0 .TP .B name The name of the sysctl value to edit. .TP .B value The sysctl value to apply. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.assign net.inet.icmp.icmplim 50 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_sysctl.get(name) Return a single sysctl parameter for this minion .INDENT 7.0 .TP .B name The name of the sysctl value to display. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.get hw.physmem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_sysctl.persist(name, value, config=\(aq/etc/sysctl.conf\(aq, apply_change=False) Assign and persist a simple sysctl parameter for this minion .INDENT 7.0 .TP .B name The name of the sysctl value to edit. .TP .B value The sysctl value to apply. .TP .B config The location of the sysctl configuration file. .TP .B apply_change Default is False; Default behavior only creates or edits the sysctl.conf file. If apply is set to True, the changes are applied to the system. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.persist net.inet.icmp.icmplim 50 salt \(aq*\(aq sysctl.persist coretemp_load NO config=/etc/sysctl.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_sysctl.show(config_file=False) Return a list of sysctl parameters for this minion .INDENT 7.0 .TP .B config: Pull the data from the system configuration file instead of the live data. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.show .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_system .sp System module for sleeping, restarting, and shutting down the system on Mac OS X .sp New in version 2016.3.0. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Using this module will enable \fBatrun\fP on the system if it is disabled. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.get_boot_arch() Get the kernel architecture setting from \fBcom.apple.Boot.plist\fP .INDENT 7.0 .TP .B Returns A string value representing the boot architecture setting .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_boot_arch .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.get_computer_name() Gets the computer name .INDENT 7.0 .TP .B Returns The computer name .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_computer_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.get_disable_keyboard_on_lock() Get whether or not the keyboard should be disabled when the X Serve enclosure lock is engaged. .INDENT 7.0 .TP .B Returns True if disable keyboard on lock is on, False if off .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_disable_keyboard_on_lock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.get_remote_events() Displays whether remote apple events are on or off. .INDENT 7.0 .TP .B Returns True if remote apple events are on, False if off .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_remote_events .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.get_remote_login() Displays whether remote login (SSH) is on or off. .INDENT 7.0 .TP .B Returns True if remote login is on, False if off .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_remote_login .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.get_restart_delay() Get the number of seconds after which the computer will start up after a power failure. .INDENT 7.0 .TP .B Returns A string value representing the number of seconds the system will delay restart after power loss .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_restart_delay .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.get_startup_disk() Displays the current startup disk .INDENT 7.0 .TP .B Returns The current startup disk .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_startup_disk .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.get_subnet_name() Gets the local subnet name .INDENT 7.0 .TP .B Returns The local subnet name .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_subnet_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.halt(at_time=None) Halt a running system .INDENT 7.0 .TP .B Parameters \fBat_time\fP (\fI\%str\fP) \-\- .sp Any valid \fIat\fP expression. For example, some valid at expressions could be: .INDENT 7.0 .IP \(bu 2 noon .IP \(bu 2 midnight .IP \(bu 2 fri .IP \(bu 2 9:00 AM .IP \(bu 2 2:30 PM tomorrow .IP \(bu 2 now + 10 minutes .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you pass a time only, with no \(aqAM/PM\(aq designation, you have to double quote the parameter on the command line. For example: \(aq\(dq14:00\(dq\(aq .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.halt salt \(aq*\(aq system.halt \(aqnow + 10 minutes\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.list_startup_disks() List all valid startup disks on the system. .INDENT 7.0 .TP .B Returns A list of valid startup disks .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.list_startup_disks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.restart(at_time=None) Restart the system .INDENT 7.0 .TP .B Parameters \fBat_time\fP (\fI\%str\fP) \-\- .sp Any valid \fIat\fP expression. For example, some valid at expressions could be: .INDENT 7.0 .IP \(bu 2 noon .IP \(bu 2 midnight .IP \(bu 2 fri .IP \(bu 2 9:00 AM .IP \(bu 2 2:30 PM tomorrow .IP \(bu 2 now + 10 minutes .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you pass a time only, with no \(aqAM/PM\(aq designation, you have to double quote the parameter on the command line. For example: \(aq\(dq14:00\(dq\(aq .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.restart salt \(aq*\(aq system.restart \(aq12:00 PM fri\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.set_boot_arch(arch=\(aqdefault\(aq) Set the kernel to boot in 32 or 64 bit mode on next boot. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When this function fails with the error \fBchanges to kernel architecture failed to save!\fP, then the boot arch is not updated. This is either an Apple bug, not available on the test system, or a result of system files being locked down in macOS (SIP Protection). .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBarch\fP (\fI\%str\fP) \-\- .sp A string representing the desired architecture. If no value is passed, default is assumed. Valid values include: .INDENT 7.0 .IP \(bu 2 i386 .IP \(bu 2 x86_64 .IP \(bu 2 default .UNINDENT .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_boot_arch i386 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.set_computer_name(name) Set the computer name .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The new computer name .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_computer_name \(dqMike\(aqs Mac\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.set_disable_keyboard_on_lock(enable) Get whether or not the keyboard should be disabled when the X Serve enclosure lock is engaged. .INDENT 7.0 .TP .B Parameters \fBenable\fP (\fI\%bool\fP) \-\- True to enable, False to disable. \(dqOn\(dq and \(dqOff\(dq are also acceptable values. Additionally you can pass 1 and 0 to represent True and False respectively .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_disable_keyboard_on_lock False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.set_remote_events(enable) Set whether the server responds to events sent by other computers (such as AppleScripts) .INDENT 7.0 .TP .B Parameters \fBenable\fP (\fI\%bool\fP) \-\- True to enable, False to disable. \(dqOn\(dq and \(dqOff\(dq are also acceptable values. Additionally you can pass 1 and 0 to represent True and False respectively .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_remote_events On .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.set_remote_login(enable) Set the remote login (SSH) to either on or off. .INDENT 7.0 .TP .B Parameters \fBenable\fP (\fI\%bool\fP) \-\- True to enable, False to disable. \(dqOn\(dq and \(dqOff\(dq are also acceptable values. Additionally you can pass 1 and 0 to represent True and False respectively .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_remote_login True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.set_restart_delay(seconds) Set the number of seconds after which the computer will start up after a power failure. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This command fails with the following error: .sp \fBError, IOServiceOpen returned 0x10000003\fP .sp The setting is not updated. This is an apple bug. It seems like it may only work on certain versions of Mac Server X. This article explains the issue in more detail, though it is quite old. .sp \fI\%http://lists.apple.com/archives/macos\-x\-server/2006/Jul/msg00967.html\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBseconds\fP (\fI\%int\fP) \-\- The number of seconds. Must be a multiple of 30 .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_restart_delay 180 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.set_startup_disk(path) Set the current startup disk to the indicated path. Use \fBsystem.list_startup_disks\fP to find valid startup disks on the system. .INDENT 7.0 .TP .B Parameters \fBpath\fP (\fI\%str\fP) \-\- The valid startup disk path .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_startup_disk /System/Library/CoreServices .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.set_subnet_name(name) Set the local subnet name .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The new local subnet name .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Spaces are changed to dashes. Other special characters are removed. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C The following will be set as \(aqMikes\-Mac\(aq salt \(aq*\(aq system.set_subnet_name \(dqMike\(aqs Mac\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.shutdown(at_time=None) Shutdown the system .INDENT 7.0 .TP .B Parameters \fBat_time\fP (\fI\%str\fP) \-\- .sp Any valid \fIat\fP expression. For example, some valid at expressions could be: .INDENT 7.0 .IP \(bu 2 noon .IP \(bu 2 midnight .IP \(bu 2 fri .IP \(bu 2 9:00 AM .IP \(bu 2 2:30 PM tomorrow .IP \(bu 2 now + 10 minutes .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you pass a time only, with no \(aqAM/PM\(aq designation, you have to double quote the parameter on the command line. For example: \(aq\(dq14:00\(dq\(aq .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.shutdown salt \(aq*\(aq system.shutdown \(aqnow + 1 hour\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_system.sleep(at_time=None) Sleep the system. If a user is active on the system it will likely fail to sleep. .INDENT 7.0 .TP .B Parameters \fBat_time\fP (\fI\%str\fP) \-\- .sp Any valid \fIat\fP expression. For example, some valid at expressions could be: .INDENT 7.0 .IP \(bu 2 noon .IP \(bu 2 midnight .IP \(bu 2 fri .IP \(bu 2 9:00 AM .IP \(bu 2 2:30 PM tomorrow .IP \(bu 2 now + 10 minutes .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you pass a time only, with no \(aqAM/PM\(aq designation, you have to double quote the parameter on the command line. For example: \(aq\(dq14:00\(dq\(aq .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.sleep salt \(aq*\(aq system.sleep \(aq10:00 PM\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_timezone .sp Module for editing date/time settings on macOS .INDENT 0.0 .INDENT 3.5 New in version 2016.3.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.get_date() Displays the current date .INDENT 7.0 .TP .B Returns the system date .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_date .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.get_hwclock() Get current hardware clock setting (UTC or localtime) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_hwclock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.get_offset() Displays the current time zone offset .INDENT 7.0 .TP .B Returns The current time zone offset .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_offset .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.get_time() Get the current system time. .INDENT 7.0 .TP .B Returns The current time in 24 hour format .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_time .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.get_time_server() Display the currently set network time server. .INDENT 7.0 .TP .B Returns the network time server .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_time_server .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.get_using_network_time() Display whether network time is on or off .INDENT 7.0 .TP .B Returns True if network time is on, False if off .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_using_network_time .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.get_zone() Displays the current time zone .INDENT 7.0 .TP .B Returns The current time zone .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.get_zonecode() Displays the current time zone abbreviated code .INDENT 7.0 .TP .B Returns The current time zone code .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_zonecode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.list_zones() Displays a list of available time zones. Use this list when setting a time zone using \fBtimezone.set_zone\fP .INDENT 7.0 .TP .B Returns a list of time zones .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.list_zones .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.set_date(date) Set the current month, day, and year .INDENT 7.0 .TP .B Parameters \fBdate\fP (\fI\%str\fP) \-\- .sp The date to set. Valid date formats are: .INDENT 7.0 .IP \(bu 2 %m:%d:%y .IP \(bu 2 %m:%d:%Y .IP \(bu 2 %m/%d/%y .IP \(bu 2 %m/%d/%Y .UNINDENT .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .TP .B Raises SaltInvocationError on Invalid Date format .TP .B Raises CommandExecutionError on failure .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.set_date 1/13/2016 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.set_hwclock(clock) Sets the hardware clock to be either UTC or localtime .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.set_hwclock UTC .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.set_time(time) Sets the current time. Must be in 24 hour format. .INDENT 7.0 .TP .B Parameters \fBtime\fP (\fI\%str\fP) \-\- The time to set in 24 hour format. The value must be double quoted. ie: \(aq\(dq17:46\(dq\(aq .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .TP .B Raises SaltInvocationError on Invalid Time format .TP .B Raises CommandExecutionError on failure .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.set_time \(aq\(dq17:34\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.set_time_server(time_server=\(aqtime.apple.com\(aq) Designates a network time server. Enter the IP address or DNS name for the network time server. .INDENT 7.0 .TP .B Parameters \fBtime_server\fP \-\- IP or DNS name of the network time server. If nothing is passed the time server will be set to the macOS default of \(aqtime.apple.com\(aq .TP .B Type \fI\%str\fP .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .TP .B Raises CommandExecutionError on failure .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.set_time_server time.acme.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.set_using_network_time(enable) Set whether network time is on or off. .INDENT 7.0 .TP .B Parameters \fBenable\fP \-\- True to enable, False to disable. Can also use \(aqon\(aq or \(aqoff\(aq .TP .B Type str bool .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .TP .B Raises CommandExecutionError on failure .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.set_using_network_time True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.set_zone(time_zone) Set the local time zone. Use \fBtimezone.list_zones\fP to list valid time_zone arguments .INDENT 7.0 .TP .B Parameters \fBtime_zone\fP (\fI\%str\fP) \-\- The time zone to apply .TP .B Returns True if successful, False if not .TP .B Return type \fI\%bool\fP .TP .B Raises SaltInvocationError on Invalid Timezone .TP .B Raises CommandExecutionError on failure .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.set_zone America/Denver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_timezone.zone_compare(time_zone) Compares the given timezone name with the system timezone name. .INDENT 7.0 .TP .B Returns True if they are the same, False if not .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.zone_compare America/Boise .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_user .sp Manage users on Mac OS 10.7+ .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage users on a minion, and it is using a different module (or gives an error similar to \fI\(aquser.info\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.add(name, uid=None, gid=None, groups=None, home=None, shell=None, fullname=None, createhome=True, **kwargs) Add a user to the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.add name <uid> <gid> <groups> <home> <shell> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.chfullname(name, fullname) Change the user\(aqs Full Name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chfullname foo \(aqFoo Bar\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.chgid(name, gid) Change the default group of the user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chgid foo 4376 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.chgroups(name, groups, append=False) Change the groups to which the user belongs. Note that the user\(aqs primary group does not have to be one of the groups passed, membership in the user\(aqs primary group is automatically assumed. .INDENT 7.0 .TP .B groups Groups to which the user should belong, can be passed either as a python list or a comma\-separated string .TP .B append Instead of removing user from groups not included in the \fBgroups\fP parameter, just add user to any groups for which they are not members .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chgroups foo wheel,root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.chhome(name, home, **kwargs) Change the home directory of the user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chhome foo /Users/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.chshell(name, shell) Change the default shell of the user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chshell foo /bin/zsh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.chuid(name, uid) Change the uid for a named user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chuid foo 4376 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.delete(name, remove=False, force=False) Remove a user from the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.delete name remove=True force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.disable_auto_login() New in version 2016.3.0. .sp Disables auto login on the machine .INDENT 7.0 .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.disable_auto_login .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.enable_auto_login(name, password) New in version 2016.3.0. .sp Configures the machine to auto login with the specified user .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The user account use for auto login .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- .sp The password to user for auto login .sp New in version 2017.7.3. .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.enable_auto_login stevej .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.get_auto_login() New in version 2016.3.0. .sp Gets the current setting for Auto Login .INDENT 7.0 .TP .B Returns If enabled, returns the user name, otherwise returns False .TP .B Return type \fI\%str\fP, \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.get_auto_login .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.getent(refresh=False) Return the list of all info for all users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.getent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.info(name) Return user information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.info root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.list_groups(name) Return a list of groups the named user belongs to. .sp name .INDENT 7.0 .INDENT 3.5 The name of the user for which to list groups. Starting in Salt 2016.11.0, all groups for the user, including groups beginning with an underscore will be listed. .sp Changed in version 2016.11.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.list_groups foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.list_users() Return a list of all users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.primary_group(name) Return the primary group of the named user .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.primary_group saltadmin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_user.rename(name, new_name) Change the username for a named user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.rename name new_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mac_xattr .sp This module allows you to manage extended attributes on files or directories .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xattr.list /path/to/file .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_xattr.clear(path) Causes the all attributes on the file/directory to be removed .INDENT 7.0 .TP .B Parameters \fBpath\fP (\fI\%str\fP) \-\- The file(s) to get attributes from .TP .B Returns True if successful, otherwise False .TP .B Raises CommandExecutionError on file not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xattr.delete /path/to/file \(dqcom.test.attr\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_xattr.delete(path, attribute) Removes the given attribute from the file .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The file(s) to get attributes from .IP \(bu 2 \fBattribute\fP (\fI\%str\fP) \-\- The attribute name to be deleted from the file/directory .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .TP .B Raises CommandExecutionError on file not found, attribute not found, and any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xattr.delete /path/to/file \(dqcom.test.attr\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_xattr.list_(path, **kwargs) List all of the extended attributes on the given file/directory .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The file(s) to get attributes from .IP \(bu 2 \fBhex\fP (\fI\%bool\fP) \-\- Return the values with forced hexadecimal values .UNINDENT .TP .B Returns A dictionary containing extended attributes and values for the given file .TP .B Return type \fI\%dict\fP .TP .B Raises CommandExecutionError on file not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xattr.list /path/to/file salt \(aq*\(aq xattr.list /path/to/file hex=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_xattr.read(path, attribute, **kwargs) Read the given attributes on the given file/directory .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The file to get attributes from .IP \(bu 2 \fBattribute\fP (\fI\%str\fP) \-\- The attribute to read .IP \(bu 2 \fBhex\fP (\fI\%bool\fP) \-\- Return the values with forced hexadecimal values .UNINDENT .TP .B Returns A string containing the value of the named attribute .TP .B Return type \fI\%str\fP .TP .B Raises CommandExecutionError on file not found, attribute not found, and any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xattr.read /path/to/file com.test.attr salt \(aq*\(aq xattr.read /path/to/file com.test.attr hex=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mac_xattr.write(path, attribute, value, **kwargs) Causes the given attribute name to be assigned the given value .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The file(s) to get attributes from .IP \(bu 2 \fBattribute\fP (\fI\%str\fP) \-\- The attribute name to be written to the file/directory .IP \(bu 2 \fBvalue\fP (\fI\%str\fP) \-\- The value to assign to the given attribute .IP \(bu 2 \fBhex\fP (\fI\%bool\fP) \-\- Set the values with forced hexadecimal values .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .TP .B Raises CommandExecutionError on file not found or any other unknown error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xattr.write /path/to/file \(dqcom.test.attr\(dq \(dqvalue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.macdefaults .sp Set defaults on Mac OS .INDENT 0.0 .TP .B salt.modules.macdefaults.delete(domain, key, user=None) Delete a default from the system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq macdefaults.delete com.apple.CrashReporter DialogType salt \(aq*\(aq macdefaults.delete NSGlobalDomain ApplePersistence .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B domain The name of the domain to delete from .TP .B key The key of the given domain to delete .TP .B user The user to delete the defaults with .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.macdefaults.read(domain, key, user=None) Read a default from the system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq macdefaults.read com.apple.CrashReporter DialogType salt \(aq*\(aq macdefaults.read NSGlobalDomain ApplePersistence .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B domain The name of the domain to read from .TP .B key The key of the given domain to read from .TP .B user The user to read the defaults as .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.macdefaults.write(domain, key, value, type=\(aqstring\(aq, user=None) Write a default to the system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq macdefaults.write com.apple.CrashReporter DialogType Server salt \(aq*\(aq macdefaults.write NSGlobalDomain ApplePersistence True type=bool .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B domain The name of the domain to write to .TP .B key The key of the given domain to write to .TP .B value The value to write to the given key .TP .B type The type of value to be written, valid types are string, data, int[eger], float, bool[ean], date, array, array\-add, dict, dict\-add .TP .B user The user to write the defaults to .UNINDENT .UNINDENT .SS salt.modules.macpackage .sp Install pkg, dmg and .app applications on macOS minions. .INDENT 0.0 .TP .B salt.modules.macpackage.get_mpkg_ids(mpkg) Attempt to get the package IDs from a mounted .mpkg file .INDENT 7.0 .TP .B Parameters \fBmpkg\fP (\fI\%str\fP) \-\- The location of the mounted mpkg file .TP .B Returns List of package IDs .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq macpackage.get_mpkg_ids /dev/disk2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.macpackage.get_pkg_id(pkg) Attempt to get the package ID from a .pkg file .INDENT 7.0 .TP .B Parameters \fBpkg\fP (\fI\%str\fP) \-\- The location of the pkg file .TP .B Returns List of all of the package IDs .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq macpackage.get_pkg_id /tmp/test.pkg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.macpackage.install(pkg, target=\(aqLocalSystem\(aq, store=False, allow_untrusted=False) Install a pkg file .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpkg\fP (\fI\%str\fP) \-\- The package to install .IP \(bu 2 \fBtarget\fP (\fI\%str\fP) \-\- The target in which to install the package to .IP \(bu 2 \fBstore\fP (\fI\%bool\fP) \-\- Should the package be installed as if it was from the store? .IP \(bu 2 \fBallow_untrusted\fP (\fI\%bool\fP) \-\- Allow the installation of untrusted packages? .UNINDENT .TP .B Returns A dictionary containing the results of the installation .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq macpackage.install test.pkg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.macpackage.install_app(app, target=\(aq/Applications/\(aq) Install an app file by moving it into the specified Applications directory .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapp\fP (\fI\%str\fP) \-\- The location of the .app file .IP \(bu 2 \fBtarget\fP (\fI\%str\fP) \-\- The target in which to install the package to Default is \(aq\(aq/Applications/\(aq\(aq .UNINDENT .TP .B Returns The results of the rsync command .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq macpackage.install_app /tmp/tmp.app /Applications/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.macpackage.installed_pkgs() Return the list of installed packages on the machine .INDENT 7.0 .TP .B Returns List of installed packages .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq macpackage.installed_pkgs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.macpackage.mount(dmg) Attempt to mount a dmg file to a temporary location and return the location of the pkg file inside .INDENT 7.0 .TP .B Parameters \fBdmg\fP (\fI\%str\fP) \-\- The location of the dmg file to mount .TP .B Returns .INDENT 7.0 .TP .B Tuple containing the results of the command along with the mount point .UNINDENT .TP .B Return type \fI\%tuple\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq macpackage.mount /tmp/software.dmg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.macpackage.uninstall_app(app) Uninstall an app file by removing it from the Applications directory .INDENT 7.0 .TP .B Parameters \fBapp\fP (\fI\%str\fP) \-\- The location of the .app file .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq macpackage.uninstall_app /Applications/app.app .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.macpackage.unmount(mountpoint) Attempt to unmount a dmg file from a temporary location .INDENT 7.0 .TP .B Parameters \fBmountpoint\fP (\fI\%str\fP) \-\- The location of the mount point .TP .B Returns The results of the hdutil detach command .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq macpackage.unmount /dev/disk2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.makeconf .sp Support for modifying make.conf under Gentoo .INDENT 0.0 .TP .B salt.modules.makeconf.append_cflags(value) Add to or create a new CFLAGS in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.append_cflags \(aq\-pipe\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.append_cxxflags(value) Add to or create a new CXXFLAGS in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.append_cxxflags \(aq\-pipe\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.append_emerge_default_opts(value) Add to or create a new EMERGE_DEFAULT_OPTS in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.append_emerge_default_opts \(aq\-\-jobs\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.append_features(value) Add to or create a new FEATURES in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.append_features \(aqwebrsync\-gpg\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.append_gentoo_mirrors(value) Add to or create a new GENTOO_MIRRORS in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.append_gentoo_mirrors \(aqhttp://distfiles.gentoo.org\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.append_makeopts(value) Add to or create a new MAKEOPTS in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.append_makeopts \(aq\-j3\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.append_var(var, value) Add to or create a new variable in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.append_var \(aqLINGUAS\(aq \(aqen\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.cflags_contains(value) Verify if CFLAGS variable contains a value in make.conf .sp Return True if value is set for var .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.cflags_contains \(aq\-pipe\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.chost_contains(value) Verify if CHOST variable contains a value in make.conf .sp Return True if value is set for var .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.chost_contains \(aqx86_64\-pc\-linux\-gnu\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.cxxflags_contains(value) Verify if CXXFLAGS variable contains a value in make.conf .sp Return True if value is set for var .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.cxxflags_contains \(aq\-pipe\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.emerge_default_opts_contains(value) Verify if EMERGE_DEFAULT_OPTS variable contains a value in make.conf .sp Return True if value is set for var .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.emerge_default_opts_contains \(aq\-\-jobs\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.features_contains(value) Verify if FEATURES variable contains a value in make.conf .sp Return True if value is set for var .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.features_contains \(aqwebrsync\-gpg\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.gentoo_mirrors_contains(value) Verify if GENTOO_MIRRORS variable contains a value in make.conf .sp Return True if value is set for var .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.gentoo_mirrors_contains \(aqhttp://distfiles.gentoo.org\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.get_cflags() Get the value of CFLAGS variable in the make.conf .sp Return the value of the variable or None if the variable is not in the make.conf .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.get_cflags .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.get_chost() Get the value of CHOST variable in the make.conf .sp Return the value of the variable or None if the variable is not in the make.conf .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.get_chost .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.get_cxxflags() Get the value of CXXFLAGS variable in the make.conf .sp Return the value of the variable or None if the variable is not in the make.conf .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.get_cxxflags .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.get_emerge_default_opts() Get the value of EMERGE_DEFAULT_OPTS variable in the make.conf .sp Return the value of the variable or None if the variable is not in the make.conf .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.get_emerge_default_opts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.get_features() Get the value of FEATURES variable in the make.conf .sp Return the value of the variable or None if the variable is not in the make.conf .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.get_features .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.get_gentoo_mirrors() Get the value of GENTOO_MIRRORS variable in the make.conf .sp Return the value of the variable or None if the variable is not in the make.conf .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.get_gentoo_mirrors .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.get_makeopts() Get the value of MAKEOPTS variable in the make.conf .sp Return the value of the variable or None if the variable is not in the make.conf .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.get_makeopts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.get_sync() Get the value of SYNC variable in the make.conf .sp Return the value of the variable or None if the variable is not in the make.conf .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.get_sync .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.get_var(var) Get the value of a variable in make.conf .sp Return the value of the variable or None if the variable is not in make.conf .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.get_var \(aqLINGUAS\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.makeopts_contains(value) Verify if MAKEOPTS variable contains a value in make.conf .sp Return True if value is set for var .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.makeopts_contains \(aq\-j3\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.remove_var(var) Remove a variable from the make.conf .sp Return a dict containing the new value for the variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.remove_var \(aqLINGUAS\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.set_cflags(value) Set the CFLAGS variable .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.set_cflags \(aq\-march=native \-O2 \-pipe\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.set_chost(value) Set the CHOST variable .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.set_chost \(aqx86_64\-pc\-linux\-gnu\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.set_cxxflags(value) Set the CXXFLAGS variable .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.set_cxxflags \(aq\-march=native \-O2 \-pipe\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.set_emerge_default_opts(value) Set the EMERGE_DEFAULT_OPTS variable .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.set_emerge_default_opts \(aq\-\-jobs\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.set_gentoo_mirrors(value) Set the GENTOO_MIRRORS variable .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.set_gentoo_mirrors \(aqhttp://distfiles.gentoo.org\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.set_makeopts(value) Set the MAKEOPTS variable .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.set_makeopts \(aq\-j3\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.set_sync(value) Set the SYNC variable .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.set_sync \(aqrsync://rsync.namerica.gentoo.org/gentoo\-portage\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.set_var(var, value) Set a variable in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.set_var \(aqLINGUAS\(aq \(aqen\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.sync_contains(value) Verify if SYNC variable contains a value in make.conf .sp Return True if value is set for var .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.sync_contains \(aqrsync://rsync.namerica.gentoo.org/gentoo\-portage\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.trim_cflags(value) Remove a value from CFLAGS variable in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.trim_cflags \(aq\-pipe\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.trim_cxxflags(value) Remove a value from CXXFLAGS variable in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.trim_cxxflags \(aq\-pipe\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.trim_emerge_default_opts(value) Remove a value from EMERGE_DEFAULT_OPTS variable in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.trim_emerge_default_opts \(aq\-\-jobs\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.trim_features(value) Remove a value from FEATURES variable in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.trim_features \(aqwebrsync\-gpg\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.trim_gentoo_mirrors(value) Remove a value from GENTOO_MIRRORS variable in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.trim_gentoo_mirrors \(aqhttp://distfiles.gentoo.org\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.trim_makeopts(value) Remove a value from MAKEOPTS variable in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.trim_makeopts \(aq\-j3\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.trim_var(var, value) Remove a value from a variable in the make.conf .sp Return a dict containing the new value for variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq, \(aqnew\(aq: \(aq<new\-value>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.trim_var \(aqLINGUAS\(aq \(aqen\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.makeconf.var_contains(var, value) Verify if variable contains a value in make.conf .sp Return True if value is set for var .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq makeconf.var_contains \(aqLINGUAS\(aq \(aqen\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mandrill .SS Mandrill .sp Send out emails using the \fI\%Mandrill\fP \fI\%API\fP\&. .sp In the minion configuration file, the following block is required: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mandrill: key: <API_KEY> .ft P .fi .UNINDENT .UNINDENT .sp New in version 2018.3.0. .INDENT 0.0 .TP .B salt.modules.mandrill.send(message, asynchronous=False, ip_pool=None, send_at=None, api_url=None, api_version=None, api_key=None) Send out the email using the details from the \fBmessage\fP argument. .INDENT 7.0 .TP .B message The information on the message to send. This argument must be sent as dictionary with at fields as specified in the Mandrill API documentation. .TP .B asynchronous: \fBFalse\fP Enable a background sending mode that is optimized for bulk sending. In asynchronous mode, messages/send will immediately return a status of \(dqqueued\(dq for every recipient. To handle rejections when sending in asynchronous mode, set up a webhook for the \(aqreject\(aq event. Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of asynchronous. .TP .B ip_pool The name of the dedicated ip pool that should be used to send the message. If you do not have any dedicated IPs, this parameter has no effect. If you specify a pool that does not exist, your default pool will be used instead. .TP .B send_at When this message should be sent as a UTC timestamp in \fBYYYY\-MM\-DD HH:MM:SS\fP format. If you specify a time in the past, the message will be sent immediately. An additional fee applies for scheduled email, and this feature is only available to accounts with a positive balance. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Fur further details please consult the \fI\%API documentation\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mandrill.send message=\(dq{\(aqsubject\(aq: \(aqHi\(aq, \(aqfrom_email\(aq: \(aqtest@example.com\(aq, \(aqto\(aq: [{\(aqemail\(aq: \(aqrecv@example.com\(aq, \(aqtype\(aq: \(aqto\(aq}]}\(dq .ft P .fi .UNINDENT .UNINDENT .sp \fBmessage\fP structure example (as YAML for readability): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C message: text: | This is the body of the email. This is the second line. subject: Email subject from_name: Test At Example Dot Com from_email: test@example.com to: \- email: recv@example.com type: to name: Recv At Example Dot Com \- email: cc@example.com type: cc name: CC At Example Dot Com important: true track_clicks: true track_opens: true attachments: \- type: text/x\-yaml name: yaml_file.yml content: aV9hbV9zdXBlcl9jdXJpb3VzOiB0cnVl .ft P .fi .UNINDENT .UNINDENT .sp Output example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C minion: \-\-\-\-\-\-\-\-\-\- comment: out: |_ \-\-\-\-\-\-\-\-\-\- _id: c4353540a3c123eca112bbdd704ab6 email: recv@example.com reject_reason: None status: sent result: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.marathon .sp Module providing a simple management interface to a marathon cluster. .sp Currently this only works when run through a proxy minion. .sp New in version 2015.8.2. .INDENT 0.0 .TP .B salt.modules.marathon.app(id) Return the current server configuration for the specified app. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt marathon\-minion\-id marathon.app my\-app .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.marathon.apps() Return a list of the currently installed app ids. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt marathon\-minion\-id marathon.apps .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.marathon.has_app(id) Return whether the given app id is currently configured. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt marathon\-minion\-id marathon.has_app my\-app .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.marathon.info() Return configuration and status information about the marathon instance. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt marathon\-minion\-id marathon.info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.marathon.restart_app(id, restart=False, force=True) Restart the current server configuration for the specified app. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrestart\fP \-\- Restart the app .IP \(bu 2 \fBforce\fP \-\- Override the current deployment .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt marathon\-minion\-id marathon.restart_app my\-app .ft P .fi .UNINDENT .UNINDENT .sp By default, this will only check if the app exists in marathon. It does not check if there are any tasks associated with it or if the app is suspended. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt marathon\-minion\-id marathon.restart_app my\-app true true .ft P .fi .UNINDENT .UNINDENT .sp The restart option needs to be set to True to actually issue a rolling restart to marathon. .sp The force option tells marathon to ignore the current app deployment if there is one. .UNINDENT .INDENT 0.0 .TP .B salt.modules.marathon.rm_app(id) Remove the specified app from the server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt marathon\-minion\-id marathon.rm_app my\-app .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.marathon.update_app(id, config) Update the specified app with the given configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt marathon\-minion\-id marathon.update_app my\-app \(aq<config yaml>\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.match .sp The match module allows for match routines to be run and determine target specs .INDENT 0.0 .TP .B salt.modules.match.compound(tgt, minion_id=None) Return True if the minion ID matches the given compound target .INDENT 7.0 .TP .B minion_id Specify the minion ID to match against the target expression .sp New in version 2014.7.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.compound \(aqL@cheese,foo and *\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.match.data(tgt) Return True if the minion matches the given data target .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.data \(aqspam:eggs\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.match.filter_by(lookup, tgt_type=\(aqcompound\(aq, minion_id=None, merge=None, merge_lists=False, default=\(aqdefault\(aq) Return the first match in a dictionary of target patterns .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.filter_by \(aq{foo*: Foo!, bar*: Bar!}\(aq minion_id=bar03 .ft P .fi .UNINDENT .UNINDENT .sp Pillar Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Filter the data for the current minion into a variable: {% set roles = salt[\(aqmatch.filter_by\(aq]({ \(aqweb*\(aq: [\(aqapp\(aq, \(aqcaching\(aq], \(aqdb*\(aq: [\(aqdb\(aq], }, minion_id=grains[\(aqid\(aq], default=\(aqweb*\(aq) %} # Make the filtered data available to Pillar: roles: {{ roles | yaml() }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.match.glob(tgt, minion_id=None) Return True if the minion ID matches the given glob target .INDENT 7.0 .TP .B minion_id Specify the minion ID to match against the target expression .sp New in version 2014.7.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.glob \(aq*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.match.grain(tgt, delimiter=\(aq:\(aq) Return True if the minion matches the given grain target. The \fBdelimiter\fP argument can be used to specify a different delimiter. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.grain \(aqos:Ubuntu\(aq salt \(aq*\(aq match.grain \(aqipv6|2001:db8::ff00:42:8329\(aq delimiter=\(aq|\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B delimiter Specify an alternate delimiter to use when traversing a nested dict .sp New in version 2014.7.0. .TP .B delim Specify an alternate delimiter to use when traversing a nested dict .sp New in version 0.16.4. .sp Deprecated since version 2015.8.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.match.grain_pcre(tgt, delimiter=\(aq:\(aq) Return True if the minion matches the given grain_pcre target. The \fBdelimiter\fP argument can be used to specify a different delimiter. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.grain_pcre \(aqos:Fedo.*\(aq salt \(aq*\(aq match.grain_pcre \(aqipv6|2001:.*\(aq delimiter=\(aq|\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B delimiter Specify an alternate delimiter to use when traversing a nested dict .sp New in version 2014.7.0. .TP .B delim Specify an alternate delimiter to use when traversing a nested dict .sp New in version 0.16.4. .sp Deprecated since version 2015.8.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.match.ifelse(*args, tgt_type=\(aqcompound\(aq, minion_id=None, merge=None, merge_lists=False) New in version 3006.0. .sp Evaluate each pair of arguments up to the last one as a (matcher, value) tuple, returning \fBvalue\fP if matched. If none match, returns the last argument. .sp The \fBifelse\fP function is like a multi\-level if\-else statement. It was inspired by CFEngine\(aqs \fBifelse\fP function which in turn was inspired by Oracle\(aqs \fBDECODE\fP function. It must have an odd number of arguments (from 1 to N). The last argument is the default value, like the \fBelse\fP clause in standard programming languages. Every pair of arguments before the last one are evaluated as a pair. If the first one evaluates true then the second one is returned, as if you had used the first one in a compound match expression. Boolean values can also be used as the first item in a pair, as it will be translated to a match that will always match (\(dq*\(dq) or never match (\(dqSALT_IFELSE_MATCH_NOTHING\(dq) a target system. .sp This is essentially another way to express the \fBfilter_by\fP functionality in way that\(aqs familiar to CFEngine or Oracle users. Consider using \fBfilter_by\fP unless this function fits your workflow. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.ifelse \(aqfoo*\(aq \(aqFoo!\(aq \(aqbar*\(aq \(aqBar!\(aq minion_id=bar03 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.match.ipcidr(tgt) Return True if the minion matches the given ipcidr target .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.ipcidr \(aq192.168.44.0/24\(aq .ft P .fi .UNINDENT .UNINDENT .sp delimiter Pillar Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \(aq172.16.0.0/12\(aq: \- match: ipcidr \- nodeclass: internal .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.match.list_(tgt, minion_id=None) Return True if the minion ID matches the given list target .INDENT 7.0 .TP .B minion_id Specify the minion ID to match against the target expression .sp New in version 2014.7.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.list \(aqserver1,server2\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.match.pcre(tgt, minion_id=None) Return True if the minion ID matches the given pcre target .INDENT 7.0 .TP .B minion_id Specify the minion ID to match against the target expression .sp New in version 2014.7.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.pcre \(aq.*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.match.pillar(tgt, delimiter=\(aq:\(aq) Return True if the minion matches the given pillar target. The \fBdelimiter\fP argument can be used to specify a different delimiter. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.pillar \(aqcheese:foo\(aq salt \(aq*\(aq match.pillar \(aqclone_url|https://github.com/saltstack/salt.git\(aq delimiter=\(aq|\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B delimiter Specify an alternate delimiter to use when traversing a nested dict .sp New in version 2014.7.0. .TP .B delim Specify an alternate delimiter to use when traversing a nested dict .sp New in version 0.16.4. .sp Deprecated since version 2015.8.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.match.pillar_pcre(tgt, delimiter=\(aq:\(aq) Return True if the minion matches the given pillar_pcre target. The \fBdelimiter\fP argument can be used to specify a different delimiter. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.pillar_pcre \(aqcheese:(swiss|american)\(aq salt \(aq*\(aq match.pillar_pcre \(aqclone_url|https://github\e.com/.*\e.git\(aq delimiter=\(aq|\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B delimiter Specify an alternate delimiter to use when traversing a nested dict .sp New in version 2014.7.0. .TP .B delim Specify an alternate delimiter to use when traversing a nested dict .sp New in version 0.16.4. .sp Deprecated since version 2015.8.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.match.search_by(lookup, tgt_type=\(aqcompound\(aq, minion_id=None) Search a dictionary of target strings for matching targets .sp This is the inverse of \fI\%match.filter_by\fP and allows matching values instead of matching keys. A minion can be matched by multiple entries. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq match.search_by \(aq{web: [node1, node2], db: [node2, node]}\(aq .ft P .fi .UNINDENT .UNINDENT .sp Pillar Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set roles = salt.match.search_by({ \(aqweb\(aq: [\(aqG@os_family:Debian not nodeX\(aq], \(aqdb\(aq: [\(aqL@node2,node3 and G@datacenter:west\(aq], \(aqcaching\(aq: [\(aqnode3\(aq, \(aqnode4\(aq], }) %} # Make the filtered data available to Pillar: roles: {{ roles | yaml() }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mattermost .sp Module for sending messages to Mattermost .sp New in version 2017.7.0. .INDENT 0.0 .TP .B configuration This module can be used by either passing an api_url and hook directly or by specifying both in a configuration profile in the salt master/minion config. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mattermost: hook: peWcBiMOS9HrZG15peWcBiMOS9HrZG15 api_url: https://example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mattermost.post_message(message, channel=None, username=None, api_url=None, hook=None) Send a message to a Mattermost channel. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBchannel\fP \-\- The channel name, either will work. .IP \(bu 2 \fBusername\fP \-\- The username of the poster. .IP \(bu 2 \fBmessage\fP \-\- The message to send to the Mattermost channel. .IP \(bu 2 \fBapi_url\fP \-\- The Mattermost api url, if not specified in the configuration. .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 .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mattermost.post_message message=\(aqBuild is done\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mdadm_raid .sp Salt module to manage RAID arrays with mdadm .INDENT 0.0 .TP .B salt.modules.mdadm_raid.add(name, device) Add new device to RAID array. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq raid.add /dev/md0 /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdadm_raid.assemble(name, devices, test_mode=False, **kwargs) Assemble a RAID device. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq raid.assemble /dev/md0 [\(aq/dev/xvdd\(aq, \(aq/dev/xvde\(aq] .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Adding \fBtest_mode=True\fP as an argument will print out the mdadm command that would have been run. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the array to assemble. .TP .B devices The list of devices comprising the array to assemble. .TP .B kwargs Optional arguments to be passed to mdadm. .TP .B returns .INDENT 7.0 .TP .B test_mode=True: Prints out the full command. .TP .B test_mode=False (Default): Executes command on the host(s) and prints out the mdadm output. .UNINDENT .UNINDENT .sp For more info, read the \fBmdadm\fP manpage. .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdadm_raid.create(name, level, devices, metadata=\(aqdefault\(aq, test_mode=False, **kwargs) Create a RAID device. .sp Changed in version 2014.7.0. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Use with CAUTION, as this function can be very destructive if not used properly! .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq raid.create /dev/md0 level=1 chunk=256 devices=\(dq[\(aq/dev/xvdd\(aq, \(aq/dev/xvde\(aq]\(dq test_mode=True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Adding \fBtest_mode=True\fP as an argument will print out the mdadm command that would have been run. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the array to create. .TP .B level The RAID level to use when creating the raid. .TP .B devices A list of devices used to build the array. .TP .B metadata Version of metadata to use when creating the array. .TP .B kwargs Optional arguments to be passed to mdadm. .TP .B returns .INDENT 7.0 .TP .B test_mode=True: Prints out the full command. .TP .B test_mode=False (Default): Executes command on remote the host(s) and Prints out the mdadm output. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 It takes time to create a RAID array. You can check the progress in \(dqresync_status:\(dq field of the results from the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq raid.detail /dev/md0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp For more info, read the \fBmdadm(8)\fP manpage .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdadm_raid.destroy(device) Destroy a RAID device. .sp WARNING This will zero the superblock of all members of the RAID array.. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq raid.destroy /dev/md0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdadm_raid.detail(device=\(aq/dev/md0\(aq) Show detail for a specified RAID device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq raid.detail \(aq/dev/md0\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdadm_raid.examine(device, quiet=False) Show detail for a specified RAID component device .INDENT 7.0 .TP .B device Device to examine, that is part of the RAID .TP .B quiet If the device is not part of the RAID, do not show any error .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq raid.examine \(aq/dev/sda1\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdadm_raid.list_() List the RAID devices. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq raid.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdadm_raid.save_config() Save RAID configuration to config file. .sp Same as: mdadm \-\-detail \-\-scan >> /etc/mdadm/mdadm.conf .sp Fixes this issue with Ubuntu REF: \fI\%http://askubuntu.com/questions/209702/why\-is\-my\-raid\-dev\-md1\-showing\-up\-as\-dev\-md126\-is\-mdadm\-conf\-being\-ignored\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq raid.save_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdadm_raid.stop() Shut down all arrays that can be shut down (i.e. are not currently in use). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq raid.stop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mdata .sp Module for managaging metadata in SmartOS Zones .sp New in version 2016.3.0. .INDENT 0.0 .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B platform smartos .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdata.delete_(*keyname) Delete metadata .INDENT 7.0 .TP .B prop string name of property .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mdata.get salt:role salt \(aq*\(aq mdata.get user\-script salt:role .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdata.get_(*keyname) Get metadata .INDENT 7.0 .TP .B keyname string name of key .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no keynames are specified, we get all (public) properties .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mdata.get salt:role salt \(aq*\(aq mdata.get user\-script salt:role .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdata.list_() List available metadata .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mdata.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdata.put_(keyname, val) Put metadata .INDENT 7.0 .TP .B prop string name of property .TP .B val string value to set .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mdata.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.memcached .sp Module for Management of Memcached Keys .sp New in version 2014.1.0. .INDENT 0.0 .TP .B salt.modules.memcached.add(key, value, host=\(aq127.0.0.1\(aq, port=11211, time=0, min_compress_len=0) Add a key to the memcached server, but only if it does not exist. Returns False if the key already exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq memcached.add <key> <value> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.memcached.decr(key, delta=1, host=\(aq127.0.0.1\(aq, port=11211) This function is an alias of \fBdecrement\fP\&. .INDENT 7.0 .INDENT 3.5 Decrement the value of a key .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq memcached.decrement <key> salt \(aq*\(aq memcached.decrement <key> 2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.memcached.decrement(key, delta=1, host=\(aq127.0.0.1\(aq, port=11211) Decrement the value of a key .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq memcached.decrement <key> salt \(aq*\(aq memcached.decrement <key> 2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.memcached.delete(key, host=\(aq127.0.0.1\(aq, port=11211, time=0) Delete a key from memcache server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq memcached.delete <key> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.memcached.get(key, host=\(aq127.0.0.1\(aq, port=11211) Retrieve value for a key .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq memcached.get <key> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.memcached.incr(key, delta=1, host=\(aq127.0.0.1\(aq, port=11211) This function is an alias of \fBincrement\fP\&. .INDENT 7.0 .INDENT 3.5 Increment the value of a key .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq memcached.increment <key> salt \(aq*\(aq memcached.increment <key> 2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.memcached.increment(key, delta=1, host=\(aq127.0.0.1\(aq, port=11211) Increment the value of a key .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq memcached.increment <key> salt \(aq*\(aq memcached.increment <key> 2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.memcached.replace(key, value, host=\(aq127.0.0.1\(aq, port=11211, time=0, min_compress_len=0) Replace a key on the memcached server. This only succeeds if the key already exists. This is the opposite of \fI\%memcached.add\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq memcached.replace <key> <value> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.memcached.set_(key, value, host=\(aq127.0.0.1\(aq, port=11211, time=0, min_compress_len=0) Set a key on the memcached server, overwriting the value if it exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq memcached.set <key> <value> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.memcached.status(host=\(aq127.0.0.1\(aq, port=11211) Get memcached status .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq memcached.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mine .sp The function cache system allows for data to be stored on the master so it can be easily read by other minions .INDENT 0.0 .TP .B salt.modules.mine.delete(fun) Remove specific function contents of minion. .INDENT 7.0 .TP .B Parameters \fBfun\fP (\fI\%str\fP) \-\- The name of the function. .TP .B Return type \fI\%bool\fP .TP .B Returns True on success. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mine.delete \(aqnetwork.interfaces\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mine.flush() Remove all mine contents of minion. .INDENT 7.0 .TP .B Return type \fI\%bool\fP .TP .B Returns True on success .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mine.flush .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mine.get(tgt, fun, tgt_type=\(aqglob\(aq, exclude_minion=False) Get data from the mine. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtgt\fP (\fI\%str\fP) \-\- Target whose mine data to get. .IP \(bu 2 \fBfun\fP (\fI\%str\fP\fI or \fP\fI\%list\fP) \-\- Function to get the mine data of. You can specify multiple functions to retrieve using either a list or a comma\-separated string of functions. .IP \(bu 2 \fBtgt_type\fP (\fI\%str\fP) \-\- Default \fBglob\fP\&. Target type to use with \fBtgt\fP\&. See \fI\%Targeting Minions\fP for more information. Note that all pillar matches, whether using the compound matching system or the pillar matching system, will be exact matches, with globbing disabled. .IP \(bu 2 \fBexclude_minion\fP (\fI\%bool\fP) \-\- Excludes the current minion from the result set. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mine.get \(aq*\(aq network.interfaces salt \(aq*\(aq mine.get \(aqos:Fedora\(aq network.interfaces grain salt \(aq*\(aq mine.get \(aqG@os:Fedora and S@192.168.5.0/24\(aq network.ipaddrs compound .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 Retrieving Mine data from Pillar and Orchestrate .sp This execution module is intended to be executed on minions. Master\-side operations such as Pillar or Orchestrate that require Mine data should use the \fI\%Mine Runner module\fP instead; it can be invoked from a Pillar SLS file using the \fI\%saltutil.runner\fP module. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set minion_ips = salt.saltutil.runner(\(aqmine.get\(aq, tgt=\(aq*\(aq, fun=\(aqnetwork.ip_addrs\(aq, tgt_type=\(aqglob\(aq) %} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mine.get_docker(interfaces=None, cidrs=None, with_container_id=False) Changed in version 2017.7.8,2018.3.3: When \fI\%docker.update_mine\fP is set to \fBFalse\fP for a given minion, no mine data will be populated for that minion, and thus none will be returned for it. .sp Changed in version 2019.2.0: \fI\%docker.update_mine\fP now defaults to \fBFalse\fP .sp Get all mine data for \fI\%docker.ps\fP and run an aggregation routine. The \fBinterfaces\fP parameter allows for specifying the network interfaces from which to select IP addresses. The \fBcidrs\fP parameter allows for specifying a list of subnets which the IP address must match. .INDENT 7.0 .TP .B with_container_id Boolean, to expose container_id in the list of results .sp New in version 2015.8.2. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mine.get_docker salt \(aq*\(aq mine.get_docker interfaces=\(aqeth0\(aq salt \(aq*\(aq mine.get_docker interfaces=\(aq[\(dqeth0\(dq, \(dqeth1\(dq]\(aq salt \(aq*\(aq mine.get_docker cidrs=\(aq107.170.147.0/24\(aq salt \(aq*\(aq mine.get_docker cidrs=\(aq[\(dq107.170.147.0/24\(dq, \(dq172.17.42.0/24\(dq]\(aq salt \(aq*\(aq mine.get_docker interfaces=\(aq[\(dqeth0\(dq, \(dqeth1\(dq]\(aq cidrs=\(aq[\(dq107.170.147.0/24\(dq, \(dq172.17.42.0/24\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mine.send(name, *args, **kwargs) Send a specific function and its result to the salt mine. This gets stored in either the local cache, or the salt master\(aqs cache. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- Name of the function to add to the mine. .UNINDENT .sp The following pameters are extracted from kwargs if present: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmine_function\fP (\fI\%str\fP) \-\- The name of the execution_module.function to run and whose value will be stored in the salt mine. Defaults to \fBname\fP\&. .IP \(bu 2 \fBallow_tgt\fP (\fI\%str\fP) \-\- Targeting specification for ACL. Specifies which minions are allowed to access this function. Please note both your master and minion need to be on, at least, version 3000 for this to work properly. .IP \(bu 2 \fBallow_tgt_type\fP (\fI\%str\fP) \-\- Type of the targeting specification. This value will be ignored if \fBallow_tgt\fP is not specified. Please note both your master and minion need to be on, at least, version 3000 for this to work properly. .UNINDENT .UNINDENT .sp Remaining args and kwargs will be passed on to the function to run. .INDENT 7.0 .TP .B Return type \fI\%bool\fP .TP .B Returns Whether executing the function and storing the information was successful. .UNINDENT .sp Changed in version 3000: Added \fBallow_tgt\fP\- and \fBallow_tgt_type\fP\-parameters to specify which minions are allowed to access this function. See \fI\%Targeting Minions\fP for more information about targeting. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mine.send network.ip_addrs interface=eth0 salt \(aq*\(aq mine.send eth0_ip_addrs mine_function=network.ip_addrs interface=eth0 salt \(aq*\(aq mine.send eth0_ip_addrs mine_function=network.ip_addrs interface=eth0 allow_tgt=\(aqG@grain:value\(aq allow_tgt_type=compound .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mine.update(clear=False, mine_functions=None) Call the configured functions and send the data back up to the master. The functions to be called are merged from the master config, pillar and minion config under the option \fImine_functions\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mine_functions: network.ip_addrs: \- eth0 disk.usage: [] .ft P .fi .UNINDENT .UNINDENT .sp This function accepts the following arguments: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBclear\fP (\fI\%bool\fP) \-\- Default: \fBFalse\fP Specifies whether updating will clear the existing values (\fBTrue\fP), or whether it will update them (\fBFalse\fP). .IP \(bu 2 \fBmine_functions\fP (\fI\%dict\fP) \-\- .sp Update (or clear, see \fBclear\fP) the mine data on these functions only. This will need to have the structure as defined on \fI\%https://docs.saltproject.io/en/latest/topics/mine/index.html#mine\-functions\fP .sp This feature can be used when updating the mine for functions that require a refresh at different intervals than the rest of the functions specified under \fImine_functions\fP in the minion/master config or pillar. A potential use would be together with the \fIscheduler\fP, for example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C schedule: lldp_mine_update: function: mine.update kwargs: mine_functions: net.lldp: [] hours: 12 .ft P .fi .UNINDENT .UNINDENT .sp In the example above, the mine for \fInet.lldp\fP would be refreshed every 12 hours, while \fInetwork.ip_addrs\fP would continue to be updated as specified in \fImine_interval\fP\&. .UNINDENT .UNINDENT .sp The function cache will be populated with information from executing these functions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mine.update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mine.valid() List valid entries in mine configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mine.valid .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.minion .sp Module to provide information about minions .INDENT 0.0 .TP .B salt.modules.minion.kill(timeout=15) Kill the salt minion. .INDENT 7.0 .TP .B timeout int seconds to wait for the minion to die. .UNINDENT .sp If you have a monitor that restarts \fBsalt\-minion\fP when it dies then this is a great way to restart after a minion upgrade. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion[12] minion.kill minion1: \-\-\-\-\-\-\-\-\-\- killed: 7874 retcode: 0 minion2: \-\-\-\-\-\-\-\-\-\- killed: 29071 retcode: 0 .ft P .fi .UNINDENT .UNINDENT .sp The result of the salt command shows the process ID of the minions and the results of a kill signal to the minion in as the \fBretcode\fP value: \fB0\fP is success, anything else is a failure. .UNINDENT .INDENT 0.0 .TP .B salt.modules.minion.list_() Return a list of accepted, denied, unaccepted and rejected keys. This is the same output as \fIsalt\-key \-L\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmaster\(aq minion.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.minion.restart() Kill and restart the salt minion. .sp The configuration key \fBminion_restart_command\fP is an argv list for the command to restart the minion. If \fBminion_restart_command\fP is not specified or empty then the \fBargv\fP of the current process will be used. .sp if the configuration value \fBminion_restart_command\fP is not set and the \fB\-d\fP (daemonize) argument is missing from \fBargv\fP then the minion \fIwill\fP be killed but will \fInot\fP be restarted and will require the parent process to perform the restart. This behavior is intended for managed salt minion processes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion[12] minion.restart minion1: \-\-\-\-\-\-\-\-\-\- comment: \- Restart using process argv: \- /home/omniture/install/bin/salt\-minion \- \-d \- \-c \- /home/omniture/install/etc/salt killed: 10070 restart: \-\-\-\-\-\-\-\-\-\- stderr: stdout: retcode: 0 minion2: \-\-\-\-\-\-\-\-\-\- comment: \- Using configuration minion_restart_command: \- /home/omniture/install/bin/salt\-minion \- \-\-not\-an\-option \- \-d \- \-c \- /home/omniture/install/etc/salt \- Restart failed killed: 10896 restart: \-\-\-\-\-\-\-\-\-\- stderr: Usage: salt\-minion salt\-minion: error: no such option: \-\-not\-an\-option stdout: retcode: 64 .ft P .fi .UNINDENT .UNINDENT .sp The result of the command shows the process ID of \fBminion1\fP that is shutdown (killed) and the results of the restart. If there is a failure in the restart it will be reflected in a non\-zero \fBretcode\fP and possibly output in the \fBstderr\fP and/or \fBstdout\fP values along with addition information in the \fBcomment\fP field as is demonstrated with \fBminion2\fP\&. .UNINDENT .SS salt.modules.mod_random .SS Provides access to randomness generators. .sp New in version 2014.7.0. .INDENT 0.0 .TP .B salt.modules.mod_random.get_str(length=20, chars=None, lowercase=True, uppercase=True, digits=True, punctuation=True, whitespace=False, printable=False) New in version 2014.7.0. .sp Changed in version 3004: Changed the default character set used to include symbols and implemented arguments to control the used character set. .sp Returns a random string of the specified length. .INDENT 7.0 .TP .B length 20 Any valid number of bytes. .TP .B chars None New in version 3004. .sp String with any character that should be used to generate random string. .sp This argument supersedes all other character controlling arguments. .TP .B lowercase True New in version 3004. .sp Use lowercase letters in generated random string. (see \fI\%string.ascii_lowercase\fP) .sp This argument is superseded by chars. .TP .B uppercase True New in version 3004. .sp Use uppercase letters in generated random string. (see \fI\%string.ascii_uppercase\fP) .sp This argument is superseded by chars. .TP .B digits True New in version 3004. .sp Use digits in generated random string. (see \fI\%string.digits\fP) .sp This argument is superseded by chars. .TP .B printable False New in version 3004. .sp Use printable characters in generated random string and includes lowercase, uppercase, digits, punctuation and whitespace. (see \fI\%string.printable\fP) .sp It is disabled by default as includes whitespace characters which some systems do not handle well in passwords. This argument also supersedes all other classes because it includes them. .sp This argument is superseded by chars. .TP .B punctuation True New in version 3004. .sp Use punctuation characters in generated random string. (see \fI\%string.punctuation\fP) .sp This argument is superseded by chars. .TP .B whitespace False New in version 3004. .sp Use whitespace characters in generated random string. (see \fI\%string.whitespace\fP) .sp It is disabled by default as some systems do not handle whitespace characters in passwords well. .sp This argument is superseded by chars. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random.get_str 128 salt \(aq*\(aq random.get_str 128 chars=\(aqabc123.!()\(aq salt \(aq*\(aq random.get_str 128 lowercase=False whitespace=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mod_random.hash(value, algorithm=\(aqsha512\(aq) New in version 2014.7.0. .sp Encodes a value with the specified encoder. .INDENT 7.0 .TP .B value The value to be hashed. .TP .B algorithm sha512 The algorithm to use. May be any valid algorithm supported by hashlib. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random.hash \(aqI am a string\(aq md5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mod_random.rand_int(start=1, end=10, seed=None) Returns a random integer number between the start and end number. .sp New in version 2015.5.3. .INDENT 7.0 .TP .B start 1 Any valid integer number .TP .B end 10 Any valid integer number .TP .B seed : Optional hashable object .UNINDENT .sp Changed in version 2019.2.0: Added seed argument. Will return the same result when run with the same seed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random.rand_int 1 10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mod_random.sample(value, size, seed=None) Return a given sample size from a list. By default, the random number generator uses the current system time unless given a seed value. .sp New in version 3005. .INDENT 7.0 .TP .B value A list to e used as input. .TP .B size The sample size to return. .TP .B seed Any value which will be hashed as a seed for random. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random.sample \(aq[\(dqone\(dq, \(dqtwo\(dq]\(aq 1 seed=\(dqsomething\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mod_random.seed(range=10, hash=None) Returns a random number within a range. Optional hash argument can be any hashable object. If hash is omitted or None, the id of the minion is used. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B hash: None Any hashable object. .TP .B range: 10 Any valid integer number .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random.seed 10 hash=None .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mod_random.shadow_hash(crypt_salt=None, password=None, algorithm=\(aqsha512\(aq) Generates a salted hash suitable for /etc/shadow. .INDENT 7.0 .TP .B crypt_salt None Salt to be used in the generation of the hash. If one is not provided, a random salt will be generated. .TP .B password None Value to be salted and hashed. If one is not provided, a random password will be generated. .TP .B algorithm sha512 Hash algorithm to use. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random.shadow_hash \(aqMy5alT\(aq \(aqMyP@asswd\(aq md5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mod_random.shuffle(value, seed=None) Return a shuffled copy of an input list. By default, the random number generator uses the current system time unless given a seed value. .sp New in version 3005. .INDENT 7.0 .TP .B value A list to be used as input. .TP .B seed Any value which will be hashed as a seed for random. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random.shuffle \(aq[\(dqone\(dq, \(dqtwo\(dq]\(aq seed=\(dqsomething\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mod_random.str_encode(value, encoder=\(aqbase64\(aq) New in version 2014.7.0. .INDENT 7.0 .TP .B value The value to be encoded. .TP .B encoder base64 The encoder to use on the subsequent string. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random.str_encode \(aqI am a new string\(aq base64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.modjk .sp Control Modjk via the Apache Tomcat \(dqStatus\(dq worker (\fI\%http://tomcat.apache.org/connectors\-doc/reference/status.html\fP) .sp Below is an example of the configuration needed for this module. This configuration data can be placed either in \fI\%grains\fP or \fI\%pillar\fP\&. .sp If using grains, this can be accomplished \fI\%statically\fP or via a \fI\%grain module\fP\&. .sp If using pillar, the yaml configuration can be placed directly into a pillar SLS file, making this both the easier and more dynamic method of configuring this module. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C modjk: default: url: http://localhost/jkstatus user: modjk pass: secret realm: authentication realm for digest passwords timeout: 5 otherVhost: url: http://otherVhost/jkstatus user: modjk pass: secret2 realm: authentication realm2 for digest passwords timeout: 600 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.bulk_activate(workers, lbn, profile=\(aqdefault\(aq) Activate all the given workers in the specific load balancer .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.bulk_activate node1,node2,node3 loadbalancer1 salt \(aq*\(aq modjk.bulk_activate node1,node2,node3 loadbalancer1 other\-profile salt \(aq*\(aq modjk.bulk_activate [\(dqnode1\(dq,\(dqnode2\(dq,\(dqnode3\(dq] loadbalancer1 salt \(aq*\(aq modjk.bulk_activate [\(dqnode1\(dq,\(dqnode2\(dq,\(dqnode3\(dq] loadbalancer1 other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.bulk_disable(workers, lbn, profile=\(aqdefault\(aq) Disable all the given workers in the specific load balancer .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.bulk_disable node1,node2,node3 loadbalancer1 salt \(aq*\(aq modjk.bulk_disable node1,node2,node3 loadbalancer1 other\-profile salt \(aq*\(aq modjk.bulk_disable [\(dqnode1\(dq,\(dqnode2\(dq,\(dqnode3\(dq] loadbalancer1 salt \(aq*\(aq modjk.bulk_disable [\(dqnode1\(dq,\(dqnode2\(dq,\(dqnode3\(dq] loadbalancer1 other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.bulk_recover(workers, lbn, profile=\(aqdefault\(aq) Recover all the given workers in the specific load balancer .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.bulk_recover node1,node2,node3 loadbalancer1 salt \(aq*\(aq modjk.bulk_recover node1,node2,node3 loadbalancer1 other\-profile salt \(aq*\(aq modjk.bulk_recover [\(dqnode1\(dq,\(dqnode2\(dq,\(dqnode3\(dq] loadbalancer1 salt \(aq*\(aq modjk.bulk_recover [\(dqnode1\(dq,\(dqnode2\(dq,\(dqnode3\(dq] loadbalancer1 other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.bulk_stop(workers, lbn, profile=\(aqdefault\(aq) Stop all the given workers in the specific load balancer .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.bulk_stop node1,node2,node3 loadbalancer1 salt \(aq*\(aq modjk.bulk_stop node1,node2,node3 loadbalancer1 other\-profile salt \(aq*\(aq modjk.bulk_stop [\(dqnode1\(dq,\(dqnode2\(dq,\(dqnode3\(dq] loadbalancer1 salt \(aq*\(aq modjk.bulk_stop [\(dqnode1\(dq,\(dqnode2\(dq,\(dqnode3\(dq] loadbalancer1 other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.dump_config(profile=\(aqdefault\(aq) Dump the original configuration that was loaded from disk .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.dump_config salt \(aq*\(aq modjk.dump_config other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.get_running(profile=\(aqdefault\(aq) Get the current running config (not from disk) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.get_running salt \(aq*\(aq modjk.get_running other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.lb_edit(lbn, settings, profile=\(aqdefault\(aq) Edit the loadbalancer settings .sp Note: \fI\%http://tomcat.apache.org/connectors\-doc/reference/status.html\fP Data Parameters for the standard Update Action .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.lb_edit loadbalancer1 \(dq{\(aqvlr\(aq: 1, \(aqvlt\(aq: 60}\(dq salt \(aq*\(aq modjk.lb_edit loadbalancer1 \(dq{\(aqvlr\(aq: 1, \(aqvlt\(aq: 60}\(dq other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.list_configured_members(lbn, profile=\(aqdefault\(aq) Return a list of member workers from the configuration files .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.list_configured_members loadbalancer1 salt \(aq*\(aq modjk.list_configured_members loadbalancer1 other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.recover_all(lbn, profile=\(aqdefault\(aq) Set the all the workers in lbn to recover and activate them if they are not .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.recover_all loadbalancer1 salt \(aq*\(aq modjk.recover_all loadbalancer1 other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.reset_stats(lbn, profile=\(aqdefault\(aq) Reset all runtime statistics for the load balancer .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.reset_stats loadbalancer1 salt \(aq*\(aq modjk.reset_stats loadbalancer1 other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.version(profile=\(aqdefault\(aq) Return the modjk version .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.version salt \(aq*\(aq modjk.version other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.worker_activate(worker, lbn, profile=\(aqdefault\(aq) Set the worker to activate state in the lbn load balancer .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.worker_activate node1 loadbalancer1 salt \(aq*\(aq modjk.worker_activate node1 loadbalancer1 other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.worker_disable(worker, lbn, profile=\(aqdefault\(aq) Set the worker to disable state in the lbn load balancer .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.worker_disable node1 loadbalancer1 salt \(aq*\(aq modjk.worker_disable node1 loadbalancer1 other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.worker_edit(worker, lbn, settings, profile=\(aqdefault\(aq) Edit the worker settings .sp Note: \fI\%http://tomcat.apache.org/connectors\-doc/reference/status.html\fP Data Parameters for the standard Update Action .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.worker_edit node1 loadbalancer1 \(dq{\(aqvwf\(aq: 500, \(aqvwd\(aq: 60}\(dq salt \(aq*\(aq modjk.worker_edit node1 loadbalancer1 \(dq{\(aqvwf\(aq: 500, \(aqvwd\(aq: 60}\(dq other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.worker_recover(worker, lbn, profile=\(aqdefault\(aq) Set the worker to recover this module will fail if it is in OK state .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.worker_recover node1 loadbalancer1 salt \(aq*\(aq modjk.worker_recover node1 loadbalancer1 other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.worker_status(worker, profile=\(aqdefault\(aq) Return the state of the worker .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.worker_status node1 salt \(aq*\(aq modjk.worker_status node1 other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.worker_stop(worker, lbn, profile=\(aqdefault\(aq) Set the worker to stopped state in the lbn load balancer .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.worker_activate node1 loadbalancer1 salt \(aq*\(aq modjk.worker_activate node1 loadbalancer1 other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.modjk.workers(profile=\(aqdefault\(aq) Return a list of member workers and their status .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq modjk.workers salt \(aq*\(aq modjk.workers other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mongodb .sp Module to provide MongoDB functionality to Salt .INDENT 0.0 .TP .B configuration This module uses PyMongo, and accepts configuration details as parameters as well as configuration settings: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mongodb.host: \(aqlocalhost\(aq mongodb.port: 27017 mongodb.user: \(aq\(aq mongodb.password: \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .sp This data can also be passed into pillar. Options passed into opts will overwrite options passed into pillar. .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.collection_create(collection, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None) New in version 3006.0. .sp Create a collection in the specified database. .INDENT 7.0 .TP .B collection The name of the collection to create. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.collection_create mycollection <user> <password> <host> <port> <database> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.collection_drop(collection, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None) New in version 3006.0. .sp Drop a collection in the specified database. .INDENT 7.0 .TP .B collection The name of the collection to drop. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.collection_drop mycollection <user> <password> <host> <port> <database> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.collections_list(user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None) New in version 3006.0. .sp List the collections available in the specified database. .INDENT 7.0 .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.collections_list mycollection <user> <password> <host> <port> <database> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.db_exists(name, user=None, password=None, host=None, port=None, authdb=None) Checks if a database exists in MongoDB .INDENT 7.0 .TP .B name The name of the database to check for. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.db_exists <name> <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.db_list(user=None, password=None, host=None, port=None, authdb=None) List all MongoDB databases .INDENT 7.0 .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.db_list <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.db_remove(name, user=None, password=None, host=None, port=None, authdb=None) Remove a MongoDB database .INDENT 7.0 .TP .B name The name of the database to remove. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.db_remove <name> <user> <password> <host> <port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.find(collection, query=None, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None) Find an object or list of objects in a collection .INDENT 7.0 .TP .B collection The collection to find the objects in. .TP .B query The query to use when locating objects in the collection. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.find mycollection \(aq[{\(dqfoo\(dq: \(dqFOO\(dq, \(dqbar\(dq: \(dqBAR\(dq}]\(aq <user> <password> <host> <port> <database> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.insert(objects, collection, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None) Insert an object or list of objects into a collection .INDENT 7.0 .TP .B objects The objects to insert into the collection, should be provided as a list. .TP .B collection The collection to insert the objects into. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.insert \(aq[{\(dqfoo\(dq: \(dqFOO\(dq, \(dqbar\(dq: \(dqBAR\(dq}, {\(dqfoo\(dq: \(dqBAZ\(dq, \(dqbar\(dq: \(dqBAM\(dq}]\(aq mycollection <user> <password> <host> <port> <database> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.remove(collection, query=None, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, w=1, authdb=None) Remove an object or list of objects from a collection .INDENT 7.0 .TP .B collection The collection to remove objects from based on the query. .TP .B query Query to determine which objects to remove. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B database The database where the collection is. .TP .B w The number of matches to remove from the collection. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.remove mycollection \(aq[{\(dqfoo\(dq: \(dqFOO\(dq, \(dqbar\(dq: \(dqBAR\(dq}, {\(dqfoo\(dq: \(dqBAZ\(dq, \(dqbar\(dq: \(dqBAM\(dq}]\(aq <user> <password> <host> <port> <database> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.update_one(objects, collection, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None) Update an object into a collection \fI\%http://api.mongodb.com/python/current/api/pymongo/collection.html#pymongo.collection.Collection.update_one\fP .sp New in version 2016.11.0. .INDENT 7.0 .TP .B objects The objects to update in the collection, should be provided as a list. .TP .B collection The collection to insert the objects into. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.update_one \(aq{\(dq_id\(dq: \(dqmy_minion\(dq} {\(dqbar\(dq: \(dqBAR\(dq}\(aq mycollection <user> <password> <host> <port> <database> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.user_create(name, passwd, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None, roles=None) Create a MongoDB user .INDENT 7.0 .TP .B name The name of the user to create. .TP .B passwd The password for the user that is being created. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B database The MongoDB database to use when checking if the user exists. Default is \fBadmin\fP\&. .TP .B authdb The MongoDB database to use for authentication. Default is None. .TP .B roles The roles that should be associated with the user. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.user_create <user_name> <user_password> <roles> <user> <password> <host> <port> <database> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.user_exists(name, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None) Checks if a user exists in MongoDB .INDENT 7.0 .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B database The MongoDB database to use when checking if the user exists. Default is \fBadmin\fP\&. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.user_exists <name> <user> <password> <host> <port> <database> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.user_find(name, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None) Get single user from MongoDB .INDENT 7.0 .TP .B name The name of the user to find. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B database The MongoDB database to use when looking for the user. Default is \fBadmin\fP\&. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.user_find <name> <user> <password> <host> <port> <database> <authdb> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.user_grant_roles(name, roles, database, user=None, password=None, host=None, port=None, authdb=None) Grant one or many roles to a MongoDB user .INDENT 7.0 .TP .B name The user to grant the specified roles to. .TP .B roles The roles to grant to the specified user. .TP .B database The database to great the roles against for the specified user. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.user_grant_roles johndoe \(aq[\(dqreadWrite\(dq]\(aq dbname admin adminpwd localhost 27017 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.user_grant_roles janedoe \(aq[{\(dqrole\(dq: \(dqreadWrite\(dq, \(dqdb\(dq: \(dqdbname\(dq }, {\(dqrole\(dq: \(dqread\(dq, \(dqdb\(dq: \(dqotherdb\(dq}]\(aq dbname admin adminpwd localhost 27017 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.user_list(user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None) List users of a MongoDB database .INDENT 7.0 .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B database The MongoDB database to use when listing users. Default is \fBadmin\fP\&. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.user_list <user> <password> <host> <port> <database> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.user_remove(name, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None) Remove a MongoDB user .INDENT 7.0 .TP .B name The name of the user that should be removed. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.user_remove <name> <user> <password> <host> <port> <database> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.user_revoke_roles(name, roles, database, user=None, password=None, host=None, port=None, authdb=None) Revoke one or many roles to a MongoDB user .INDENT 7.0 .TP .B user The user to connect to MongoDB as. Default is None. .TP .B roles The roles to revoke from the specified user. .TP .B database The database to revoke the roles from for the specified user. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.user_revoke_roles johndoe \(aq[\(dqreadWrite\(dq]\(aq dbname admin adminpwd localhost 27017 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.user_revoke_roles janedoe \(aq[{\(dqrole\(dq: \(dqreadWrite\(dq, \(dqdb\(dq: \(dqdbname\(dq }, {\(dqrole\(dq: \(dqread\(dq, \(dqdb\(dq: \(dqotherdb\(dq}]\(aq dbname admin adminpwd localhost 27017 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.user_roles_exists(name, roles, database, user=None, password=None, host=None, port=None, authdb=None) Checks if a user of a MongoDB database has specified roles .INDENT 7.0 .TP .B name The name of the user to check for the specified roles. .TP .B roles The roles to check are associated with the specified user. .TP .B database The database to check has the specified roles for the specified user. .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.user_roles_exists johndoe \(aq[\(dqreadWrite\(dq]\(aq dbname admin adminpwd localhost 27017 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.user_roles_exists johndoe \(aq[{\(dqrole\(dq: \(dqreadWrite\(dq, \(dqdb\(dq: \(dqdbname\(dq }, {\(dqrole\(dq: \(dqread\(dq, \(dqdb\(dq: \(dqotherdb\(dq}]\(aq dbname admin adminpwd localhost 27017 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mongodb.version(user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None) Get MongoDB instance version .INDENT 7.0 .TP .B user The user to connect to MongoDB as. Default is None. .TP .B password The password to use to connect to MongoDB as. Default is None. .TP .B host The host where MongoDB is running. Default is None. .TP .B port The host where MongoDB is running. Default is None. .TP .B authdb The MongoDB database to use for authentication. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mongodb.version <user> <password> <host> <port> <database> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.monit .sp Monit service module. This module will create a monit type service watcher. .INDENT 0.0 .TP .B salt.modules.monit.configtest() New in version 2016.3.0. .sp Test monit configuration syntax .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq monit.configtest .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.monit.id_(reset=False) New in version 2016.3.0. .sp Return monit unique id. .INDENT 7.0 .TP .B reset False Reset current id and generate a new id when it\(aqs True. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq monit.id [reset=True] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.monit.monitor(name) monitor service via monit .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq monit.monitor <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.monit.reload_() New in version 2016.3.0. .sp Reload monit configuration .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq monit.reload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.monit.restart(name) Restart service via monit .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq monit.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.monit.start(name) CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq monit.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.monit.status(svc_name=\(aq\(aq) Display a process status from monit .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq monit.status salt \(aq*\(aq monit.status <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.monit.stop(name) Stops service via monit .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq monit.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.monit.summary(svc_name=\(aq\(aq) Display a summary from monit .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq monit.summary salt \(aq*\(aq monit.summary <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.monit.unmonitor(name) Unmonitor service via monit .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq monit.unmonitor <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.monit.validate() New in version 2016.3.0. .sp Check all services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq monit.validate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.monit.version() New in version 2016.3.0. .sp Return version from monit \-V .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq monit.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.moosefs .sp Module for gathering and managing information about MooseFS .INDENT 0.0 .TP .B salt.modules.moosefs.dirinfo(path, opts=None) Return information on a directory located on the Moose .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq moosefs.dirinfo /path/to/dir/ [\-[n][h|H]] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.moosefs.fileinfo(path) Return information on a file located on the Moose .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq moosefs.fileinfo /path/to/dir/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.moosefs.getgoal(path, opts=None) Return goal(s) for a file or directory .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq moosefs.getgoal /path/to/file [\-[n][h|H]] salt \(aq*\(aq moosefs.getgoal /path/to/dir/ [\-[n][h|H][r]] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.moosefs.mounts() Return a list of current MooseFS mounts .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq moosefs.mounts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mount .sp Salt module to manage Unix mounts and the fstab file .INDENT 0.0 .TP .B salt.modules.mount.active(extended=False) List the active mounts. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.active .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.automaster(config=\(aq/etc/auto_salt\(aq) List the contents of the auto master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.automaster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.delete_mount_cache(real_name) New in version 2018.3.0. .sp Provide information if the path is mounted .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.delete_mount_cache /mnt/share .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.filesystems(config=\(aq/etc/filesystems\(aq) New in version 2018.3.3. .sp List the contents of the filesystems .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.filesystems .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.fstab(config=\(aq/etc/fstab\(aq) Changed in version 2016.3.2. .sp List the contents of the fstab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.fstab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.get_device_from_path(path) Return the underlying device for a specified path. .sp New in version 3006.0. .INDENT 7.0 .TP .B path The path for the function to evaluate. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.get_device_from_path / .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.get_mount_from_path(path) Return the mount providing a specified path. .sp New in version 3006.0. .INDENT 7.0 .TP .B path The path for the function to evaluate. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.get_mount_from_path /opt/some/nested/path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.is_fuse_exec(cmd) Returns true if the command passed is a fuse mountable application. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.is_fuse_exec sshfs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.is_mounted(name) New in version 2014.7.0. .sp Provide information if the path is mounted .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.is_mounted /mnt/share .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.mount(name, device=False, mkmnt=False, fstype=\(aq\(aq, opts=\(aqdefaults\(aq, user=None, util=\(aqmount\(aq) Mount a device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.mount /mnt/foo /dev/sdz1 True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.read_mount_cache(name) New in version 2018.3.0. .sp Provide information if the path is mounted .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.read_mount_cache /mnt/share .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.remount(name, device, mkmnt=False, fstype=\(aq\(aq, opts=\(aqdefaults\(aq, user=None) Attempt to remount a device, if the device is not already mounted, mount is called .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.remount /mnt/foo /dev/sdz1 True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.rm_automaster(name, device, config=\(aq/etc/auto_salt\(aq) Remove the mount point from the auto_master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.rm_automaster /mnt/foo /dev/sdg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.rm_filesystems(name, device, config=\(aq/etc/filesystems\(aq) New in version 2018.3.3. .sp Remove the mount point from the filesystems .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.rm_filesystems /mnt/foo /dev/sdg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.rm_fstab(name, device, config=\(aq/etc/fstab\(aq) Changed in version 2016.3.2. .sp Remove the mount point from the fstab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.rm_fstab /mnt/foo /dev/sdg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.rm_vfstab(name, device, config=\(aq/etc/vfstab\(aq) New in version 2016.3.2. .sp Remove the mount point from the vfstab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.rm_vfstab /mnt/foo /device/c0t0d0p0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.set_automaster(name, device, fstype, opts=\(aq\(aq, config=\(aq/etc/auto_salt\(aq, test=False, not_change=False, **kwargs) Verify that this mount is represented in the auto_salt, change the mount to match the data passed, or add the mount if it is not present. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.set_automaster /mnt/foo /dev/sdz1 ext4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.set_filesystems(name, device, vfstype, opts=\(aq\-\(aq, mount=\(aqtrue\(aq, config=\(aq/etc/filesystems\(aq, test=False, match_on=\(aqauto\(aq, not_change=False, **kwargs) New in version 2018.3.3. .sp Verify that this mount is represented in the filesystems, change the mount to match the data passed, or add the mount if it is not present on AIX .sp If the entry is found via \fImatch_on\fP and \fInot_change\fP is True, the current line will be preserved. .INDENT 7.0 .INDENT 3.5 Provide information if the path is mounted .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the mount point where the device is mounted. .IP \(bu 2 \fBdevice\fP \-\- The device that is being mounted. .IP \(bu 2 \fBvfstype\fP \-\- The file system that is used (AIX has two fstypes, fstype and vfstype \- similar to Linux fstype) .IP \(bu 2 \fBopts\fP \-\- Additional options used when mounting the device. .IP \(bu 2 \fBmount\fP \-\- Mount if not mounted, default True. .IP \(bu 2 \fBconfig\fP \-\- Configuration file, default /etc/filesystems. .IP \(bu 2 \fBmatch\fP \-\- File systems type to match on, default auto .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.set_filesystems /mnt/foo /dev/sdz1 jfs2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.set_fstab(name, device, fstype, opts=\(aqdefaults\(aq, dump=0, pass_num=0, config=\(aq/etc/fstab\(aq, test=False, match_on=\(aqauto\(aq, not_change=False, **kwargs) Verify that this mount is represented in the fstab, change the mount to match the data passed, or add the mount if it is not present. .sp If the entry is found via \fImatch_on\fP and \fInot_change\fP is True, the current line will be preserved. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.set_fstab /mnt/foo /dev/sdz1 ext4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.set_vfstab(name, device, fstype, opts=\(aq\-\(aq, device_fsck=\(aq\-\(aq, pass_fsck=\(aq\-\(aq, mount_at_boot=\(aqyes\(aq, config=\(aq/etc/vfstab\(aq, test=False, match_on=\(aqauto\(aq, not_change=False, **kwargs) New in version 2016.3.2. .sp Verify that this mount is represented in the fstab, change the mount to match the data passed, or add the mount if it is not present. .sp If the entry is found via \fImatch_on\fP and \fInot_change\fP is True, the current line will be preserved. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.set_vfstab /mnt/foo /device/c0t0d0p0 ufs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.swapoff(name) Deactivate a named swap mount .sp Changed in version 2016.3.2. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.swapoff /root/swapfile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.swapon(name, priority=None) Activate a swap disk .sp Changed in version 2016.3.2. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.swapon /root/swapfile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.swaps() Return a dict containing information on active swap .sp Changed in version 2016.3.2. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.swaps .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.umount(name, device=None, user=None, util=\(aqmount\(aq, lazy=False) Attempt to unmount a device by specifying the directory it is mounted on .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.umount /mnt/foo .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.umount /mnt/foo /dev/xvdc1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.vfstab(config=\(aq/etc/vfstab\(aq) New in version 2016.3.2. .sp List the contents of the vfstab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.vfstab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.write_mount_cache(real_name, device, mkmnt, fstype, mount_opts) New in version 2018.3.0. .sp Provide information if the path is mounted .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBreal_name\fP \-\- The real name of the mount point where the device is mounted. .IP \(bu 2 \fBdevice\fP \-\- The device that is being mounted. .IP \(bu 2 \fBmkmnt\fP \-\- Whether or not the mount point should be created. .IP \(bu 2 \fBfstype\fP \-\- The file system that is used. .IP \(bu 2 \fBmount_opts\fP \-\- Additional options used when mounting the device. .UNINDENT .TP .B Returns Boolean if message was sent successfully. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mount.write_mount_cache /mnt/share /dev/sda1 False ext4 defaults,nosuid .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mssql .sp Module to provide MS SQL Server compatibility to salt. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 FreeTDS .IP \(bu 2 pymssql Python module .UNINDENT .TP .B configuration In order to connect to MS SQL Server, certain configuration is required in minion configs/pillars on the relevant minions. Some sample pillars might look like: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mssql.server: \(aqlocalhost\(aq mssql.port: 1433 mssql.user: \(aqsysdba\(aq mssql.password: \(aqSome preferable complex password\(aq mssql.database: \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .sp The default for the port is \(aq1433\(aq and for the database is \(aq\(aq (empty string); in most cases they can be left at the default setting. Options that are directly passed into functions will overwrite options from configs or pillars. .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.db_create(database, containment=\(aqNONE\(aq, new_database_options=None, **kwargs) Creates a new database. Does not update options of existing databases. new_database_options can only be a list of strings .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.db_create DB_NAME .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.db_exists(database_name, **kwargs) Find if a specific database exists on the MS SQL server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.db_exists database_name=\(aqDBNAME\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.db_list(**kwargs) Return the database list created on a MS SQL server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.db_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.db_remove(database_name, **kwargs) Drops a specific database from the MS SQL server. It will not drop any of \(aqmaster\(aq, \(aqmodel\(aq, \(aqmsdb\(aq or \(aqtempdb\(aq. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.db_remove database_name=\(aqDBNAME\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.login_create(login, new_login_password=None, new_login_domain=\(aq\(aq, new_login_roles=None, new_login_options=None, **kwargs) Creates a new login. Does not update password of existing logins. For Windows authentication, provide \fBnew_login_domain\fP\&. For SQL Server authentication, prvide \fBnew_login_password\fP\&. Since hashed passwords are \fIvarbinary\fP values, if the \fBnew_login_password\fP is \(aqint / long\(aq, it will be considered to be HASHED. .INDENT 7.0 .TP .B new_login_roles a list of SERVER roles .TP .B new_login_options a list of strings .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.login_create LOGIN_NAME database=DBNAME [new_login_password=PASSWORD] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.login_exists(login, domain=\(aq\(aq, **kwargs) Find if a login exists in the MS SQL server. domain, if provided, will be prepended to login .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.login_exists \(aqLOGIN\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.login_remove(login, **kwargs) Removes an login. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.login_remove LOGINNAME .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.role_create(role, owner=None, grants=None, **kwargs) Creates a new database role. If no owner is specified, the role will be owned by the user that executes CREATE ROLE, which is the user argument or mssql.user option. grants is list of strings. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.role_create role=product01 owner=sysdba grants=\(aq[\(dqSELECT\(dq, \(dqINSERT\(dq, \(dqUPDATE\(dq, \(dqDELETE\(dq, \(dqEXECUTE\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.role_exists(role, **kwargs) Checks if a role exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.role_exists db_owner .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.role_list(**kwargs) Lists database roles. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.role_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.role_remove(role, **kwargs) Remove a database role. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.role_create role=test_role01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.tsql_query(query, **kwargs) Run a SQL query and return query result as list of tuples, or a list of dictionaries if as_dict was passed, or an empty list if no data is available. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.tsql_query \(aqSELECT @@version as version\(aq as_dict=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.user_create(username, login=None, domain=\(aq\(aq, database=None, roles=None, options=None, **kwargs) Creates a new user. If login is not specified, the user will be created without a login. domain, if provided, will be prepended to username. options can only be a list of strings .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.user_create USERNAME database=DBNAME .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.user_exists(username, domain=\(aq\(aq, database=None, **kwargs) Find if an user exists in a specific database on the MS SQL server. domain, if provided, will be prepended to username .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.user_exists \(aqUSERNAME\(aq [database=\(aqDBNAME\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.user_list(**kwargs) Get the user list for a specific database on the MS SQL server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.user_list [database=\(aqDBNAME\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.user_remove(username, **kwargs) Removes an user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.user_remove USERNAME database=DBNAME .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mssql.version(**kwargs) Return the version of a MS SQL server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion mssql.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.msteams .sp Module for sending messages to MS Teams .sp New in version 2017.7.0. .INDENT 0.0 .TP .B configuration This module can be used by either passing a hook_url directly or by specifying it in a configuration profile in the salt master/minion config. For example: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C msteams: hook_url: https://outlook.office.com/webhook/837 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.msteams.post_card(message, hook_url=None, title=None, theme_color=None) Send a message to an MS Teams channel. :param message: The message to send to the MS Teams channel. :param hook_url: The Teams webhook URL, if not specified in the configuration. :param title: Optional title for the posted card :param theme_color: Optional hex color highlight for the posted card :return: Boolean if message was sent successfully. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq msteams.post_card message=\(dqBuild is done\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.munin .sp Run munin plugins/checks from salt and format the output as data. .INDENT 0.0 .TP .B salt.modules.munin.list_plugins() List all the munin plugins .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq munin.list_plugins .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.munin.run(plugins) Run one or more named munin plugins .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq munin.run uptime salt \(aq*\(aq munin.run uptime,cpu,load,memory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.munin.run_all() Run all the munin plugins .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq munin.run_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.mysql .sp Module to provide MySQL compatibility to salt. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 Python module: MySQLdb, mysqlclient, or PyMYSQL .UNINDENT .TP .B configuration In order to connect to MySQL, certain configuration is required in either the relevant minion config (/etc/salt/minion), or pillar. .sp Some sample configs might look like: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mysql.host: \(aqlocalhost\(aq mysql.port: 3306 mysql.user: \(aqroot\(aq mysql.pass: \(aq\(aq mysql.db: \(aqmysql\(aq mysql.unix_socket: \(aq/tmp/mysql.sock\(aq mysql.charset: \(aqutf8\(aq .ft P .fi .UNINDENT .UNINDENT .sp You can also use a defaults file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mysql.default_file: \(aq/etc/mysql/debian.cnf\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Changed in version 2014.1.0: \(aqcharset\(aq connection argument added. This is a MySQL charset, not a python one. .sp Changed in version 0.16.2: Connection arguments from the minion config file can be overridden on the CLI by using the arguments defined \fI\%here\fP\&. Additionally, it is now possible to setup a user with no password. .INDENT 0.0 .TP .B salt.modules.mysql.alter_db(name, character_set=None, collate=None, **connection_args) Modify database using \fBALTER DATABASE %(dbname)s CHARACTER SET %(charset)s COLLATE %(collation)s;\fP query. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.alter_db testdb charset=\(aqlatin1\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_check(name, table=None, **connection_args) Repairs the full database or just a given table .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.db_check dbname salt \(aq*\(aq mysql.db_check dbname dbtable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_create(name, character_set=None, collate=None, **connection_args) Adds a databases to the MySQL server. .INDENT 7.0 .TP .B name The name of the database to manage .TP .B character_set The character set, if left empty the MySQL default will be used .TP .B collate The collation, if left empty the MySQL default will be used .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.db_create \(aqdbname\(aq salt \(aq*\(aq mysql.db_create \(aqdbname\(aq \(aqutf8\(aq \(aqutf8_general_ci\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_exists(name, **connection_args) Checks if a database exists on the MySQL server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.db_exists \(aqdbname\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_get(name, **connection_args) Return a list of databases of a MySQL server using the output from the \fBSELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME=\(aqdbname\(aq;\fP query. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.db_get test .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_list(**connection_args) Return a list of databases of a MySQL server using the output from the \fBSHOW DATABASES\fP query. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.db_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_optimize(name, table=None, **connection_args) Optimizes the full database or just a given table .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.db_optimize dbname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_remove(name, **connection_args) Removes a databases from the MySQL server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.db_remove \(aqdbname\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_repair(name, table=None, **connection_args) Repairs the full database or just a given table .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.db_repair dbname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_tables(name, **connection_args) Shows the tables in the given MySQL database (if exists) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.db_tables \(aqdatabase\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.file_query(database, file_name, **connection_args) Run an arbitrary SQL query from the specified file and return the the number of affected rows. .sp New in version 2017.7.0. .sp database .INDENT 7.0 .INDENT 3.5 database to run script inside .UNINDENT .UNINDENT .sp file_name .INDENT 7.0 .INDENT 3.5 File name of the script. This can be on the minion, or a file that is reachable by the fileserver .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.file_query mydb file_name=/tmp/sqlfile.sql salt \(aq*\(aq mysql.file_query mydb file_name=salt://sqlfile.sql .ft P .fi .UNINDENT .UNINDENT .sp Return data: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqquery time\(aq: {\(aqhuman\(aq: \(aq39.0ms\(aq, \(aqraw\(aq: \(aq0.03899\(aq}, \(aqrows affected\(aq: 1L} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.free_slave(**connection_args) Frees a slave from its master. This is a WIP, do not use. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.free_slave .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.get_master_status(**connection_args) Retrieves the master status from the minion. .sp Returns: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqhost.domain.com\(aq: {\(aqBinlog_Do_DB\(aq: \(aq\(aq, \(aqBinlog_Ignore_DB\(aq: \(aq\(aq, \(aqFile\(aq: \(aqmysql\-bin.000021\(aq, \(aqPosition\(aq: 107}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.get_master_status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.get_slave_status(**connection_args) Retrieves the slave status from the minion. .sp Returns: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqhost.domain.com\(aq: {\(aqConnect_Retry\(aq: 60, \(aqExec_Master_Log_Pos\(aq: 107, \(aqLast_Errno\(aq: 0, \(aqLast_Error\(aq: \(aq\(aq, \(aqLast_IO_Errno\(aq: 0, \(aqLast_IO_Error\(aq: \(aq\(aq, \(aqLast_SQL_Errno\(aq: 0, \(aqLast_SQL_Error\(aq: \(aq\(aq, \(aqMaster_Host\(aq: \(aqcomet.scion\-eng.com\(aq, \(aqMaster_Log_File\(aq: \(aqmysql\-bin.000021\(aq, \(aqMaster_Port\(aq: 3306, \(aqMaster_SSL_Allowed\(aq: \(aqNo\(aq, \(aqMaster_SSL_CA_File\(aq: \(aq\(aq, \(aqMaster_SSL_CA_Path\(aq: \(aq\(aq, \(aqMaster_SSL_Cert\(aq: \(aq\(aq, \(aqMaster_SSL_Cipher\(aq: \(aq\(aq, \(aqMaster_SSL_Key\(aq: \(aq\(aq, \(aqMaster_SSL_Verify_Server_Cert\(aq: \(aqNo\(aq, \(aqMaster_Server_Id\(aq: 1, \(aqMaster_User\(aq: \(aqreplu\(aq, \(aqRead_Master_Log_Pos\(aq: 107, \(aqRelay_Log_File\(aq: \(aqklo\-relay\-bin.000071\(aq, \(aqRelay_Log_Pos\(aq: 253, \(aqRelay_Log_Space\(aq: 553, \(aqRelay_Master_Log_File\(aq: \(aqmysql\-bin.000021\(aq, \(aqReplicate_Do_DB\(aq: \(aq\(aq, \(aqReplicate_Do_Table\(aq: \(aq\(aq, \(aqReplicate_Ignore_DB\(aq: \(aq\(aq, \(aqReplicate_Ignore_Server_Ids\(aq: \(aq\(aq, \(aqReplicate_Ignore_Table\(aq: \(aq\(aq, \(aqReplicate_Wild_Do_Table\(aq: \(aq\(aq, \(aqReplicate_Wild_Ignore_Table\(aq: \(aq\(aq, \(aqSeconds_Behind_Master\(aq: 0, \(aqSkip_Counter\(aq: 0, \(aqSlave_IO_Running\(aq: \(aqYes\(aq, \(aqSlave_IO_State\(aq: \(aqWaiting for master to send event\(aq, \(aqSlave_SQL_Running\(aq: \(aqYes\(aq, \(aqUntil_Condition\(aq: \(aqNone\(aq, \(aqUntil_Log_File\(aq: \(aq\(aq, \(aqUntil_Log_Pos\(aq: 0}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.get_slave_status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.grant_add(grant, database, user, host=\(aqlocalhost\(aq, grant_option=False, escape=True, ssl_option=False, **connection_args) Adds a grant to the MySQL server. .sp For database, make sure you specify database.table or database.* .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.grant_add \(aqSELECT,INSERT,UPDATE,...\(aq \(aqdatabase.*\(aq \(aqfrank\(aq \(aqlocalhost\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.grant_exists(grant, database, user, host=\(aqlocalhost\(aq, grant_option=False, escape=True, **connection_args) Checks to see if a grant exists in the database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.grant_exists \(aqSELECT,INSERT,UPDATE,...\(aq \(aqdatabase.*\(aq \(aqfrank\(aq \(aqlocalhost\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.grant_revoke(grant, database, user, host=\(aqlocalhost\(aq, grant_option=False, escape=True, **connection_args) Removes a grant from the MySQL server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.grant_revoke \(aqSELECT,INSERT,UPDATE\(aq \(aqdatabase.*\(aq \(aqfrank\(aq \(aqlocalhost\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.plugin_add(name, soname=None, **connection_args) Add a plugina. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.plugin_add auth_socket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.plugin_remove(name, **connection_args) Remove a plugin. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.plugin_remove auth_socket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.plugin_status(name, **connection_args) Return the status of a plugin. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.plugin_status auth_socket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.plugins_list(**connection_args) Return a list of plugins and their status from the \fBSHOW PLUGINS\fP query. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.plugins_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.processlist(**connection_args) Retrieves the processlist from the MySQL server via \(dqSHOW FULL PROCESSLIST\(dq. .sp Returns: a list of dicts, with each dict representing a process: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqCommand\(aq: \(aqQuery\(aq, \(aqHost\(aq: \(aqlocalhost\(aq, \(aqId\(aq: 39, \(aqInfo\(aq: \(aqSHOW FULL PROCESSLIST\(aq, \(aqRows_examined\(aq: 0, \(aqRows_read\(aq: 1, \(aqRows_sent\(aq: 0, \(aqState\(aq: None, \(aqTime\(aq: 0, \(aqUser\(aq: \(aqroot\(aq, \(aqdb\(aq: \(aqmysql\(aq} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.processlist .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.query(database, query, **connection_args) Run an arbitrary SQL query and return the results or the number of affected rows. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.query mydb \(dqUPDATE mytable set myfield=1 limit 1\(dq .ft P .fi .UNINDENT .UNINDENT .sp Return data: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqquery time\(aq: {\(aqhuman\(aq: \(aq39.0ms\(aq, \(aqraw\(aq: \(aq0.03899\(aq}, \(aqrows affected\(aq: 1L} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.query mydb \(dqSELECT id,name,cash from users limit 3\(dq .ft P .fi .UNINDENT .UNINDENT .sp Return data: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqcolumns\(aq: (\(aqid\(aq, \(aqname\(aq, \(aqcash\(aq), \(aqquery time\(aq: {\(aqhuman\(aq: \(aq1.0ms\(aq, \(aqraw\(aq: \(aq0.001\(aq}, \(aqresults\(aq: ((1L, \(aqUser 1\(aq, Decimal(\(aq110.000000\(aq)), (2L, \(aqUser 2\(aq, Decimal(\(aq215.636756\(aq)), (3L, \(aqUser 3\(aq, Decimal(\(aq0.040000\(aq))), \(aqrows returned\(aq: 3L} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.query mydb \(aqINSERT into users values (null,\(dquser 4\(dq, 5)\(aq .ft P .fi .UNINDENT .UNINDENT .sp Return data: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqquery time\(aq: {\(aqhuman\(aq: \(aq25.6ms\(aq, \(aqraw\(aq: \(aq0.02563\(aq}, \(aqrows affected\(aq: 1L} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.query mydb \(aqDELETE from users where id = 4 limit 1\(aq .ft P .fi .UNINDENT .UNINDENT .sp Return data: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqquery time\(aq: {\(aqhuman\(aq: \(aq39.0ms\(aq, \(aqraw\(aq: \(aq0.03899\(aq}, \(aqrows affected\(aq: 1L} .ft P .fi .UNINDENT .UNINDENT .sp Jinja Example: Run a query on \fBmydb\fP and use row 0, column 0\(aqs data. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {{ salt[\(aqmysql.query\(aq](\(aqmydb\(aq, \(aqSELECT info from mytable limit 1\(aq)[\(aqresults\(aq][0][0] }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.quote_identifier(identifier, for_grants=False) Return an identifier name (column, table, database, etc) escaped for MySQL .sp This means surrounded by \(dq\(ga\(dq character and escaping this character inside. It also means doubling the \(aq%\(aq character for MySQLdb internal usage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBidentifier\fP \-\- the table, column or database identifier .IP \(bu 2 \fBfor_grants\fP \-\- is False by default, when using database names on grant queries you should set it to True to also escape \(dq_\(dq and \(dq%\(dq characters as requested by MySQL. Note that theses characters should only be escaped when requesting grants on the database level (\fImy_%db\fP\&.*) but not for table level grants (\fImy_%db\fP\&.\(gafoo\(ga) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.quote_identifier \(aqfoo\(gabar\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.showglobal(**connection_args) Retrieves the show global variables from the minion. .INDENT 7.0 .TP .B Returns:: show global variables full dict .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.showglobal .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.showvariables(**connection_args) Retrieves the show variables from the minion. .INDENT 7.0 .TP .B Returns:: show variables full dict .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.showvariables .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.slave_lag(**connection_args) Return the number of seconds that a slave SQL server is lagging behind the master, if the host is not a slave it will return \-1. If the server is configured to be a slave for replication but slave IO is not running then \-2 will be returned. If there was an error connecting to the database or checking the slave status, \-3 will be returned. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.slave_lag .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.status(**connection_args) Return the status of a MySQL server using the output from the \fBSHOW STATUS\fP query. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.tokenize_grant(grant) External wrapper function :param grant: :return: dict .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.tokenize_grant \(dqGRANT SELECT, INSERT ON testdb.* TO \(aqtestuser\(aq@\(aqlocalhost\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_chpass(user, host=\(aqlocalhost\(aq, password=None, password_hash=None, allow_passwordless=False, unix_socket=None, password_column=None, **connection_args) Change password for a MySQL user .INDENT 7.0 .TP .B host Host for which this user/password combo applies .TP .B password The password to set for the new user. Will take precedence over the \fBpassword_hash\fP option if both are specified. .TP .B password_hash The password in hashed form. Be sure to quote the password because YAML doesn\(aqt like the \fB*\fP\&. A password hash can be obtained from the mysql command\-line client like so: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mysql> SELECT PASSWORD(\(aqmypass\(aq); +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | PASSWORD(\(aqmypass\(aq) | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4 | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ 1 row in set (0.00 sec) .ft P .fi .UNINDENT .UNINDENT .TP .B allow_passwordless If \fBTrue\fP, then \fBpassword\fP and \fBpassword_hash\fP can be omitted (or set to \fBNone\fP) to permit a passwordless login. .UNINDENT .sp New in version 0.16.2: The \fBallow_passwordless\fP option was added. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.user_chpass frank localhost newpassword salt \(aq*\(aq mysql.user_chpass frank localhost password_hash=\(aqhash\(aq salt \(aq*\(aq mysql.user_chpass frank localhost allow_passwordless=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_create(user, host=\(aqlocalhost\(aq, password=None, password_hash=None, allow_passwordless=False, unix_socket=False, password_column=None, auth_plugin=\(aqmysql_native_password\(aq, **connection_args) Creates a MySQL user .INDENT 7.0 .TP .B host Host for which this user/password combo applies .TP .B password The password to use for the new user. Will take precedence over the \fBpassword_hash\fP option if both are specified. .TP .B password_hash The password in hashed form. Be sure to quote the password because YAML doesn\(aqt like the \fB*\fP\&. A password hash can be obtained from the mysql command\-line client like so: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mysql> SELECT PASSWORD(\(aqmypass\(aq); +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | PASSWORD(\(aqmypass\(aq) | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4 | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ 1 row in set (0.00 sec) .ft P .fi .UNINDENT .UNINDENT .TP .B allow_passwordless If \fBTrue\fP, then \fBpassword\fP and \fBpassword_hash\fP can be omitted (or set to \fBNone\fP) to permit a passwordless login. .TP .B unix_socket If \fBTrue\fP and allow_passwordless is \fBTrue\fP then will be used unix_socket auth plugin. .TP .B password_column The password column to use in the user table. .TP .B auth_plugin The authentication plugin to use, default is to use the mysql_native_password plugin. .UNINDENT .sp New in version 0.16.2: The \fBallow_passwordless\fP option was added. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.user_create \(aqusername\(aq \(aqhostname\(aq \(aqpassword\(aq salt \(aq*\(aq mysql.user_create \(aqusername\(aq \(aqhostname\(aq password_hash=\(aqhash\(aq salt \(aq*\(aq mysql.user_create \(aqusername\(aq \(aqhostname\(aq allow_passwordless=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_exists(user, host=\(aqlocalhost\(aq, password=None, password_hash=None, passwordless=False, unix_socket=False, password_column=None, **connection_args) Checks if a user exists on the MySQL server. A login can be checked to see if passwordless login is permitted by omitting \fBpassword\fP and \fBpassword_hash\fP, and using \fBpasswordless=True\fP\&. .sp New in version 0.16.2: The \fBpasswordless\fP option was added. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.user_exists \(aqusername\(aq \(aqhostname\(aq \(aqpassword\(aq salt \(aq*\(aq mysql.user_exists \(aqusername\(aq \(aqhostname\(aq password_hash=\(aqhash\(aq salt \(aq*\(aq mysql.user_exists \(aqusername\(aq passwordless=True salt \(aq*\(aq mysql.user_exists \(aqusername\(aq password_column=\(aqauthentication_string\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_grants(user, host=\(aqlocalhost\(aq, **connection_args) Shows the grants for the given MySQL user (if it exists) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.user_grants \(aqfrank\(aq \(aqlocalhost\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_info(user, host=\(aqlocalhost\(aq, **connection_args) Get full info on a MySQL user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.user_info root localhost .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_list(**connection_args) Return a list of users on a MySQL server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.user_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_remove(user, host=\(aqlocalhost\(aq, **connection_args) Delete MySQL user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.user_remove frank localhost .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.verify_login(user, password=None, **connection_args) Attempt to login using the provided credentials. If successful, return true. Otherwise, return False. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.verify_login root password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.version(**connection_args) Return the version of a MySQL server using the output from the \fBSELECT VERSION()\fP query. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mysql.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nacl .sp This module helps include encrypted passwords in pillars, grains and salt state files. .INDENT 0.0 .TP .B depends PyNaCl, \fI\%https://github.com/pyca/pynacl\fP .UNINDENT .sp This is often useful if you wish to store your pillars in source control or share your pillar data with others that you trust. I don\(aqt advise making your pillars public regardless if they are encrypted or not. .sp When generating keys and encrypting passwords use \-\-local when using salt\-call for extra security. Also consider using just the salt runner nacl when encrypting pillar passwords. .INDENT 0.0 .TP .B configuration The following configuration defaults can be define (pillar or config files) Avoid storing private keys in pillars! Ensure master does not have \fIpillar_opts=True\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # cat /etc/salt/master.d/nacl.conf nacl.config: # NOTE: \(gakey\(ga and \(gakey_file\(ga have been renamed to \(gask\(ga, \(gask_file\(ga # also \(gabox_type\(ga default changed from secretbox to sealedbox. box_type: sealedbox (default) sk_file: /etc/salt/pki/master/nacl (default) pk_file: /etc/salt/pki/master/nacl.pub (default) sk: None pk: None .ft P .fi .UNINDENT .UNINDENT .sp Usage can override the config defaults: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call nacl.enc sk_file=/etc/salt/pki/master/nacl pk_file=/etc/salt/pki/master/nacl.pub .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp The nacl lib uses 32byte keys, these keys are base64 encoded to make your life more simple. To generate your \fIsk_file\fP and \fIpk_file\fP use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local nacl.keygen sk_file=/etc/salt/pki/master/nacl # or if you want to work without files. salt\-call \-\-local nacl.keygen local: \-\-\-\-\-\-\-\-\-\- pk: /kfGX7PbWeu099702PBbKWLpG/9p06IQRswkdWHCDk0= sk: SVWut5SqNpuPeNzb1b9y6b2eXg2PLIog43GBzp48Sow= .ft P .fi .UNINDENT .UNINDENT .sp Now with your keypair, you can encrypt data: .sp You have two option, \fIsealedbox\fP or \fIsecretbox\fP\&. .sp SecretBox is data encrypted using private key \fIpk\fP\&. Sealedbox is encrypted using public key \fIpk\fP\&. .sp Recommend using Sealedbox because the one way encryption permits developers to encrypt data for source control but not decrypt. Sealedbox only has one key that is for both encryption and decryption. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local nacl.enc asecretpass pk=/kfGX7PbWeu099702PBbKWLpG/9p06IQRswkdWHCDk0= tqXzeIJnTAM9Xf0mdLcpEdklMbfBGPj2oTKmlgrm3S1DTVVHNnh9h8mU1GKllGq/+cYsk6m5WhGdk58= .ft P .fi .UNINDENT .UNINDENT .sp To decrypt the data: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local nacl.dec data=\(aqtqXzeIJnTAM9Xf0mdLcpEdklMbfBGPj2oTKmlgrm3S1DTVVHNnh9h8mU1GKllGq/+cYsk6m5WhGdk58=\(aq sk=\(aqSVWut5SqNpuPeNzb1b9y6b2eXg2PLIog43GBzp48Sow=\(aq .ft P .fi .UNINDENT .UNINDENT .sp When the keys are defined in the master config you can use them from the nacl runner without extra parameters: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # cat /etc/salt/master.d/nacl.conf nacl.config: sk_file: /etc/salt/pki/master/nacl pk: \(aqcTIqXwnUiD1ulg4kXsbeCE7/NoeKEzd4nLeYcCFpd9k=\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.enc \(aqasecretpass\(aq salt\-run nacl.dec data=\(aqtqXzeIJnTAM9Xf0mdLcpEdklMbfBGPj2oTKmlgrm3S1DTVVHNnh9h8mU1GKllGq/+cYsk6m5WhGdk58=\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # a salt developers minion could have pillar data that includes a nacl public key nacl.config: pk: \(aq/kfGX7PbWeu099702PBbKWLpG/9p06IQRswkdWHCDk0=\(aq .ft P .fi .UNINDENT .UNINDENT .sp The developer can then use a less\-secure system to encrypt data. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local nacl.enc apassword .ft P .fi .UNINDENT .UNINDENT .sp Pillar files can include protected data that the salt master decrypts: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillarexample: user: root password1: {{salt.nacl.dec(\(aqDRB7Q6/X5gGSRCTpZyxS6hlbWj0llUA+uaVyvou3vJ4=\(aq)|json}} cert_key: {{salt.nacl.dec_file(\(aq/srv/salt/certs/example.com/key.nacl\(aq)|json}} cert_key2: {{salt.nacl.dec_file(\(aqsalt:///certs/example.com/key.nacl\(aq)|json}} .ft P .fi .UNINDENT .UNINDENT .sp Larger files like certificates can be encrypted with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call nacl.enc_file /tmp/cert.crt out=/tmp/cert.nacl # or more advanced cert=$(cat /tmp/cert.crt) salt\-call \-\-out=newline_values_only nacl.enc_pub data=\(dq$cert\(dq > /tmp/cert.nacl .ft P .fi .UNINDENT .UNINDENT .sp In pillars rended with jinja be sure to include \fI|json\fP so line breaks are encoded: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cert: \(dq{{salt.nacl.dec(\(aqS2uogToXkgENz9...085KYt\(aq)|json}}\(dq .ft P .fi .UNINDENT .UNINDENT .sp In states rendered with jinja it is also good pratice to include \fI|json\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{sls}} private key: file.managed: \- name: /etc/ssl/private/cert.key \- mode: 700 \- contents: \(dq{{pillar[\(aqpillarexample\(aq][\(aqcert_key\(aq]|json}}\(dq .ft P .fi .UNINDENT .UNINDENT .sp Optional small program to encrypt data without needing salt modules. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!/bin/python3 import sys, base64, nacl.public pk = base64.b64decode(\(aqYOURPUBKEY\(aq) b = nacl.public.SealedBox(pk) data = sys.stdin.buffer.read() print(base64.b64encode(b.encrypt(data)).decode()) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C echo \(aqapassword\(aq | nacl_enc.py .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nacl.dec(data, **kwargs) Alias to \fI{box_type}_decrypt\fP .sp box_type: secretbox, sealedbox(default) .UNINDENT .INDENT 0.0 .TP .B salt.modules.nacl.dec_file(name, out=None, **kwargs) This is a helper function to decrypt a file and return its contents. .sp You can provide an optional output file using \fIout\fP .sp \fIname\fP can be a local file or when not using \fIsalt\-run\fP can be a url like \fIsalt://\fP, \fIhttps://\fP etc. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.dec_file name=/tmp/id_rsa.nacl salt\-call nacl.dec_file name=salt://crt/mycert.nacl out=/tmp/id_rsa salt\-run nacl.dec_file name=/tmp/id_rsa.nacl box_type=secretbox sk_file=/etc/salt/pki/master/nacl.pub .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nacl.enc(data, **kwargs) Alias to \fI{box_type}_encrypt\fP .sp box_type: secretbox, sealedbox(default) .UNINDENT .INDENT 0.0 .TP .B salt.modules.nacl.enc_file(name, out=None, **kwargs) This is a helper function to encrypt a file and return its contents. .sp You can provide an optional output file using \fIout\fP .sp \fIname\fP can be a local file or when not using \fIsalt\-run\fP can be a url like \fIsalt://\fP, \fIhttps://\fP etc. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.enc_file name=/tmp/id_rsa salt\-call nacl.enc_file name=salt://crt/mycert out=/tmp/cert salt\-run nacl.enc_file name=/tmp/id_rsa box_type=secretbox sk_file=/etc/salt/pki/master/nacl.pub .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nacl.keygen(sk_file=None, pk_file=None, **kwargs) Use PyNaCl to generate a keypair. .sp If no \fIsk_file\fP is defined return a keypair. .sp If only the \fIsk_file\fP is defined \fIpk_file\fP will use the same name with a postfix \fI\&.pub\fP\&. .sp When the \fIsk_file\fP is already existing, but \fIpk_file\fP is not. The \fIpk_file\fP will be generated using the \fIsk_file\fP\&. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call nacl.keygen salt\-call nacl.keygen sk_file=/etc/salt/pki/master/nacl salt\-call nacl.keygen sk_file=/etc/salt/pki/master/nacl pk_file=/etc/salt/pki/master/nacl.pub salt\-call \-\-local nacl.keygen .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nacl.sealedbox_decrypt(data, **kwargs) Decrypt data using a secret key that was encrypted using a public key with \fInacl.sealedbox_encrypt\fP\&. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call nacl.sealedbox_decrypt pEXHQM6cuaF7A= salt\-call \-\-local nacl.sealedbox_decrypt data=\(aqpEXHQM6cuaF7A=\(aq sk_file=/etc/salt/pki/master/nacl salt\-call \-\-local nacl.sealedbox_decrypt data=\(aqpEXHQM6cuaF7A=\(aq sk=\(aqYmFkcGFzcwo=\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nacl.sealedbox_encrypt(data, **kwargs) Encrypt data using a public key generated from \fInacl.keygen\fP\&. The encryptd data can be decrypted using \fInacl.sealedbox_decrypt\fP only with the secret key. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.sealedbox_encrypt datatoenc salt\-call \-\-local nacl.sealedbox_encrypt datatoenc pk_file=/etc/salt/pki/master/nacl.pub salt\-call \-\-local nacl.sealedbox_encrypt datatoenc pk=\(aqvrwQF7cNiNAVQVAiS3bvcbJUnF0cN6fU9YTZD9mBfzQ=\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nacl.secretbox_decrypt(data, **kwargs) Decrypt data that was encrypted using \fInacl.secretbox_encrypt\fP using the secret key that was generated from \fInacl.keygen\fP\&. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call nacl.secretbox_decrypt pEXHQM6cuaF7A= salt\-call \-\-local nacl.secretbox_decrypt data=\(aqpEXHQM6cuaF7A=\(aq sk_file=/etc/salt/pki/master/nacl salt\-call \-\-local nacl.secretbox_decrypt data=\(aqpEXHQM6cuaF7A=\(aq sk=\(aqYmFkcGFzcwo=\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nacl.secretbox_encrypt(data, **kwargs) Encrypt data using a secret key generated from \fInacl.keygen\fP\&. The same secret key can be used to decrypt the data using \fInacl.secretbox_decrypt\fP\&. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.secretbox_encrypt datatoenc salt\-call \-\-local nacl.secretbox_encrypt datatoenc sk_file=/etc/salt/pki/master/nacl salt\-call \-\-local nacl.secretbox_encrypt datatoenc sk=\(aqYmFkcGFzcwo=\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nagios .sp Run nagios plugins/checks from salt and get the return as data. .INDENT 0.0 .TP .B salt.modules.nagios.list_plugins() List all the nagios plugins .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nagios.list_plugins .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nagios.retcode(plugin, args=\(aq\(aq, key_name=None) Run one nagios plugin and return retcode of the execution .UNINDENT .INDENT 0.0 .TP .B salt.modules.nagios.retcode_pillar(pillar_name) Run one or more nagios plugins from pillar data and get the result of cmd.retcode The pillar have to be in this format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \-\-\-\-\-\- webserver: Ping_google: \- check_icmp: 8.8.8.8 \- check_icmp: google.com Load: \- check_load: \-w 0.8 \-c 1 APT: \- check_apt \-\-\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .sp webserver is the role to check, the next keys are the group and the items the check with the arguments if needed .sp You must to group different checks(one o more) and always it will return the highest value of all the checks .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nagios.retcode webserver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nagios.run(plugin, args=\(aq\(aq) Run nagios plugin and return all the data execution with cmd.run .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nagios.run check_apt salt \(aq*\(aq nagios.run check_icmp \(aq8.8.8.8\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nagios.run_all(plugin, args=\(aq\(aq) Run nagios plugin and return all the data execution with cmd.run_all .UNINDENT .INDENT 0.0 .TP .B salt.modules.nagios.run_all_pillar(pillar_name) Run one or more nagios plugins from pillar data and get the result of cmd.run_all The pillar have to be in this format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \-\-\-\-\-\- webserver: Ping_google: \- check_icmp: 8.8.8.8 \- check_icmp: google.com Load: \- check_load: \-w 0.8 \-c 1 APT: \- check_apt \-\-\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .sp webserver is the role to check, the next keys are the group and the items the check with the arguments if needed .sp You have to group different checks in a group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nagios.run webserver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nagios.run_pillar(pillar_name) Run one or more nagios plugins from pillar data and get the result of cmd.run The pillar have to be in this format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \-\-\-\-\-\- webserver: Ping_google: \- check_icmp: 8.8.8.8 \- check_icmp: google.com Load: \- check_load: \-w 0.8 \-c 1 APT: \- check_apt \-\-\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .sp webserver is the role to check, the next keys are the group and the items the check with the arguments if needed .sp You have to group different checks in a group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nagios.run webserver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nagios_rpc .sp Check Host & Service status from Nagios via JSON RPC. .sp New in version 2015.8.0. .INDENT 0.0 .TP .B salt.modules.nagios_rpc.host_status(hostname=None, **kwargs) Check status of a particular host By default statuses are returned in a numeric format. .sp Parameters: .INDENT 7.0 .TP .B hostname The hostname to check the status of the service in Nagios. .TP .B numeric Turn to false in order to return status in text format (\(aqOK\(aq instead of 0, \(aqWarning\(aq instead of 1 etc) .UNINDENT .INDENT 7.0 .TP .B Returns status: \(aqOK\(aq, \(aqWarning\(aq, \(aqCritical\(aq or \(aqUnknown\(aq .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nagios_rpc.host_status hostname=webserver.domain.com salt \(aq*\(aq nagios_rpc.host_status hostname=webserver.domain.com numeric=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nagios_rpc.service_status(hostname=None, service=None, **kwargs) Check status of a particular service on a host on it in Nagios. By default statuses are returned in a numeric format. .sp Parameters: .INDENT 7.0 .TP .B hostname The hostname to check the status of the service in Nagios. .TP .B service The service to check the status of in Nagios. .TP .B numeric Turn to false in order to return status in text format (\(aqOK\(aq instead of 0, \(aqWarning\(aq instead of 1 etc) .UNINDENT .INDENT 7.0 .TP .B Returns status: \(aqOK\(aq, \(aqWarning\(aq, \(aqCritical\(aq or \(aqUnknown\(aq .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nagios_rpc.service_status hostname=webserver.domain.com service=\(aqHTTP\(aq salt \(aq*\(aq nagios_rpc.service_status hostname=webserver.domain.com service=\(aqHTTP\(aq numeric=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.namecheap_domains .sp Namecheap Domain Management .sp New in version 2017.7.0. .SS Prerequisites .sp This module uses the \fBrequests\fP Python module to communicate to the namecheap API. .SS Configuration .sp The Namecheap username, API key and URL should be set in the minion configuration file, or in the Pillar data. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C namecheap.name: companyname namecheap.key: a1b2c3d4e5f67a8b9c0d1e2f3 namecheap.client_ip: 162.155.30.172 #Real url namecheap.url: https://api.namecheap.com/xml.response #Sandbox url #namecheap.url: https://api.sandbox.namecheap.xml.response .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains.check(*domains_to_check) Checks the availability of domains .INDENT 7.0 .TP .B domains_to_check array of strings List of domains to check .UNINDENT .sp Returns a dictionary mapping the each domain name to a boolean denoting whether or not it is available. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_domains.check domain\-to\-check .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains.create(domain_name, years, **kwargs) Try to register the specified domain name .INDENT 7.0 .TP .B domain_name The domain name to be registered .TP .B years Number of years to register .UNINDENT .sp Returns the following information: .INDENT 7.0 .IP \(bu 2 Whether or not the domain was renewed successfully .IP \(bu 2 Whether or not WhoisGuard is enabled .IP \(bu 2 Whether or not registration is instant .IP \(bu 2 The amount charged for registration .IP \(bu 2 The domain ID .IP \(bu 2 The order ID .IP \(bu 2 The transaction ID .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_domains.create my\-domain\-name 2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains.get_info(domain_name) Returns information about the requested domain .sp returns a dictionary of information about the domain_name .INDENT 7.0 .TP .B domain_name string Domain name to get information about .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_domains.get_info my\-domain\-name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains.get_list(list_type=None, search_term=None, page=None, page_size=None, sort_by=None) Returns a list of domains for the particular user as a list of objects offset by \fBpage\fP length of \fBpage_size\fP .INDENT 7.0 .TP .B list_type ALL One of \fBALL\fP, \fBEXPIRING\fP, \fBEXPIRED\fP .TP .B search_term Keyword to look for on the domain list .TP .B page 1 Number of result page to return .TP .B page_size 20 Number of domains to be listed per page (minimum: \fB10\fP, maximum: \fB100\fP) .TP .B sort_by One of \fBNAME\fP, \fBNAME_DESC\fP, \fBEXPIREDATE\fP, \fBEXPIREDATE_DESC\fP, \fBCREATEDATE\fP, or \fBCREATEDATE_DESC\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_domains.get_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains.get_tld_list() Returns a list of TLDs as objects .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_domains.get_tld_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains.reactivate(domain_name) Try to reactivate the expired domain name .sp Returns the following information: .INDENT 7.0 .IP \(bu 2 Whether or not the domain was reactivated successfully .IP \(bu 2 The amount charged for reactivation .IP \(bu 2 The order ID .IP \(bu 2 The transaction ID .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_domains.reactivate my\-domain\-name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains.renew(domain_name, years, promotion_code=None) Try to renew the specified expiring domain name for a specified number of years .INDENT 7.0 .TP .B domain_name The domain name to be renewed .TP .B years Number of years to renew .UNINDENT .sp Returns the following information: .INDENT 7.0 .IP \(bu 2 Whether or not the domain was renewed successfully .IP \(bu 2 The domain ID .IP \(bu 2 The order ID .IP \(bu 2 The transaction ID .IP \(bu 2 The amount charged for renewal .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_domains.renew my\-domain\-name 5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.namecheap_domains_dns .sp Namecheap DNS Management .sp New in version 2017.7.0. .SS Prerequisites .sp This module uses the \fBrequests\fP Python module to communicate to the namecheap API. .SS Configuration .sp The Namecheap username, API key and URL should be set in the minion configuration file, or in the Pillar data. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C namecheap.name: companyname namecheap.key: a1b2c3d4e5f67a8b9c0d1e2f3 namecheap.client_ip: 162.155.30.172 #Real url namecheap.url: https://api.namecheap.com/xml.response #Sandbox url #namecheap.url: https://api.sandbox.namecheap.xml.response .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains_dns.get_hosts(sld, tld) Retrieves DNS host record settings for the requested domain. .sp returns a dictionary of information about the requested domain .INDENT 7.0 .TP .B sld SLD of the domain name .TP .B tld TLD of the domain name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_domains_dns.get_hosts sld tld .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains_dns.get_list(sld, tld) Gets a list of DNS servers associated with the requested domain. .sp returns a dictionary of information about requested domain .INDENT 7.0 .TP .B sld SLD of the domain name .TP .B tld TLD of the domain name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_domains_dns.get_list sld tld .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains_dns.set_custom(sld, tld, nameservers) Sets domain to use custom DNS servers. .sp returns True if the custom nameservers were set successfully .INDENT 7.0 .TP .B sld SLD of the domain name .TP .B tld TLD of the domain name .TP .B nameservers array of strings List of nameservers to be associated with this domain .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_domains_dns.set_custom sld tld nameserver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains_dns.set_default(sld, tld) Sets domain to use namecheap default DNS servers. Required for free services like Host record management, URL forwarding, email forwarding, dynamic DNS and other value added services. .INDENT 7.0 .TP .B sld SLD of the domain name .TP .B tld TLD of the domain name .UNINDENT .sp Returns \fBTrue\fP if the domain was successfully pointed at the default DNS servers. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_domains_dns.set_default sld tld .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains_dns.set_hosts(sld, tld, hosts) Sets DNS host records settings for the requested domain. .sp returns True if the host records were set successfully .INDENT 7.0 .TP .B sld SLD of the domain name .TP .B tld TLD of the domain name .TP .B hosts Must be passed as a list of Python dictionaries, with each dictionary containing the following keys: .INDENT 7.0 .IP \(bu 2 \fBhostname\fP .IP \(bu 2 \fBrecordtype\fP \- One of \fBA\fP, \fBAAAA\fP, \fBCNAME\fP, \fBMX\fP, \fBMXE\fP, \fBTXT\fP, \fBURL\fP, \fBURL301\fP, or \fBFRAME\fP .IP \(bu 2 \fBaddress\fP \- URL or IP address .IP \(bu 2 \fBttl\fP \- An integer between 60 and 60000 (default: \fB1800\fP) .UNINDENT .sp Additionally, the \fBmxpref\fP key can be present, but must be accompanied by an \fBemailtype\fP key. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_domains_dns.set_hosts sld tld hosts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.namecheap_domains_ns .sp Namecheap Nameserver Management .sp New in version 2017.7.0. .SS Prerequisites .sp This module uses the \fBrequests\fP Python module to communicate to the namecheap API. .SS Configuration .sp The Namecheap username, API key and URL should be set in the minion configuration file, or in the Pillar data. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C namecheap.name: companyname namecheap.key: a1b2c3d4e5f67a8b9c0d1e2f3 namecheap.client_ip: 162.155.30.172 #Real url namecheap.url: https://api.namecheap.com/xml.response #Sandbox url #namecheap.url: https://api.sandbox.namecheap.xml.response .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains_ns.create(sld, tld, nameserver, ip) Creates a new nameserver. Returns \fBTrue\fP if the nameserver was created successfully. .INDENT 7.0 .TP .B sld SLD of the domain name .TP .B tld TLD of the domain name .TP .B nameserver Nameserver to create .TP .B ip Nameserver IP address .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq namecheap_domains_ns.create sld tld nameserver ip .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains_ns.delete(sld, tld, nameserver) Deletes a nameserver. Returns \fBTrue\fP if the nameserver was deleted successfully .INDENT 7.0 .TP .B sld SLD of the domain name .TP .B tld TLD of the domain name .TP .B nameserver Nameserver to delete .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq namecheap_domains_ns.delete sld tld nameserver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains_ns.get_info(sld, tld, nameserver) Retrieves information about a registered nameserver. Returns the following information: .INDENT 7.0 .IP \(bu 2 IP Address set for the nameserver .IP \(bu 2 Domain name which was queried .IP \(bu 2 A list of nameservers and their statuses .UNINDENT .INDENT 7.0 .TP .B sld SLD of the domain name .TP .B tld TLD of the domain name .TP .B nameserver Nameserver to retrieve .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq namecheap_domains_ns.get_info sld tld nameserver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_domains_ns.update(sld, tld, nameserver, old_ip, new_ip) Deletes a nameserver. Returns \fBTrue\fP if the nameserver was updated successfully. .INDENT 7.0 .TP .B sld SLD of the domain name .TP .B tld TLD of the domain name .TP .B nameserver Nameserver to create .TP .B old_ip Current ip address .TP .B new_ip New ip address .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq namecheap_domains_ns.update sld tld nameserver old_ip new_ip .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.namecheap_ssl .sp Namecheap SSL Certificate Management .sp New in version 2017.7.0. .SS Prerequisites .sp This module uses the \fBrequests\fP Python module to communicate to the namecheap API. .SS Configuration .sp The Namecheap username, API key and URL should be set in the minion configuration file, or in the Pillar data. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C namecheap.name: companyname namecheap.key: a1b2c3d4e5f67a8b9c0d1e2f3 namecheap.client_ip: 162.155.30.172 #Real url namecheap.url: https://api.namecheap.com/xml.response #Sandbox url #namecheap.url: https://api.sandbox.namecheap.xml.response .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_ssl.activate(csr_file, certificate_id, web_server_type, approver_email=None, http_dc_validation=False, **kwargs) Activates a newly\-purchased SSL certificate. Returns a dictionary of result values. .INDENT 7.0 .TP .B csr_file Path to Certificate Signing Request file .TP .B certificate_id Unique ID of the SSL certificate you wish to activate .TP .B web_server_type The type of certificate format to return. Possible values include: .INDENT 7.0 .IP \(bu 2 apache2 .IP \(bu 2 apacheapachessl .IP \(bu 2 apacheopenssl .IP \(bu 2 apacheraven .IP \(bu 2 apachessl .IP \(bu 2 apachessleay .IP \(bu 2 c2net .IP \(bu 2 cobaltseries .IP \(bu 2 cpanel .IP \(bu 2 domino .IP \(bu 2 dominogo4625 .IP \(bu 2 dominogo4626 .IP \(bu 2 ensim .IP \(bu 2 hsphere .IP \(bu 2 ibmhttp .IP \(bu 2 iis .IP \(bu 2 iis4 .IP \(bu 2 iis5 .IP \(bu 2 iplanet .IP \(bu 2 ipswitch .IP \(bu 2 netscape .IP \(bu 2 other .IP \(bu 2 plesk .IP \(bu 2 tomcat .IP \(bu 2 weblogic .IP \(bu 2 website .IP \(bu 2 webstar .IP \(bu 2 zeusv3 .UNINDENT .TP .B approver_email The email ID which is on the approver email list. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBhttp_dc_validation\fP must be set to \fBFalse\fP if this option is used. .UNINDENT .UNINDENT .TP .B http_dc_validation False Whether or not to activate using HTTP\-based validation. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For other parameters which may be required, see \fI\%here\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_ssl.activate my\-csr\-file my\-cert\-id apachessl .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_ssl.create(years, certificate_type, promotion_code=None, sans_to_add=None) Creates a new SSL certificate. Returns the following information: .INDENT 7.0 .IP \(bu 2 Whether or not the SSL order was successful .IP \(bu 2 The certificate ID .IP \(bu 2 The order ID .IP \(bu 2 The transaction ID .IP \(bu 2 The amount charged for the order .IP \(bu 2 The date on which the certificate was created .IP \(bu 2 The date on which the certificate will expire .IP \(bu 2 The type of SSL certificate .IP \(bu 2 The number of years for which the certificate was purchased .IP \(bu 2 The current status of the SSL certificate .UNINDENT .INDENT 7.0 .TP .B years 1 Number of years to register .TP .B certificate_type Type of SSL Certificate. Possible values include: .INDENT 7.0 .IP \(bu 2 EV Multi Domain SSL .IP \(bu 2 EV SSL .IP \(bu 2 EV SSL SGC .IP \(bu 2 EssentialSSL .IP \(bu 2 EssentialSSL Wildcard .IP \(bu 2 InstantSSL .IP \(bu 2 InstantSSL Pro .IP \(bu 2 Multi Domain SSL .IP \(bu 2 PositiveSSL .IP \(bu 2 PositiveSSL Multi Domain .IP \(bu 2 PositiveSSL Wildcard .IP \(bu 2 PremiumSSL .IP \(bu 2 PremiumSSL Wildcard .IP \(bu 2 QuickSSL Premium .IP \(bu 2 RapidSSL .IP \(bu 2 RapidSSL Wildcard .IP \(bu 2 SGC Supercert .IP \(bu 2 SSL Web Server .IP \(bu 2 SSL Webserver EV .IP \(bu 2 SSL123 .IP \(bu 2 Secure Site .IP \(bu 2 Secure Site Pro .IP \(bu 2 Secure Site Pro with EV .IP \(bu 2 Secure Site with EV .IP \(bu 2 True BusinessID .IP \(bu 2 True BusinessID Multi Domain .IP \(bu 2 True BusinessID Wildcard .IP \(bu 2 True BusinessID with EV .IP \(bu 2 True BusinessID with EV Multi Domain .IP \(bu 2 Unified Communications .UNINDENT .TP .B promotional_code An optional promo code to use when creating the certificate .TP .B sans_to_add 0 This parameter defines the number of add\-on domains to be purchased in addition to the default number of domains included with a multi\-domain certificate. Each certificate that supports SANs has the default number of domains included. You may check the default number of domains included and the maximum number of domains that can be added to it in the table below. .UNINDENT .TS center; |l|l|l|l|l|. _ T{ Provider T} T{ Product name T} T{ Default number of domains (domain from CSR is counted here) T} T{ Maximum number of total domains T} T{ Maximum number of domains that can be passed in sans_to_add parameter T} _ T{ Comodo T} T{ PositiveSSL Multi\-Domain T} T{ 3 T} T{ 100 T} T{ 97 T} _ T{ Comodo T} T{ Multi\-Domain SSL T} T{ 3 T} T{ 100 T} T{ 97 T} _ T{ Comodo T} T{ EV Multi\- Domain SSL T} T{ 3 T} T{ 100 T} T{ 97 T} _ T{ Comodo T} T{ Unified Communications T} T{ 3 T} T{ 100 T} T{ 97 T} _ T{ GeoTrust T} T{ QuickSSL Premium T} T{ 1 T} T{ 1 domain + 4 subdomains T} T{ The only supported value is 4 T} _ T{ GeoTrust T} T{ True BusinessID with EV Multi\-Domain T} T{ 5 T} T{ 25 T} T{ 20 T} _ T{ GeoTrust T} T{ True Business ID Multi\- Domain T} T{ 5 T} T{ 25 T} T{ 20 T} _ T{ Thawte T} T{ SSL Web Server T} T{ 1 T} T{ 25 T} T{ 24 T} _ T{ Thawte T} T{ SSL Web Server with EV T} T{ 1 T} T{ 25 T} T{ 24 T} _ T{ Thawte T} T{ SGC Supercerts T} T{ 1 T} T{ 25 T} T{ 24 T} _ T{ Symantec T} T{ Secure Site Pro with EV T} T{ 1 T} T{ 25 T} T{ 24 T} _ T{ Symantec T} T{ Secure Site with EV T} T{ 1 T} T{ 25 T} T{ 24 T} _ T{ Symantec T} T{ Secure Site T} T{ 1 T} T{ 25 T} T{ 24 T} _ T{ Symantec T} T{ Secure Site Pro T} T{ 1 T} T{ 25 T} T{ 24 T} _ .TE .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_ssl.create 2 RapidSSL .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_ssl.get_info(certificate_id, returncertificate=False, returntype=None) Retrieves information about the requested SSL certificate. Returns a dictionary of information about the SSL certificate with two keys: .INDENT 7.0 .IP \(bu 2 \fBssl\fP \- Contains the metadata information .IP \(bu 2 \fBcertificate\fP \- Contains the details for the certificate such as the CSR, Approver, and certificate data .UNINDENT .INDENT 7.0 .TP .B certificate_id Unique ID of the SSL certificate .TP .B returncertificate False Set to \fBTrue\fP to ask for the certificate in response .TP .B returntype Optional type for the returned certificate. Can be either \(dqIndividual\(dq (for X.509 format) or \(dqPKCS7\(dq .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Required if \fBreturncertificate\fP is \fBTrue\fP .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_ssl.get_info my\-cert\-id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_ssl.get_list(**kwargs) Returns a list of SSL certificates for a particular user .INDENT 7.0 .TP .B ListType All Possible values: .INDENT 7.0 .IP \(bu 2 All .IP \(bu 2 Processing .IP \(bu 2 EmailSent .IP \(bu 2 TechnicalProblem .IP \(bu 2 InProgress .IP \(bu 2 Completed .IP \(bu 2 Deactivated .IP \(bu 2 Active .IP \(bu 2 Cancelled .IP \(bu 2 NewPurchase .IP \(bu 2 NewRenewal .UNINDENT .INDENT 7.0 .TP .B SearchTerm Keyword to look for on the SSL list .TP .B Page 1 Page number to return .TP .B PageSize 20 Total number of SSL certificates to display per page (minimum: \fB10\fP, maximum: \fB100\fP) .TP .B SoryBy One of \fBPURCHASEDATE\fP, \fBPURCHASEDATE_DESC\fP, \fBSSLTYPE\fP, \fBSSLTYPE_DESC\fP, \fBEXPIREDATETIME\fP, \fBEXPIREDATETIME_DESC\fP, \fBHost_Name\fP, or \fBHost_Name_DESC\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_ssl.get_list Processing .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_ssl.parse_csr(csr_file, certificate_type, http_dc_validation=False) Parses the CSR. Returns a dictionary of result values. .INDENT 7.0 .TP .B csr_file Path to Certificate Signing Request file .TP .B certificate_type Type of SSL Certificate. Possible values include: .INDENT 7.0 .IP \(bu 2 EV Multi Domain SSL .IP \(bu 2 EV SSL .IP \(bu 2 EV SSL SGC .IP \(bu 2 EssentialSSL .IP \(bu 2 EssentialSSL Wildcard .IP \(bu 2 InstantSSL .IP \(bu 2 InstantSSL Pro .IP \(bu 2 Multi Domain SSL .IP \(bu 2 PositiveSSL .IP \(bu 2 PositiveSSL Multi Domain .IP \(bu 2 PositiveSSL Wildcard .IP \(bu 2 PremiumSSL .IP \(bu 2 PremiumSSL Wildcard .IP \(bu 2 QuickSSL Premium .IP \(bu 2 RapidSSL .IP \(bu 2 RapidSSL Wildcard .IP \(bu 2 SGC Supercert .IP \(bu 2 SSL Web Server .IP \(bu 2 SSL Webserver EV .IP \(bu 2 SSL123 .IP \(bu 2 Secure Site .IP \(bu 2 Secure Site Pro .IP \(bu 2 Secure Site Pro with EV .IP \(bu 2 Secure Site with EV .IP \(bu 2 True BusinessID .IP \(bu 2 True BusinessID Multi Domain .IP \(bu 2 True BusinessID Wildcard .IP \(bu 2 True BusinessID with EV .IP \(bu 2 True BusinessID with EV Multi Domain .IP \(bu 2 Unified Communications .UNINDENT .TP .B http_dc_validation False Set to \fBTrue\fP if a Comodo certificate and validation should be done with files instead of emails and to return the info to do so .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_ssl.parse_csr my\-csr\-file PremiumSSL .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_ssl.reissue(csr_file, certificate_id, web_server_type, approver_email=None, http_dc_validation=False, **kwargs) Reissues a purchased SSL certificate. Returns a dictionary of result values. .INDENT 7.0 .TP .B csr_file Path to Certificate Signing Request file .TP .B certificate_id Unique ID of the SSL certificate you wish to activate .TP .B web_server_type The type of certificate format to return. Possible values include: .INDENT 7.0 .IP \(bu 2 apache2 .IP \(bu 2 apacheapachessl .IP \(bu 2 apacheopenssl .IP \(bu 2 apacheraven .IP \(bu 2 apachessl .IP \(bu 2 apachessleay .IP \(bu 2 c2net .IP \(bu 2 cobaltseries .IP \(bu 2 cpanel .IP \(bu 2 domino .IP \(bu 2 dominogo4625 .IP \(bu 2 dominogo4626 .IP \(bu 2 ensim .IP \(bu 2 hsphere .IP \(bu 2 ibmhttp .IP \(bu 2 iis .IP \(bu 2 iis4 .IP \(bu 2 iis5 .IP \(bu 2 iplanet .IP \(bu 2 ipswitch .IP \(bu 2 netscape .IP \(bu 2 other .IP \(bu 2 plesk .IP \(bu 2 tomcat .IP \(bu 2 weblogic .IP \(bu 2 website .IP \(bu 2 webstar .IP \(bu 2 zeusv3 .UNINDENT .TP .B approver_email The email ID which is on the approver email list. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBhttp_dc_validation\fP must be set to \fBFalse\fP if this option is used. .UNINDENT .UNINDENT .TP .B http_dc_validation False Whether or not to activate using HTTP\-based validation. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For other parameters which may be required, see \fI\%here\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_ssl.reissue my\-csr\-file my\-cert\-id apachessl .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_ssl.renew(years, certificate_id, certificate_type, promotion_code=None) Renews an SSL certificate if it is ACTIVE and Expires <= 30 days. Returns the following information: .INDENT 7.0 .IP \(bu 2 The certificate ID .IP \(bu 2 The order ID .IP \(bu 2 The transaction ID .IP \(bu 2 The amount charged for the order .UNINDENT .INDENT 7.0 .TP .B years 1 Number of years to register .TP .B certificate_id Unique ID of the SSL certificate you wish to renew .TP .B certificate_type Type of SSL Certificate. Possible values include: .INDENT 7.0 .IP \(bu 2 EV Multi Domain SSL .IP \(bu 2 EV SSL .IP \(bu 2 EV SSL SGC .IP \(bu 2 EssentialSSL .IP \(bu 2 EssentialSSL Wildcard .IP \(bu 2 InstantSSL .IP \(bu 2 InstantSSL Pro .IP \(bu 2 Multi Domain SSL .IP \(bu 2 PositiveSSL .IP \(bu 2 PositiveSSL Multi Domain .IP \(bu 2 PositiveSSL Wildcard .IP \(bu 2 PremiumSSL .IP \(bu 2 PremiumSSL Wildcard .IP \(bu 2 QuickSSL Premium .IP \(bu 2 RapidSSL .IP \(bu 2 RapidSSL Wildcard .IP \(bu 2 SGC Supercert .IP \(bu 2 SSL Web Server .IP \(bu 2 SSL Webserver EV .IP \(bu 2 SSL123 .IP \(bu 2 Secure Site .IP \(bu 2 Secure Site Pro .IP \(bu 2 Secure Site Pro with EV .IP \(bu 2 Secure Site with EV .IP \(bu 2 True BusinessID .IP \(bu 2 True BusinessID Multi Domain .IP \(bu 2 True BusinessID Wildcard .IP \(bu 2 True BusinessID with EV .IP \(bu 2 True BusinessID with EV Multi Domain .IP \(bu 2 Unified Communications .UNINDENT .TP .B promotional_code An optional promo code to use when renewing the certificate .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_ssl.renew 1 my\-cert\-id RapidSSL .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.namecheap_users .sp Namecheap User Management .sp New in version 2017.7.0. .SS Prerequisites .sp This module uses the \fBrequests\fP Python module to communicate to the namecheap API. .SS Configuration .sp The Namecheap username, API key and URL should be set in the minion configuration file, or in the Pillar data. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C namecheap.name: companyname namecheap.key: a1b2c3d4e5f67a8b9c0d1e2f3 namecheap.client_ip: 162.155.30.172 #Real url namecheap.url: https://api.namecheap.com/xml.response #Sandbox url #namecheap.url: https://api.sandbox.namecheap.xml.response .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_users.check_balances(minimum=100) Checks if the provided minimum value is present in the user\(aqs account. .sp Returns a boolean. Returns \fBFalse\fP if the user\(aqs account balance is less than the provided minimum or \fBTrue\fP if greater than the minimum. .INDENT 7.0 .TP .B minimum 100 The value to check .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_users.check_balances salt \(aqmy\-minion\(aq namecheap_users.check_balances minimum=150 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.namecheap_users.get_balances() Gets information about fund in the user\(aqs account. This method returns the following information: Available Balance, Account Balance, Earned Amount, Withdrawable Amount and Funds Required for AutoRenew. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If a domain setup with automatic renewal is expiring within the next 90 days, the FundsRequiredForAutoRenew attribute shows the amount needed in your Namecheap account to complete auto renewal. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-minion\(aq namecheap_users.get_balances .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.napalm_bgp .SS NAPALM BGP .sp Manages BGP configuration on network devices and provides statistics. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> & Jerome Fleury <\fI\%jf@cloudflare.com\fP> .TP .B maturity new .TP .B depends napalm .TP .B platform unix .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 \fI\%napalm proxy minion\fP .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.modules.napalm_bgp.config(group=None, neighbor=None, **kwargs) Provides the BGP configuration on the device. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgroup\fP \-\- Name of the group selected to display the configuration. .IP \(bu 2 \fBneighbor\fP \-\- IP Address of the neighbor to display the configuration. If the group parameter is not specified, the neighbor setting will be ignored. .UNINDENT .TP .B Returns A dictionary containing the BGP configuration from the network device. The keys of the main dictionary are the group names. .UNINDENT .sp Each group has the following properties: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 type (string) .IP \(bu 2 description (string) .IP \(bu 2 apply_groups (string list) .IP \(bu 2 multihop_ttl (int) .IP \(bu 2 multipath (True/False) .IP \(bu 2 local_address (string) .IP \(bu 2 local_as (int) .IP \(bu 2 remote_as (int) .IP \(bu 2 import_policy (string) .IP \(bu 2 export_policy (string) .IP \(bu 2 remove_private_as (True/False) .IP \(bu 2 prefix_limit (dictionary) .IP \(bu 2 neighbors (dictionary) .UNINDENT .UNINDENT .UNINDENT .sp Each neighbor in the dictionary of neighbors provides: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 description (string) .IP \(bu 2 import_policy (string) .IP \(bu 2 export_policy (string) .IP \(bu 2 local_address (string) .IP \(bu 2 local_as (int) .IP \(bu 2 remote_as (int) .IP \(bu 2 authentication_key (string) .IP \(bu 2 prefix_limit (dictionary) .IP \(bu 2 route_reflector_client (True/False) .IP \(bu 2 nhs (True/False) .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bgp.config # entire BGP config salt \(aq*\(aq bgp.config PEERS\-GROUP\-NAME # provides detail only about BGP group PEERS\-GROUP\-NAME salt \(aq*\(aq bgp.config PEERS\-GROUP\-NAME 172.17.17.1 # provides details only about BGP neighbor 172.17.17.1, # configured in the group PEERS\-GROUP\-NAME .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqPEERS\-GROUP\-NAME\(aq:{ \(aqtype\(aq : \(aqexternal\(aq, \(aqdescription\(aq : \(aqHere we should have a nice description\(aq, \(aqapply_groups\(aq : [\(aqBGP\-PREFIX\-LIMIT\(aq], \(aqimport_policy\(aq : \(aqPUBLIC\-PEER\-IN\(aq, \(aqexport_policy\(aq : \(aqPUBLIC\-PEER\-OUT\(aq, \(aqremove_private\(aq: True, \(aqmultipath\(aq : True, \(aqmultihop_ttl\(aq : 30, \(aqneighbors\(aq : { \(aq192.168.0.1\(aq: { \(aqdescription\(aq : \(aqFacebook [CDN]\(aq, \(aqprefix_limit\(aq : { \(aqinet\(aq: { \(aqunicast\(aq: { \(aqlimit\(aq: 100, \(aqteardown\(aq: { \(aqthreshold\(aq : 95, \(aqtimeout\(aq : 5 } } } } \(aqpeer\-as\(aq : 32934, \(aqroute_reflector\(aq: False, \(aqnhs\(aq : True }, \(aq172.17.17.1\(aq: { \(aqdescription\(aq : \(aqTwitter [CDN]\(aq, \(aqprefix_limit\(aq : { \(aqinet\(aq: { \(aqunicast\(aq: { \(aqlimit\(aq: 500, \(aqno\-validate\(aq: \(aqIMPORT\-FLOW\-ROUTES\(aq } } } \(aqpeer_as\(aq : 13414 \(aqroute_reflector\(aq: False, \(aqnhs\(aq : False } } } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_bgp.neighbors(neighbor=None, **kwargs) Provides details regarding the BGP sessions configured on the network device. .INDENT 7.0 .TP .B Parameters \fBneighbor\fP \-\- IP Address of a specific neighbor. .TP .B Returns A dictionary with the statistics of the all/selected BGP neighbors. Outer dictionary keys represent the VRF name. Keys of inner dictionary represent the AS numbers, while the values are lists of dictionaries, having the following keys: .INDENT 7.0 .IP \(bu 2 up (True/False) .IP \(bu 2 local_as (int) .IP \(bu 2 remote_as (int) .IP \(bu 2 local_address (string) .IP \(bu 2 routing_table (string) .IP \(bu 2 local_address_configured (True/False) .IP \(bu 2 local_port (int) .IP \(bu 2 remote_address (string) .IP \(bu 2 remote_port (int) .IP \(bu 2 multihop (True/False) .IP \(bu 2 multipath (True/False) .IP \(bu 2 remove_private_as (True/False) .IP \(bu 2 import_policy (string) .IP \(bu 2 export_policy (string) .IP \(bu 2 input_messages (int) .IP \(bu 2 output_messages (int) .IP \(bu 2 input_updates (int) .IP \(bu 2 output_updates (int) .IP \(bu 2 messages_queued_out (int) .IP \(bu 2 connection_state (string) .IP \(bu 2 previous_connection_state (string) .IP \(bu 2 last_event (string) .IP \(bu 2 suppress_4byte_as (True/False) .IP \(bu 2 local_as_prepend (True/False) .IP \(bu 2 holdtime (int) .IP \(bu 2 configured_holdtime (int) .IP \(bu 2 keepalive (int) .IP \(bu 2 configured_keepalive (int) .IP \(bu 2 active_prefix_count (int) .IP \(bu 2 received_prefix_count (int) .IP \(bu 2 accepted_prefix_count (int) .IP \(bu 2 suppressed_prefix_count (int) .IP \(bu 2 advertised_prefix_count (int) .IP \(bu 2 flap_count (int) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bgp.neighbors # all neighbors salt \(aq*\(aq bgp.neighbors 172.17.17.1 # only session with BGP neighbor(s) 172.17.17.1 .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqdefault\(aq: { 8121: [ { \(aqup\(aq : True, \(aqlocal_as\(aq : 13335, \(aqremote_as\(aq : 8121, \(aqlocal_address\(aq : \(aq172.101.76.1\(aq, \(aqlocal_address_configured\(aq : True, \(aqlocal_port\(aq : 179, \(aqremote_address\(aq : \(aq192.247.78.0\(aq, \(aqrouter_id\(aq : \(aq192.168.0.1\(aq, \(aqremote_port\(aq : 58380, \(aqmultihop\(aq : False, \(aqimport_policy\(aq : \(aq4\-NTT\-TRANSIT\-IN\(aq, \(aqexport_policy\(aq : \(aq4\-NTT\-TRANSIT\-OUT\(aq, \(aqinput_messages\(aq : 123, \(aqoutput_messages\(aq : 13, \(aqinput_updates\(aq : 123, \(aqoutput_updates\(aq : 5, \(aqmessages_queued_out\(aq : 23, \(aqconnection_state\(aq : \(aqEstablished\(aq, \(aqprevious_connection_state\(aq : \(aqEstabSync\(aq, \(aqlast_event\(aq : \(aqRecvKeepAlive\(aq, \(aqsuppress_4byte_as\(aq : False, \(aqlocal_as_prepend\(aq : False, \(aqholdtime\(aq : 90, \(aqconfigured_holdtime\(aq : 90, \(aqkeepalive\(aq : 30, \(aqconfigured_keepalive\(aq : 30, \(aqactive_prefix_count\(aq : 132808, \(aqreceived_prefix_count\(aq : 566739, \(aqaccepted_prefix_count\(aq : 566479, \(aqsuppressed_prefix_count\(aq : 0, \(aqadvertise_prefix_count\(aq : 0, \(aqflap_count\(aq : 27 } ] } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.napalm_formula .SS NAPALM Formula helpers .sp New in version 2019.2.0. .sp This is an Execution Module providing helpers for various NAPALM formulas, e.g., napalm\-interfaces\-formula, napalm\-bgp\-formula, napalm\-ntp\-formula etc., meant to provide various helper functions to make the templates more readable. .INDENT 0.0 .TP .B salt.modules.napalm_formula.container_path(model, key=None, container=None, delim=\(aq:\(aq) Return the list of all the possible paths in a container, down to the \fBconfig\fP container. This function can be used to verify that the \fBmodel\fP is a Python object correctly structured and respecting the OpenConfig hierarchy. .INDENT 7.0 .TP .B model The OpenConfig\-structured object to inspect. .TP .B delim: \fB:\fP The key delimiter. In particular cases, it is indicated to use \fB//\fP as \fB:\fP might be already used in various cases, e.g., IPv6 addresses, interface name (e.g., Juniper QFX series), etc. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm_formula.container_path \(dq{\(aqinterfaces\(aq: {\(aqinterface\(aq: {\(aqEthernet1\(aq: {\(aqconfig\(aq: {\(aqname\(aq: \(aqEthernet1\(aq}}}}}\(dq .ft P .fi .UNINDENT .UNINDENT .sp The example above would return a list with the following element: \fBinterfaces:interface:Ethernet1:config\fP which is the only possible path in that hierarchy. .sp Other output examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- interfaces:interface:Ethernet1:config \- interfaces:interface:Ethernet1:subinterfaces:subinterface:0:config \- interfaces:interface:Ethernet2:config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_formula.defaults(model, defaults_, delim=\(aq//\(aq, flipped_merge=False) Apply the defaults to a Python dictionary having the structure as described in the OpenConfig standards. .INDENT 7.0 .TP .B model The OpenConfig model to apply the defaults to. .TP .B defaults The dictionary of defaults. This argument must equally be structured with respect to the OpenConfig standards. .sp For ease of use, the keys of these support glob matching, therefore we don\(aqt have to provide the defaults for each entity but only for the entity type. See an example below. .TP .B delim: \fB//\fP The key delimiter to use. Generally, \fB//\fP should cover all the possible cases, and you don\(aqt need to override this value. .TP .B flipped_merge: \fBFalse\fP Whether should merge the model into the defaults, or the defaults into the model. Default: \fBFalse\fP (merge the model into the defaults, i.e., any defaults would be overridden by the values from the \fBmodel\fP). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm_formula.defaults \(dq{\(aqinterfaces\(aq: {\(aqinterface\(aq: {\(aqEthernet1\(aq: {\(aqconfig\(aq: {\(aqname\(aq: \(aqEthernet1\(aq}}}}}\(dq \(dq{\(aqinterfaces\(aq: {\(aqinterface\(aq: {\(aq*\(aq: {\(aqconfig\(aq: {\(aqenabled\(aq: True}}}}}\(dq .ft P .fi .UNINDENT .UNINDENT .sp As one can notice in the example above, the \fB*\fP corresponds to the interface name, therefore, the defaults will be applied on all the interfaces. .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_formula.dictupdate(dest, upd, recursive_update=True, merge_lists=False) Recursive version of the default dict.update .sp Merges upd recursively into dest .sp If recursive_update=False, will use the classic dict.update, or fall back on a manual merge (helpful for non\-dict types like \fBFunctionWrapper\fP). .sp If \fBmerge_lists=True\fP, will aggregate list object types instead of replace. The list in \fBupd\fP is added to the list in \fBdest\fP, so the resulting list is \fBdest[key] + upd[key]\fP\&. This behaviour is only activated when \fBrecursive_update=True\fP\&. By default \fBmerge_lists=False\fP\&. .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_formula.render_field(dictionary, field, prepend=None, append=None, quotes=False, **opts) Render a field found under the \fBfield\fP level of the hierarchy in the \fBdictionary\fP object. This is useful to render a field in a Jinja template without worrying that the hierarchy might not exist. For example if we do the following in Jinja: \fB{{ interfaces.interface.Ethernet5.config.description }}\fP for the following object: \fB{\(aqinterfaces\(aq: {\(aqinterface\(aq: {\(aqEthernet1\(aq: {\(aqconfig\(aq: {\(aqenabled\(aq: True}}}}}\fP it would error, as the \fBEthernet5\fP key does not exist. With this helper, we can skip this and avoid existence checks. This must be however used with care. .INDENT 7.0 .TP .B dictionary The dictionary to traverse. .TP .B field The key name or part to traverse in the \fBdictionary\fP\&. .TP .B prepend: \fBNone\fP The text to prepend in front of the text. Usually, we need to have the name of the field too when generating the configuration. .TP .B append: \fBNone\fP Text to append at the end. .TP .B quotes: \fBFalse\fP Whether should wrap the text around quotes. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm_formula.render_field \(dq{\(aqenabled\(aq: True}\(dq enabled # This would return the value of the \(ga\(gaenabled\(ga\(ga leaf key salt \(aq*\(aq napalm_formula.render_field \(dq{\(aqenabled\(aq: True}\(dq description # This would not error .ft P .fi .UNINDENT .UNINDENT .sp Jinja usage example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set config = {\(aqenabled\(aq: True, \(aqdescription\(aq: \(aqInterface description\(aq} %} {{ salt.napalm_formula.render_field(config, \(aqdescription\(aq, quotes=True) }} .ft P .fi .UNINDENT .UNINDENT .sp The example above would be rendered on Arista / Cisco as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C description \(dqInterface description\(dq .ft P .fi .UNINDENT .UNINDENT .sp While on Junos (the semicolon is important to be added, otherwise the configuration won\(aqt be accepted by Junos): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C description \(dqInterface description\(dq; .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_formula.render_fields(dictionary, *fields, **opts) This function works similarly to \fI\%render_field\fP but for a list of fields from the same dictionary, rendering, indenting and distributing them on separate lines. .INDENT 7.0 .TP .B dictionary The dictionary to traverse. .TP .B fields A list of field names or paths in the dictionary. .TP .B indent: \fB0\fP The indentation to use, prepended to the rendered field. .TP .B separator: \fB\en\fP The separator to use between fields. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm_formula.render_fields \(dq{\(aqmtu\(aq: 68, \(aqdescription\(aq: \(aqInterface description\(aq}\(dq mtu description .ft P .fi .UNINDENT .UNINDENT .sp Jinja usage example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set config={\(aqmtu\(aq: 68, \(aqdescription\(aq: \(aqInterface description\(aq} %} {{ salt.napalm_formula.render_fields(config, \(aqmtu\(aq, \(aqdescription\(aq, quotes=True) }} .ft P .fi .UNINDENT .UNINDENT .sp The Jinja example above would generate the following configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mtu \(dq68\(dq description \(dqInterface description\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_formula.setval(key, val, dict_=None, delim=\(aq:\(aq) Set a value under the dictionary hierarchy identified under the key. The target \(aqfoo/bar/baz\(aq returns the dictionary hierarchy {\(aqfoo\(aq: {\(aqbar\(aq: {\(aqbaz\(aq: {}}}}. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Currently this doesn\(aqt work with integers, i.e. cannot build lists dynamically. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq formula.setval foo:baz:bar True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_formula.traverse(data, key, default=None, delimiter=\(aq:\(aq) Traverse a dict or list using a colon\-delimited (or otherwise delimited, using the \fBdelimiter\fP param) target string. The target \fBfoo:bar:0\fP will return \fBdata[\(aqfoo\(aq][\(aqbar\(aq][0]\fP if this value exists, and will otherwise return the dict in the default argument. Function will automatically determine the target type. The target \fBfoo:bar:0\fP will return data[\(aqfoo\(aq][\(aqbar\(aq][0] if data like \fB{\(aqfoo\(aq:{\(aqbar\(aq:[\(aqbaz\(aq]}}\fP , if data like \fB{\(aqfoo\(aq:{\(aqbar\(aq:{\(aq0\(aq:\(aqbaz\(aq}}}\fP then \fBreturn data[\(aqfoo\(aq][\(aqbar\(aq][\(aq0\(aq]\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm_formula.traverse \(dq{\(aqfoo\(aq: {\(aqbar\(aq: {\(aqbaz\(aq: True}}}\(dq foo:baz:bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.napalm_mod .SS NAPALM helpers .sp Helpers for the NAPALM modules. .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.modules.napalm_mod.alive(**kwargs) Returns the alive status of the connection layer. The output is a dictionary under the usual dictionary output of the NAPALM modules. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.alive .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C result: True out: is_alive: False comment: \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.call(method, *args, **kwargs) Execute arbitrary methods from the NAPALM library. To see the expected output, please consult the NAPALM documentation. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This feature is not recommended to be used in production. It should be used for testing only! .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.call get_lldp_neighbors salt \(aq*\(aq napalm.call get_firewall_policies salt \(aq*\(aq napalm.call get_bgp_config group=\(aqmy\-group\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.compliance_report(filepath=None, string=None, renderer=\(aqjinja|yaml\(aq, **kwargs) Return the compliance report. .INDENT 7.0 .TP .B filepath The absolute path to the validation file. .sp Changed in version 2019.2.0. .sp Beginning with release codename \fB2019.2.0\fP, this function has been enhanced, to be able to leverage the multi\-engine template rendering of Salt, besides the possibility to retrieve the file source from remote systems, the URL schemes supported being: .INDENT 7.0 .IP \(bu 2 \fBsalt://\fP .IP \(bu 2 \fBhttp://\fP and \fBhttps://\fP .IP \(bu 2 \fBftp://\fP .IP \(bu 2 \fBs3://\fP .IP \(bu 2 \fBswift:/\fP .UNINDENT .sp Or on the local file system (on the Minion). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The rendering result does not necessarily need to be YAML, instead it can be any format interpreted by Salt\(aqs rendering pipeline (including pure Python). .UNINDENT .UNINDENT .TP .B string New in version 2019.2.0. .sp The compliance report send as inline string, to be used as the file to send through the renderer system. Note, not all renderer modules can work with strings; the \(aqpy\(aq renderer requires a file, for example. .TP .B renderer: \fBjinja|yaml\fP New in version 2019.2.0. .sp The renderer pipe to send the file through; this is overridden by a \(dqshe\-bang\(dq at the top of the file. .TP .B kwargs Changed in version 2019.2.0. .sp Keyword args to pass to Salt\(aqs compile_template() function. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.compliance_report ~/validate.yml salt \(aq*\(aq napalm.compliance_report salt://path/to/validator.sls .ft P .fi .UNINDENT .UNINDENT .sp Validation File Example (pure YAML): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- get_facts: os_version: 4.17 \- get_interfaces_ip: Management1: ipv4: 10.0.2.14: prefix_length: 24 _mode: strict .ft P .fi .UNINDENT .UNINDENT .sp Validation File Example (as Jinja + YAML): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- get_facts: os_version: {{ grains.version }} \- get_interfaces_ip: Loopback0: ipv4: {{ grains.lo0.ipv4 }}: prefix_length: 24 _mode: strict \- get_bgp_neighbors: {{ pillar.bgp.neighbors }} .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C device1: \-\-\-\-\-\-\-\-\-\- comment: out: \-\-\-\-\-\-\-\-\-\- complies: False get_facts: \-\-\-\-\-\-\-\-\-\- complies: False extra: missing: present: \-\-\-\-\-\-\-\-\-\- os_version: \-\-\-\-\-\-\-\-\-\- actual_value: 15.1F6\-S1.4 complies: False nested: False get_interfaces_ip: \-\-\-\-\-\-\-\-\-\- complies: False extra: missing: \- Management1 present: \-\-\-\-\-\-\-\-\-\- skipped: result: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.config_diff_text(source1=\(aqcandidate\(aq, candidate_path=None, source2=\(aqrunning\(aq, running_path=None) New in version 2019.2.0. .sp Return the diff, as text, between the two different configuration sources. The sources can be either specified using the \fBsource1\fP and \fBsource2\fP arguments when retrieving from the managed network device. .INDENT 7.0 .TP .B source1: \fBcandidate\fP The source from where to retrieve the configuration to be compared with. Available options: \fBcandidate\fP, \fBrunning\fP, \fBstartup\fP\&. Default: \fBcandidate\fP\&. .TP .B candidate_path Absolute or remote path from where to load the candidate configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B source2: \fBrunning\fP The source from where to retrieve the configuration to compare with. Available options: \fBcandidate\fP, \fBrunning\fP, \fBstartup\fP\&. Default: \fBrunning\fP\&. .TP .B running_path Absolute or remote path from where to load the running configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBcandidate_path\fP or \fBrunning_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.config_diff_text salt \(aq*\(aq napalm.config_diff_text candidate_path=https://bit.ly/2mAdq7z # Would compare the running config with the configuration available at # https://bit.ly/2mAdq7z .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.config_diff_tree(source1=\(aqcandidate\(aq, candidate_path=None, source2=\(aqrunning\(aq, running_path=None) New in version 2019.2.0. .sp Return the diff, as Python dictionary, between two different sources. The sources can be either specified using the \fBsource1\fP and \fBsource2\fP arguments when retrieving from the managed network device. .INDENT 7.0 .TP .B source1: \fBcandidate\fP The source from where to retrieve the configuration to be compared with. Available options: \fBcandidate\fP, \fBrunning\fP, \fBstartup\fP\&. Default: \fBcandidate\fP\&. .TP .B candidate_path Absolute or remote path from where to load the candidate configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B source2: \fBrunning\fP The source from where to retrieve the configuration to compare with. Available options: \fBcandidate\fP, \fBrunning\fP, \fBstartup\fP\&. Default: \fBrunning\fP\&. .TP .B running_path Absolute or remote path from where to load the running configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBcandidate_path\fP or \fBrunning_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.config_diff_text salt \(aq*\(aq napalm.config_diff_text candidate_path=https://bit.ly/2mAdq7z # Would compare the running config with the configuration available at # https://bit.ly/2mAdq7z .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.config_diff_tree salt \(aq*\(aq napalm.config_diff_tree running startup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.config_filter_lines(parent_regex, child_regex, source=\(aqrunning\(aq) New in version 2019.2.0. .sp Return a list of detailed matches, for the configuration blocks (parent\-child relationship) whose parent respects the regular expressions configured via the \fBparent_regex\fP argument, and the child matches the \fBchild_regex\fP regular expression. The result is a list of dictionaries with the following keys: .INDENT 7.0 .IP \(bu 2 \fBmatch\fP: a boolean value that tells whether \fBchild_regex\fP matched any children lines. .IP \(bu 2 \fBparent\fP: the parent line (as text). .IP \(bu 2 \fBchild\fP: the child line (as text). If no child line matched, this field will be \fBNone\fP\&. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function is only available only when the underlying library \fI\%ciscoconfparse\fP is installed. See \fI\%ciscoconfparse module\fP for more details. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B parent_regex The regular expression to match the parent configuration lines against. .TP .B child_regex The regular expression to match the child configuration lines against. .TP .B source: \fBrunning\fP The configuration type to retrieve from the network device. Default: \fBrunning\fP\&. Available options: \fBrunning\fP, \fBstartup\fP, \fBcandidate\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.config_filter_lines \(aq^interface\(aq \(aqip address\(aq salt \(aq*\(aq napalm.config_filter_lines \(aq^interface\(aq \(aqshutdown\(aq source=candidate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.config_find_lines(regex, source=\(aqrunning\(aq) New in version 2019.2.0. .sp Return the configuration lines that match the regular expressions from the \fBregex\fP argument. The configuration is read from the network device interrogated. .INDENT 7.0 .TP .B regex The regular expression to match the configuration lines against. .TP .B source: \fBrunning\fP The configuration type to retrieve from the network device. Default: \fBrunning\fP\&. Available options: \fBrunning\fP, \fBstartup\fP, \fBcandidate\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.config_find_lines \(aq^interface Ethernet1\ed\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.config_lines_w_child(parent_regex, child_regex, source=\(aqrunning\(aq) .INDENT 7.0 .INDENT 3.5 New in version 2019.2.0. .UNINDENT .UNINDENT .sp Return the configuration lines that match the regular expressions from the \fBparent_regex\fP argument, having child lines matching \fBchild_regex\fP\&. The configuration is read from the network device interrogated. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function is only available only when the underlying library \fI\%ciscoconfparse\fP is installed. See \fI\%ciscoconfparse module\fP for more details. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B parent_regex The regular expression to match the parent configuration lines against. .TP .B child_regex The regular expression to match the child configuration lines against. .TP .B source: \fBrunning\fP The configuration type to retrieve from the network device. Default: \fBrunning\fP\&. Available options: \fBrunning\fP, \fBstartup\fP, \fBcandidate\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.config_lines_w_child \(aq^interface\(aq \(aqip address\(aq salt \(aq*\(aq napalm.config_lines_w_child \(aq^interface\(aq \(aqshutdown\(aq source=candidate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.config_lines_wo_child(parent_regex, child_regex, source=\(aqrunning\(aq) .INDENT 7.0 .INDENT 3.5 New in version 2019.2.0. .UNINDENT .UNINDENT .sp Return the configuration lines that match the regular expressions from the \fBparent_regex\fP argument, having the child lines \fInot\fP matching \fBchild_regex\fP\&. The configuration is read from the network device interrogated. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function is only available only when the underlying library \fI\%ciscoconfparse\fP is installed. See \fI\%ciscoconfparse module\fP for more details. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B parent_regex The regular expression to match the parent configuration lines against. .TP .B child_regex The regular expression to match the child configuration lines against. .TP .B source: \fBrunning\fP The configuration type to retrieve from the network device. Default: \fBrunning\fP\&. Available options: \fBrunning\fP, \fBstartup\fP, \fBcandidate\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.config_lines_wo_child \(aq^interface\(aq \(aqip address\(aq salt \(aq*\(aq napalm.config_lines_wo_child \(aq^interface\(aq \(aqshutdown\(aq source=candidate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.config_merge_diff(source=\(aqrunning\(aq, merge_config=None, merge_path=None, saltenv=\(aqbase\(aq) New in version 2019.2.0. .sp Return the merge diff, as text, after merging the merge config into the configuration source requested (without loading the config on the device). .INDENT 7.0 .TP .B source: \fBrunning\fP The configuration type to retrieve from the network device. Default: \fBrunning\fP\&. Available options: \fBrunning\fP, \fBstartup\fP, \fBcandidate\fP\&. .TP .B merge_config The config to be merged into the initial config, sent as text. This argument is ignored when \fBmerge_path\fP is set. .TP .B merge_path Absolute or remote path from where to load the merge configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBmerge_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.config_merge_diff merge_path=salt://path/to/merge.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.config_merge_text(source=\(aqrunning\(aq, merge_config=None, merge_path=None, saltenv=\(aqbase\(aq) New in version 2019.2.0. .sp Return the merge result of the configuration from \fBsource\fP with the merge configuration, as plain text (without loading the config on the device). .INDENT 7.0 .TP .B source: \fBrunning\fP The configuration type to retrieve from the network device. Default: \fBrunning\fP\&. Available options: \fBrunning\fP, \fBstartup\fP, \fBcandidate\fP\&. .TP .B merge_config The config to be merged into the initial config, sent as text. This argument is ignored when \fBmerge_path\fP is set. .TP .B merge_path Absolute or remote path from where to load the merge configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBmerge_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.config_merge_text merge_path=salt://path/to/merge.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.config_merge_tree(source=\(aqrunning\(aq, merge_config=None, merge_path=None, saltenv=\(aqbase\(aq) New in version 2019.2.0. .sp Return the merge tree of the \fBinitial_config\fP with the \fBmerge_config\fP, as a Python dictionary. .INDENT 7.0 .TP .B source: \fBrunning\fP The configuration type to retrieve from the network device. Default: \fBrunning\fP\&. Available options: \fBrunning\fP, \fBstartup\fP, \fBcandidate\fP\&. .TP .B merge_config The config to be merged into the initial config, sent as text. This argument is ignored when \fBmerge_path\fP is set. .TP .B merge_path Absolute or remote path from where to load the merge configuration text. This argument allows any URI supported by \fI\%cp.get_url\fP), e.g., \fBsalt://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp:/\fP, etc. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBmerge_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.config_merge_tree merge_path=salt://path/to/merge.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.config_tree(source=\(aqrunning\(aq, with_tags=False) New in version 2019.2.0. .sp Transform Cisco IOS style configuration to structured Python dictionary. Depending on the value of the \fBwith_tags\fP argument, this function may provide different views, valuable in different situations. .INDENT 7.0 .TP .B source: \fBrunning\fP The configuration type to retrieve from the network device. Default: \fBrunning\fP\&. Available options: \fBrunning\fP, \fBstartup\fP, \fBcandidate\fP\&. .TP .B with_tags: \fBFalse\fP Whether this function should return a detailed view, with tags. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.config_tree .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.junos_call(fun, *args, **kwargs) New in version 2019.2.0. .sp Execute an arbitrary function from the \fBjunos execution module\fP\&. To check what \fBargs\fP and \fBkwargs\fP you must send to the function, please consult the appropriate documentation. .INDENT 7.0 .TP .B fun The name of the function. E.g., \fBset_hostname\fP\&. .TP .B args List of arguments to send to the \fBjunos\fP function invoked. .TP .B kwargs Dictionary of key\-value arguments to send to the \fBjuno\fP function invoked. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.junos_fun cli \(aqshow system commit\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.junos_cli(command, format=None, dev_timeout=None, dest=None, **kwargs) New in version 2019.2.0. .sp Execute a CLI command and return the output in the specified format. .INDENT 7.0 .TP .B command The command to execute on the Junos CLI. .TP .B format: \fBtext\fP Format in which to get the CLI output (either \fBtext\fP or \fBxml\fP). .TP .B dev_timeout: \fB30\fP The NETCONF RPC timeout (in seconds). .TP .B dest Destination file where the RPC output is stored. Note that the file will be stored on the Proxy Minion. To push the files to the Master, use \fI\%cp.push\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.junos_cli \(aqshow lldp neighbors\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.junos_commit(**kwargs) New in version 2019.2.0. .sp Commit the changes loaded in the candidate configuration. .INDENT 7.0 .TP .B dev_timeout: \fB30\fP The NETCONF RPC timeout (in seconds). .TP .B comment Provide a comment for the commit. .TP .B confirm Provide time in minutes for commit confirmation. If this option is specified, the commit will be rolled back in the specified amount of time unless the commit is confirmed. .TP .B sync: \fBFalse\fP When \fBTrue\fP, on dual control plane systems, requests that the candidate configuration on one control plane be copied to the other control plane, checked for correct syntax, and committed on both Routing Engines. .TP .B force_sync: \fBFalse\fP When \fBTrue\fP, on dual control plane systems, force the candidate configuration on one control plane to be copied to the other control plane. .TP .B full When \fBTrue\fP, requires all the daemons to check and evaluate the new configuration. .TP .B detail When \fBTrue\fP, return commit detail. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.junos_commit comment=\(aqCommitiing via Salt\(aq detail=True salt \(aq*\(aq napalm.junos_commit dev_timeout=60 confirm=10 salt \(aq*\(aq napalm.junos_commit sync=True dev_timeout=90 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.junos_copy_file(src, dst, **kwargs) New in version 2019.2.0. .sp Copies the file on the remote Junos device. .INDENT 7.0 .TP .B src The source file path. This argument accepts the usual Salt URIs (e.g., \fBsalt://\fP, \fBhttp://\fP, \fBhttps://\fP, \fBs3://\fP, \fBftp://\fP, etc.). .TP .B dst The destination path on the device where to copy the file. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.junos_copy_file https://example.com/junos.cfg /var/tmp/myjunos.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.junos_facts(**kwargs) New in version 2019.2.0. .sp The complete list of Junos facts collected by \fBjunos\-eznc\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.junos_facts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.junos_install_os(path=None, **kwargs) New in version 2019.2.0. .sp Installs the given image on the device. .INDENT 7.0 .TP .B path The image file source. This argument supports the following URIs: .INDENT 7.0 .IP \(bu 2 Absolute path on the Minion. .IP \(bu 2 \fBsalt://\fP to fetch from the Salt fileserver. .IP \(bu 2 \fBhttp://\fP and \fBhttps://\fP .IP \(bu 2 \fBftp://\fP .IP \(bu 2 \fBswift:/\fP .IP \(bu 2 \fBs3://\fP .UNINDENT .TP .B dev_timeout: \fB30\fP The NETCONF RPC timeout (in seconds) .TP .B reboot: \fBFalse\fP Whether to reboot the device after the installation is complete. .TP .B no_copy: \fBFalse\fP If \fBTrue\fP the software package will not be copied to the remote device. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.junos_install_os salt://images/junos_16_1.tgz reboot=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.junos_rpc(cmd=None, dest=None, format=None, **kwargs) New in version 2019.2.0. .sp Execute an RPC request on the remote Junos device. .INDENT 7.0 .TP .B cmd The RPC request to the executed. To determine the RPC request, you can check the from the command line of the device, by executing the usual command followed by \fB| display xml rpc\fP, e.g., \fBshow lldp neighbors | display xml rpc\fP\&. .TP .B dest Destination file where the RPC output is stored. Note that the file will be stored on the Proxy Minion. To push the files to the Master, use \fI\%cp.push\fP Execution function. .TP .B format: \fBxml\fP The format in which the RPC reply is received from the device. .TP .B dev_timeout: \fB30\fP The NETCONF RPC timeout. .TP .B filter Used with the \fBget\-config\fP RPC request to filter out the config tree. .TP .B terse: \fBFalse\fP Whether to return terse output. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Some RPC requests may not support this argument. .UNINDENT .UNINDENT .TP .B interface_name Name of the interface to query. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.junos_rpc get\-lldp\-neighbors\-information salt \(aq*\(aq napalm.junos_rpc get\-config <configuration><system><ntp/></system></configuration> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.netmiko_args(**kwargs) New in version 2019.2.0. .sp Return the key\-value arguments used for the authentication arguments for the netmiko module. .sp When running in a non\-native NAPALM driver (e.g., \fBpanos\fP, \fIf5\(ga\fP, \fBmos\fP \- either from \fI\%https://github.com/napalm\-automation\-community\fP or defined in user\(aqs own environment, one can specify the Netmiko device type (the \fBdevice_type\fP argument) via the \fBnetmiko_device_type_map\fP configuration option / Pillar key, e.g., .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C netmiko_device_type_map: f5: f5_ltm dellos10: dell_os10 .ft P .fi .UNINDENT .UNINDENT .sp The configuration above defines the mapping between the NAPALM \fBos\fP Grain and the Netmiko \fBdevice_type\fP, e.g., when the NAPALM Grain is \fBf5\fP, it would use the \fBf5_ltm\fP SSH Netmiko driver to execute commands over SSH on the remote network device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.netmiko_args .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.netmiko_call(method, *args, **kwargs) New in version 2019.2.0. .sp Execute an arbitrary Netmiko method, passing the authentication details from the existing NAPALM connection. .INDENT 7.0 .TP .B method The name of the Netmiko method to execute. .TP .B args List of arguments to send to the Netmiko method specified in \fBmethod\fP\&. .TP .B kwargs Key\-value arguments to send to the execution function specified in \fBmethod\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.netmiko_call send_command \(aqshow version\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.netmiko_commands(*commands, **kwargs) New in version 2019.2.0. .sp Invoke one or more commands to be executed on the remote device, via Netmiko. Returns a list of strings, with the output from each command. .INDENT 7.0 .TP .B commands A list of commands to be executed. .TP .B expect_string Regular expression pattern to use for determining end of output. If left blank will default to being based on router prompt. .TP .B delay_factor: \fB1\fP Multiplying factor used to adjust delays (default: \fB1\fP). .TP .B max_loops: \fB500\fP Controls wait time in conjunction with delay_factor. Will default to be based upon self.timeout. .TP .B auto_find_prompt: \fBTrue\fP Whether it should try to auto\-detect the prompt (default: \fBTrue\fP). .TP .B strip_prompt: \fBTrue\fP Remove the trailing router prompt from the output (default: \fBTrue\fP). .TP .B strip_command: \fBTrue\fP Remove the echo of the command from the output (default: \fBTrue\fP). .TP .B normalize: \fBTrue\fP Ensure the proper enter is sent at end of command (default: \fBTrue\fP). .TP .B use_textfsm: \fBFalse\fP Process command output through TextFSM template (default: \fBFalse\fP). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.netmiko_commands \(aqshow version\(aq \(aqshow interfaces\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.netmiko_config(*config_commands, **kwargs) New in version 2019.2.0. .sp Load a list of configuration commands on the remote device, via Netmiko. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Please remember that \fBnetmiko\fP does not have any rollback safeguards and any configuration change will be directly loaded into the running config if the platform doesn\(aqt have the concept of \fBcandidate\fP config. .sp On Junos, or other platforms that have this capability, the changes will not be loaded into the running config, and the user must set the \fBcommit\fP argument to \fBTrue\fP to transfer the changes from the candidate into the running config before exiting. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B config_commands A list of configuration commands to be loaded on the remote device. .TP .B config_file Read the configuration commands from a file. The file can equally be a template that can be rendered using the engine of choice (see \fBtemplate_engine\fP). .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 exit_config_mode: \fBTrue\fP Determines whether or not to exit config mode after complete. .TP .B delay_factor: \fB1\fP Factor to adjust delays. .TP .B max_loops: \fB150\fP Controls wait time in conjunction with delay_factor (default: \fB150\fP). .TP .B strip_prompt: \fBFalse\fP Determines whether or not to strip the prompt (default: \fBFalse\fP). .TP .B strip_command: \fBFalse\fP Determines whether or not to strip the command (default: \fBFalse\fP). .TP .B config_mode_command The command to enter into config mode. .TP .B commit: \fBFalse\fP Commit the configuration changes before exiting the config mode. This option is by default disabled, as many platforms don\(aqt have this capability natively. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.netmiko_config \(aqset system ntp peer 1.2.3.4\(aq commit=True salt \(aq*\(aq napalm.netmiko_config https://bit.ly/2sgljCB .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.netmiko_fun(fun, *args, **kwargs) New in version 2019.2.0. .sp Call an arbitrary function from the \fI\%Netmiko\fP module, passing the authentication details from the existing NAPALM connection. .INDENT 7.0 .TP .B fun The name of the function from the \fI\%Netmiko\fP to invoke. .TP .B args List of arguments to send to the execution function specified in \fBfun\fP\&. .TP .B kwargs Key\-value arguments to send to the execution function specified in \fBfun\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.netmiko_fun send_command \(aqshow version\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.netmiko_multi_call(*methods, **kwargs) New in version 2019.2.0. .sp Execute a list of arbitrary Netmiko methods, passing the authentication details from the existing NAPALM connection. .INDENT 7.0 .TP .B methods List of dictionaries with the following keys: .INDENT 7.0 .IP \(bu 2 \fBname\fP: the name of the Netmiko function to invoke. .IP \(bu 2 \fBargs\fP: list of arguments to send to the \fBname\fP method. .IP \(bu 2 \fBkwargs\fP: key\-value arguments to send to the \fBname\fP method. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.netmiko_multi_call \(dq{\(aqname\(aq: \(aqsend_command\(aq, \(aqargs\(aq: [\(aqshow version\(aq]}\(dq \(dq{\(aqname\(aq: \(aqsend_command\(aq, \(aqargs\(aq: [\(aqshow interfaces\(aq]}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.nxos_api_config(commands=None, config_file=None, template_engine=\(aqjinja\(aq, context=None, defaults=None, saltenv=\(aqbase\(aq, **kwargs) .INDENT 7.0 .INDENT 3.5 New in version 2019.2.0. .UNINDENT .UNINDENT .sp Configures the Nexus switch with the specified commands, via the NX\-API. .INDENT 7.0 .TP .B commands The list of configuration commands to load on the Nexus switch. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument is ignored when \fBconfig_file\fP is specified. .UNINDENT .UNINDENT .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. 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 .IP \(bu 2 \fBhttps://\fP .IP \(bu 2 \fBftp:/\fP .IP \(bu 2 \fBs3:/\fP .IP \(bu 2 \fBswift://\fP .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: \fBNone\fP Variables to add to the template context. .TP .B defaults: \fBNone\fP Default values of the \fBcontext\fP dict. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBconfig_file\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.nxos_api_config \(aqspanning\-tree mode mstp\(aq salt \(aq*\(aq napalm.nxos_api_config config_file=https://bit.ly/2LGLcDy context=\(dq{\(aqservers\(aq: [\(aq1.2.3.4\(aq]}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.nxos_api_rpc(commands, method=\(aqcli\(aq, **kwargs) New in version 2019.2.0. .sp Execute an arbitrary RPC request via the Nexus API. .INDENT 7.0 .TP .B commands The RPC commands to be executed. .TP .B method: \fBcli\fP The type of the response, i.e., raw text (\fBcli_ascii\fP) or structured document (\fBcli\fP). Defaults to \fBcli\fP (structured data). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.nxos_api_rpc \(aqshow version\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.nxos_api_show(commands, raw_text=True, **kwargs) New in version 2019.2.0. .sp Execute one or more show (non\-configuration) commands. .INDENT 7.0 .TP .B commands The commands to be executed. .TP .B raw_text: \fBTrue\fP Whether to return raw text or structured data. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.nxos_api_show \(aqshow version\(aq salt \(aq*\(aq napalm.nxos_api_show \(aqshow bgp sessions\(aq \(aqshow processes\(aq raw_text=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.pyeapi_call(method, *args, **kwargs) New in version 2019.2.0. .sp Invoke an arbitrary method from the \fBpyeapi\fP library. This function forwards the existing connection details to the \fBpyeapi.run_commands\fP execution function. .INDENT 7.0 .TP .B method The name of the \fBpyeapi\fP method to invoke. .TP .B kwargs Key\-value arguments to send to the \fBpyeapi\fP method. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.pyeapi_call run_commands \(aqshow version\(aq encoding=text salt \(aq*\(aq napalm.pyeapi_call get_config as_string=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.pyeapi_config(commands=None, config_file=None, template_engine=\(aqjinja\(aq, context=None, defaults=None, saltenv=\(aqbase\(aq, **kwargs) New in version 2019.2.0. .sp Configures the Arista switch with the specified commands, via the \fBpyeapi\fP library. This function forwards the existing connection details to the \fBpyeapi.run_commands\fP execution function. .INDENT 7.0 .TP .B commands The list of configuration commands to load on the Arista switch. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument is ignored when \fBconfig_file\fP is specified. .UNINDENT .UNINDENT .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. 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 .IP \(bu 2 \fBhttps://\fP .IP \(bu 2 \fBftp:/\fP .IP \(bu 2 \fBs3:/\fP .IP \(bu 2 \fBswift://\fP .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: \fBNone\fP Variables to add to the template context. .TP .B defaults: \fBNone\fP Default values of the \fBcontext\fP dict. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBconfig_file\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.pyeapi_config \(aqntp server 1.2.3.4\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.pyeapi_nxos_api_args(**prev_kwargs) New in version 2019.2.0. .sp Return the key\-value arguments used for the authentication arguments for the \fBpyeapi execution module\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.pyeapi_nxos_api_args .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.pyeapi_run_commands(*commands, **kwargs) Execute a list of commands on the Arista switch, via the \fBpyeapi\fP library. This function forwards the existing connection details to the \fBpyeapi.run_commands\fP execution function. .INDENT 7.0 .TP .B commands A list of commands to execute. .TP .B encoding: \fBjson\fP The requested encoding of the command output. Valid values for encoding are \fBjson\fP (default) or \fBtext\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.pyeapi_run_commands \(aqshow version\(aq encoding=text salt \(aq*\(aq napalm.pyeapi_run_commands \(aqshow ip bgp neighbors\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.reconnect(force=False, **kwargs) Reconnect the NAPALM proxy when the connection is dropped by the network device. The connection can be forced to be restarted using the \fBforce\fP argument. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function can be used only when running proxy minions. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.reconnect salt \(aq*\(aq napalm.reconnect force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.rpc(command, **kwargs) New in version 2019.2.0. .sp This is a wrapper to execute RPC requests on various network operating systems supported by NAPALM, invoking the following functions for the NAPALM native drivers: .INDENT 7.0 .IP \(bu 2 \fI\%napalm.junos_rpc\fP for \fBjunos\fP .IP \(bu 2 \fI\%napalm.pyeapi_run_commands\fP for \fBeos\fP .IP \(bu 2 \fI\%napalm.nxos_api_rpc\fP for \fBnxos\fP .IP \(bu 2 \fI\%napalm.netmiko_commands\fP for \fBios\fP, \fBiosxr\fP, and \fBnxos_ssh\fP .UNINDENT .INDENT 7.0 .TP .B command The RPC command to execute. This depends on the nature of the operating system. .TP .B kwargs Key\-value arguments to be sent to the underlying Execution function. .UNINDENT .sp The function capabilities are extensible in the user environment via the \fBnapalm_rpc_map\fP configuration option / Pillar, e.g., .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C napalm_rpc_map: f5: napalm.netmiko_commands panos: panos.call .ft P .fi .UNINDENT .UNINDENT .sp The mapping above reads: when the NAPALM \fBos\fP Grain is \fBf5\fP, then call \fBnapalm.netmiko_commands\fP for RPC requests. .sp By default, if the user does not specify any map, non\-native NAPALM drivers will invoke the \fBnapalm.netmiko_commands\fP Execution function. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.rpc \(aqshow version\(aq salt \(aq*\(aq napalm.rpc get\-interfaces .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.scp_get(remote_path, local_path=\(aq\(aq, recursive=False, preserve_times=False, **kwargs) New in version 2019.2.0. .sp Transfer files and directories from remote network device to the localhost of the Minion. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function is only available only when the underlying library \fI\%scp\fP is installed. See \fI\%scp module\fP for more details. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B remote_path Path to retrieve from remote host. Since this is evaluated by scp on the remote host, shell wildcards and environment variables may be used. .TP .B recursive: \fBFalse\fP Transfer files and directories recursively. .TP .B preserve_times: \fBFalse\fP Preserve \fBmtime\fP and \fBatime\fP of transferred files and directories. .TP .B passphrase Used for decrypting private keys. .TP .B pkey An optional private key to use for authentication. .TP .B key_filename The filename, or list of filenames, of optional private key(s) and/or certificates to try for authentication. .TP .B timeout An optional timeout (in seconds) for the TCP connect. .TP .B socket_timeout: \fB10\fP The channel socket timeout in seconds. .TP .B buff_size: \fB16384\fP The size of the SCP send buffer. .TP .B allow_agent: \fBTrue\fP Set to \fBFalse\fP to disable connecting to the SSH agent. .TP .B look_for_keys: \fBTrue\fP Set to \fBFalse\fP to disable searching for discoverable private key files in \fB~/.ssh/\fP .TP .B banner_timeout An optional timeout (in seconds) to wait for the SSH banner to be presented. .TP .B auth_timeout An optional timeout (in seconds) to wait for an authentication response. .TP .B auto_add_policy: \fBFalse\fP Automatically add the host to the \fBknown_hosts\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.scp_get /var/tmp/file /tmp/file auto_add_policy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_mod.scp_put(files, remote_path=None, recursive=False, preserve_times=False, saltenv=\(aqbase\(aq, **kwargs) New in version 2019.2.0. .sp Transfer files and directories to remote network device. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function is only available only when the underlying library \fI\%scp\fP is installed. See \fI\%scp module\fP for more details. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B files A single path or a list of paths to be transferred. .TP .B remote_path The path on the remote device where to store the files. .TP .B recursive: \fBTrue\fP Transfer files and directories recursively. .TP .B preserve_times: \fBFalse\fP Preserve \fBmtime\fP and \fBatime\fP of transferred files and directories. .TP .B saltenv: \fBbase\fP The name of the Salt environment. Ignored when \fBfiles\fP is not a \fBsalt://\fP URL. .TP .B hostname The hostname of the remote device. .TP .B port: \fB22\fP The port of the remote device. .TP .B username The username required for SSH authentication on the device. .TP .B password Used for password authentication. It is also used for private key decryption if \fBpassphrase\fP is not given. .TP .B passphrase Used for decrypting private keys. .TP .B pkey An optional private key to use for authentication. .TP .B key_filename The filename, or list of filenames, of optional private key(s) and/or certificates to try for authentication. .TP .B timeout An optional timeout (in seconds) for the TCP connect. .TP .B socket_timeout: \fB10\fP The channel socket timeout in seconds. .TP .B buff_size: \fB16384\fP The size of the SCP send buffer. .TP .B allow_agent: \fBTrue\fP Set to \fBFalse\fP to disable connecting to the SSH agent. .TP .B look_for_keys: \fBTrue\fP Set to \fBFalse\fP to disable searching for discoverable private key files in \fB~/.ssh/\fP .TP .B banner_timeout An optional timeout (in seconds) to wait for the SSH banner to be presented. .TP .B auth_timeout An optional timeout (in seconds) to wait for an authentication response. .TP .B auto_add_policy: \fBFalse\fP Automatically add the host to the \fBknown_hosts\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm.scp_put /path/to/file /var/tmp/file auto_add_policy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.napalm_netacl .SS NAPALM ACL .sp Generate and load ACL (firewall) configuration on network devices. .sp New in version 2017.7.0. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> .TP .B maturity new .TP .B depends capirca, napalm .TP .B platform unix .UNINDENT .SS Dependencies .sp The firewall configuration is generated by \fI\%Capirca\fP\&. .sp To install Capirca, execute: \fBpip install capirca\fP\&. .sp To be able to load configuration on network devices, it requires \fI\%NAPALM\fP library to be installed: \fBpip install napalm\fP\&. Please check \fI\%Installation\fP for complete details. .INDENT 0.0 .TP .B salt.modules.napalm_netacl.get_filter_pillar(filter_name, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None) Helper that can be used inside a state SLS, in order to get the filter configuration given its name. .INDENT 7.0 .TP .B filter_name The name of the filter. .TP .B pillar_key The root key of the whole policy config. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_netacl.get_term_pillar(filter_name, term_name, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None) Helper that can be used inside a state SLS, in order to get the term configuration given its name, under a certain filter uniquely identified by its name. .INDENT 7.0 .TP .B filter_name The name of the filter. .TP .B term_name The name of the term. .TP .B pillar_key: \fBacl\fP The root key of the whole policy config. Default: \fBacl\fP\&. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_netacl.load_filter_config(filter_name, filter_options=None, terms=None, prepend=True, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None, merge_pillar=True, only_lower_merge=False, revision_id=None, revision_no=None, revision_date=True, revision_date_format=\(aq%Y/%m/%d\(aq, test=False, commit=True, debug=False, **kwargs) Generate and load the configuration of a policy filter. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The order of the terms is very important. The configuration loaded on the device respects the order defined in the \fBterms\fP and/or inside the pillar. .sp When merging the \fBterms\fP with the pillar data, consider the \fBprepend\fP argument to make sure the order is correct! .UNINDENT .UNINDENT .INDENT 7.0 .TP .B filter_name The name of the policy filter. .TP .B filter_options Additional filter options. These options are platform\-specific. See the complete list of \fI\%options\fP\&. .TP .B terms List of terms for this policy filter. If not specified or empty, will try to load the configuration from the pillar, unless \fBmerge_pillar\fP is set as \fBFalse\fP\&. .TP .B prepend: \fBTrue\fP When \fBmerge_pillar\fP is set as \fBTrue\fP, the final list of terms generated by merging the terms from \fBterms\fP with those defined in the pillar (if any): new terms are prepended at the beginning, while existing ones will preserve the position. To add the new terms at the end of the list, set this argument to \fBFalse\fP\&. .TP .B pillar_key: \fBacl\fP The key in the pillar containing the default attributes values. Default: \fBacl\fP\&. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .TP .B merge_pillar: \fBTrue\fP Merge the CLI variables with the pillar. Default: \fBTrue\fP\&. .sp The merge logic depends on the \fBprepend\fP argument and the CLI has higher priority than the pillar. .TP .B only_lower_merge: \fBFalse\fP Specify if it should merge only the terms fields. Otherwise it will try to merge also filters fields. Default: \fBFalse\fP\&. This option requires \fBmerge_pillar\fP, otherwise it is ignored. .TP .B revision_id Add a comment in the filter config having the description for the changes applied. .TP .B revision_no The revision count. .TP .B revision_date: \fBTrue\fP Boolean flag: display the date when the filter configuration was generated. Default: \fBTrue\fP\&. .TP .B revision_date_format: \fB%Y/%m/%d\fP The date format to be used when generating the perforce data. Default: \fB%Y/%m/%d\fP (<year>/<month>/<day>). .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: \fBTrue\fP Commit? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key under the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .UNINDENT .sp The output is a dictionary having the same form as \fI\%net.load_config\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqedge01.bjm01\(aq netacl.load_filter_config my\-filter pillar_key=netacl debug=True .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C edge01.bjm01: \-\-\-\-\-\-\-\-\-\- already_configured: False comment: diff: [edit firewall] + family inet { + /* + ** $Date: 2017/03/22 $ + ** + */ + filter my\-filter { + interface\-specific; + term my\-term { + from { + source\-port [ 1234 1235 ]; + } + then { + reject; + } + } + term my\-other\-term { + from { + protocol tcp; + source\-port 5678\-5680; + } + then accept; + } + } + } loaded_config: firewall { family inet { replace: /* ** $Date: 2017/03/22 $ ** */ filter my\-filter { interface\-specific; term my\-term { from { source\-port [ 1234 1235 ]; } then { reject; } } term my\-other\-term { from { protocol tcp; source\-port 5678\-5680; } then accept; } } } } result: True .ft P .fi .UNINDENT .UNINDENT .sp The filter configuration has been loaded from the pillar, having the following structure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C netacl: \- my\-filter: terms: \- my\-term: source_port: \- 1234 \- 1235 action: reject \- my\-other\-term: source_port: \- \- 5678 \- 5680 protocol: tcp action: accept .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_netacl.load_policy_config(filters=None, prepend=True, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None, merge_pillar=True, only_lower_merge=False, revision_id=None, revision_no=None, revision_date=True, revision_date_format=\(aq%Y/%m/%d\(aq, test=False, commit=True, debug=False, **kwargs) Generate and load the configuration of the whole policy. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The order of the filters and their terms is very important. The configuration loaded on the device respects the order defined in the \fBfilters\fP and/or inside the pillar. .sp When merging the \fBfilters\fP with the pillar data, consider the \fBprepend\fP argument to make sure the order is correct! .UNINDENT .UNINDENT .INDENT 7.0 .TP .B filters List of filters for this policy. If not specified or empty, will try to load the configuration from the pillar, unless \fBmerge_pillar\fP is set as \fBFalse\fP\&. .TP .B prepend: \fBTrue\fP When \fBmerge_pillar\fP is set as \fBTrue\fP, the final list of filters generated by merging the filters from \fBfilters\fP with those defined in the pillar (if any): new filters are prepended at the beginning, while existing ones will preserve the position. To add the new filters at the end of the list, set this argument to \fBFalse\fP\&. .TP .B pillar_key: \fBacl\fP The key in the pillar containing the default attributes values. Default: \fBacl\fP\&. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .TP .B merge_pillar: \fBTrue\fP Merge the CLI variables with the pillar. Default: \fBTrue\fP\&. .sp The merge logic depends on the \fBprepend\fP argument and the CLI has higher priority than the pillar. .TP .B only_lower_merge: \fBFalse\fP Specify if it should merge only the filters and terms fields. Otherwise it will try to merge everything at the policy level. Default: \fBFalse\fP\&. This option requires \fBmerge_pillar\fP, otherwise it is ignored. .TP .B revision_id Add a comment in the policy config having the description for the changes applied. .TP .B revision_no The revision count. .TP .B revision_date: \fBTrue\fP Boolean flag: display the date when the policy configuration was generated. Default: \fBTrue\fP\&. .TP .B revision_date_format: \fB%Y/%m/%d\fP The date format to be used when generating the perforce data. Default: \fB%Y/%m/%d\fP (<year>/<month>/<day>). .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: \fBTrue\fP Commit? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key under the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .UNINDENT .sp The output is a dictionary having the same form as \fI\%net.load_config\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqedge01.flw01\(aq netacl.load_policy_config debug=True .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C edge01.flw01: \-\-\-\-\-\-\-\-\-\- already_configured: False comment: diff: \-\-\- +++ @@ \-1228,9 +1228,24 @@ ! +ipv4 access\-list my\-filter + 10 remark my\-term + 20 deny tcp host 1.2.3.4 eq 1234 any + 30 deny udp host 1.2.3.4 eq 1234 any + 40 deny tcp host 1.2.3.4 eq 1235 any + 50 deny udp host 1.2.3.4 eq 1235 any + 60 remark my\-other\-term + 70 permit tcp any range 5678 5680 any +! +! +ipv4 access\-list block\-icmp + 10 remark first\-term + 20 deny icmp any any ! loaded_config: ! $Date: 2017/03/22 $ no ipv4 access\-list my\-filter ipv4 access\-list my\-filter remark my\-term deny tcp host 1.2.3.4 eq 1234 any deny udp host 1.2.3.4 eq 1234 any deny tcp host 1.2.3.4 eq 1235 any deny udp host 1.2.3.4 eq 1235 any remark my\-other\-term permit tcp any range 5678 5680 any exit no ipv4 access\-list block\-icmp ipv4 access\-list block\-icmp remark first\-term deny icmp any any exit result: True .ft P .fi .UNINDENT .UNINDENT .sp The policy configuration has been loaded from the pillar, having the following structure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C acl: \- my\-filter: terms: \- my\-term: source_port: \- 1234 \- 1235 protocol: \- tcp \- udp source_address: 1.2.3.4 action: reject \- my\-other\-term: source_port: \- [5678, 5680] protocol: tcp action: accept \- block\-icmp: terms: \- first\-term: protocol: \- icmp action: reject .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_netacl.load_term_config(filter_name, term_name, filter_options=None, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None, merge_pillar=True, revision_id=None, revision_no=None, revision_date=True, revision_date_format=\(aq%Y/%m/%d\(aq, test=False, commit=True, debug=False, source_service=None, destination_service=None, **term_fields) Generate and load the configuration of a policy term. .INDENT 7.0 .TP .B filter_name The name of the policy filter. .TP .B term_name The name of the term. .TP .B filter_options Additional filter options. These options are platform\-specific. See the complete list of \fI\%options\fP\&. .TP .B pillar_key: \fBacl\fP The key in the pillar containing the default attributes values. Default: \fBacl\fP\&. If the pillar contains the following structure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C firewall: \- my\-filter: terms: \- my\-term: source_port: 1234 source_address: \- 1.2.3.4/32 \- 5.6.7.8/32 .ft P .fi .UNINDENT .UNINDENT .sp The \fBpillar_key\fP field would be specified as \fBfirewall\fP\&. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .TP .B merge_pillar: \fBTrue\fP Merge the CLI variables with the pillar. Default: \fBTrue\fP\&. .sp The properties specified through the CLI have higher priority than the pillar. .TP .B revision_id Add a comment in the term config having the description for the changes applied. .TP .B revision_no The revision count. .TP .B revision_date: \fBTrue\fP Boolean flag: display the date when the term configuration was generated. Default: \fBTrue\fP\&. .TP .B revision_date_format: \fB%Y/%m/%d\fP The date format to be used when generating the perforce data. Default: \fB%Y/%m/%d\fP (<year>/<month>/<day>). .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: \fBTrue\fP Commit? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key under the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .TP .B source_service A special service to choose from. This is a helper so the user is able to select a source just using the name, instead of specifying a source_port and protocol. .sp As this module is available on Unix platforms only, it reads the \fI\%IANA\fP port assignment from /etc/services. .sp If the user requires additional shortcuts to be referenced, they can add entries under /etc/services, which can be managed using the \fI\%file state\fP\&. .TP .B destination_service A special service to choose from. This is a helper so the user is able to select a source just using the name, instead of specifying a destination_port and protocol. Allows the same options as \fBsource_service\fP\&. .TP .B term_fields Term attributes. To see what fields are supported, please consult the list of supported \fI\%keywords\fP\&. Some platforms have a few other \fI\%optional\fP keywords. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The following fields are accepted (some being platform\-specific): .INDENT 0.0 .IP \(bu 2 action .IP \(bu 2 address .IP \(bu 2 address_exclude .IP \(bu 2 comment .IP \(bu 2 counter .IP \(bu 2 expiration .IP \(bu 2 destination_address .IP \(bu 2 destination_address_exclude .IP \(bu 2 destination_port .IP \(bu 2 destination_prefix .IP \(bu 2 forwarding_class .IP \(bu 2 forwarding_class_except .IP \(bu 2 logging .IP \(bu 2 log_name .IP \(bu 2 loss_priority .IP \(bu 2 option .IP \(bu 2 policer .IP \(bu 2 port .IP \(bu 2 precedence .IP \(bu 2 principals .IP \(bu 2 protocol .IP \(bu 2 protocol_except .IP \(bu 2 qos .IP \(bu 2 pan_application .IP \(bu 2 routing_instance .IP \(bu 2 source_address .IP \(bu 2 source_address_exclude .IP \(bu 2 source_port .IP \(bu 2 source_prefix .IP \(bu 2 verbatim .IP \(bu 2 packet_length .IP \(bu 2 fragment_offset .IP \(bu 2 hop_limit .IP \(bu 2 icmp_type .IP \(bu 2 ether_type .IP \(bu 2 traffic_class_count .IP \(bu 2 traffic_type .IP \(bu 2 translated .IP \(bu 2 dscp_set .IP \(bu 2 dscp_match .IP \(bu 2 dscp_except .IP \(bu 2 next_ip .IP \(bu 2 flexible_match_range .IP \(bu 2 source_prefix_except .IP \(bu 2 destination_prefix_except .IP \(bu 2 vpn .IP \(bu 2 source_tag .IP \(bu 2 destination_tag .IP \(bu 2 source_interface .IP \(bu 2 destination_interface .IP \(bu 2 flattened .IP \(bu 2 flattened_addr .IP \(bu 2 flattened_saddr .IP \(bu 2 flattened_daddr .IP \(bu 2 priority .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The following fields can be also a single value and a list of values: .INDENT 0.0 .IP \(bu 2 action .IP \(bu 2 address .IP \(bu 2 address_exclude .IP \(bu 2 comment .IP \(bu 2 destination_address .IP \(bu 2 destination_address_exclude .IP \(bu 2 destination_port .IP \(bu 2 destination_prefix .IP \(bu 2 forwarding_class .IP \(bu 2 forwarding_class_except .IP \(bu 2 logging .IP \(bu 2 option .IP \(bu 2 port .IP \(bu 2 precedence .IP \(bu 2 principals .IP \(bu 2 protocol .IP \(bu 2 protocol_except .IP \(bu 2 pan_application .IP \(bu 2 source_address .IP \(bu 2 source_address_exclude .IP \(bu 2 source_port .IP \(bu 2 source_prefix .IP \(bu 2 verbatim .IP \(bu 2 icmp_type .IP \(bu 2 ether_type .IP \(bu 2 traffic_type .IP \(bu 2 dscp_match .IP \(bu 2 dscp_except .IP \(bu 2 flexible_match_range .IP \(bu 2 source_prefix_except .IP \(bu 2 destination_prefix_except .IP \(bu 2 source_tag .IP \(bu 2 destination_tag .IP \(bu 2 source_service .IP \(bu 2 destination_service .UNINDENT .sp Example: \fBdestination_address\fP can be either defined as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C destination_address: 172.17.17.1/24 .ft P .fi .UNINDENT .UNINDENT .sp or as a list of destination IP addresses: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C destination_address: \- 172.17.17.1/24 \- 172.17.19.1/24 .ft P .fi .UNINDENT .UNINDENT .sp or a list of services to be matched: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source_service: \- ntp \- snmp \- ldap \- bgpd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The port fields \fBsource_port\fP and \fBdestination_port\fP can be used as above to select either a single value, either a list of values, but also they can select port ranges. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source_port: \- \- 1000 \- 2000 \- \- 3000 \- 4000 .ft P .fi .UNINDENT .UNINDENT .sp With the configuration above, the user is able to select the 1000\-2000 and 3000\-4000 source port ranges. .UNINDENT .UNINDENT .sp The output is a dictionary having the same form as \fI\%net.load_config\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqedge01.bjm01\(aq netacl.load_term_config filter\-name term\-name source_address=1.2.3.4 destination_address=5.6.7.8 action=accept test=True debug=True .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C edge01.bjm01: \-\-\-\-\-\-\-\-\-\- already_configured: False comment: Configuration discarded. diff: [edit firewall] + family inet { + /* + ** $Date: 2017/03/22 $ + ** + */ + filter filter\-name { + interface\-specific; + term term\-name { + from { + source\-address { + 1.2.3.4/32; + } + destination\-address { + 5.6.7.8/32; + } + } + then accept; + } + } + } loaded_config: firewall { family inet { replace: /* ** $Date: 2017/03/22 $ ** */ filter filter\-name { interface\-specific; term term\-name { from { source\-address { 1.2.3.4/32; } destination\-address { 5.6.7.8/32; } } then accept; } } } } result: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.napalm_network .SS NAPALM Network .sp Basic methods for interaction with the network device through the virtual proxy \(aqnapalm\(aq. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> & Jerome Fleury <\fI\%jf@cloudflare.com\fP> .TP .B maturity new .TP .B depends napalm .TP .B platform unix .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 \fI\%napalm proxy minion\fP .UNINDENT .sp New in version 2016.11.0. .sp Changed in version 2017.7.0. .INDENT 0.0 .TP .B salt.modules.napalm_network.arp(interface=\(aq\(aq, ipaddr=\(aq\(aq, macaddr=\(aq\(aq, **kwargs) NAPALM returns a list of dictionaries with details of the ARP entries. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBinterface\fP \-\- interface name to filter on .IP \(bu 2 \fBipaddr\fP \-\- IP address to filter on .IP \(bu 2 \fBmacaddr\fP \-\- MAC address to filter on .UNINDENT .TP .B Returns List of the entries in the ARP table .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.arp salt \(aq*\(aq net.arp macaddr=\(aq5c:5e:ab:da:3c:f0\(aq .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ { \(aqinterface\(aq : \(aqMgmtEth0/RSP0/CPU0/0\(aq, \(aqmac\(aq : \(aq5c:5e:ab:da:3c:f0\(aq, \(aqip\(aq : \(aq172.17.17.1\(aq, \(aqage\(aq : 1454496274.84 }, { \(aqinterface\(aq: \(aqMgmtEth0/RSP0/CPU0/0\(aq, \(aqmac\(aq : \(aq66:0e:94:96:e0:ff\(aq, \(aqip\(aq : \(aq172.17.17.2\(aq, \(aqage\(aq : 1435641582.49 } ] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.blockreplace(marker_start, marker_end, content=\(aq\(aq, append_if_not_found=False, prepend_if_not_found=False, show_changes=True, append_newline=False, source=\(aqrunning\(aq, path=None, test=False, commit=True, debug=False, replace=True) New in version 2019.2.0. .sp Replace content of the configuration source, delimited by the line markers. .sp A block of content delimited by comments can help you manage several lines without worrying about old entries removal. .INDENT 7.0 .TP .B marker_start The line content identifying a line as the start of the content block. Note that the whole line containing this marker will be considered, so whitespace or extra content before or after the marker is included in final output. .TP .B marker_end The line content identifying a line as the end of the content block. Note that the whole line containing this marker will be considered, so whitespace or extra content before or after the marker is included in final output. .TP .B content The content to be used between the two lines identified by \fBmarker_start\fP and \fBmarker_stop\fP\&. .TP .B append_if_not_found: \fBFalse\fP If markers are not found and set to True then, the markers and content will be appended to the file. .TP .B prepend_if_not_found: \fBFalse\fP If markers are not found and set to True then, the markers and content will be prepended to the file. .TP .B append_newline: \fBFalse\fP Controls whether or not a newline is appended to the content block. If the value of this argument is \fBTrue\fP then a newline will be added to the content block. If it is \fBFalse\fP, then a newline will not be added to the content block. If it is \fBNone\fP then a newline will only be added to the content block if it does not already end in a newline. .TP .B show_changes: \fBTrue\fP Controls how changes are presented. If \fBTrue\fP, this function will return the of the changes made. If \fBFalse\fP, then it will return a boolean (\fBTrue\fP if any changes were made, otherwise False). .TP .B source: \fBrunning\fP The configuration source. Choose from: \fBrunning\fP, \fBcandidate\fP, or \fBstartup\fP\&. Default: \fBrunning\fP\&. .TP .B path: \fBNone\fP Save the temporary configuration to a specific path, then read from there. This argument is optional, can be used when you prefers a particular location of the temporary file. .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: \fBTrue\fP Commit the configuration changes? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key in the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .TP .B replace: \fBTrue\fP Load and replace the configuration. Default: \fBTrue\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.blockreplace \(aqntp\(aq \(aqinterface\(aq \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.cancel_commit(jid) New in version 2019.2.0. .sp Cancel a commit scheduled to be executed via the \fBcommit_in\fP and \fBcommit_at\fP arguments from the \fI\%net.load_template\fP or \fI\%net.load_config\fP execution functions. The commit ID is displayed when the commit is scheduled via the functions named above. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.cancel_commit 20180726083540640360 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.cli(*commands, **kwargs) Returns a dictionary with the raw output of all commands passed as arguments. .INDENT 7.0 .TP .B commands List of commands to be executed on the device. .TP .B textfsm_parse: \fBFalse\fP Try parsing the outputs using the TextFSM templates. .sp New in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option can be also specified in the minion configuration file or pillar as \fBnapalm_cli_textfsm_parse\fP\&. .UNINDENT .UNINDENT .TP .B textfsm_path The path where the TextFSM templates can be found. This option implies the usage of the TextFSM index file. \fBtextfsm_path\fP can be either absolute path on the server, either specified using the following URL mschemes: \fBfile://\fP, \fBsalt://\fP, \fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP, \fBs3://\fP, \fBswift://\fP\&. .sp New in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This needs to be a directory with a flat structure, having an index file (whose name can be specified using the \fBindex_file\fP option) and a number of TextFSM templates. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option can be also specified in the minion configuration file or pillar as \fBtextfsm_path\fP\&. .UNINDENT .UNINDENT .TP .B textfsm_template The path to a certain the TextFSM template. 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 template 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 .sp New in version 2018.3.0. .TP .B textfsm_template_dict A dictionary with the mapping between a command and the corresponding TextFSM path to use to extract the data. The TextFSM paths can be specified as in \fBtextfsm_template\fP\&. .sp New in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option can be also specified in the minion configuration file or pillar as \fBnapalm_cli_textfsm_template_dict\fP\&. .UNINDENT .UNINDENT .TP .B platform_grain_name: \fBos\fP The name of the grain used to identify the platform name in the TextFSM index file. Default: \fBos\fP\&. .sp New in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option can be also specified in the minion configuration file or pillar as \fBtextfsm_platform_grain\fP\&. .UNINDENT .UNINDENT .TP .B platform_column_name: \fBPlatform\fP The column name used to identify the platform, exactly as specified in the TextFSM index file. Default: \fBPlatform\fP\&. .sp New in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is field is case sensitive, make sure to assign the correct value to this option, exactly as defined in the index file. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option can be also specified in the minion configuration file or pillar as \fBtextfsm_platform_column_name\fP\&. .UNINDENT .UNINDENT .TP .B index_file: \fBindex\fP The name of the TextFSM index file, under the \fBtextfsm_path\fP\&. Default: \fBindex\fP\&. .sp New in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option can be also specified in the minion configuration file or pillar as \fBtextfsm_index_file\fP\&. .UNINDENT .UNINDENT .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBtextfsm_path\fP is not a \fBsalt://\fP URL. .sp New in version 2018.3.0. .TP .B include_empty: \fBFalse\fP Include empty files under the \fBtextfsm_path\fP\&. .sp New in version 2018.3.0. .TP .B include_pat Glob or regex to narrow down the files cached from the given path. If matching with a regex, the regex must be prefixed with \fBE@\fP, otherwise the expression will be interpreted as a glob. .sp New in version 2018.3.0. .TP .B exclude_pat Glob or regex to exclude certain files from being cached from the given path. If matching with a regex, the regex must be prefixed with \fBE@\fP, otherwise the expression will be interpreted as a glob. .sp New in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If used with \fBinclude_pat\fP, files matching this pattern will be excluded from the subset of files defined by \fBinclude_pat\fP\&. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.cli \(dqshow version\(dq \(dqshow chassis fan\(dq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example with TextFSM template: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.cli textfsm_parse=True textfsm_path=salt://textfsm/ .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqshow version and haiku\(aq: \(aqHostname: re0.edge01.arn01 Model: mx480 Junos: 13.3R6.5 Help me, Obi\-Wan I just saw Episode Two You\(aqre my only hope \(aq, \(aqshow chassis fan\(aq : \(aqItem Status RPM Measurement Top Rear Fan OK 3840 Spinning at intermediate\-speed Bottom Rear Fan OK 3840 Spinning at intermediate\-speed Top Middle Fan OK 3900 Spinning at intermediate\-speed Bottom Middle Fan OK 3840 Spinning at intermediate\-speed Top Front Fan OK 3810 Spinning at intermediate\-speed Bottom Front Fan OK 3840 Spinning at intermediate\-speed \(aq } .ft P .fi .UNINDENT .UNINDENT .sp Example output with TextFSM parsing: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(dqcomment\(dq: \(dq\(dq, \(dqresult\(dq: true, \(dqout\(dq: { \(dqsh ver\(dq: [ { \(dqkernel\(dq: \(dq9.1S3.5\(dq, \(dqdocumentation\(dq: \(dq9.1S3.5\(dq, \(dqboot\(dq: \(dq9.1S3.5\(dq, \(dqcrypto\(dq: \(dq9.1S3.5\(dq, \(dqchassis\(dq: \(dq\(dq, \(dqrouting\(dq: \(dq9.1S3.5\(dq, \(dqbase\(dq: \(dq9.1S3.5\(dq, \(dqmodel\(dq: \(dqmx960\(dq } ] } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.commit(inherit_napalm_device=None, **kwargs) Commits the configuration changes made on the network device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.commit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.compare_config(inherit_napalm_device=None, **kwargs) Returns the difference between the running config and the candidate config. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.compare_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.config(source=None, **kwargs) New in version 2017.7.0. .sp Return the whole configuration of the network device. By default, it will return all possible configuration sources supported by the network device. At most, there will be: .INDENT 7.0 .IP \(bu 2 running config .IP \(bu 2 startup config .IP \(bu 2 candidate config .UNINDENT .sp To return only one of the configurations, you can use the \fBsource\fP argument. .INDENT 7.0 .TP .B source Which configuration type you want to display, default is all of them. .sp Options: .INDENT 7.0 .IP \(bu 2 running .IP \(bu 2 candidate .IP \(bu 2 startup .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns The object returned is a dictionary with the following keys: .INDENT 7.0 .IP \(bu 2 running (string): Representation of the native running configuration. .IP \(bu 2 .INDENT 2.0 .TP .B candidate (string): Representation of the native candidate configuration. If the device doesn\(aqt differentiate between running and startup configuration this will an empty string. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B startup (string): Representation of the native startup configuration. If the device doesn\(aqt differentiate between running and startup configuration this will an empty string. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.config salt \(aq*\(aq net.config source=candidate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.config_changed(inherit_napalm_device=None, **kwargs) Will prompt if the configuration has been changed. .INDENT 7.0 .TP .B Returns A tuple with a boolean that specifies if the config was changed on the device. And a string that provides more details of the reason why the configuration was not changed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.config_changed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.config_control(inherit_napalm_device=None, **kwargs) Will check if the configuration was changed. If differences found, will try to commit. In case commit unsuccessful, will try to rollback. .INDENT 7.0 .TP .B Returns A tuple with a boolean that specifies if the config was changed/committed/rollbacked on the device. And a string that provides more details of the reason why the configuration was not committed properly. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.config_control .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.confirm_commit(jid) New in version 2019.2.0. .sp Confirm a commit scheduled to be reverted via the \fBrevert_in\fP and \fBrevert_at\fP arguments from the \fI\%net.load_template\fP or \fI\%net.load_config\fP execution functions. The commit ID is displayed when the commit confirmed is scheduled via the functions named above. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.confirm_commit 20180726083540640360 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.connected(**kwargs) Specifies if the connection to the device succeeded. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.connected .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.discard_config(inherit_napalm_device=None, **kwargs) Discards the changes applied. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.discard_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.environment(**kwargs) Returns the environment of the device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.environment .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqfans\(aq: { \(aqBottom Rear Fan\(aq: { \(aqstatus\(aq: True }, \(aqBottom Middle Fan\(aq: { \(aqstatus\(aq: True }, \(aqTop Middle Fan\(aq: { \(aqstatus\(aq: True }, \(aqBottom Front Fan\(aq: { \(aqstatus\(aq: True }, \(aqTop Front Fan\(aq: { \(aqstatus\(aq: True }, \(aqTop Rear Fan\(aq: { \(aqstatus\(aq: True } }, \(aqmemory\(aq: { \(aqavailable_ram\(aq: 16349, \(aqused_ram\(aq: 4934 }, \(aqtemperature\(aq: { \(aqFPC 0 Exhaust A\(aq: { \(aqis_alert\(aq: False, \(aqtemperature\(aq: 35.0, \(aqis_critical\(aq: False } }, \(aqcpu\(aq: { \(aq1\(aq: { \(aq%usage\(aq: 19.0 }, \(aq0\(aq: { \(aq%usage\(aq: 35.0 } } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.facts(**kwargs) Returns characteristics of the network device. :return: a dictionary with the following keys: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 uptime \- Uptime of the device in seconds. .IP \(bu 2 vendor \- Manufacturer of the device. .IP \(bu 2 model \- Device model. .IP \(bu 2 hostname \- Hostname of the device .IP \(bu 2 fqdn \- Fqdn of the device .IP \(bu 2 os_version \- String with the OS version running on the device. .IP \(bu 2 serial_number \- Serial number of the device .IP \(bu 2 interface_list \- List of the interfaces of the device .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.facts .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqos_version\(aq: \(aq13.3R6.5\(aq, \(aquptime\(aq: 10117140, \(aqinterface_list\(aq: [ \(aqlc\-0/0/0\(aq, \(aqpfe\-0/0/0\(aq, \(aqpfh\-0/0/0\(aq, \(aqxe\-0/0/0\(aq, \(aqxe\-0/0/1\(aq, \(aqxe\-0/0/2\(aq, \(aqxe\-0/0/3\(aq, \(aqgr\-0/0/10\(aq, \(aqip\-0/0/10\(aq ], \(aqvendor\(aq: \(aqJuniper\(aq, \(aqserial_number\(aq: \(aqJN131356FBFA\(aq, \(aqmodel\(aq: \(aqMX480\(aq, \(aqhostname\(aq: \(aqre0.edge05.syd01\(aq, \(aqfqdn\(aq: \(aqre0.edge05.syd01\(aq } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.interfaces(**kwargs) Returns details of the interfaces on the device. .INDENT 7.0 .TP .B Returns Returns a dictionary of dictionaries. The keys for the first dictionary will be the interfaces in the devices. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.interfaces .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqManagement1\(aq: { \(aqis_up\(aq: False, \(aqis_enabled\(aq: False, \(aqdescription\(aq: \(aq\(aq, \(aqlast_flapped\(aq: \-1, \(aqspeed\(aq: 1000, \(aqmac_address\(aq: \(aqdead:beef:dead\(aq, }, \(aqEthernet1\(aq:{ \(aqis_up\(aq: True, \(aqis_enabled\(aq: True, \(aqdescription\(aq: \(aqfoo\(aq, \(aqlast_flapped\(aq: 1429978575.1554043, \(aqspeed\(aq: 1000, \(aqmac_address\(aq: \(aqbeef:dead:beef\(aq, } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.ipaddrs(**kwargs) Returns IP addresses configured on the device. .INDENT 7.0 .TP .B Returns A dictionary with the IPv4 and IPv6 addresses of the interfaces. Returns all configured IP addresses on all interfaces as a dictionary of dictionaries. Keys of the main dictionary represent the name of the interface. Values of the main dictionary represent are dictionaries that may consist of two keys \(aqipv4\(aq and \(aqipv6\(aq (one, both or none) which are themselvs dictionaries with the IP addresses as keys. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.ipaddrs .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqFastEthernet8\(aq: { \(aqipv4\(aq: { \(aq10.66.43.169\(aq: { \(aqprefix_length\(aq: 22 } } }, \(aqLoopback555\(aq: { \(aqipv4\(aq: { \(aq192.168.1.1\(aq: { \(aqprefix_length\(aq: 24 } }, \(aqipv6\(aq: { \(aq1::1\(aq: { \(aqprefix_length\(aq: 64 }, \(aq2001:DB8:1::1\(aq: { \(aqprefix_length\(aq: 64 }, \(aqFE80::3\(aq: { \(aqprefix_length\(aq: \(aqN/A\(aq } } } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.lldp(interface=\(aq\(aq, **kwargs) Returns a detailed view of the LLDP neighbors. .INDENT 7.0 .TP .B Parameters \fBinterface\fP \-\- interface name to filter on .TP .B Returns A dictionary with the LLDL neighbors. The keys are the interfaces with LLDP activated on. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.lldp salt \(aq*\(aq net.lldp interface=\(aqTenGigE0/0/0/8\(aq .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqTenGigE0/0/0/8\(aq: [ { \(aqparent_interface\(aq: \(aqBundle\-Ether8\(aq, \(aqinterface_description\(aq: \(aqTenGigE0/0/0/8\(aq, \(aqremote_chassis_id\(aq: \(aq8c60.4f69.e96c\(aq, \(aqremote_system_name\(aq: \(aqswitch\(aq, \(aqremote_port\(aq: \(aqEth2/2/1\(aq, \(aqremote_port_description\(aq: \(aqEthernet2/2/1\(aq, \(aqremote_system_description\(aq: \(aqCisco Nexus Operating System (NX\-OS) Software 7.1(0)N1(1a) TAC support: http://www.cisco.com/tac Copyright (c) 2002\-2015, Cisco Systems, Inc. All rights reserved.\(aq, \(aqremote_system_capab\(aq: \(aqB, R\(aq, \(aqremote_system_enable_capab\(aq: \(aqB\(aq } ] } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.load_config(filename=None, text=None, test=False, commit=True, debug=False, replace=False, commit_in=None, commit_at=None, revert_in=None, revert_at=None, commit_jid=None, inherit_napalm_device=None, saltenv=\(aqbase\(aq, **kwargs) Applies configuration changes on the device. It can be loaded from a file or from inline string. If you send both a filename and a string containing the configuration, the file has higher precedence. .sp By default this function will commit the changes. If there are no changes, it does not commit and the flag \fBalready_configured\fP will be set as \fBTrue\fP to point this out. .sp To avoid committing the configuration, set the argument \fBtest\fP to \fBTrue\fP and will discard (dry run). .sp To keep the changes but not commit, set \fBcommit\fP to \fBFalse\fP\&. .sp To replace the config, set \fBreplace\fP to \fBTrue\fP\&. .INDENT 7.0 .TP .B filename Path to the file containing the desired configuration. 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 template 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 .sp Changed in version 2018.3.0. .TP .B text String containing the desired configuration. This argument is ignored when \fBfilename\fP is specified. .TP .B test: False Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: True Commit? Default: \fBTrue\fP\&. .TP .B debug: False Debug mode. Will insert a new key under the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .sp New in version 2016.11.2. .TP .B replace: False Load and replace the configuration. Default: \fBFalse\fP\&. .sp New in version 2016.11.2. .TP .B commit_in: \fBNone\fP Commit the changes in a specific number of minutes / hours. Example of accepted formats: \fB5\fP (commit in 5 minutes), \fB2m\fP (commit in 2 minutes), \fB1h\fP (commit the changes in 1 hour)\(ga, \fB5h30m\fP (commit the changes in 5 hours and 30 minutes). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This feature works on any platforms, as it does not rely on the native features of the network operating system. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 After the command is executed and the \fBdiff\fP is not satisfactory, or for any other reasons you have to discard the commit, you are able to do so using the \fI\%net.cancel_commit\fP execution function, using the commit ID returned by this function. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Using this feature, Salt will load the exact configuration you expect, however the diff may change in time (i.e., if an user applies a manual configuration change, or a different process or command changes the configuration in the meanwhile). .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B commit_at: \fBNone\fP Commit the changes at a specific time. Example of accepted formats: \fB1am\fP (will commit the changes at the next 1AM), \fB13:20\fP (will commit at 13:20), \fB1:20am\fP, etc. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This feature works on any platforms, as it does not rely on the native features of the network operating system. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 After the command is executed and the \fBdiff\fP is not satisfactory, or for any other reasons you have to discard the commit, you are able to do so using the \fI\%net.cancel_commit\fP execution function, using the commit ID returned by this function. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Using this feature, Salt will load the exact configuration you expect, however the diff may change in time (i.e., if an user applies a manual configuration change, or a different process or command changes the configuration in the meanwhile). .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B revert_in: \fBNone\fP Commit and revert the changes in a specific number of minutes / hours. Example of accepted formats: \fB5\fP (revert in 5 minutes), \fB2m\fP (revert in 2 minutes), \fB1h\fP (revert the changes in 1 hour)\(ga, \fB5h30m\fP (revert the changes in 5 hours and 30 minutes). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To confirm the commit, and prevent reverting the changes, you will have to execute the \fI\%net.confirm_commit\fP function, using the commit ID returned by this function. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This works on any platform, regardless if they have or don\(aqt have native capabilities to confirming a commit. However, please be \fIvery\fP cautious when using this feature: on Junos (as it is the only NAPALM core platform supporting this natively) it executes a commit confirmed as you would do from the command line. All the other platforms don\(aqt have this capability natively, therefore the revert is done via Salt. That means, your device needs to be reachable at the moment when Salt will attempt to revert your changes. Be cautious when pushing configuration changes that would prevent you reach the device. .sp Similarly, if an user or a different process apply other configuration changes in the meanwhile (between the moment you commit and till the changes are reverted), these changes would be equally reverted, as Salt cannot be aware of them. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B revert_at: \fBNone\fP Commit and revert the changes at a specific time. Example of accepted formats: \fB1am\fP (will commit and revert the changes at the next 1AM), \fB13:20\fP (will commit and revert at 13:20), \fB1:20am\fP, etc. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To confirm the commit, and prevent reverting the changes, you will have to execute the \fI\%net.confirm_commit\fP function, using the commit ID returned by this function. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This works on any platform, regardless if they have or don\(aqt have native capabilities to confirming a commit. However, please be \fIvery\fP cautious when using this feature: on Junos (as it is the only NAPALM core platform supporting this natively) it executes a commit confirmed as you would do from the command line. All the other platforms don\(aqt have this capability natively, therefore the revert is done via Salt. That means, your device needs to be reachable at the moment when Salt will attempt to revert your changes. Be cautious when pushing configuration changes that would prevent you reach the device. .sp Similarly, if an user or a different process apply other configuration changes in the meanwhile (between the moment you commit and till the changes are reverted), these changes would be equally reverted, as Salt cannot be aware of them. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B saltenv: \fBbase\fP Specifies the Salt environment name. .sp New in version 2018.3.0. .UNINDENT .INDENT 7.0 .TP .B Returns a dictionary having the following keys: .UNINDENT .INDENT 7.0 .IP \(bu 2 result (bool): if the config was applied successfully. It is \fBFalse\fP only in case of failure. In case there are no changes to be applied and successfully performs all operations it is still \fBTrue\fP and so will be the \fBalready_configured\fP flag (example below) .IP \(bu 2 comment (str): a message for the user .IP \(bu 2 already_configured (bool): flag to check if there were no changes applied .IP \(bu 2 loaded_config (str): the configuration loaded on the device. Requires \fBdebug\fP to be set as \fBTrue\fP .IP \(bu 2 diff (str): returns the config changes applied .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.load_config text=\(aqntp peer 192.168.0.1\(aq salt \(aq*\(aq net.load_config filename=\(aq/absolute/path/to/your/file\(aq salt \(aq*\(aq net.load_config filename=\(aq/absolute/path/to/your/file\(aq test=True salt \(aq*\(aq net.load_config filename=\(aq/absolute/path/to/your/file\(aq commit=False .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqcomment\(aq: \(aqConfiguration discarded.\(aq, \(aqalready_configured\(aq: False, \(aqresult\(aq: True, \(aqdiff\(aq: \(aq[edit interfaces xe\-0/0/5]+ description \(dqAdding a description\(dq;\(aq } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.load_template(template_name=None, template_source=None, context=None, defaults=None, template_engine=\(aqjinja\(aq, saltenv=\(aqbase\(aq, template_hash=None, template_hash_name=None, skip_verify=False, test=False, commit=True, debug=False, replace=False, commit_in=None, commit_at=None, revert_in=None, revert_at=None, inherit_napalm_device=None, **template_vars) Renders a configuration template (default: Jinja) and loads the result on the device. .sp By default this function will commit the changes. If there are no changes, it does not commit, discards he config and the flag \fBalready_configured\fP will be set as \fBTrue\fP to point this out. .sp To avoid committing the configuration, set the argument \fBtest\fP to \fBTrue\fP and will discard (dry run). .sp To preserve the changes, set \fBcommit\fP to \fBFalse\fP\&. However, this is recommended to be used only in exceptional cases when there are applied few consecutive states and/or configuration changes. Otherwise the user might forget that the config DB is locked and the candidate config buffer is not cleared/merged in the running config. .sp To replace the config, set \fBreplace\fP to \fBTrue\fP\&. .INDENT 7.0 .TP .B template_name Identifies path to the template source. The template can be either stored on the local machine, either remotely. The recommended location is under the \fBfile_roots\fP as specified in the master config file. For example, let\(aqs suppose the \fBfile_roots\fP is configured as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /etc/salt/states .ft P .fi .UNINDENT .UNINDENT .sp Placing the template under \fB/etc/salt/states/templates/example.jinja\fP, it can be used as \fBsalt://templates/example.jinja\fP\&. Alternatively, for local files, the user can specify the absolute path. If remotely, the source can be retrieved via \fBhttp\fP, \fBhttps\fP or \fBftp\fP\&. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBsalt://my_template.jinja\fP .IP \(bu 2 \fB/absolute/path/to/my_template.jinja\fP .IP \(bu 2 \fBhttp://example.com/template.cheetah\fP .IP \(bu 2 \fBhttps:/example.com/template.mako\fP .IP \(bu 2 \fBftp://example.com/template.py\fP .UNINDENT .sp Changed in version 2019.2.0: This argument can now support a list of templates to be rendered. The resulting configuration text is loaded at once, as a single configuration chunk. .TP .B template_source: None Inline config template to be rendered and loaded on the device. .TP .B template_hash: None Hash of the template file. Format: \fB{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\fP .sp New in version 2016.11.2. .TP .B context: None Overrides default context variables passed to the template. .sp New in version 2019.2.0. .TP .B template_hash_name: None When \fBtemplate_hash\fP refers to a remote file, this specifies the filename to look for in that file. .sp New in version 2016.11.2. .TP .B saltenv: \fBbase\fP Specifies the template environment. This will influence the relative imports inside the templates. .sp New in version 2016.11.2. .TP .B template_engine: jinja The following templates engines are supported: .INDENT 7.0 .IP \(bu 2 \fI\%cheetah\fP .IP \(bu 2 \fI\%genshi\fP .IP \(bu 2 \fI\%jinja\fP .IP \(bu 2 \fI\%mako\fP .IP \(bu 2 \fI\%py\fP .IP \(bu 2 \fI\%wempy\fP .UNINDENT .sp New in version 2016.11.2. .TP .B skip_verify: True If \fBTrue\fP, hash verification of remote file sources (\fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP) will be skipped, and the \fBsource_hash\fP argument will be ignored. .sp New in version 2016.11.2. .TP .B test: False Dry run? If set to \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: True Commit? (default: \fBTrue\fP) .TP .B debug: False Debug mode. Will insert a new key under the output dictionary, as \fBloaded_config\fP containing the raw result after the template was rendered. .sp New in version 2016.11.2. .TP .B replace: False Load and replace the configuration. .sp New in version 2016.11.2. .TP .B commit_in: \fBNone\fP Commit the changes in a specific number of minutes / hours. Example of accepted formats: \fB5\fP (commit in 5 minutes), \fB2m\fP (commit in 2 minutes), \fB1h\fP (commit the changes in 1 hour)\(ga, \fB5h30m\fP (commit the changes in 5 hours and 30 minutes). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This feature works on any platforms, as it does not rely on the native features of the network operating system. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 After the command is executed and the \fBdiff\fP is not satisfactory, or for any other reasons you have to discard the commit, you are able to do so using the \fI\%net.cancel_commit\fP execution function, using the commit ID returned by this function. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Using this feature, Salt will load the exact configuration you expect, however the diff may change in time (i.e., if an user applies a manual configuration change, or a different process or command changes the configuration in the meanwhile). .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B commit_at: \fBNone\fP Commit the changes at a specific time. Example of accepted formats: \fB1am\fP (will commit the changes at the next 1AM), \fB13:20\fP (will commit at 13:20), \fB1:20am\fP, etc. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This feature works on any platforms, as it does not rely on the native features of the network operating system. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 After the command is executed and the \fBdiff\fP is not satisfactory, or for any other reasons you have to discard the commit, you are able to do so using the \fI\%net.cancel_commit\fP execution function, using the commit ID returned by this function. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Using this feature, Salt will load the exact configuration you expect, however the diff may change in time (i.e., if an user applies a manual configuration change, or a different process or command changes the configuration in the meanwhile). .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B revert_in: \fBNone\fP Commit and revert the changes in a specific number of minutes / hours. Example of accepted formats: \fB5\fP (revert in 5 minutes), \fB2m\fP (revert in 2 minutes), \fB1h\fP (revert the changes in 1 hour)\(ga, \fB5h30m\fP (revert the changes in 5 hours and 30 minutes). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To confirm the commit, and prevent reverting the changes, you will have to execute the \fI\%net.confirm_commit\fP function, using the commit ID returned by this function. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This works on any platform, regardless if they have or don\(aqt have native capabilities to confirming a commit. However, please be \fIvery\fP cautious when using this feature: on Junos (as it is the only NAPALM core platform supporting this natively) it executes a commit confirmed as you would do from the command line. All the other platforms don\(aqt have this capability natively, therefore the revert is done via Salt. That means, your device needs to be reachable at the moment when Salt will attempt to revert your changes. Be cautious when pushing configuration changes that would prevent you reach the device. .sp Similarly, if an user or a different process apply other configuration changes in the meanwhile (between the moment you commit and till the changes are reverted), these changes would be equally reverted, as Salt cannot be aware of them. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B revert_at: \fBNone\fP Commit and revert the changes at a specific time. Example of accepted formats: \fB1am\fP (will commit and revert the changes at the next 1AM), \fB13:20\fP (will commit and revert at 13:20), \fB1:20am\fP, etc. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To confirm the commit, and prevent reverting the changes, you will have to execute the \fI\%net.confirm_commit\fP function, using the commit ID returned by this function. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This works on any platform, regardless if they have or don\(aqt have native capabilities to confirming a commit. However, please be \fIvery\fP cautious when using this feature: on Junos (as it is the only NAPALM core platform supporting this natively) it executes a commit confirmed as you would do from the command line. All the other platforms don\(aqt have this capability natively, therefore the revert is done via Salt. That means, your device needs to be reachable at the moment when Salt will attempt to revert your changes. Be cautious when pushing configuration changes that would prevent you reach the device. .sp Similarly, if an user or a different process apply other configuration changes in the meanwhile (between the moment you commit and till the changes are reverted), these changes would be equally reverted, as Salt cannot be aware of them. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B defaults: None Default variables/context passed to the template. .sp New in version 2016.11.2. .TP .B template_vars Dictionary with the arguments/context to be used when the template is rendered. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Do not explicitly specify this argument. This represents any other variable that will be sent to the template rendering system. Please see the examples below! .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 It is more recommended to use the \fBcontext\fP argument to avoid conflicts between CLI arguments and template variables. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns a dictionary having the following keys: .UNINDENT .INDENT 7.0 .IP \(bu 2 result (bool): if the config was applied successfully. It is \fBFalse\fP only in case of failure. In case there are no changes to be applied and successfully performs all operations it is still \fBTrue\fP and so will be the \fBalready_configured\fP flag (example below) .IP \(bu 2 comment (str): a message for the user .IP \(bu 2 already_configured (bool): flag to check if there were no changes applied .IP \(bu 2 loaded_config (str): the configuration loaded on the device, after rendering the template. Requires \fBdebug\fP to be set as \fBTrue\fP .IP \(bu 2 diff (str): returns the config changes applied .UNINDENT .sp The template can use variables from the \fBgrains\fP, \fBpillar\fP or \fBopts\fP, for example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set router_model = grains.get(\(aqmodel\(aq) \-%} {% set router_vendor = grains.get(\(aqvendor\(aq) \-%} {% set os_version = grains.get(\(aqversion\(aq) \-%} {% set hostname = pillar.get(\(aqproxy\(aq, {}).get(\(aqhost\(aq) \-%} {% if router_vendor|lower == \(aqjuniper\(aq %} system { host\-name {{hostname}}; } {% elif router_vendor|lower == \(aqcisco\(aq %} hostname {{hostname}} {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.load_template set_ntp_peers peers=[192.168.0.1] # uses NAPALM default templates # inline template: salt \-G \(aqos:junos\(aq net.load_template template_source=\(aqsystem { host\-name {{host_name}}; }\(aq host_name=\(aqMX480.lab\(aq # inline template using grains info: salt \-G \(aqos:junos\(aq net.load_template template_source=\(aqsystem { host\-name {{grains.model}}.lab; }\(aq # if the device is a MX480, the command above will set the hostname as: MX480.lab # inline template using pillar data: salt \-G \(aqos:junos\(aq net.load_template template_source=\(aqsystem { host\-name {{pillar.proxy.host}}; }\(aq salt \(aq*\(aq net.load_template https://bit.ly/2OhSgqP hostname=example # will commit salt \(aq*\(aq net.load_template https://bit.ly/2OhSgqP hostname=example test=True # dry run salt \(aq*\(aq net.load_template salt://templates/example.jinja debug=True # Using the salt:// URI # render a mako template: salt \(aq*\(aq net.load_template salt://templates/example.mako template_engine=mako debug=True # render remote template salt \-G \(aqos:junos\(aq net.load_template http://bit.ly/2fReJg7 test=True debug=True peers=[\(aq192.168.0.1\(aq] salt \-G \(aqos:ios\(aq net.load_template http://bit.ly/2gKOj20 test=True debug=True peers=[\(aq192.168.0.1\(aq] # render multiple templates at once salt \(aq*\(aq net.load_template \(dq[\(aqhttps://bit.ly/2OhSgqP\(aq, \(aqsalt://templates/example.jinja\(aq]\(dq context=\(dq{\(aqhostname\(aq: \(aqexample\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqcomment\(aq: \(aq\(aq, \(aqalready_configured\(aq: False, \(aqresult\(aq: True, \(aqdiff\(aq: \(aq[edit system]+ host\-name edge01.bjm01\(aq, \(aqloaded_config\(aq: \(aqsystem { host\-name edge01.bjm01; }\(aq\(aq } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.mac(address=\(aq\(aq, interface=\(aq\(aq, vlan=0, **kwargs) Returns the MAC Address Table on the device. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBaddress\fP \-\- MAC address to filter on .IP \(bu 2 \fBinterface\fP \-\- Interface name to filter on .IP \(bu 2 \fBvlan\fP \-\- VLAN identifier .UNINDENT .TP .B Returns A list of dictionaries representing the entries in the MAC Address Table .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.mac salt \(aq*\(aq net.mac vlan=10 .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ { \(aqmac\(aq : \(aq00:1c:58:29:4a:71\(aq, \(aqinterface\(aq : \(aqxe\-3/0/2\(aq, \(aqstatic\(aq : False, \(aqactive\(aq : True, \(aqmoves\(aq : 1, \(aqvlan\(aq : 10, \(aqlast_move\(aq : 1454417742.58 }, { \(aqmac\(aq : \(aq8c:60:4f:58:e1:c1\(aq, \(aqinterface\(aq : \(aqxe\-1/0/1\(aq, \(aqstatic\(aq : False, \(aqactive\(aq : True, \(aqmoves\(aq : 2, \(aqvlan\(aq : 42, \(aqlast_move\(aq : 1453191948.11 } ] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.optics(**kwargs) New in version 2017.7.0. .sp Fetches the power usage on the various transceivers installed on the network device (in dBm), and returns a view that conforms with the OpenConfig model openconfig\-platform\-transceiver.yang. .INDENT 7.0 .TP .B Returns .INDENT 7.0 .TP .B Returns a dictionary where the keys are as listed below: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B intf_name (unicode) .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B physical_channels .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B channels (list of dicts) .INDENT 7.0 .IP \(bu 2 index (int) .IP \(bu 2 .INDENT 2.0 .TP .B state .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B input_power .INDENT 7.0 .IP \(bu 2 instant (float) .IP \(bu 2 avg (float) .IP \(bu 2 min (float) .IP \(bu 2 max (float) .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B output_power .INDENT 7.0 .IP \(bu 2 instant (float) .IP \(bu 2 avg (float) .IP \(bu 2 min (float) .IP \(bu 2 max (float) .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B laser_bias_current .INDENT 7.0 .IP \(bu 2 instant (float) .IP \(bu 2 avg (float) .IP \(bu 2 min (float) .IP \(bu 2 max (float) .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.optics .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.patch(patchfile, options=\(aq\(aq, saltenv=\(aqbase\(aq, source_hash=None, show_changes=True, source=\(aqrunning\(aq, path=None, test=False, commit=True, debug=False, replace=True) New in version 2019.2.0. .sp Apply a patch to the configuration source, and load the result into the running config of the device. .INDENT 7.0 .TP .B patchfile A patch file to apply to the configuration source. .TP .B options Options to pass to patch. .TP .B source_hash If the patch file (specified via the \fBpatchfile\fP argument) is an HTTP(S) or 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 file if the cached copy matches the specified hash. .TP .B show_changes: \fBTrue\fP Controls how changes are presented. If \fBTrue\fP, this function will return the of the changes made. If \fBFalse\fP, then it will return a boolean (\fBTrue\fP if any changes were made, otherwise False). .TP .B source: \fBrunning\fP The configuration source. Choose from: \fBrunning\fP, \fBcandidate\fP, or \fBstartup\fP\&. Default: \fBrunning\fP\&. .TP .B path: \fBNone\fP Save the temporary configuration to a specific path, then read from there. This argument is optional, can the user prefers a particular location of the temporary file. .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: \fBTrue\fP Commit the configuration changes? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key in the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .TP .B replace: \fBTrue\fP Load and replace the configuration. Default: \fBTrue\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.patch https://example.com/running_config.patch .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.ping(destination, source=None, ttl=None, timeout=None, size=None, count=None, vrf=None, **kwargs) Executes a ping on the network device and returns a dictionary as a result. .INDENT 7.0 .TP .B destination Hostname or IP address of remote host .TP .B source Source address of echo request .TP .B ttl IP time\-to\-live value (IPv6 hop\-limit value) (1..255 hops) .TP .B timeout Maximum wait time after sending final packet (seconds) .TP .B size Size of request packets (0..65468 bytes) .TP .B count Number of ping requests to send (1..2000000000 packets) .TP .B vrf VRF (routing instance) for ping attempt .sp New in version 2016.11.4. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.ping 8.8.8.8 salt \(aq*\(aq net.ping 8.8.8.8 ttl=3 size=65468 salt \(aq*\(aq net.ping 8.8.8.8 source=127.0.0.1 timeout=1 count=100 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.replace_pattern(pattern, repl, count=0, flags=8, bufsize=1, append_if_not_found=False, prepend_if_not_found=False, not_found_content=None, search_only=False, show_changes=True, backslash_literal=False, source=None, path=None, test=False, replace=True, debug=False, commit=True) New in version 2019.2.0. .sp Replace occurrences of a pattern in the configuration source. If \fBshow_changes\fP is \fBTrue\fP, then a diff of what changed will be returned, otherwise a \fBTrue\fP will be returned when changes are made, and \fBFalse\fP when no changes are made. This is a pure Python implementation that wraps Python\(aqs \fI\%sub()\fP\&. .INDENT 7.0 .TP .B pattern A regular expression, to be matched using Python\(aqs \fI\%search()\fP\&. .TP .B repl The replacement text. .TP .B count: \fB0\fP Maximum number of pattern occurrences to be replaced. If count is a positive integer \fBn\fP, only \fBn\fP occurrences will be replaced, otherwise all occurrences will be replaced. .TP .B flags (list or int): \fB8\fP A list of flags defined in the \fBre\fP module documentation from the Python standard library. Each list item should be a string that will correlate to the human\-friendly flag name. E.g., \fB[\(aqIGNORECASE\(aq, \(aqMULTILINE\(aq]\fP\&. Optionally, \fBflags\fP may be an int, with a value corresponding to the XOR (\fB|\fP) of all the desired flags. Defaults to 8 (which supports \(aqMULTILINE\(aq). .TP .B bufsize (int or str): \fB1\fP How much of the configuration to buffer into memory at once. The default value \fB1\fP processes one line at a time. The special value \fBfile\fP may be specified which will read the entire file into memory before processing. .TP .B append_if_not_found: \fBFalse\fP If set to \fBTrue\fP, and pattern is not found, then the content will be appended to the file. .TP .B prepend_if_not_found: \fBFalse\fP If set to \fBTrue\fP and pattern is not found, then the content will be prepended to the file. .TP .B not_found_content Content to use for append/prepend if not found. If None (default), uses \fBrepl\fP\&. Useful when \fBrepl\fP uses references to group in pattern. .TP .B search_only: \fBFalse\fP If set to true, this no changes will be performed on the file, and this function will simply return \fBTrue\fP if the pattern was matched, and \fBFalse\fP if not. .TP .B show_changes: \fBTrue\fP If \fBTrue\fP, return a diff of changes made. Otherwise, return \fBTrue\fP if changes were made, and \fBFalse\fP if not. .TP .B backslash_literal: \fBFalse\fP Interpret backslashes as literal backslashes for the repl and not escape characters. This will help when using append/prepend so that the backslashes are not interpreted for the repl on the second run of the state. .TP .B source: \fBrunning\fP The configuration source. Choose from: \fBrunning\fP, \fBcandidate\fP, or \fBstartup\fP\&. Default: \fBrunning\fP\&. .TP .B path Save the temporary configuration to a specific path, then read from there. .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: \fBTrue\fP Commit the configuration changes? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key in the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .TP .B replace: \fBTrue\fP Load and replace the configuration. Default: \fBTrue\fP\&. .UNINDENT .sp If an equal sign (\fB=\fP) appears in an argument to a Salt command it is interpreted as a keyword argument in the format \fBkey=val\fP\&. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.replace_pattern \(dqbind\-address\es*=\(dq \(dqbind\-address:\(dq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.replace_pattern PREFIX\-LIST_NAME new\-prefix\-list\-name salt \(aq*\(aq net.replace_pattern bgp\-group\-name new\-bgp\-group\-name count=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.rollback(inherit_napalm_device=None, **kwargs) Rollbacks the configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.rollback .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.save_config(source=None, path=None) New in version 2019.2.0. .sp Save the configuration to a file on the local file system. .INDENT 7.0 .TP .B source: \fBrunning\fP The configuration source. Choose from: \fBrunning\fP, \fBcandidate\fP, \fBstartup\fP\&. Default: \fBrunning\fP\&. .TP .B path Absolute path to file where to save the configuration. To push the files to the Master, use \fI\%cp.push\fP Execution function. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.save_config source=running .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_network.traceroute(destination, source=None, ttl=None, timeout=None, vrf=None, **kwargs) Calls the method traceroute from the NAPALM driver object and returns a dictionary with the result of the traceroute command executed on the device. .INDENT 7.0 .TP .B destination Hostname or address of remote host .TP .B source Source address to use in outgoing traceroute packets .TP .B ttl IP maximum time\-to\-live value (or IPv6 maximum hop\-limit value) .TP .B timeout Number of seconds to wait for response (seconds) .TP .B vrf VRF (routing instance) for traceroute attempt .sp New in version 2016.11.4. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq net.traceroute 8.8.8.8 salt \(aq*\(aq net.traceroute 8.8.8.8 source=127.0.0.1 ttl=5 timeout=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.napalm_ntp .SS NAPALM NTP .sp Manages NTP on network devices. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> & Jerome Fleury <\fI\%jf@cloudflare.com\fP> .TP .B maturity new .TP .B depends napalm .TP .B platform unix .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 \fI\%NAPALM proxy minion\fP .IP \(bu 2 \fI\%NET basic features\fP .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%NTP peers management state\fP .UNINDENT .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.modules.napalm_ntp.delete_peers(*peers, **options) Removes NTP peers configured on the device. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpeers\fP \-\- list of IP Addresses/Domain Names to be removed as NTP peers .IP \(bu 2 \fB(\fP\fBbool\fP\fB)\fP (\fIcommit\fP) \-\- discard loaded config. By default \fBtest\fP is False (will not dicard the changes) .IP \(bu 2 \fB(\fP\fBbool\fP\fB)\fP \-\- commit loaded config. By default \fBcommit\fP is True (will commit the changes). Useful when the user does not want to commit after each change, but after a couple. .UNINDENT .UNINDENT .sp By default this function will commit the config changes (if any). To load without committing, use the \fBcommit\fP option. For a dry run, use the \fBtest\fP argument. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ntp.delete_peers 8.8.8.8 time.apple.com salt \(aq*\(aq ntp.delete_peers 172.17.17.1 test=True # only displays the diff salt \(aq*\(aq ntp.delete_peers 192.168.0.1 commit=False # preserves the changes, but does not commit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_ntp.delete_servers(*servers, **options) Removes NTP servers configured on the device. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBservers\fP \-\- list of IP Addresses/Domain Names to be removed as NTP servers .IP \(bu 2 \fB(\fP\fBbool\fP\fB)\fP (\fIcommit\fP) \-\- discard loaded config. By default \fBtest\fP is False (will not dicard the changes) .IP \(bu 2 \fB(\fP\fBbool\fP\fB)\fP \-\- commit loaded config. By default \fBcommit\fP is True (will commit the changes). Useful when the user does not want to commit after each change, but after a couple. .UNINDENT .UNINDENT .sp By default this function will commit the config changes (if any). To load without committing, use the \fBcommit\fP option. For dry run use the \fBtest\fP argument. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ntp.delete_servers 8.8.8.8 time.apple.com salt \(aq*\(aq ntp.delete_servers 172.17.17.1 test=True # only displays the diff salt \(aq*\(aq ntp.delete_servers 192.168.0.1 commit=False # preserves the changes, but does not commit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_ntp.peers(**kwargs) Returns a list the NTP peers configured on the network device. .INDENT 7.0 .TP .B Returns configured NTP peers as list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ntp.peers .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ \(aq192.168.0.1\(aq, \(aq172.17.17.1\(aq, \(aq172.17.17.2\(aq, \(aq2400:cb00:6:1024::c71b:840a\(aq ] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_ntp.servers(**kwargs) Returns a list of the configured NTP servers on the device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ntp.servers .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ \(aq192.168.0.1\(aq, \(aq172.17.17.1\(aq, \(aq172.17.17.2\(aq, \(aq2400:cb00:6:1024::c71b:840a\(aq ] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_ntp.set_peers(*peers, **options) Configures a list of NTP peers on the device. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpeers\fP \-\- list of IP Addresses/Domain Names .IP \(bu 2 \fB(\fP\fBbool\fP\fB)\fP (\fItest\fP) \-\- discard loaded config. By default \fBtest\fP is False (will not dicard the changes) .UNINDENT .TP .B Commit commit (bool) commit loaded config. By default \fBcommit\fP is True (will commit the changes). Useful when the user does not want to commit after each change, but after a couple. .UNINDENT .sp By default this function will commit the config changes (if any). To load without committing, use the \fIcommit\fP option. For dry run use the \fItest\fP argument. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ntp.set_peers 192.168.0.1 172.17.17.1 time.apple.com salt \(aq*\(aq ntp.set_peers 172.17.17.1 test=True # only displays the diff salt \(aq*\(aq ntp.set_peers 192.168.0.1 commit=False # preserves the changes, but does not commit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_ntp.set_servers(*servers, **options) Configures a list of NTP servers on the device. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBservers\fP \-\- list of IP Addresses/Domain Names .IP \(bu 2 \fB(\fP\fBbool\fP\fB)\fP (\fItest\fP) \-\- discard loaded config. By default \fBtest\fP is False (will not dicard the changes) .UNINDENT .TP .B Commit commit (bool) commit loaded config. By default \fBcommit\fP is True (will commit the changes). Useful when the user does not want to commit after each change, but after a couple. .UNINDENT .sp By default this function will commit the config changes (if any). To load without committing, use the \fIcommit\fP option. For dry run use the \fItest\fP argument. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ntp.set_servers 192.168.0.1 172.17.17.1 time.apple.com salt \(aq*\(aq ntp.set_servers 172.17.17.1 test=True # only displays the diff salt \(aq*\(aq ntp.set_servers 192.168.0.1 commit=False # preserves the changes, but does not commit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_ntp.stats(peer=None, **kwargs) Returns a dictionary containing synchronization details of the NTP peers. .INDENT 7.0 .TP .B Parameters \fBpeer\fP \-\- Returns only the details of a specific NTP peer. .TP .B Returns a list of dictionaries, with the following keys: .INDENT 7.0 .IP \(bu 2 remote .IP \(bu 2 referenceid .IP \(bu 2 synchronized .IP \(bu 2 stratum .IP \(bu 2 type .IP \(bu 2 when .IP \(bu 2 hostpoll .IP \(bu 2 reachability .IP \(bu 2 delay .IP \(bu 2 offset .IP \(bu 2 jitter .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ntp.stats .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ { \(aqremote\(aq : \(aq188.114.101.4\(aq, \(aqreferenceid\(aq : \(aq188.114.100.1\(aq, \(aqsynchronized\(aq : True, \(aqstratum\(aq : 4, \(aqtype\(aq : \(aq\-\(aq, \(aqwhen\(aq : \(aq107\(aq, \(aqhostpoll\(aq : 256, \(aqreachability\(aq : 377, \(aqdelay\(aq : 164.228, \(aqoffset\(aq : \-13.866, \(aqjitter\(aq : 2.695 } ] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.napalm_probes .SS NAPALM Probes .sp Manages RPM/SLA probes on the network device. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> & Jerome Fleury <\fI\%jf@cloudflare.com\fP> .TP .B maturity new .TP .B depends napalm .TP .B platform unix .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 \fI\%napalm proxy minion\fP .IP \(bu 2 \fI\%NET basic features\fP .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Probes configuration management state\fP .UNINDENT .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.modules.napalm_probes.config(**kwargs) Returns the configuration of the RPM probes. .INDENT 7.0 .TP .B Returns A dictionary containing the configuration of the RPM/SLA probes. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq probes.config .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqprobe1\(aq:{ \(aqtest1\(aq: { \(aqprobe_type\(aq : \(aqicmp\-ping\(aq, \(aqtarget\(aq : \(aq192.168.0.1\(aq, \(aqsource\(aq : \(aq192.168.0.2\(aq, \(aqprobe_count\(aq : 13, \(aqtest_interval\(aq: 3 }, \(aqtest2\(aq: { \(aqprobe_type\(aq : \(aqhttp\-ping\(aq, \(aqtarget\(aq : \(aq172.17.17.1\(aq, \(aqsource\(aq : \(aq192.17.17.2\(aq, \(aqprobe_count\(aq : 5, \(aqtest_interval\(aq: 60 } } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_probes.delete_probes(probes, test=False, commit=True, **kwargs) Removes RPM/SLA probes from the network device. Calls the configuration template \(aqdelete_probes\(aq from the NAPALM library, providing as input a rich formatted dictionary with the configuration details of the probes to be removed from the configuration of the device. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprobes\fP \-\- Dictionary with a similar format as the output dictionary of the function config(), where the details are not necessary. .IP \(bu 2 \fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and return the changes. Default: False .IP \(bu 2 \fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit the config immediately after loading the changes. E.g.: a state loads a couple of parts (add / remove / update) and would not be optimal to commit after each operation. Also, from the CLI when the user needs to apply the similar changes before committing, can specify commit=False and will not discard the config. .UNINDENT .TP .B Raises \fBMergeConfigException\fP \-\- If there is an error on the configuration sent. .TP .B Returns A dictionary having the following keys: .UNINDENT .INDENT 7.0 .IP \(bu 2 result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be the \fIalready_configured\fP flag (example below) .IP \(bu 2 comment (str): a message for the user .IP \(bu 2 already_configured (bool): flag to check if there were no changes applied .IP \(bu 2 diff (str): returns the config changes applied .UNINDENT .sp Input example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C probes = { \(aqexisting_probe\(aq:{ \(aqexisting_test1\(aq: {}, \(aqexisting_test2\(aq: {} } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_probes.results(**kwargs) Provides the results of the measurements of the RPM/SLA probes. .sp :return a dictionary with the results of the probes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq probes.results .ft P .fi .UNINDENT .UNINDENT .sp Output example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqprobe1\(aq: { \(aqtest1\(aq: { \(aqlast_test_min_delay\(aq : 63.120, \(aqglobal_test_min_delay\(aq : 62.912, \(aqcurrent_test_avg_delay\(aq: 63.190, \(aqglobal_test_max_delay\(aq : 177.349, \(aqcurrent_test_max_delay\(aq: 63.302, \(aqglobal_test_avg_delay\(aq : 63.802, \(aqlast_test_avg_delay\(aq : 63.438, \(aqlast_test_max_delay\(aq : 65.356, \(aqprobe_type\(aq : \(aqicmp\-ping\(aq, \(aqrtt\(aq : 63.138, \(aqlast_test_loss\(aq : 0, \(aqround_trip_jitter\(aq : \-59.0, \(aqtarget\(aq : \(aq192.168.0.1\(aq, \(aqsource\(aq : \(aq192.168.0.2\(aq, \(aqprobe_count\(aq : 15, \(aqcurrent_test_min_delay\(aq: 63.138 }, \(aqtest2\(aq: { \(aqlast_test_min_delay\(aq : 176.384, \(aqglobal_test_min_delay\(aq : 169.226, \(aqcurrent_test_avg_delay\(aq: 177.098, \(aqglobal_test_max_delay\(aq : 292.628, \(aqcurrent_test_max_delay\(aq: 180.055, \(aqglobal_test_avg_delay\(aq : 177.959, \(aqlast_test_avg_delay\(aq : 177.178, \(aqlast_test_max_delay\(aq : 184.671, \(aqprobe_type\(aq : \(aqicmp\-ping\(aq, \(aqrtt\(aq : 176.449, \(aqlast_test_loss\(aq : 0, \(aqround_trip_jitter\(aq : \-34.0, \(aqtarget\(aq : \(aq172.17.17.1\(aq, \(aqsource\(aq : \(aq172.17.17.2\(aq, \(aqprobe_count\(aq : 15, \(aqcurrent_test_min_delay\(aq: 176.402 } } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_probes.schedule_probes(probes, test=False, commit=True, **kwargs) Will schedule the probes. On Cisco devices, it is not enough to define the probes, it is also necessary to schedule them. .sp This function calls the configuration template \fBschedule_probes\fP from the NAPALM library, providing as input a rich formatted dictionary with the names of the probes and the tests to be scheduled. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprobes\fP \-\- Dictionary with a similar format as the output dictionary of the function config(), where the details are not necessary. .IP \(bu 2 \fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and return the changes. Default: False .IP \(bu 2 \fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit the config immediately after loading the changes. E.g.: a state loads a couple of parts (add / remove / update) and would not be optimal to commit after each operation. Also, from the CLI when the user needs to apply the similar changes before committing, can specify commit=False and will not discard the config. .UNINDENT .TP .B Raises \fBMergeConfigException\fP \-\- If there is an error on the configuration sent. .TP .B Returns a dictionary having the following keys: .UNINDENT .INDENT 7.0 .IP \(bu 2 result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be the \fIalready_configured\fP flag (example below) .IP \(bu 2 comment (str): a message for the user .IP \(bu 2 already_configured (bool): flag to check if there were no changes applied .IP \(bu 2 diff (str): returns the config changes applied .UNINDENT .sp Input example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C probes = { \(aqnew_probe\(aq:{ \(aqnew_test1\(aq: {}, \(aqnew_test2\(aq: {} } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_probes.set_probes(probes, test=False, commit=True, **kwargs) Configures RPM/SLA probes on the device. Calls the configuration template \(aqset_probes\(aq from the NAPALM library, providing as input a rich formatted dictionary with the configuration details of the probes to be configured. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprobes\fP \-\- Dictionary formatted as the output of the function config() .IP \(bu 2 \fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and return the changes. Default: False .IP \(bu 2 \fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit the config immediately after loading the changes. E.g.: a state loads a couple of parts (add / remove / update) and would not be optimal to commit after each operation. Also, from the CLI when the user needs to apply the similar changes before committing, can specify commit=False and will not discard the config. .UNINDENT .TP .B Raises \fBMergeConfigException\fP \-\- If there is an error on the configuration sent. .TP .B Return a dictionary having the following keys .INDENT 7.0 .IP \(bu 2 result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be the \fIalready_configured\fP flag (example below) .IP \(bu 2 comment (str): a message for the user .IP \(bu 2 already_configured (bool): flag to check if there were no changes applied .IP \(bu 2 diff (str): returns the config changes applied .UNINDENT .UNINDENT .sp Input example \- via state/script: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C probes = { \(aqnew_probe\(aq:{ \(aqnew_test1\(aq: { \(aqprobe_type\(aq : \(aqicmp\-ping\(aq, \(aqtarget\(aq : \(aq192.168.0.1\(aq, \(aqsource\(aq : \(aq192.168.0.2\(aq, \(aqprobe_count\(aq : 13, \(aqtest_interval\(aq: 3 }, \(aqnew_test2\(aq: { \(aqprobe_type\(aq : \(aqhttp\-ping\(aq, \(aqtarget\(aq : \(aq172.17.17.1\(aq, \(aqsource\(aq : \(aq192.17.17.2\(aq, \(aqprobe_count\(aq : 5, \(aqtest_interval\(aq: 60 } } } set_probes(probes) .ft P .fi .UNINDENT .UNINDENT .sp CLI Example \- to push changes on the fly (not recommended): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqjunos_minion\(aq probes.set_probes \(dq{\(aqnew_probe\(aq:{\(aqnew_test1\(aq:{\(aqprobe_type\(aq:\(aqicmp\-ping\(aq, \(aqtarget\(aq:\(aq192.168.0.1\(aq,\(aqsource\(aq:\(aq192.168.0.2\(aq,\(aqprobe_count\(aq:13,\(aqtest_interval\(aq:3}}}\(dq test=True .ft P .fi .UNINDENT .UNINDENT .sp Output example \- for the CLI example above: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C junos_minion: \-\-\-\-\-\-\-\-\-\- already_configured: False comment: Configuration discarded. diff: [edit services rpm] probe transit { ... } + probe new_probe { + test new_test1 { + probe\-type icmp\-ping; + target address 192.168.0.1; + probe\-count 13; + test\-interval 3; + source\-address 192.168.0.2; + } + } result: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.napalm_route .SS NAPALM Route .sp Retrieves route details from network devices. .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 \fI\%NAPALM proxy minion\fP .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.modules.napalm_route.show(destination, protocol=None, **kwargs) Displays all details for a certain route learned via a specific protocol. If the protocol is not specified, will return all possible routes. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function return the routes from the RIB. In case the destination prefix is too short, there may be too many routes matched. Therefore in cases of devices having a very high number of routes it may be necessary to adjust the prefix length and request using a longer prefix. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B destination destination prefix. .TP .B protocol (optional) protocol used to learn the routes to the destination. .UNINDENT .sp Changed in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy_router\(aq route.show 172.16.0.0/25 salt \(aqmy_router\(aq route.show 172.16.0.0/25 bgp .ft P .fi .UNINDENT .UNINDENT .sp Output example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aq172.16.0.0/25\(aq: [ { \(aqprotocol\(aq: \(aqBGP\(aq, \(aqlast_active\(aq: True, \(aqcurrent_active\(aq: True, \(aqage\(aq: 1178693, \(aqrouting_table\(aq: \(aqinet.0\(aq, \(aqnext_hop\(aq: \(aq192.168.0.11\(aq, \(aqoutgoing_interface\(aq: \(aqxe\-1/1/1.100\(aq, \(aqpreference\(aq: 170, \(aqselected_next_hop\(aq: False, \(aqprotocol_attributes\(aq: { \(aqremote_as\(aq: 65001, \(aqmetric\(aq: 5, \(aqlocal_as\(aq: 13335, \(aqas_path\(aq: \(aq\(aq, \(aqremote_address\(aq: \(aq192.168.0.11\(aq, \(aqmetric2\(aq: 0, \(aqlocal_preference\(aq: 0, \(aqcommunities\(aq: [ \(aq0:2\(aq, \(aqno\-export\(aq ], \(aqpreference2\(aq: \-1 }, \(aqinactive_reason\(aq: \(aq\(aq }, { \(aqprotocol\(aq: \(aqBGP\(aq, \(aqlast_active\(aq: False, \(aqcurrent_active\(aq: False, \(aqage\(aq: 2359429, \(aqrouting_table\(aq: \(aqinet.0\(aq, \(aqnext_hop\(aq: \(aq192.168.0.17\(aq, \(aqoutgoing_interface\(aq: \(aqxe\-1/1/1.100\(aq, \(aqpreference\(aq: 170, \(aqselected_next_hop\(aq: True, \(aqprotocol_attributes\(aq: { \(aqremote_as\(aq: 65001, \(aqmetric\(aq: 5, \(aqlocal_as\(aq: 13335, \(aqas_path\(aq: \(aq\(aq, \(aqremote_address\(aq: \(aq192.168.0.17\(aq, \(aqmetric2\(aq: 0, \(aqlocal_preference\(aq: 0, \(aqcommunities\(aq: [ \(aq0:3\(aq, \(aqno\-export\(aq ], \(aqpreference2\(aq: \-1 }, \(aqinactive_reason\(aq: \(aqNot Best in its group \- Router ID\(aq } ] } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.napalm_snmp .SS NAPALM SNMP .sp Manages SNMP on network devices. .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 \fI\%NAPALM proxy minion\fP .IP \(bu 2 \fI\%NET basic features\fP .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%SNMP configuration management state\fP .UNINDENT .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.modules.napalm_snmp.config(**kwargs) Returns the SNMP configuration .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snmp.config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_snmp.remove_config(chassis_id=None, community=None, contact=None, location=None, test=False, commit=True, **kwargs) Removes a configuration element from the SNMP configuration. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBchassis_id\fP \-\- (optional) Chassis ID .IP \(bu 2 \fBcommunity\fP \-\- (optional) A dictionary having the following optional keys: .UNINDENT .UNINDENT .INDENT 7.0 .IP \(bu 2 acl (if any policy / ACL need to be set) .IP \(bu 2 mode: rw or ro. Default: ro .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontact\fP \-\- Contact details .IP \(bu 2 \fBlocation\fP \-\- Location .IP \(bu 2 \fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and return the changes. Default: False .IP \(bu 2 \fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit the config immediately after loading the changes. E.g.: a state loads a couple of parts (add / remove / update) and would not be optimal to commit after each operation. Also, from the CLI when the user needs to apply the similar changes before committing, can specify commit=False and will not discard the config. .UNINDENT .TP .B Raises \fBMergeConfigException\fP \-\- If there is an error on the configuration sent. .TP .B Returns A dictionary having the following keys: .UNINDENT .INDENT 7.0 .IP \(bu 2 result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be the \fIalready_configured\fP flag (example below) .IP \(bu 2 comment (str): a message for the user .IP \(bu 2 already_configured (bool): flag to check if there were no changes applied .IP \(bu 2 diff (str): returns the config changes applied .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snmp.remove_config community=\(aqabcd\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_snmp.update_config(chassis_id=None, community=None, contact=None, location=None, test=False, commit=True, **kwargs) Updates the SNMP configuration. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBchassis_id\fP \-\- (optional) Chassis ID .IP \(bu 2 \fBcommunity\fP \-\- (optional) A dictionary having the following optional keys: .UNINDENT .UNINDENT .INDENT 7.0 .IP \(bu 2 acl (if any policy / ACL need to be set) .IP \(bu 2 mode: rw or ro. Default: ro .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontact\fP \-\- Contact details .IP \(bu 2 \fBlocation\fP \-\- Location .IP \(bu 2 \fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and return the changes. Default: False .IP \(bu 2 \fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit the config immediately after loading the changes. E.g.: a state loads a couple of parts (add / remove / update) and would not be optimal to commit after each operation. Also, from the CLI when the user needs to apply the similar changes before committing, can specify commit=False and will not discard the config. .UNINDENT .TP .B Raises \fBMergeConfigException\fP \-\- If there is an error on the configuration sent. .TP .B Return a dictionary having the following keys .UNINDENT .INDENT 7.0 .IP \(bu 2 result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be the \fIalready_configured\fP flag (example below) .IP \(bu 2 comment (str): a message for the user .IP \(bu 2 already_configured (bool): flag to check if there were no changes applied .IP \(bu 2 diff (str): returns the config changes applied .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqedge01.lon01\(aq snmp.update_config location=\(dqGreenwich, UK\(dq test=True .ft P .fi .UNINDENT .UNINDENT .sp Output example (for the CLI example above): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C edge01.lon01: \-\-\-\-\-\-\-\-\-\- already_configured: False comment: Configuration discarded. diff: [edit snmp] \- location \(dqLondon, UK\(dq; + location \(dqGreenwich, UK\(dq; result: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.napalm_users .SS NAPALM Users .sp Manages the configuration of the users on network devices. .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 \fI\%NAPALM proxy minion\fP .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Users management state\fP .UNINDENT .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.modules.napalm_users.config(**kwargs) Returns the configuration of the users on the device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq users.config .ft P .fi .UNINDENT .UNINDENT .sp Output example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqmircea\(aq: { \(aqlevel\(aq: 15, \(aqpassword\(aq: \(aq$1$0P70xKPa$4jt5/10cBTckk6I/w/\(aq, \(aqsshkeys\(aq: [ \(aqssh\-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC4pFn+shPwTb2yELO4L7NtQrKOJXNeCl1je l9STXVaGnRAnuc2PXl35vnWmcUq6YbUEcgUTRzzXfmelJKuVJTJIlMXii7h2xkbQp0YZIEs4P 8ipwnRBAxFfk/ZcDsN3mjep4/yjN56ejk345jhk345jk345jk341p3A/9LIL7l6YewLBCwJj6 D+fWSJ0/YW+7oH17Fk2HH+tw0L5PcWLHkwA4t60iXn16qDbIk/ze6jv2hDGdCdz7oYQeCE55C CHOHMJWYfN3jcL4s0qv8/u6Ka1FVkV7iMmro7ChThoV/5snI4Ljf2wKqgHH7TfNaCfpU0WvHA nTs8zhOrGScSrtb mircea@master\-roshi\(aq ] } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_users.delete_users(users, test=False, commit=True, **kwargs) Removes users from the configuration of network devices. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBusers\fP \-\- Dictionary formatted as the output of the function config() .IP \(bu 2 \fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and return the changes. Default: False .IP \(bu 2 \fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit the config immediately after loading the changes. E.g.: a state loads a couple of parts (add / remove / update) and would not be optimal to commit after each operation. Also, from the CLI when the user needs to apply the similar changes before committing, can specify commit=False and will not discard the config. .UNINDENT .TP .B Raises \fBMergeConfigException\fP \-\- If there is an error on the configuration sent. .TP .B Return a dictionary having the following keys .INDENT 7.0 .IP \(bu 2 result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be the \fIalready_configured\fP flag (example below) .IP \(bu 2 comment (str): a message for the user .IP \(bu 2 already_configured (bool): flag to check if there were no changes applied .IP \(bu 2 diff (str): returns the config changes applied .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq users.delete_users \(dq{\(aqmircea\(aq: {}}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_users.set_users(users, test=False, commit=True, **kwargs) Configures users on network devices. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBusers\fP \-\- Dictionary formatted as the output of the function config() .IP \(bu 2 \fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and return the changes. Default: False .IP \(bu 2 \fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit the config immediately after loading the changes. E.g.: a state loads a couple of parts (add / remove / update) and would not be optimal to commit after each operation. Also, from the CLI when the user needs to apply the similar changes before committing, can specify commit=False and will not discard the config. .UNINDENT .TP .B Raises \fBMergeConfigException\fP \-\- If there is an error on the configuration sent. .TP .B Return a dictionary having the following keys .UNINDENT .INDENT 7.0 .IP \(bu 2 result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be the \fIalready_configured\fP flag (example below) .IP \(bu 2 comment (str): a message for the user .IP \(bu 2 already_configured (bool): flag to check if there were no changes applied .IP \(bu 2 diff (str): returns the config changes applied .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq users.set_users \(dq{\(aqmircea\(aq: {}}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.napalm_yang_mod .SS NAPALM YANG .sp NAPALM YANG basic operations. .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.modules.napalm_yang_mod.compliance_report(data, *models, **kwargs) Return the compliance report using YANG objects. .INDENT 7.0 .TP .B data Dictionary structured with respect to the models referenced. .TP .B models A list of models to be used when generating the config. .TP .B filepath The absolute path to the validation file. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm_yang.compliance_report {} models.openconfig_interfaces filepath=~/validate.yml .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(dqskipped\(dq: [], \(dqcomplies\(dq: true, \(dqget_interfaces_ip\(dq: { \(dqmissing\(dq: [], \(dqcomplies\(dq: true, \(dqpresent\(dq: { \(dqge\-0/0/0.0\(dq: { \(dqcomplies\(dq: true, \(dqnested\(dq: true } }, \(dqextra\(dq: [] } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_yang_mod.diff(candidate, running, *models) Returns the difference between two configuration entities structured according to the YANG model. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function is recommended to be used mostly as a state helper. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B candidate First model to compare. .TP .B running Second model to compare. .TP .B models A list of models to be used when comparing. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm_yang.diff {} {} models.openconfig_interfaces .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(dqinterfaces\(dq: { \(dqinterface\(dq: { \(dqboth\(dq: { \(dqPort\-Channel1\(dq: { \(dqconfig\(dq: { \(dqmtu\(dq: { \(dqfirst\(dq: \(dq0\(dq, \(dqsecond\(dq: \(dq9000\(dq } } } }, \(dqfirst_only\(dq: [ \(dqLoopback0\(dq ], \(dqsecond_only\(dq: [ \(dqLoopback1\(dq ] } } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_yang_mod.get_config(data, *models, **kwargs) Return the native config. .INDENT 7.0 .TP .B data Dictionary structured with respect to the models referenced. .TP .B models A list of models to be used when generating the config. .TP .B profiles: \fBNone\fP Use certain profiles to generate the config. If not specified, will use the platform default profile(s). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm_yang.get_config {} models.openconfig_interfaces .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C interface et1 ip address 192.168.1.1/24 description Uplink1 mtu 9000 interface et2 ip address 192.168.2.1/24 description Uplink2 mtu 9000 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_yang_mod.load_config(data, *models, **kwargs) Generate and load the config on the device using the OpenConfig or IETF models and device profiles. .INDENT 7.0 .TP .B data Dictionary structured with respect to the models referenced. .TP .B models A list of models to be used when generating the config. .TP .B profiles: \fBNone\fP Use certain profiles to generate the config. If not specified, will use the platform default profile(s). .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: \fBTrue\fP Commit? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key under the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .TP .B replace: \fBFalse\fP Should replace the config with the new generate one? .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm_yang.load_config {} models.openconfig_interfaces test=True debug=True .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C device1: \-\-\-\-\-\-\-\-\-\- already_configured: False comment: diff: [edit interfaces ge\-0/0/0] \- mtu 1400; [edit interfaces ge\-0/0/0 unit 0 family inet] \- dhcp; [edit interfaces lo0] \- unit 0 { \- description lo0.0; \- } + unit 1 { + description \(dqnew loopback\(dq; + } loaded_config: <configuration> <interfaces replace=\(dqreplace\(dq> <interface> <name>ge\-0/0/0</name> <unit> <name>0</name> <family> <inet/> </family> <description>ge\-0/0/0.0</description> </unit> <description>management interface</description> </interface> <interface> <name>ge\-0/0/1</name> <disable/> <description>ge\-0/0/1</description> </interface> <interface> <name>ae0</name> <unit> <name>0</name> <vlan\-id>100</vlan\-id> <family> <inet> <address> <name>192.168.100.1/24</name> </address> <address> <name>172.20.100.1/24</name> </address> </inet> </family> <description>a description</description> </unit> <vlan\-tagging/> <unit> <name>1</name> <vlan\-id>1</vlan\-id> <family> <inet> <address> <name>192.168.101.1/24</name> </address> </inet> </family> <disable/> <description>ae0.1</description> </unit> <vlan\-tagging/> <unit> <name>2</name> <vlan\-id>2</vlan\-id> <family> <inet> <address> <name>192.168.102.1/24</name> </address> </inet> </family> <description>ae0.2</description> </unit> <vlan\-tagging/> </interface> <interface> <name>lo0</name> <unit> <name>1</name> <description>new loopback</description> </unit> <description>lo0</description> </interface> </interfaces> </configuration> result: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.napalm_yang_mod.parse(*models, **kwargs) Parse configuration from the device. .INDENT 7.0 .TP .B models A list of models to be used when parsing. .TP .B config: \fBFalse\fP Parse config. .TP .B state: \fBFalse\fP Parse state. .TP .B profiles: \fBNone\fP Use certain profiles to parse. If not specified, will use the device default profile(s). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq napalm_yang.parse models.openconfig_interfaces .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(dqinterfaces\(dq: { \(dqinterface\(dq: { \(dq.local.\(dq: { \(dqname\(dq: \(dq.local.\(dq, \(dqstate\(dq: { \(dqadmin\-status\(dq: \(dqUP\(dq, \(dqcounters\(dq: { \(dqin\-discards\(dq: 0, \(dqin\-errors\(dq: 0, \(dqout\-errors\(dq: 0 }, \(dqenabled\(dq: True, \(dqifindex\(dq: 0, \(dqlast\-change\(dq: 0, \(dqoper\-status\(dq: \(dqUP\(dq, \(dqtype\(dq: \(dqsoftwareLoopback\(dq }, \(dqsubinterfaces\(dq: { \(dqsubinterface\(dq: { \(dq.local..0\(dq: { \(dqindex\(dq: \(dq.local..0\(dq, \(dqstate\(dq: { \(dqifindex\(dq: 0, \(dqname\(dq: \(dq.local..0\(dq } } } } }, \(dqae0\(dq: { \(dqname\(dq: \(dqae0\(dq, \(dqstate\(dq: { \(dqadmin\-status\(dq: \(dqUP\(dq, \(dqcounters\(dq: { \(dqin\-discards\(dq: 0, \(dqin\-errors\(dq: 0, \(dqout\-errors\(dq: 0 }, \(dqenabled\(dq: True, \(dqifindex\(dq: 531, \(dqlast\-change\(dq: 255203, \(dqmtu\(dq: 1518, \(dqoper\-status\(dq: \(dqDOWN\(dq }, \(dqsubinterfaces\(dq: { \(dqsubinterface\(dq: { \(dqae0.0\(dq: { \(dqindex\(dq: \(dqae0.0\(dq, \(dqstate\(dq: { \(dqdescription\(dq: \(dqASDASDASD\(dq, \(dqifindex\(dq: 532, \(dqname\(dq: \(dqae0.0\(dq } } \(dqae0.32767\(dq: { \(dqindex\(dq: \(dqae0.32767\(dq, \(dqstate\(dq: { \(dqifindex\(dq: 535, \(dqname\(dq: \(dqae0.32767\(dq } } } } }, \(dqdsc\(dq: { \(dqname\(dq: \(dqdsc\(dq, \(dqstate\(dq: { \(dqadmin\-status\(dq: \(dqUP\(dq, \(dqcounters\(dq: { \(dqin\-discards\(dq: 0, \(dqin\-errors\(dq: 0, \(dqout\-errors\(dq: 0 }, \(dqenabled\(dq: True, \(dqifindex\(dq: 5, \(dqlast\-change\(dq: 0, \(dqoper\-status\(dq: \(dqUP\(dq } }, \(dqge\-0/0/0\(dq: { \(dqname\(dq: \(dqge\-0/0/0\(dq, \(dqstate\(dq: { \(dqadmin\-status\(dq: \(dqUP\(dq, \(dqcounters\(dq: { \(dqin\-broadcast\-pkts\(dq: 0, \(dqin\-discards\(dq: 0, \(dqin\-errors\(dq: 0, \(dqin\-multicast\-pkts\(dq: 0, \(dqin\-unicast\-pkts\(dq: 16877, \(dqout\-broadcast\-pkts\(dq: 0, \(dqout\-errors\(dq: 0, \(dqout\-multicast\-pkts\(dq: 0, \(dqout\-unicast\-pkts\(dq: 15742 }, \(dqdescription\(dq: \(dqmanagement interface\(dq, \(dqenabled\(dq: True, \(dqifindex\(dq: 507, \(dqlast\-change\(dq: 258467, \(dqmtu\(dq: 1400, \(dqoper\-status\(dq: \(dqUP\(dq }, \(dqsubinterfaces\(dq: { \(dqsubinterface\(dq: { \(dqge\-0/0/0.0\(dq: { \(dqindex\(dq: \(dqge\-0/0/0.0\(dq, \(dqstate\(dq: { \(dqdescription\(dq: \(dqge\-0/0/0.0\(dq, \(dqifindex\(dq: 521, \(dqname\(dq: \(dqge\-0/0/0.0\(dq } } } } } \(dqirb\(dq: { \(dqname\(dq: \(dqirb\(dq, \(dqstate\(dq: { \(dqadmin\-status\(dq: \(dqUP\(dq, \(dqcounters\(dq: { \(dqin\-discards\(dq: 0, \(dqin\-errors\(dq: 0, \(dqout\-errors\(dq: 0 }, \(dqenabled\(dq: True, \(dqifindex\(dq: 502, \(dqlast\-change\(dq: 0, \(dqmtu\(dq: 1514, \(dqoper\-status\(dq: \(dqUP\(dq, \(dqtype\(dq: \(dqethernetCsmacd\(dq } }, \(dqlo0\(dq: { \(dqname\(dq: \(dqlo0\(dq, \(dqstate\(dq: { \(dqadmin\-status\(dq: \(dqUP\(dq, \(dqcounters\(dq: { \(dqin\-discards\(dq: 0, \(dqin\-errors\(dq: 0, \(dqout\-errors\(dq: 0 }, \(dqdescription\(dq: \(dqlo0\(dq, \(dqenabled\(dq: True, \(dqifindex\(dq: 6, \(dqlast\-change\(dq: 0, \(dqoper\-status\(dq: \(dqUP\(dq, \(dqtype\(dq: \(dqsoftwareLoopback\(dq }, \(dqsubinterfaces\(dq: { \(dqsubinterface\(dq: { \(dqlo0.0\(dq: { \(dqindex\(dq: \(dqlo0.0\(dq, \(dqstate\(dq: { \(dqdescription\(dq: \(dqlo0.0\(dq, \(dqifindex\(dq: 16, \(dqname\(dq: \(dqlo0.0\(dq } }, \(dqlo0.16384\(dq: { \(dqindex\(dq: \(dqlo0.16384\(dq, \(dqstate\(dq: { \(dqifindex\(dq: 21, \(dqname\(dq: \(dqlo0.16384\(dq } }, \(dqlo0.16385\(dq: { \(dqindex\(dq: \(dqlo0.16385\(dq, \(dqstate\(dq: { \(dqifindex\(dq: 22, \(dqname\(dq: \(dqlo0.16385\(dq } }, \(dqlo0.32768\(dq: { \(dqindex\(dq: \(dqlo0.32768\(dq, \(dqstate\(dq: { \(dqifindex\(dq: 248, \(dqname\(dq: \(dqlo0.32768\(dq } } } } } } } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.netaddress .sp Module for getting information about network addresses. .sp New in version 2016.3.0. .INDENT 0.0 .TP .B depends netaddr .UNINDENT .INDENT 0.0 .TP .B salt.modules.netaddress.cidr_broadcast(cidr) Get the broadcast address associated with a CIDR address. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netaddress.cidr_netmask 192.168.0.0/20 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netaddress.cidr_netmask(cidr) Get the netmask address associated with a CIDR address. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netaddress.cidr_netmask 192.168.0.0/20 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netaddress.list_cidr_ips(cidr) Get a list of IP addresses from a CIDR. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netaddress.list_cidr_ips 192.168.0.0/20 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netaddress.list_cidr_ips_ipv6(cidr) Get a list of IPv6 addresses from a CIDR. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netaddress.list_cidr_ips_ipv6 192.168.0.0/20 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.netbox .SS NetBox .sp Module to query NetBox .INDENT 0.0 .TP .B codeauthor Zach Moody <\fI\%zmoody@do.co\fP> .TP .B maturity new .TP .B depends pynetbox .UNINDENT .sp The following config should be in the minion config file. In order to work with \fBsecrets\fP you should provide a token and path to your private key file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C netbox: url: <NETBOX_URL> token: <NETBOX_USERNAME_API_TOKEN (OPTIONAL)> keyfile: </PATH/TO/NETBOX/KEY (OPTIONAL)> .ft P .fi .UNINDENT .UNINDENT .sp New in version 2018.3.0. .INDENT 0.0 .TP .B salt.modules.netbox.create_circuit(name, provider_id, circuit_type, description=None) New in version 2019.2.0. .sp Create a new Netbox circuit .INDENT 7.0 .TP .B name Name of the circuit .TP .B provider_id The netbox id of the circuit provider .TP .B circuit_type The name of the circuit type .TP .B asn The ASN of the circuit provider .TP .B description The description of the circuit .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_circuit NEW_CIRCUIT_01 Telia Transit 1299 \(dqNew Telia circuit\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_circuit_provider(name, asn=None) New in version 2019.2.0. .sp Create a new Netbox circuit provider .INDENT 7.0 .TP .B name The name of the circuit provider .TP .B asn The ASN of the circuit provider .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_circuit_provider Telia 1299 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_circuit_termination(circuit, interface, device, speed, xconnect_id=None, term_side=\(aqA\(aq) New in version 2019.2.0. .sp Terminate a circuit on an interface .INDENT 7.0 .TP .B circuit The name of the circuit .TP .B interface The name of the interface to terminate on .TP .B device The name of the device the interface belongs to .TP .B speed The speed of the circuit, in Kbps .TP .B xconnect_id The cross\-connect identifier .TP .B term_side The side of the circuit termination .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_circuit_termination NEW_CIRCUIT_01 xe\-0/0/1 myminion 10000 xconnect_id=XCON01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_circuit_type(name) New in version 2019.2.0. .sp Create a new Netbox circuit type. .INDENT 7.0 .TP .B name The name of the circuit type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_circuit_type Transit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_device(name, role, model, manufacturer, site) New in version 2019.2.0. .sp Create a new device with a name, role, model, manufacturer and site. All these components need to be already in Netbox. .INDENT 7.0 .TP .B name The name of the device, e.g., \fBedge_router\fP .TP .B role String of device role, e.g., \fBrouter\fP .TP .B model String of device model, e.g., \fBMX480\fP .TP .B manufacturer String of device manufacturer, e.g., \fBJuniper\fP .TP .B site String of device site, e.g., \fBBRU\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_device edge_router router MX480 Juniper BRU .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_device_role(role, color) New in version 2019.2.0. .sp Create a device role .INDENT 7.0 .TP .B role String of device role, e.g., \fBrouter\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_device_role router .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_device_type(model, manufacturer) New in version 2019.2.0. .sp Create a device type. If the manufacturer doesn\(aqt exist, create a new manufacturer. .INDENT 7.0 .TP .B model String of device model, e.g., \fBMX480\fP .TP .B manufacturer String of device manufacturer, e.g., \fBJuniper\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_device_type MX480 Juniper .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_interface(device_name, interface_name, mac_address=None, description=None, enabled=None, lag=None, lag_parent=None, form_factor=None) New in version 2019.2.0. .sp Attach an interface to a device. If not all arguments are provided, they will default to Netbox defaults. .INDENT 7.0 .TP .B device_name The name of the device, e.g., \fBedge_router\fP .TP .B interface_name The name of the interface, e.g., \fBTenGigE0/0/0/0\fP .TP .B mac_address String of mac address, e.g., \fB50:87:89:73:92:C8\fP .TP .B description String of interface description, e.g., \fBNTT\fP .TP .B enabled String of boolean interface status, e.g., \fBTrue\fP .TP .B lag: Boolean of interface lag status, e.g., \fBTrue\fP .TP .B lag_parent String of interface lag parent name, e.g., \fBae13\fP .TP .B form_factor Integer of form factor id, obtained through _choices API endpoint, e.g., \fB200\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_interface edge_router ae13 description=\(dqCore uplink\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_interface_connection(interface_a, interface_b) New in version 2019.2.0. .sp Create an interface connection between 2 interfaces .INDENT 7.0 .TP .B interface_a Interface id for Side A .TP .B interface_b Interface id for Side B .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_interface_connection 123 456 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_inventory_item(device_name, item_name, manufacturer_name=None, serial=\(aq\(aq, part_id=\(aq\(aq, description=\(aq\(aq) New in version 2019.2.0. .sp Add an inventory item to an existing device. .INDENT 7.0 .TP .B device_name The name of the device, e.g., \fBedge_router\fP\&. .TP .B item_name String of inventory item name, e.g., \fBTransceiver\fP\&. .TP .B manufacturer_name String of inventory item manufacturer, e.g., \fBFiberstore\fP\&. .TP .B serial String of inventory item serial, e.g., \fBFS1238931\fP\&. .TP .B part_id String of inventory item part id, e.g., \fB740\-01234\fP\&. .TP .B description String of inventory item description, e.g., \fBSFP+\-10G\-LR\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_inventory_item edge_router Transceiver part_id=740\-01234 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_ipaddress(ip_address, family, device=None, interface=None) New in version 2019.2.0. .sp Add an IP address, and optionally attach it to an interface. .INDENT 7.0 .TP .B ip_address The IP address and CIDR, e.g., \fB192.168.1.1/24\fP .TP .B family Integer of IP family, e.g., \fB4\fP .TP .B device The name of the device to attach IP to, e.g., \fBedge_router\fP .TP .B interface The name of the interface to attach IP to, e.g., \fBae13\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_ipaddress 192.168.1.1/24 4 device=edge_router interface=ae13 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_manufacturer(name) New in version 2019.2.0. .sp Create a device manufacturer. .INDENT 7.0 .TP .B name The name of the manufacturer, e.g., \fBJuniper\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_manufacturer Juniper .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_platform(platform) New in version 2019.2.0. .sp Create a new device platform .INDENT 7.0 .TP .B platform String of device platform, e.g., \fBjunos\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_platform junos .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.create_site(site) New in version 2019.2.0. .sp Create a new device site .INDENT 7.0 .TP .B site String of device site, e.g., \fBBRU\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.create_site BRU .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.delete_interface(device_name, interface_name) New in version 2019.2.0. .sp Delete an interface from a device. .INDENT 7.0 .TP .B device_name The name of the device, e.g., \fBedge_router\fP\&. .TP .B interface_name The name of the interface, e.g., \fBae13\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.delete_interface edge_router ae13 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.delete_inventory_item(item_id) New in version 2019.2.0. .sp Remove an item from a devices inventory. Identified by the netbox id .INDENT 7.0 .TP .B item_id Integer of item to be deleted .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.delete_inventory_item 1354 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.delete_ipaddress(ipaddr_id) New in version 2019.2.0. .sp Delete an IP address. IP addresses in Netbox are a combination of address and the interface it is assigned to. .INDENT 7.0 .TP .B id The Netbox id for the IP address. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.delete_ipaddress 9002 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.filter_(app, endpoint, **kwargs) Get a list of items from NetBox. .INDENT 7.0 .TP .B app String of netbox app, e.g., \fBdcim\fP, \fBcircuits\fP, \fBipam\fP .TP .B endpoint String of app endpoint, e.g., \fBsites\fP, \fBregions\fP, \fBdevices\fP .TP .B kwargs Optional arguments that can be used to filter. All filter keywords are available in Netbox, which can be found by surfing to the corresponding API endpoint, and clicking Filters. e.g., \fBrole=router\fP .UNINDENT .sp Returns a list of dictionaries .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.filter dcim devices status=1 role=router .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.get_(app, endpoint, id=None, **kwargs) Get a single item from NetBox. .INDENT 7.0 .TP .B app String of netbox app, e.g., \fBdcim\fP, \fBcircuits\fP, \fBipam\fP .TP .B endpoint String of app endpoint, e.g., \fBsites\fP, \fBregions\fP, \fBdevices\fP .UNINDENT .sp Returns a single dictionary .sp To get an item based on ID. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.get dcim devices id=123 .ft P .fi .UNINDENT .UNINDENT .sp Or using named arguments that correspond with accepted filters on the NetBox endpoint. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.get dcim devices name=my\-router .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.get_circuit_provider(name, asn=None) New in version 2019.2.0. .sp Get a circuit provider with a given name and optional ASN. .INDENT 7.0 .TP .B name The name of the circuit provider .TP .B asn The ASN of the circuit provider .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.get_circuit_provider Telia 1299 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.get_interfaces(device_name=None, **kwargs) New in version 2019.2.0. .sp Returns interfaces for a specific device using arbitrary netbox filters .INDENT 7.0 .TP .B device_name The name of the device, e.g., \fBedge_router\fP .TP .B kwargs Optional arguments to be used for filtering .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.get_interfaces edge_router name=\(dqet\-0/0/5\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.get_ipaddresses(device_name=None, **kwargs) New in version 2019.2.0. .sp Filters for an IP address using specified filters .INDENT 7.0 .TP .B device_name The name of the device to check for the IP address .TP .B kwargs Optional arguments that can be used to filter, e.g., \fBfamily=4\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.get_ipaddresses device_name family=4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.make_interface_child(device_name, interface_name, parent_name) New in version 2019.2.0. .sp Set an interface as part of a LAG. .INDENT 7.0 .TP .B device_name The name of the device, e.g., \fBedge_router\fP\&. .TP .B interface_name The name of the interface to be attached to LAG, e.g., \fBxe\-1/0/2\fP\&. .TP .B parent_name The name of the LAG interface, e.g., \fBae13\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.make_interface_child xe\-1/0/2 ae13 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.make_interface_lag(device_name, interface_name) New in version 2019.2.0. .sp Update an interface to be a LAG. .INDENT 7.0 .TP .B device_name The name of the device, e.g., \fBedge_router\fP\&. .TP .B interface_name The name of the interface, e.g., \fBae13\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.make_interface_lag edge_router ae13 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.openconfig_interfaces(device_name=None) New in version 2019.2.0. .sp Return a dictionary structured as standardised in the \fI\%openconfig\-interfaces\fP YANG model, containing physical and configuration data available in Netbox, e.g., IP addresses, MTU, enabled / disabled, etc. .INDENT 7.0 .TP .B device_name: \fBNone\fP The name of the device to query the interface data for. If not provided, will use the Minion ID. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netbox.openconfig_interfaces salt \(aq*\(aq netbox.openconfig_interfaces device_name=cr1.thn.lon .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.openconfig_lacp(device_name=None) New in version 2019.2.0. .sp Return a dictionary structured as standardised in the \fI\%openconfig\-lacp\fP YANG model, with configuration data for Link Aggregation Control Protocol (LACP) for aggregate interfaces. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fBinterval\fP and \fBlacp_mode\fP keys have the values set as \fBSLOW\fP and \fBACTIVE\fP respectively, as this data is not currently available in Netbox, therefore defaulting to the values defined in the standard. See \fI\%interval\fP and \fI\%lacp\-mode\fP for further details. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B device_name: \fBNone\fP The name of the device to query the LACP information for. If not provided, will use the Minion ID. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netbox.openconfig_lacp salt \(aq*\(aq netbox.openconfig_lacp device_name=cr1.thn.lon .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.slugify(value) \(aq Slugify given value. Credit to Djangoproject \fI\%https://docs.djangoproject.com/en/2.0/_modules/django/utils/text/#slugify\fP .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.update_device(name, **kwargs) New in version 2019.2.0. .sp Add attributes to an existing device, identified by name. .INDENT 7.0 .TP .B name The name of the device, e.g., \fBedge_router\fP .TP .B kwargs Arguments to change in device, e.g., \fBserial=JN2932930\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.update_device edge_router serial=JN2932920 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbox.update_interface(device_name, interface_name, **kwargs) New in version 2019.2.0. .sp Update an existing interface with new attributes. .INDENT 7.0 .TP .B device_name The name of the device, e.g., \fBedge_router\fP .TP .B interface_name The name of the interface, e.g., \fBae13\fP .TP .B kwargs Arguments to change in interface, e.g., \fBmac_address=50:87:69:53:32:D0\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion netbox.update_interface edge_router ae13 mac_address=50:87:69:53:32:D0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.netbsd_sysctl .sp Module for viewing and modifying sysctl parameters .INDENT 0.0 .TP .B salt.modules.netbsd_sysctl.assign(name, value) Assign a single sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.assign net.inet.icmp.icmplim 50 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsd_sysctl.get(name) Return a single sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.get hw.physmem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsd_sysctl.persist(name, value, config=\(aq/etc/sysctl.conf\(aq) Assign and persist a simple sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.persist net.inet.icmp.icmplim 50 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsd_sysctl.show(config_file=False) Return a list of sysctl parameters for this minion .INDENT 7.0 .TP .B config: Pull the data from the system configuration file instead of the live data. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.show .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.netbsdservice .sp The service module for NetBSD .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage services on a minion, and it is using a different module (or gives an error similar to \fI\(aqservice.start\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.disable(name, **kwargs) Disable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.disabled(name) Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.enable(name, **kwargs) Enable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.enabled(name, **kwargs) Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.force_reload(name) Force\-reload the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.force_reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.get_all() Return all available boot services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.get_disabled() Return a set of services that are installed but disabled .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.get_enabled() Return a list of service that are enabled on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.missing(name) The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.reload_(name) Reload the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.restart(name) Restart the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.start(name) Start the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.status(name, sig=None) Return the status for a service. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Signature to use to find the service via ps .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> [service signature] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netbsdservice.stop(name) Stop the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.netmiko_mod .SS Netmiko Execution Module .sp New in version 2019.2.0. .sp Execution module to interface the connection with a remote network device. It is flexible enough to execute the commands both when running under a Netmiko Proxy Minion, as well as running under a Regular Minion by specifying the connection arguments, i.e., \fBdevice_type\fP, \fBip\fP, \fBusername\fP, \fBpassword\fP etc. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> & Kirk Byers <\fI\%ktbyers@twb\-tech.com\fP> .TP .B maturity new .TP .B depends netmiko .TP .B platform unix .UNINDENT .SS Dependencies .sp The \fBnetmiko\fP proxy modules requires Netmiko to be installed: \fBpip install netmiko\fP\&. .SS Usage .sp This module can equally be used via the \fI\%netmiko\fP Proxy module (check documentation), or directly from an arbitrary (Proxy) Minion that is running on a server (computer) having access to the network device, and has the \fBnetmiko\fP library installed. .sp When running outside of the \fI\%netmiko Proxy\fP (i.e., from another Proxy Minion type, or regular Minion), the netmiko connection arguments can be either specified from the CLI when executing the command, or in a configuration block under the \fBnetmiko\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 \fBnetmiko\fP Proxy Module: .INDENT 0.0 .IP \(bu 2 \fBdevice_type\fP \- Class selection based on device type. Supported options: .INDENT 2.0 .IP \(bu 2 \fBa10\fP: A10 Networks .IP \(bu 2 \fBaccedian\fP: Accedian Networks .IP \(bu 2 \fBalcatel_aos\fP: Alcatel AOS .IP \(bu 2 \fBalcatel_sros\fP: Alcatel SROS .IP \(bu 2 \fBapresia_aeos\fP: Apresia AEOS .IP \(bu 2 \fBarista_eos\fP: Arista EOS .IP \(bu 2 \fBaruba_os\fP: Aruba .IP \(bu 2 \fBavaya_ers\fP: Avaya ERS .IP \(bu 2 \fBavaya_vsp\fP: Avaya VSP .IP \(bu 2 \fBbrocade_fastiron\fP: Brocade Fastiron .IP \(bu 2 \fBbrocade_netiron\fP: Brocade Netiron .IP \(bu 2 \fBbrocade_nos\fP: Brocade NOS .IP \(bu 2 \fBbrocade_vdx\fP: Brocade NOS .IP \(bu 2 \fBbrocade_vyos\fP: VyOS .IP \(bu 2 \fBcheckpoint_gaia\fP: Check Point GAiA .IP \(bu 2 \fBcalix_b6\fP: Calix B6 .IP \(bu 2 \fBciena_saos\fP: Ciena SAOS .IP \(bu 2 \fBcisco_asa\fP: Cisco SA .IP \(bu 2 \fBcisco_ios\fP: Cisco IOS .IP \(bu 2 \fBcisco_nxos\fP: Cisco NX\-oS .IP \(bu 2 \fBcisco_s300\fP: Cisco S300 .IP \(bu 2 \fBcisco_tp\fP: Cisco TpTcCe .IP \(bu 2 \fBcisco_wlc\fP: Cisco WLC .IP \(bu 2 \fBcisco_xe\fP: Cisco IOS .IP \(bu 2 \fBcisco_xr\fP: Cisco XR .IP \(bu 2 \fBcoriant\fP: Coriant .IP \(bu 2 \fBdell_force10\fP: Dell Force10 .IP \(bu 2 \fBdell_os10\fP: Dell OS10 .IP \(bu 2 \fBdell_powerconnect\fP: Dell PowerConnect .IP \(bu 2 \fBeltex\fP: Eltex .IP \(bu 2 \fBenterasys\fP: Enterasys .IP \(bu 2 \fBextreme\fP: Extreme .IP \(bu 2 \fBextreme_wing\fP: Extreme Wing .IP \(bu 2 \fBf5_ltm\fP: F5 LTM .IP \(bu 2 \fBfortinet\fP: Fortinet .IP \(bu 2 \fBgeneric_termserver\fP: TerminalServer .IP \(bu 2 \fBhp_comware\fP: HP Comware .IP \(bu 2 \fBhp_procurve\fP: HP Procurve .IP \(bu 2 \fBhuawei\fP: Huawei .IP \(bu 2 \fBhuawei_vrpv8\fP: Huawei VRPV8 .IP \(bu 2 \fBjuniper\fP: Juniper Junos .IP \(bu 2 \fBjuniper_junos\fP: Juniper Junos .IP \(bu 2 \fBlinux\fP: Linux .IP \(bu 2 \fBmellanox\fP: Mellanox .IP \(bu 2 \fBmrv_optiswitch\fP: MrvOptiswitch .IP \(bu 2 \fBnetapp_cdot\fP: NetAppcDot .IP \(bu 2 \fBnetscaler\fP: Netscaler .IP \(bu 2 \fBovs_linux\fP: OvsLinux .IP \(bu 2 \fBpaloalto_panos\fP: PaloAlto Panos .IP \(bu 2 \fBpluribus\fP: Pluribus .IP \(bu 2 \fBquanta_mesh\fP: Quanta Mesh .IP \(bu 2 \fBruckus_fastiron\fP: Ruckus Fastiron .IP \(bu 2 \fBubiquiti_edge\fP: Ubiquiti Edge .IP \(bu 2 \fBubiquiti_edgeswitch\fP: Ubiquiti Edge .IP \(bu 2 \fBvyatta_vyos\fP: VyOS .IP \(bu 2 \fBvyos\fP: VyOS .IP \(bu 2 \fBbrocade_fastiron_telnet\fP: Brocade Fastiron over Telnet .IP \(bu 2 \fBbrocade_netiron_telnet\fP: Brocade Netiron over Telnet .IP \(bu 2 \fBcisco_ios_telnet\fP: Cisco IOS over Telnet .IP \(bu 2 \fBapresia_aeos_telnet\fP: Apresia AEOS over Telnet .IP \(bu 2 \fBarista_eos_telnet\fP: Arista EOS over Telnet .IP \(bu 2 \fBhp_procurve_telnet\fP: HP Procurve over Telnet .IP \(bu 2 \fBhp_comware_telnet\fP: HP Comware over Telnet .IP \(bu 2 \fBjuniper_junos_telnet\fP: Juniper Junos over Telnet .IP \(bu 2 \fBcalix_b6_telnet\fP: Calix B6 over Telnet .IP \(bu 2 \fBdell_powerconnect_telnet\fP: Dell PowerConnect over Telnet .IP \(bu 2 \fBgeneric_termserver_telnet\fP: TerminalServer over Telnet .IP \(bu 2 \fBextreme_telnet\fP: Extreme Networks over Telnet .IP \(bu 2 \fBruckus_fastiron_telnet\fP: Ruckus Fastiron over Telnet .IP \(bu 2 \fBcisco_ios_serial\fP: Cisco IOS over serial port .UNINDENT .IP \(bu 2 \fBip\fP \- IP address of target device (not required if \fBhost\fP is provided) .IP \(bu 2 \fBhost\fP \- Hostname of target device (not required if \fBip\fP is provided) .IP \(bu 2 \fBusername\fP \- Username to authenticate against target device, if required .IP \(bu 2 \fBpassword\fP \- Password to authenticate against target device, if required .IP \(bu 2 \fBsecret\fP \- The enable password if target device requires one .IP \(bu 2 \fBport\fP \- The destination port used to connect to the target device .IP \(bu 2 \fBglobal_delay_factor\fP \- Multiplication factor affecting Netmiko delays (default: \fB1\fP) .IP \(bu 2 \fBuse_keys\fP \- Connect to target device using SSH keys (default: \fBFalse\fP) .IP \(bu 2 \fBkey_file\fP \- Filename path of the SSH key file to use .IP \(bu 2 \fBallow_agent\fP \- Enable use of SSH key\-agent .IP \(bu 2 \fBssh_strict\fP \- Automatically reject unknown SSH host keys (default: \fBFalse\fP, which means unknown SSH host keys will be accepted) .IP \(bu 2 \fBsystem_host_keys\fP \- Load host keys from the user\(aqs \(dqknown_hosts\(dq file (default: \fBFalse\fP) .IP \(bu 2 \fBalt_host_keys\fP \- If \fBTrue\fP, host keys will be loaded from the file specified in \fBalt_key_file\fP (default: \fBFalse\fP) .IP \(bu 2 \fBalt_key_file\fP \- SSH host key file to use (if \fBalt_host_keys=True\fP) .IP \(bu 2 \fBssh_config_file\fP \- File name of OpenSSH configuration file .IP \(bu 2 \fBtimeout\fP \- Connection timeout, in seconds (default: \fB90\fP) .IP \(bu 2 \fBsession_timeout\fP \- Set a timeout for parallel requests, in seconds (default: \fB60\fP) .IP \(bu 2 \fBkeepalive\fP \- Send SSH keepalive packets at a specific interval, in seconds. Currently defaults to \fB0\fP, for backwards compatibility (it will not attempt to keep the connection alive using the KEEPALIVE packets). .IP \(bu 2 \fBdefault_enter\fP \- Character(s) to send to correspond to enter key (default: \fB\en\fP) .IP \(bu 2 \fBresponse_return\fP \- Character(s) to use in normalized return data to represent enter key (default: \fB\en\fP) .UNINDENT .sp Example (when not running in a \fBnetmiko\fP Proxy Minion): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C netmiko: 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 \fBnetmiko\fP Proxy, e.g.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netmiko.send_command \(aqshow version\(aq host=router1.example.com device_type=juniper salt \(aq*\(aq netmiko.send_config https://bit.ly/2sgljCB host=sw2.example.com device_type=cisco_ios .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 \fBnetmiko\fP Proxy Minion. If you want to use the \fB<salt.proxy.netmiko_px>\fP, please follow the documentation notes for a proper setup. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netmiko_mod.call(method, *args, **kwargs) Invoke an arbitrary Netmiko method. .INDENT 7.0 .TP .B method The name of the Netmiko 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. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netmiko_mod.commit(**kwargs) Commit the configuration changes. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This function is supported only on the platforms that support the \fBcommit\fP operation. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netmiko.commit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netmiko_mod.enter_config_mode(**kwargs) Enter into config mode. .INDENT 7.0 .TP .B config_command Configuration command to send to the device. .TP .B pattern Pattern to terminate reading of channel. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netmiko.enter_config_mode salt \(aq*\(aq netmiko.enter_config_mode device_type=\(aqjuniper_junos\(aq ip=\(aq192.168.0.1\(aq username=\(aqexample\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netmiko_mod.exit_config_mode(**kwargs) Exit from configuration mode. .INDENT 7.0 .TP .B exit_config Command to exit configuration mode. .TP .B pattern Pattern to terminate reading of channel. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netmiko.exit_config_mode salt \(aq*\(aq netmiko.exit_config_mode device_type=\(aqjuniper\(aq ip=\(aq192.168.0.1\(aq username=\(aqexample\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netmiko_mod.get_connection(**kwargs) Return the Netmiko connection object. .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__[\(aqnetmiko.get_connection\(aq](host=\(aqrouter1.example.com\(aq, username=\(aqexample\(aq, password=\(aqexample\(aq) show_if = conn.send_command(\(aqshow interfaces\(aq) conn.disconnect() .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netmiko_mod.multi_call(*methods, **kwargs) Invoke multiple Netmiko methods at once, and return their output, as list. .INDENT 7.0 .TP .B methods A list of dictionaries with the following keys: .INDENT 7.0 .IP \(bu 2 \fBname\fP: the name of the Netmiko method to be executed. .IP \(bu 2 \fBargs\fP: list of arguments to be sent to the Netmiko method. .IP \(bu 2 \fBkwargs\fP: dictionary of arguments to be sent to the Netmiko method. .UNINDENT .TP .B kwargs Key\-value dictionary with the connection details (when not running under a Proxy Minion). .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netmiko_mod.send_command(command_string, **kwargs) Execute command_string on the SSH channel using a pattern\-based mechanism. Generally used for show commands. By default this method will keep waiting to receive data until the network device prompt is detected. The current network device prompt will be determined automatically. .INDENT 7.0 .TP .B command_string The command to be executed on the remote device. .TP .B expect_string Regular expression pattern to use for determining end of output. If left blank will default to being based on router prompt. .TP .B delay_factor: \fB1\fP Multiplying factor used to adjust delays (default: \fB1\fP). .TP .B max_loops: \fB500\fP Controls wait time in conjunction with delay_factor. Will default to be based upon self.timeout. .TP .B auto_find_prompt: \fBTrue\fP Whether it should try to auto\-detect the prompt (default: \fBTrue\fP). .TP .B strip_prompt: \fBTrue\fP Remove the trailing router prompt from the output (default: \fBTrue\fP). .TP .B strip_command: \fBTrue\fP Remove the echo of the command from the output (default: \fBTrue\fP). .TP .B normalize: \fBTrue\fP Ensure the proper enter is sent at end of command (default: \fBTrue\fP). .TP .B use_textfsm: \fBFalse\fP Process command output through TextFSM template (default: \fBFalse\fP). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netmiko.send_command \(aqshow version\(aq salt \(aq*\(aq netmiko.send_command \(aqshow_version\(aq host=\(aqrouter1.example.com\(aq username=\(aqexample\(aq device_type=\(aqcisco_ios\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netmiko_mod.send_command_timing(command_string, **kwargs) Execute command_string on the SSH channel using a delay\-based mechanism. Generally used for show commands. .INDENT 7.0 .TP .B command_string The command to be executed on the remote device. .TP .B delay_factor: \fB1\fP Multiplying factor used to adjust delays (default: \fB1\fP). .TP .B max_loops: \fB500\fP Controls wait time in conjunction with delay_factor. Will default to be based upon self.timeout. .TP .B strip_prompt: \fBTrue\fP Remove the trailing router prompt from the output (default: \fBTrue\fP). .TP .B strip_command: \fBTrue\fP Remove the echo of the command from the output (default: \fBTrue\fP). .TP .B normalize: \fBTrue\fP Ensure the proper enter is sent at end of command (default: \fBTrue\fP). .TP .B use_textfsm: \fBFalse\fP Process command output through TextFSM template (default: \fBFalse\fP). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netmiko.send_command_timing \(aqshow version\(aq salt \(aq*\(aq netmiko.send_command_timing \(aqshow version\(aq host=\(aqrouter1.example.com\(aq username=\(aqexample\(aq device_type=\(aqarista_eos\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netmiko_mod.send_config(config_file=None, config_commands=None, template_engine=\(aqjinja\(aq, commit=False, context=None, defaults=None, saltenv=\(aqbase\(aq, **kwargs) Send configuration commands down the SSH channel. Return the configuration lines sent to the device. .sp The function is flexible to send the configuration from a local or remote file, or simply the commands as list. .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 config_commands Multiple configuration commands to be sent to the device. .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 commit: \fBFalse\fP Commit the configuration changes before exiting the config mode. This option is by default disabled, as many platforms don\(aqt have this capability natively. .TP .B context Variables to add to the template context. .TP .B defaults Default values of the context_dict. .TP .B exit_config_mode: \fBTrue\fP Determines whether or not to exit config mode after complete. .TP .B delay_factor: \fB1\fP Factor to adjust delays. .TP .B max_loops: \fB150\fP Controls wait time in conjunction with delay_factor (default: \fB150\fP). .TP .B strip_prompt: \fBFalse\fP Determines whether or not to strip the prompt (default: \fBFalse\fP). .TP .B strip_command: \fBFalse\fP Determines whether or not to strip the command (default: \fBFalse\fP). .TP .B config_mode_command The command to enter into config mode. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netmiko.send_config config_commands=\(dq[\(aqinterface GigabitEthernet3\(aq, \(aqno ip address\(aq]\(dq salt \(aq*\(aq netmiko.send_config config_commands=\(dq[\(aqsnmp\-server location {{ grains.location }}\(aq]\(dq salt \(aq*\(aq netmiko.send_config config_file=salt://config.txt salt \(aq*\(aq netmiko.send_config config_file=https://bit.ly/2sgljCB device_type=\(aqcisco_ios\(aq ip=\(aq1.2.3.4\(aq username=\(aqexample\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.netscaler .sp Module to provide Citrix Netscaler compatibility to Salt (compatible with netscaler 9.2+) .sp New in version 2015.2.0. .INDENT 0.0 .TP .B depends .UNINDENT .INDENT 0.0 .IP \(bu 2 nsnitro Python module .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You can install nsnitro using: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install nsnitro .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B configuration This module accepts connection configuration details either as parameters, or as configuration settings in /etc/salt/minion on the relevant minions .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C netscaler.host: 1.2.3.4 netscaler.user: user netscaler.pass: password .ft P .fi .UNINDENT .UNINDENT .sp This data can also be passed into pillar. Options passed into opts will overwrite options passed into pillar. .UNINDENT .sp CLI Examples: .INDENT 0.0 .INDENT 3.5 Calls relying on configuration passed using /etc/salt/minion, grains, or pillars: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call netscaler.server_exists server_name .ft P .fi .UNINDENT .UNINDENT .sp Calls passing configuration as opts .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call netscaler.server_exists server_name netscaler_host=1.2.3.4 netscaler_user=username netscaler_pass=password salt\-call netscaler.server_exists server_name netscaler_host=1.2.3.5 netscaler_user=username2 netscaler_pass=password2 salt\-call netscaler.server_enable server_name2 netscaler_host=1.2.3.5 salt\-call netscaler.server_up server_name3 netscaler_host=1.2.3.6 netscaler_useSSL=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.server_add(s_name, s_ip, s_state=None, **connection_args) Add a server Note: The default server state is ENABLED .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.server_add \(aqserverName\(aq \(aqserverIpAddress\(aq salt \(aq*\(aq netscaler.server_add \(aqserverName\(aq \(aqserverIpAddress\(aq \(aqserverState\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.server_delete(s_name, **connection_args) Delete a server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.server_delete \(aqserverName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.server_disable(s_name, **connection_args) Disable a server globally .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.server_disable \(aqserverName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.server_enable(s_name, **connection_args) Enables a server globally .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.server_enable \(aqserverName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.server_enabled(s_name, **connection_args) Check if a server is enabled globally .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.server_enabled \(aqserverName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.server_exists(s_name, ip=None, s_state=None, **connection_args) Checks if a server exists .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.server_exists \(aqserverName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.server_update(s_name, s_ip, **connection_args) Update a server\(aqs attributes .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.server_update \(aqserverName\(aq \(aqserverIP\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.service_disable(s_name, s_delay=None, **connection_args) Disable a service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.service_disable \(aqserviceName\(aq salt \(aq*\(aq netscaler.service_disable \(aqserviceName\(aq \(aqdelayInSeconds\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.service_enable(s_name, **connection_args) Enable a service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.service_enable \(aqserviceName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.service_exists(s_name, **connection_args) Checks if a service exists .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.service_exists \(aqserviceName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.service_up(s_name, **connection_args) Checks if a service is UP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.service_up \(aqserviceName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.servicegroup_add(sg_name, sg_type=\(aqHTTP\(aq, **connection_args) Add a new service group If no service type is specified, HTTP will be used. Most common service types: HTTP, SSL, and SSL_BRIDGE .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.servicegroup_add \(aqserviceGroupName\(aq salt \(aq*\(aq netscaler.servicegroup_add \(aqserviceGroupName\(aq \(aqserviceGroupType\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.servicegroup_delete(sg_name, **connection_args) Delete a new service group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.servicegroup_delete \(aqserviceGroupName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.servicegroup_exists(sg_name, sg_type=None, **connection_args) Checks if a service group exists .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.servicegroup_exists \(aqserviceGroupName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.servicegroup_server_add(sg_name, s_name, s_port, **connection_args) Add a server:port member to a servicegroup .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.servicegroup_server_add \(aqserviceGroupName\(aq \(aqserverName\(aq \(aqserverPort\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.servicegroup_server_delete(sg_name, s_name, s_port, **connection_args) Remove a server:port member from a servicegroup .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.servicegroup_server_delete \(aqserviceGroupName\(aq \(aqserverName\(aq \(aqserverPort\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.servicegroup_server_disable(sg_name, s_name, s_port, **connection_args) Disable a server:port member of a servicegroup .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.servicegroup_server_disable \(aqserviceGroupName\(aq \(aqserverName\(aq \(aqserverPort\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.servicegroup_server_enable(sg_name, s_name, s_port, **connection_args) Enable a server:port member of a servicegroup .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.servicegroup_server_enable \(aqserviceGroupName\(aq \(aqserverName\(aq \(aqserverPort\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.servicegroup_server_exists(sg_name, s_name, s_port=None, **connection_args) Check if a server:port combination is a member of a servicegroup .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.servicegroup_server_exists \(aqserviceGroupName\(aq \(aqserverName\(aq \(aqserverPort\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.servicegroup_server_up(sg_name, s_name, s_port, **connection_args) Check if a server:port combination is in state UP in a servicegroup .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.servicegroup_server_up \(aqserviceGroupName\(aq \(aqserverName\(aq \(aqserverPort\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.vserver_add(v_name, v_ip, v_port, v_type, **connection_args) Add a new lb vserver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.vserver_add \(aqvserverName\(aq \(aqvserverIP\(aq \(aqvserverPort\(aq \(aqvserverType\(aq salt \(aq*\(aq netscaler.vserver_add \(aqalex.patate.chaude.443\(aq \(aq1.2.3.4\(aq \(aq443\(aq \(aqSSL\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.vserver_delete(v_name, **connection_args) Delete a lb vserver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.vserver_delete \(aqvserverName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.vserver_exists(v_name, v_ip=None, v_port=None, v_type=None, **connection_args) Checks if a vserver exists .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.vserver_exists \(aqvserverName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.vserver_servicegroup_add(v_name, sg_name, **connection_args) Bind a servicegroup to a vserver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.vserver_servicegroup_add \(aqvserverName\(aq \(aqserviceGroupName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.vserver_servicegroup_delete(v_name, sg_name, **connection_args) Unbind a servicegroup from a vserver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.vserver_servicegroup_delete \(aqvserverName\(aq \(aqserviceGroupName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.vserver_servicegroup_exists(v_name, sg_name, **connection_args) Checks if a servicegroup is tied to a vserver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.vserver_servicegroup_exists \(aqvserverName\(aq \(aqserviceGroupName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.vserver_sslcert_add(v_name, sc_name, **connection_args) Binds a SSL certificate to a vserver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.vserver_sslcert_add \(aqvserverName\(aq \(aqsslCertificateName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.vserver_sslcert_delete(v_name, sc_name, **connection_args) Unbinds a SSL certificate from a vserver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.vserver_sslcert_delete \(aqvserverName\(aq \(aqsslCertificateName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.netscaler.vserver_sslcert_exists(v_name, sc_name, **connection_args) Checks if a SSL certificate is tied to a vserver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq netscaler.vserver_sslcert_exists \(aqvserverName\(aq \(aqsslCertificateName\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.network .sp Module for gathering and managing network information .INDENT 0.0 .TP .B salt.modules.network.active_tcp() Return a dict containing information on all of the running TCP connections (currently linux and solaris only) .sp Changed in version 2015.8.4: Added support for SunOS .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.active_tcp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.arp() Return the arp table from the minion .sp Changed in version 2015.8.0: Added support for SunOS .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.arp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.calc_net(ip_addr, netmask=None) Returns the CIDR of a subnet based on an IP address (CIDR notation supported) and optional netmask. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.calc_net 172.17.0.5 255.255.255.240 salt \(aq*\(aq network.calc_net 2a02:f6e:a000:80:84d8:8332:7866:4e07/64 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.connect(host, port=None, **kwargs) Test connectivity to a host using a particular port from the minion. .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.connect archlinux.org 80 salt \(aq*\(aq network.connect archlinux.org 80 timeout=3 salt \(aq*\(aq network.connect archlinux.org 80 timeout=3 family=ipv4 salt \(aq*\(aq network.connect google\-public\-dns\-a.google.com port=53 proto=udp timeout=3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.convert_cidr(cidr) returns the network address, subnet mask and broadcast address of a cidr address .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.convert_cidr 172.31.0.0/16 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.default_route(family=None) Return default route(s) from routing table .sp Changed in version 2015.8.0: Added support for SunOS (Solaris 10, Illumos, SmartOS) .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.default_route .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.dig(host) Performs a DNS lookup with dig .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.dig archlinux.org .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.fqdns() Return all known FQDNs for the system by enumerating all interfaces and then trying to reverse resolve them (excluding \(aqlo\(aq interface). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.fqdns .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.get_bufsize(iface) Return network buffer sizes as a dict (currently linux only) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.get_bufsize eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.get_fqdn() Get fully qualified domain name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.get_fqdn .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.get_hostname() Get hostname .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.get_hostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.get_route(ip) Return routing information for given destination ip .sp New in version 2015.5.3. .sp Changed in version 2015.8.0: Added support for SunOS (Solaris 10, Illumos, SmartOS) Added support for OpenBSD .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.get_route 10.10.10.10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.hw_addr(iface) Return the hardware address (a.k.a. MAC address) for a given interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.hw_addr eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.hwaddr(iface) This function is an alias of \fBhw_addr\fP\&. .INDENT 7.0 .INDENT 3.5 Return the hardware address (a.k.a. MAC address) for a given interface .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.hw_addr eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ifacestartswith(cidr) Retrieve the interface name from a specific CIDR .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ifacestartswith 10.0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.in_subnet(cidr) Returns True if host is within specified subnet, otherwise False. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.in_subnet 10.0.0.0/16 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.interface(iface) Return the inet address for a given interface .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.interface eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.interface_ip(iface) Return the inet address for a given interface .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.interface_ip eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.interfaces() Return a dictionary of information about all the interfaces on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.interfaces .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ip_addrs(interface=None, include_loopback=False, cidr=None, type=None) Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is ignored, unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is provided, then only IP addresses from that interface will be returned. Providing a CIDR via \(aqcidr=\(dq10.0.0.0/8\(dq\(aq will return only the addresses which are within that subnet. If \(aqtype\(aq is \(aqpublic\(aq, then only public addresses will be returned. Ditto for \(aqtype\(aq=\(aqprivate\(aq. .sp Changed in version 3001: \fBinterface\fP can now be a single interface name or a list of interfaces. Globbing is also supported. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_addrs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ip_addrs6(interface=None, include_loopback=False, cidr=None) Returns a list of IPv6 addresses assigned to the host. ::1 is ignored, unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is provided, then only IP addresses from that interface will be returned. Providing a CIDR via \(aqcidr=\(dq2000::/3\(dq\(aq will return only the addresses which are within that subnet. .sp Changed in version 3001: \fBinterface\fP can now be a single interface name or a list of interfaces. Globbing is also supported. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_addrs6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ip_in_subnet(ip_addr, cidr) Returns True if given IP is within specified subnet, otherwise False. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_in_subnet 172.17.0.4 172.16.0.0/12 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ip_neighs() Return the ip neighbour (arp) table from the minion for IPv4 addresses .sp New in version 3007.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_neighs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ip_neighs6() Return the ip neighbour (arp) table from the minion for IPv6 addresses .sp New in version 3007.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_neighs6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ip_networks(interface=None, include_loopback=False, verbose=False) New in version 3001. .sp Returns a list of IPv4 networks to which the minion belongs. .INDENT 7.0 .TP .B interface Restrict results to the specified interface(s). This value can be either a single interface name or a list of interfaces. Globbing is also supported. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_networks salt \(aq*\(aq network.ip_networks interface=docker0 salt \(aq*\(aq network.ip_networks interface=docker0,enp* salt \(aq*\(aq network.ip_networks interface=eth* .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ip_networks6(interface=None, include_loopback=False, verbose=False) New in version 3001. .sp Returns a list of IPv6 networks to which the minion belongs. .INDENT 7.0 .TP .B interface Restrict results to the specified interface(s). This value can be either a single interface name or a list of interfaces. Globbing is also supported. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_networks6 salt \(aq*\(aq network.ip_networks6 interface=docker0 salt \(aq*\(aq network.ip_networks6 interface=docker0,enp* salt \(aq*\(aq network.ip_networks6 interface=eth* .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ipaddrs(interface=None, include_loopback=False, cidr=None, type=None) This function is an alias of \fBip_addrs\fP\&. .INDENT 7.0 .INDENT 3.5 Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is ignored, unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is provided, then only IP addresses from that interface will be returned. Providing a CIDR via \(aqcidr=\(dq10.0.0.0/8\(dq\(aq will return only the addresses which are within that subnet. If \(aqtype\(aq is \(aqpublic\(aq, then only public addresses will be returned. Ditto for \(aqtype\(aq=\(aqprivate\(aq. .sp Changed in version 3001: \fBinterface\fP can now be a single interface name or a list of interfaces. Globbing is also supported. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_addrs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ipaddrs6(interface=None, include_loopback=False, cidr=None) This function is an alias of \fBip_addrs6\fP\&. .INDENT 7.0 .INDENT 3.5 Returns a list of IPv6 addresses assigned to the host. ::1 is ignored, unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is provided, then only IP addresses from that interface will be returned. Providing a CIDR via \(aqcidr=\(dq2000::/3\(dq\(aq will return only the addresses which are within that subnet. .sp Changed in version 3001: \fBinterface\fP can now be a single interface name or a list of interfaces. Globbing is also supported. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_addrs6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.iphexval(ip) Retrieve the hexadecimal representation of an IP address .sp New in version 2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.iphexval 10.0.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ipneighs() This function is an alias of \fBip_neighs\fP\&. .INDENT 7.0 .INDENT 3.5 Return the ip neighbour (arp) table from the minion for IPv4 addresses .sp New in version 3007.0. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_neighs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ipneighs6() This function is an alias of \fBip_neighs6\fP\&. .INDENT 7.0 .INDENT 3.5 Return the ip neighbour (arp) table from the minion for IPv6 addresses .sp New in version 3007.0. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_neighs6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.is_loopback(ip_addr) Check if the given IP address is a loopback address .sp New in version 2014.7.0. .sp Changed in version 2015.8.0: IPv6 support .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.is_loopback 127.0.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.is_private(ip_addr) Check if the given IP address is a private address .sp New in version 2014.7.0. .sp Changed in version 2015.8.0: IPv6 support .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.is_private 10.0.0.3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.mod_bufsize(iface, *args, **kwargs) Modify network interface buffers (currently linux only) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.mod_bufsize tx=<val> rx=<val> rx\-mini=<val> rx\-jumbo=<val> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.mod_hostname(hostname) Modify hostname .sp Changed in version 2015.8.0: Added support for SunOS (Solaris 10, Illumos, SmartOS) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.mod_hostname master.saltstack.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.netstat() Return information on open ports and states .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On BSD minions, the output contains PID info (where available) for each netstat entry, fetched from sockstat/fstat output. .UNINDENT .UNINDENT .sp Changed in version 2014.1.4: Added support for OpenBSD, FreeBSD, and NetBSD .sp Changed in version 2015.8.0: Added support for SunOS .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.netstat .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ping(host, timeout=False, return_boolean=False) Performs an ICMP ping to a host .sp Changed in version 2015.8.0: Added support for SunOS .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ping archlinux.org .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.5.0. .sp Return a True or False instead of ping output. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ping archlinux.org return_boolean=True .ft P .fi .UNINDENT .UNINDENT .sp Set the time to wait for a response in seconds. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ping archlinux.org timeout=3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.reverse_ip(ip_addr) Returns the reversed IP address .sp Changed in version 2015.8.0: IPv6 support .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.reverse_ip 172.17.0.4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.routes(family=None) Return currently configured routes from routing table .sp Changed in version 2015.8.0: Added support for SunOS (Solaris 10, Illumos, SmartOS) .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.routes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.subnets(interfaces=None) Returns a list of IPv4 subnets to which the host belongs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.subnets salt \(aq*\(aq network.subnets interfaces=eth1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.subnets6() Returns a list of IPv6 subnets to which the host belongs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.subnets .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.traceroute(host) Performs a traceroute to a 3rd party host .sp Changed in version 2015.8.0: Added support for SunOS .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.traceroute archlinux.org .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.wol(mac, bcast=\(aq255.255.255.255\(aq, destport=9) Send Wake On Lan packet to a host .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.wol 08\-00\-27\-13\-69\-77 salt \(aq*\(aq network.wol 080027136977 255.255.255.255 7 salt \(aq*\(aq network.wol 08:00:27:13:69:77 255.255.255.255 7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.neutron .sp Module for handling OpenStack Neutron calls .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 neutronclient Python module .UNINDENT .TP .B configuration This module is not usable until the user, password, tenant, and auth URL are specified either in a pillar or in the minion\(aqs config file. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C keystone.user: \(aqadmin\(aq keystone.password: \(aqpassword\(aq keystone.tenant: \(aqadmin\(aq keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq keystone.region_name: \(aqRegionOne\(aq keystone.service_type: \(aqnetwork\(aq .ft P .fi .UNINDENT .UNINDENT .sp If configuration for multiple OpenStack accounts is required, they can be set up as different configuration profiles: For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C openstack1: keystone.user: \(aqadmin\(aq keystone.password: \(aqpassword\(aq keystone.tenant: \(aqadmin\(aq keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq keystone.region_name: \(aqRegionOne\(aq keystone.service_type: \(aqnetwork\(aq openstack2: keystone.user: \(aqadmin\(aq keystone.password: \(aqpassword\(aq keystone.tenant: \(aqadmin\(aq keystone.auth_url: \(aqhttp://127.0.0.2:5000/v2.0/\(aq keystone.region_name: \(aqRegionOne\(aq keystone.service_type: \(aqnetwork\(aq .ft P .fi .UNINDENT .UNINDENT .sp With this configuration in place, any of the neutron functions can make use of a configuration profile by declaring it explicitly. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.network_list profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .sp To use keystoneauth1 instead of keystoneclient, include the \fIuse_keystoneauth\fP option in the pillar or minion config. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 this is required to use keystone v3 as for authentication. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C keystone.user: admin keystone.password: verybadpass keystone.tenant: admin keystone.auth_url: \(aqhttp://127.0.0.1:5000/v3/\(aq keystone.region_name: \(aqRegionOne\(aq keystone.service_type: \(aqnetwork\(aq keystone.use_keystoneauth: true keystone.verify: \(aq/path/to/custom/certs/ca\-bundle.crt\(aq .ft P .fi .UNINDENT .UNINDENT .sp Note: by default the neutron module will attempt to verify its connection utilizing the system certificates. If you need to verify against another bundle of CA certificates or want to skip verification altogether you will need to specify the \fIverify\fP option. You can specify True or False to verify (or not) against system certificates, a path to a bundle or CA certs to check against, or None to allow keystoneauth to search for the certificates on its own.(defaults to True) .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.add_gateway_router(router, ext_network, profile=None) Adds an external network gateway to the specified router .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.add_gateway_router router\-name ext\-network\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrouter\fP \-\- ID or name of the router .IP \(bu 2 \fBext_network\fP \-\- ID or name of the external network the gateway .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Added Gateway router information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.add_interface_router(router, subnet, profile=None) Adds an internal network interface to the specified router .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.add_interface_router router\-name subnet\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrouter\fP \-\- ID or name of the router .IP \(bu 2 \fBsubnet\fP \-\- ID or name of the subnet .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Added interface information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.create_firewall_rule(protocol, action, profile=None, **kwargs) Creates a new firewall rule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.create_firewall_rule protocol action tenant_id=TENANT_ID name=NAME description=DESCRIPTION ip_version=IP_VERSION source_ip_address=SOURCE_IP_ADDRESS destination_ip_address=DESTINATION_IP_ADDRESS source_port=SOURCE_PORT destination_port=DESTINATION_PORT shared=SHARED enabled=ENABLED .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprotocol\fP \-\- Protocol for the firewall rule, choose \(dqtcp\(dq,\(dqudp\(dq,\(dqicmp\(dq or \(dqNone\(dq. .IP \(bu 2 \fBaction\fP \-\- Action for the firewall rule, choose \(dqallow\(dq or \(dqdeny\(dq. .IP \(bu 2 \fBtenant_id\fP \-\- The owner tenant ID. (Optional) .IP \(bu 2 \fBname\fP \-\- Name for the firewall rule. (Optional) .IP \(bu 2 \fBdescription\fP \-\- Description for the firewall rule. (Optional) .IP \(bu 2 \fBip_version\fP \-\- IP protocol version, default: 4. (Optional) .IP \(bu 2 \fBsource_ip_address\fP \-\- Source IP address or subnet. (Optional) .IP \(bu 2 \fBdestination_ip_address\fP \-\- Destination IP address or subnet. (Optional) .IP \(bu 2 \fBsource_port\fP \-\- Source port (integer in [1, 65535] or range in a:b). (Optional) .IP \(bu 2 \fBdestination_port\fP \-\- Destination port (integer in [1, 65535] or range in a:b). (Optional) .IP \(bu 2 \fBshared\fP \-\- Set shared to True, default: False. (Optional) .IP \(bu 2 \fBenabled\fP \-\- To enable this rule, default: True. (Optional) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.create_floatingip(floating_network, port=None, profile=None) Creates a new floatingIP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.create_floatingip network\-name port\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfloating_network\fP \-\- Network name or ID to allocate floatingIP from .IP \(bu 2 \fBport\fP \-\- Of the port to be associated with the floatingIP (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Created floatingIP information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.create_ikepolicy(name, profile=None, **kwargs) Creates a new IKEPolicy .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.create_ikepolicy ikepolicy\-name phase1_negotiation_mode=main auth_algorithm=sha1 encryption_algorithm=aes\-128 pfs=group5 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Name of the IKE policy .IP \(bu 2 \fBphase1_negotiation_mode\fP \-\- IKE Phase1 negotiation mode in lowercase, default: main (Optional) .IP \(bu 2 \fBauth_algorithm\fP \-\- Authentication algorithm in lowercase, default: sha1 (Optional) .IP \(bu 2 \fBencryption_algorithm\fP \-\- Encryption algorithm in lowercase. default:aes\-128 (Optional) .IP \(bu 2 \fBpfs\fP \-\- Prefect Forward Security in lowercase, default: group5 (Optional) .IP \(bu 2 \fBunits\fP \-\- IKE lifetime attribute. default: seconds (Optional) .IP \(bu 2 \fBvalue\fP \-\- IKE lifetime attribute. default: 3600 (Optional) .IP \(bu 2 \fBike_version\fP \-\- IKE version in lowercase, default: v1 (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .IP \(bu 2 \fBkwargs\fP \-\- .UNINDENT .TP .B Returns Created IKE policy information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.create_ipsec_site_connection(name, ipsecpolicy, ikepolicy, vpnservice, peer_cidrs, peer_address, peer_id, psk, admin_state_up=True, profile=None, **kwargs) Creates a new IPsecSiteConnection .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_ipsec_site_connection connection\-name ipsec\-policy\-name ikepolicy\-name vpnservice\-name 192.168.XXX.XXX/24 192.168.XXX.XXX 192.168.XXX.XXX secret .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Set friendly name for the connection .IP \(bu 2 \fBipsecpolicy\fP \-\- IPSec policy ID or name associated with this connection .IP \(bu 2 \fBikepolicy\fP \-\- IKE policy ID or name associated with this connection .IP \(bu 2 \fBvpnservice\fP \-\- VPN service instance ID or name associated with this connection .IP \(bu 2 \fBpeer_cidrs\fP \-\- Remote subnet(s) in CIDR format .IP \(bu 2 \fBpeer_address\fP \-\- Peer gateway public IPv4/IPv6 address or FQDN .IP \(bu 2 \fBpeer_id\fP \-\- Peer router identity for authentication Can be IPv4/IPv6 address, e\-mail address, key id, or FQDN .IP \(bu 2 \fBpsk\fP \-\- Pre\-shared key string .IP \(bu 2 \fBinitiator\fP \-\- Initiator state in lowercase, default:bi\-directional .IP \(bu 2 \fBadmin_state_up\fP \-\- Set admin state up to true or false, default: True (Optional) .IP \(bu 2 \fBmtu\fP \-\- size for the connection, default:1500 (Optional) .IP \(bu 2 \fBdpd_action\fP \-\- Dead Peer Detection attribute: hold/clear/disabled/ restart/restart\-by\-peer (Optional) .IP \(bu 2 \fBdpd_interval\fP \-\- Dead Peer Detection attribute (Optional) .IP \(bu 2 \fBdpd_timeout\fP \-\- Dead Peer Detection attribute (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Created IPSec site connection information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.create_ipsecpolicy(name, profile=None, **kwargs) Creates a new IPsecPolicy .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.create_ipsecpolicy ipsecpolicy\-name transform_protocol=esp auth_algorithm=sha1 encapsulation_mode=tunnel encryption_algorithm=aes\-128 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Name of the IPSec policy .IP \(bu 2 \fBtransform_protocol\fP \-\- Transform protocol in lowercase, default: esp (Optional) .IP \(bu 2 \fBauth_algorithm\fP \-\- Authentication algorithm in lowercase, default: sha1 (Optional) .IP \(bu 2 \fBencapsulation_mode\fP \-\- Encapsulation mode in lowercase, default: tunnel (Optional) .IP \(bu 2 \fBencryption_algorithm\fP \-\- Encryption algorithm in lowercase, default:aes\-128 (Optional) .IP \(bu 2 \fBpfs\fP \-\- Prefect Forward Security in lowercase, default: group5 (Optional) .IP \(bu 2 \fBunits\fP \-\- IPSec lifetime attribute. default: seconds (Optional) .IP \(bu 2 \fBvalue\fP \-\- IPSec lifetime attribute. default: 3600 (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Created IPSec policy information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.create_network(name, router_ext=None, admin_state_up=True, network_type=None, physical_network=None, segmentation_id=None, shared=None, profile=None) Creates a new network .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.create_network network\-name salt \(aq*\(aq neutron.create_network network\-name profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Name of network to create .IP \(bu 2 \fBadmin_state_up\fP \-\- should the state of the network be up? default: True (Optional) .IP \(bu 2 \fBrouter_ext\fP \-\- True then if create the external network (Optional) .IP \(bu 2 \fBnetwork_type\fP \-\- the Type of network that the provider is such as GRE, VXLAN, VLAN, FLAT, or LOCAL (Optional) .IP \(bu 2 \fBphysical_network\fP \-\- the name of the physical network as neutron knows it (Optional) .IP \(bu 2 \fBsegmentation_id\fP \-\- the vlan id or GRE id (Optional) .IP \(bu 2 \fBshared\fP \-\- is the network shared or not (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Created network information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.create_port(name, network, device_id=None, admin_state_up=True, profile=None) Creates a new port .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.create_port network\-name port\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Name of port to create .IP \(bu 2 \fBnetwork\fP \-\- Network name or ID .IP \(bu 2 \fBdevice_id\fP \-\- ID of device (Optional) .IP \(bu 2 \fBadmin_state_up\fP \-\- Set admin state up to true or false, default: true (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Created port information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.create_router(name, ext_network=None, admin_state_up=True, profile=None) Creates a new router .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.create_router new\-router\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Name of router to create (must be first) .IP \(bu 2 \fBext_network\fP \-\- ID or name of the external for the gateway (Optional) .IP \(bu 2 \fBadmin_state_up\fP \-\- Set admin state up to true or false, default:true (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Created router information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.create_security_group(name=None, description=None, profile=None) Creates a new security group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.create_security_group security\-group\-name description=\(aqSecurity group for servers\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Name of security group (Optional) .IP \(bu 2 \fBdescription\fP \-\- Description of security group (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Created security group information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.create_security_group_rule(security_group, remote_group_id=None, direction=\(aqingress\(aq, protocol=None, port_range_min=None, port_range_max=None, ethertype=\(aqIPv4\(aq, profile=None) Creates a new security group rule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_security_group_rule security\-group\-rule\-id .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsecurity_group\fP \-\- Security group name or ID to add rule .IP \(bu 2 \fBremote_group_id\fP \-\- Remote security group name or ID to apply rule (Optional) .IP \(bu 2 \fBdirection\fP \-\- Direction of traffic: ingress/egress, default: ingress (Optional) .IP \(bu 2 \fBprotocol\fP \-\- Protocol of packet: null/icmp/tcp/udp, default: null (Optional) .IP \(bu 2 \fBport_range_min\fP \-\- Starting port range (Optional) .IP \(bu 2 \fBport_range_max\fP \-\- Ending port range (Optional) .IP \(bu 2 \fBethertype\fP \-\- IPv4/IPv6, default: IPv4 (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Created security group rule information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.create_subnet(network, cidr, name=None, ip_version=4, profile=None) Creates a new subnet .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.create_subnet network\-name 192.168.1.0/24 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnetwork\fP \-\- Network ID or name this subnet belongs to .IP \(bu 2 \fBcidr\fP \-\- CIDR of subnet to create (Ex. \(aq192.168.1.0/24\(aq) .IP \(bu 2 \fBname\fP \-\- Name of the subnet to create (Optional) .IP \(bu 2 \fBip_version\fP \-\- Version to use, default is 4(IPv4) (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Created subnet information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.create_vpnservice(subnet, router, name, admin_state_up=True, profile=None) Creates a new VPN service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.create_vpnservice router\-name name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsubnet\fP \-\- Subnet unique identifier for the VPN service deployment .IP \(bu 2 \fBrouter\fP \-\- Router unique identifier for the VPN service .IP \(bu 2 \fBname\fP \-\- Set a name for the VPN service .IP \(bu 2 \fBadmin_state_up\fP \-\- Set admin state up to true or false, default:True (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Created VPN service information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_firewall_rule(firewall_rule, profile=None) Deletes the specified firewall_rule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.delete_firewall_rule firewall\-rule .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfirewall_rule\fP \-\- ID or name of firewall rule to delete .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_floatingip(floatingip_id, profile=None) Deletes the specified floating IP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.delete_floatingip floatingip\-id .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfloatingip_id\fP \-\- ID of floatingIP to delete .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_ikepolicy(ikepolicy, profile=None) Deletes the specified IKEPolicy .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.delete_ikepolicy ikepolicy\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBikepolicy\fP \-\- ID or name of IKE policy to delete .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_ipsec_site_connection(ipsec_site_connection, profile=None) Deletes the specified IPsecSiteConnection .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.delete_ipsec_site_connection connection\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBipsec_site_connection\fP \-\- ID or name of ipsec site connection to delete .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_ipsecpolicy(ipsecpolicy, profile=None) Deletes the specified IPsecPolicy .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.delete_ipsecpolicy ipsecpolicy\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBipsecpolicy\fP \-\- ID or name of IPSec policy to delete .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_network(network, profile=None) Deletes the specified network .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.delete_network network\-name salt \(aq*\(aq neutron.delete_network network\-name profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnetwork\fP \-\- ID or name of network to delete .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_port(port, profile=None) Deletes the specified port .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.delete_network port\-name salt \(aq*\(aq neutron.delete_network port\-name profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBport\fP \-\- port name or ID .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_quota(tenant_id, profile=None) Delete the specified tenant\(aqs quota value .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.update_quota tenant\-id salt \(aq*\(aq neutron.update_quota tenant\-id profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtenant_id\fP \-\- ID of tenant to quota delete .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Delete succeed) or False(Delete failed) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_router(router, profile=None) Delete the specified router .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.delete_router router\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrouter\fP \-\- ID or name of router to delete .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_security_group(security_group, profile=None) Deletes the specified security group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.delete_security_group security\-group\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsecurity_group\fP \-\- ID or name of security group to delete .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_security_group_rule(security_group_rule_id, profile=None) Deletes the specified security group rule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.delete_security_group_rule security\-group\-rule\-id .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsecurity_group_rule_id\fP \-\- ID of security group rule to delete .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_subnet(subnet, profile=None) Deletes the specified subnet .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.delete_subnet subnet\-name salt \(aq*\(aq neutron.delete_subnet subnet\-name profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsubnet\fP \-\- ID or name of subnet to delete .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.delete_vpnservice(vpnservice, profile=None) Deletes the specified VPN service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.delete_vpnservice vpnservice\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvpnservice\fP \-\- ID or name of vpn service to delete .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.get_quotas_tenant(profile=None) Fetches tenant info in server\(aqs context for following quota operation .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.get_quotas_tenant salt \(aq*\(aq neutron.get_quotas_tenant profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns Quotas information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_agents(profile=None) List agents. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_agents .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns agents message. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_extensions(profile=None) Fetches a list of all extensions on server side .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_extensions salt \(aq*\(aq neutron.list_extensions profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of extensions .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_firewall_rules(profile=None) Fetches a list of all firewall rules for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_firewall_rules .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of firewall rules .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_firewalls(profile=None) Fetches a list of all firewalls for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_firewalls .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of firewalls .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_floatingips(profile=None) Fetch a list of all floatingIPs for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_floatingips salt \(aq*\(aq neutron.list_floatingips profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of floatingIP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_ikepolicies(profile=None) Fetches a list of all configured IKEPolicies for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_ikepolicies salt \(aq*\(aq neutron.list_ikepolicies profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of IKE policy .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_ipsec_site_connections(profile=None) Fetches all configured IPsec Site Connections for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_ipsec_site_connections salt \(aq*\(aq neutron.list_ipsec_site_connections profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of IPSec site connection .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_ipsecpolicies(profile=None) Fetches a list of all configured IPsecPolicies for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_ipsecpolicies ipsecpolicy\-name salt \(aq*\(aq neutron.list_ipsecpolicies ipsecpolicy\-name profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of IPSec policy .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_l3_agent_hosting_routers(router, profile=None) List L3 agents hosting a router. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_l3_agent_hosting_routers router .ft P .fi .UNINDENT .UNINDENT .sp :param router:router name or ID to query. :param profile: Profile to build on (Optional) :return: L3 agents message. .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_networks(profile=None) Fetches a list of all networks for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_networks salt \(aq*\(aq neutron.list_networks profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of network .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_ports(profile=None) Fetches a list of all networks for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_ports salt \(aq*\(aq neutron.list_ports profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of port .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_quotas(profile=None) Fetches all tenants quotas .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_quotas salt \(aq*\(aq neutron.list_quotas profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of quotas .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_routers(profile=None) Fetches a list of all routers for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_routers salt \(aq*\(aq neutron.list_routers profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of router .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_security_group_rules(profile=None) Fetches a list of all security group rules for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_security_group_rules salt \(aq*\(aq neutron.list_security_group_rules profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of security group rule .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_security_groups(profile=None) Fetches a list of all security groups for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_security_groups salt \(aq*\(aq neutron.list_security_groups profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of security group .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_subnets(profile=None) Fetches a list of all networks for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_subnets salt \(aq*\(aq neutron.list_subnets profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprofile\fP \-\- Profile to build on (Optional) .TP .B Returns List of subnet .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.list_vpnservices(retrieve_all=True, profile=None, **kwargs) Fetches a list of all configured VPN services for a tenant .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.list_vpnservices .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBretrieve_all\fP \-\- True or False, default: True (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns List of VPN service .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.remove_gateway_router(router, profile=None) Removes an external network gateway from the specified router .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.remove_gateway_router router\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrouter\fP \-\- ID or name of router .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.remove_interface_router(router, subnet, profile=None) Removes an internal network interface from the specified router .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.remove_interface_router router\-name subnet\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrouter\fP \-\- ID or name of the router .IP \(bu 2 \fBsubnet\fP \-\- ID or name of the subnet .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns True(Succeed) or False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_firewall(firewall, profile=None) Fetches information of a specific firewall rule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_firewall firewall .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfirewall\fP \-\- ID or name of firewall to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns firewall information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_firewall_rule(firewall_rule, profile=None) Fetches information of a specific firewall rule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_firewall_rule firewall\-rule\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBipsecpolicy\fP \-\- ID or name of firewall rule to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns firewall rule information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_floatingip(floatingip_id, profile=None) Fetches information of a certain floatingIP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_floatingip floatingip\-id .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfloatingip_id\fP \-\- ID of floatingIP to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Floating IP information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_ikepolicy(ikepolicy, profile=None) Fetches information of a specific IKEPolicy .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_ikepolicy ikepolicy\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBikepolicy\fP \-\- ID or name of ikepolicy to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns IKE policy information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_ipsec_site_connection(ipsec_site_connection, profile=None) Fetches information of a specific IPsecSiteConnection .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_ipsec_site_connection connection\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBipsec_site_connection\fP \-\- ID or name of ipsec site connection to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns IPSec site connection information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_ipsecpolicy(ipsecpolicy, profile=None) Fetches information of a specific IPsecPolicy .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_ipsecpolicy ipsecpolicy\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBipsecpolicy\fP \-\- ID or name of IPSec policy to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns IPSec policy information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_network(network, profile=None) Fetches information of a certain network .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_network network\-name salt \(aq*\(aq neutron.show_network network\-name profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnetwork\fP \-\- ID or name of network to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Network information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_port(port, profile=None) Fetches information of a certain port .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_port port\-id salt \(aq*\(aq neutron.show_port port\-id profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBport\fP \-\- ID or name of port to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Port information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_quota(tenant_id, profile=None) Fetches information of a certain tenant\(aqs quotas .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_quota tenant\-id salt \(aq*\(aq neutron.show_quota tenant\-id profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtenant_id\fP \-\- ID of tenant .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Quota information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_router(router, profile=None) Fetches information of a certain router .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_router router\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrouter\fP \-\- ID or name of router to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Router information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_security_group(security_group, profile=None) Fetches information of a certain security group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_security_group security\-group\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsecurity_group\fP \-\- ID or name of security group to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Security group information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_security_group_rule(security_group_rule_id, profile=None) Fetches information of a certain security group rule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_security_group_rule security\-group\-rule\-id .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsecurity_group_rule_id\fP \-\- ID of security group rule to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Security group rule information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_subnet(subnet, profile=None) Fetches information of a certain subnet .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_subnet subnet\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsubnet\fP \-\- ID or name of subnet to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Subnet information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.show_vpnservice(vpnservice, profile=None, **kwargs) Fetches information of a specific VPN service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.show_vpnservice vpnservice\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvpnservice\fP \-\- ID or name of vpn service to look up .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns VPN service information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.update_firewall_rule(firewall_rule, protocol=None, action=None, name=None, description=None, ip_version=None, source_ip_address=None, destination_ip_address=None, source_port=None, destination_port=None, shared=None, enabled=None, profile=None) Update a firewall rule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.update_firewall_rule firewall_rule protocol=PROTOCOL action=ACTION name=NAME description=DESCRIPTION ip_version=IP_VERSION source_ip_address=SOURCE_IP_ADDRESS destination_ip_address=DESTINATION_IP_ADDRESS source_port=SOURCE_PORT destination_port=DESTINATION_PORT shared=SHARED enabled=ENABLED .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfirewall_rule\fP \-\- ID or name of firewall rule to update. .IP \(bu 2 \fBprotocol\fP \-\- Protocol for the firewall rule, choose \(dqtcp\(dq,\(dqudp\(dq,\(dqicmp\(dq or \(dqNone\(dq. (Optional) .IP \(bu 2 \fBaction\fP \-\- Action for the firewall rule, choose \(dqallow\(dq or \(dqdeny\(dq. (Optional) .IP \(bu 2 \fBname\fP \-\- Name for the firewall rule. (Optional) .IP \(bu 2 \fBdescription\fP \-\- Description for the firewall rule. (Optional) .IP \(bu 2 \fBip_version\fP \-\- IP protocol version, default: 4. (Optional) .IP \(bu 2 \fBsource_ip_address\fP \-\- Source IP address or subnet. (Optional) .IP \(bu 2 \fBdestination_ip_address\fP \-\- Destination IP address or subnet. (Optional) .IP \(bu 2 \fBsource_port\fP \-\- Source port (integer in [1, 65535] or range in a:b). (Optional) .IP \(bu 2 \fBdestination_port\fP \-\- Destination port (integer in [1, 65535] or range in a:b). (Optional) .IP \(bu 2 \fBshared\fP \-\- Set shared to True, default: False. (Optional) .IP \(bu 2 \fBenabled\fP \-\- To enable this rule, default: True. (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.update_floatingip(floatingip_id, port=None, profile=None) Updates a floatingIP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.update_floatingip network\-name port\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfloatingip_id\fP \-\- ID of floatingIP .IP \(bu 2 \fBport\fP \-\- ID or name of port, to associate floatingip to \fINone\fP or do not specify to disassociate the floatingip (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Value of updated floating IP information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.update_network(network, name, profile=None) Updates a network .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.update_network network\-name new\-network\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnetwork\fP \-\- ID or name of network to update .IP \(bu 2 \fBname\fP \-\- Name of this network .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Value of updated network information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.update_port(port, name, admin_state_up=True, profile=None) Updates a port .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.update_port port\-name network\-name new\-port\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBport\fP \-\- Port name or ID .IP \(bu 2 \fBname\fP \-\- Name of this port .IP \(bu 2 \fBadmin_state_up\fP \-\- Set admin state up to true or false, default: true (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Value of updated port information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.update_quota(tenant_id, subnet=None, router=None, network=None, floatingip=None, port=None, security_group=None, security_group_rule=None, profile=None) Update a tenant\(aqs quota .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.update_quota tenant\-id subnet=40 router=50 network=10 floatingip=30 port=30 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtenant_id\fP \-\- ID of tenant .IP \(bu 2 \fBsubnet\fP \-\- Value of subnet quota (Optional) .IP \(bu 2 \fBrouter\fP \-\- Value of router quota (Optional) .IP \(bu 2 \fBnetwork\fP \-\- Value of network quota (Optional) .IP \(bu 2 \fBfloatingip\fP \-\- Value of floatingip quota (Optional) .IP \(bu 2 \fBport\fP \-\- Value of port quota (Optional) .IP \(bu 2 \fBsecurity_group\fP \-\- Value of security group (Optional) .IP \(bu 2 \fBsecurity_group_rule\fP \-\- Value of security group rule (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Value of updated quota .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.update_router(router, name=None, admin_state_up=None, profile=None, **kwargs) Updates a router .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.update_router router_id name=new\-router\-name admin_state_up=True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrouter\fP \-\- ID or name of router to update .IP \(bu 2 \fBname\fP \-\- Name of this router .IP \(bu 2 \fBext_network\fP \-\- ID or name of the external for the gateway (Optional) .IP \(bu 2 \fBadmin_state_up\fP \-\- Set admin state up to true or false, default: true (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .IP \(bu 2 \fBkwargs\fP \-\- .UNINDENT .TP .B Returns Value of updated router information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.update_security_group(security_group, name=None, description=None, profile=None) Updates a security group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.update_security_group security\-group\-name new\-security\-group\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsecurity_group\fP \-\- ID or name of security group to update .IP \(bu 2 \fBname\fP \-\- Name of this security group (Optional) .IP \(bu 2 \fBdescription\fP \-\- Description of security group (Optional) .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Value of updated security group information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.update_subnet(subnet, name, profile=None) Updates a subnet .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.update_subnet subnet\-name new\-subnet\-name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsubnet\fP \-\- ID or name of subnet to update .IP \(bu 2 \fBname\fP \-\- Name of this subnet .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Value of updated subnet information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutron.update_vpnservice(vpnservice, desc, profile=None) Updates a VPN service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutron.update_vpnservice vpnservice\-name desc=\(aqVPN Service1\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvpnservice\fP \-\- ID or name of vpn service to update .IP \(bu 2 \fBdesc\fP \-\- Set a description for the VPN service .IP \(bu 2 \fBprofile\fP \-\- Profile to build on (Optional) .UNINDENT .TP .B Returns Value of updated VPN service information .UNINDENT .UNINDENT .SS salt.modules.neutronng .sp Neutron module for interacting with OpenStack Neutron .sp New in version 2018.3.0. .sp :depends:shade .sp Example configuration .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C neutron: cloud: default .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C neutron: auth: username: admin password: password123 user_domain_name: mydomain project_name: myproject project_domain_name: myproject auth_url: https://example.org:5000/v3 identity_api_version: 3 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.compare_changes(obj, **kwargs) Compare two dicts returning only keys that exist in the first dict and are different in the second one .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.get_openstack_cloud(auth=None) Return an openstack_cloud .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.get_operator_cloud(auth=None) Return an operator_cloud .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.list_networks(auth=None, **kwargs) List networks .INDENT 7.0 .TP .B filters A Python dictionary of filter conditions to push down .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.list_networks salt \(aq*\(aq neutronng.list_networks filters=\(aq{\(dqtenant_id\(dq: \(dq1dcac318a83b4610b7a7f7ba01465548\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.list_subnets(auth=None, **kwargs) List subnets .INDENT 7.0 .TP .B filters A Python dictionary of filter conditions to push down .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.list_subnets salt \(aq*\(aq neutronng.list_subnets filters=\(aq{\(dqtenant_id\(dq: \(dq1dcac318a83b4610b7a7f7ba01465548\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.network_create(auth=None, **kwargs) Create a network .INDENT 7.0 .TP .B name Name of the network being created .TP .B shared False If \fBTrue\fP, set the network as shared .TP .B admin_state_up True If \fBTrue\fP, Set the network administrative state to \(dqup\(dq .TP .B external False Control whether or not this network is externally accessible .TP .B provider An optional Python dictionary of network provider options .TP .B project_id The project ID on which this network will be created .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.network_create name=network2 shared=True admin_state_up=True external=True salt \(aq*\(aq neutronng.network_create name=network3 provider=\(aq{\(dqnetwork_type\(dq: \(dqvlan\(dq, \(dqsegmentation_id\(dq: \(dq4010\(dq, \(dqphysical_network\(dq: \(dqprovider\(dq}\(aq project_id=1dcac318a83b4610b7a7f7ba01465548 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.network_delete(auth=None, **kwargs) Delete a network .INDENT 7.0 .TP .B name_or_id Name or ID of the network being deleted .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.network_delete name_or_id=network1 salt \(aq*\(aq neutronng.network_delete name_or_id=1dcac318a83b4610b7a7f7ba01465548 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.network_get(auth=None, **kwargs) Get a single network .INDENT 7.0 .TP .B filters A Python dictionary of filter conditions to push down .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.network_get name=XLB4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.security_group_create(auth=None, **kwargs) Create a security group. Use security_group_get to create default. .INDENT 7.0 .TP .B project_id The project ID on which this security group will be created .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.security_group_create name=secgroup1 description=\(dqVery secure security group\(dq salt \(aq*\(aq neutronng.security_group_create name=secgroup1 description=\(dqVery secure security group\(dq project_id=1dcac318a83b4610b7a7f7ba01465548 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.security_group_delete(auth=None, **kwargs) Delete a security group .INDENT 7.0 .TP .B name_or_id The name or unique ID of the security group .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.security_group_delete name_or_id=secgroup1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.security_group_get(auth=None, **kwargs) Get a single security group. This will create a default security group if one does not exist yet for a particular project id. .INDENT 7.0 .TP .B filters A Python dictionary of filter conditions to push down .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.security_group_get name=1dcac318a83b4610b7a7f7ba01465548 salt \(aq*\(aq neutronng.security_group_get name=default filters=\(aq{\(dqtenant_id\(dq:\(dq2e778bb64ca64a199eb526b5958d8710\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.security_group_rule_create(auth=None, **kwargs) Create a rule in a security group .INDENT 7.0 .TP .B secgroup_name_or_id The security group name or ID to associate with this security group rule. If a non\-unique group name is given, an exception is raised. .TP .B port_range_min The minimum port number in the range that is matched by the security group rule. If the protocol is TCP or UDP, this value must be less than or equal to the port_range_max attribute value. If nova is used by the cloud provider for security groups, then a value of None will be transformed to \-1. .TP .B port_range_max The maximum port number in the range that is matched by the security group rule. The port_range_min attribute constrains the port_range_max attribute. If nova is used by the cloud provider for security groups, then a value of None will be transformed to \-1. .TP .B protocol The protocol that is matched by the security group rule. Valid values are \fBNone\fP, \fBtcp\fP, \fBudp\fP, and \fBicmp\fP\&. .TP .B remote_ip_prefix The remote IP prefix to be associated with this security group rule. This attribute matches the specified IP prefix as the source IP address of the IP packet. .TP .B remote_group_id The remote group ID to be associated with this security group rule .TP .B direction Either \fBingress\fP or \fBegress\fP; the direction in which the security group rule is applied. For a compute instance, an ingress security group rule is applied to incoming (ingress) traffic for that instance. An egress rule is applied to traffic leaving the instance .TP .B ethertype Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules .TP .B project_id Specify the project ID this security group will be created on (admin\-only) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.security_group_rule_create secgroup_name_or_id=secgroup1 salt \(aq*\(aq neutronng.security_group_rule_create secgroup_name_or_id=secgroup2 port_range_min=8080 port_range_max=8080 direction=\(aqegress\(aq salt \(aq*\(aq neutronng.security_group_rule_create secgroup_name_or_id=c0e1d1ce\-7296\-405e\-919d\-1c08217be529 protocol=icmp project_id=1dcac318a83b4610b7a7f7ba01465548 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.security_group_rule_delete(auth=None, **kwargs) Delete a security group .INDENT 7.0 .TP .B name_or_id The unique ID of the security group rule .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.security_group_rule_delete name_or_id=1dcac318a83b4610b7a7f7ba01465548 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.security_group_update(secgroup=None, auth=None, **kwargs) Update a security group .INDENT 7.0 .TP .B secgroup Name, ID or Raw Object of the security group to update .TP .B name New name for the security group .TP .B description New description for the security group .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.security_group_update secgroup=secgroup1 description=\(dqVery secure security group\(dq salt \(aq*\(aq neutronng.security_group_update secgroup=secgroup1 description=\(dqVery secure security group\(dq project_id=1dcac318a83b4610b7a7f7ba01465548 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.setup_clouds(auth=None) Call functions to create Shade cloud objects in __context__ to take advantage of Shade\(aqs in\-memory caching across several states .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.subnet_create(auth=None, **kwargs) Create a subnet .INDENT 7.0 .TP .B network_name_or_id The unique name or ID of the attached network. If a non\-unique name is supplied, an exception is raised. .TP .B cidr The CIDR .TP .B ip_version The IP version, which is 4 or 6. .TP .B enable_dhcp False Set to \fBTrue\fP if DHCP is enabled and \fBFalse\fP if disabled .TP .B subnet_name The name of the subnet .TP .B tenant_id The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own. .TP .B allocation_pools A list of dictionaries of the start and end addresses for the allocation pools. .TP .B gateway_ip The gateway IP address. When you specify both \fBallocation_pools\fP and \fBgateway_ip\fP, you must ensure that the gateway IP does not overlap with the specified allocation pools. .TP .B disable_gateway_ip False Set to \fBTrue\fP if gateway IP address is disabled and \fBFalse\fP if enabled. It is not allowed with \fBgateway_ip\fP\&. .TP .B dns_nameservers A list of DNS name servers for the subnet .TP .B host_routes A list of host route dictionaries for the subnet .TP .B ipv6_ra_mode IPv6 Router Advertisement mode. Valid values are \fBdhcpv6\-stateful\fP, \fBdhcpv6\-stateless\fP, or \fBslaac\fP\&. .TP .B ipv6_address_mode IPv6 address mode. Valid values are \fBdhcpv6\-stateful\fP, \fBdhcpv6\-stateless\fP, or \fBslaac\fP\&. .TP .B use_default_subnetpool If \fBTrue\fP, use the default subnetpool for \fBip_version\fP to obtain a CIDR. It is required to pass \fBNone\fP to the \fBcidr\fP argument when enabling this option. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.subnet_create network_name_or_id=network1 subnet_name=subnet1 salt \(aq*\(aq neutronng.subnet_create subnet_name=subnet2 network_name_or_id=network2 enable_dhcp=True allocation_pools=\(aq[{\(dqstart\(dq: \(dq192.168.199.2\(dq, \(dqend\(dq: \(dq192.168.199.254\(dq}]\(aq gateway_ip=\(aq192.168.199.1\(aq cidr=192.168.199.0/24 salt \(aq*\(aq neutronng.subnet_create network_name_or_id=network1 subnet_name=subnet1 dns_nameservers=\(aq[\(dq8.8.8.8\(dq, \(dq8.8.8.7\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.subnet_delete(auth=None, **kwargs) Delete a subnet .INDENT 7.0 .TP .B name Name or ID of the subnet to update .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.subnet_delete name=subnet1 salt \(aq*\(aq neutronng.subnet_delete name=1dcac318a83b4610b7a7f7ba01465548 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.subnet_get(auth=None, **kwargs) Get a single subnet .INDENT 7.0 .TP .B filters A Python dictionary of filter conditions to push down .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.subnet_get name=subnet1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.neutronng.subnet_update(auth=None, **kwargs) Update a subnet .INDENT 7.0 .TP .B name_or_id Name or ID of the subnet to update .TP .B subnet_name The new name of the subnet .TP .B enable_dhcp Set to \fBTrue\fP if DHCP is enabled and \fBFalse\fP if disabled .TP .B gateway_ip The gateway IP address. When you specify both allocation_pools and gateway_ip, you must ensure that the gateway IP does not overlap with the specified allocation pools. .TP .B disable_gateway_ip False Set to \fBTrue\fP if gateway IP address is disabled and False if enabled. It is not allowed with \fBgateway_ip\fP\&. .TP .B allocation_pools A list of dictionaries of the start and end addresses for the allocation pools. .TP .B dns_nameservers A list of DNS name servers for the subnet .TP .B host_routes A list of host route dictionaries for the subnet .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq neutronng.subnet_update name=subnet1 subnet_name=subnet2 salt \(aq*\(aq neutronng.subnet_update name=subnet1 dns_nameservers=\(aq[\(dq8.8.8.8\(dq, \(dq8.8.8.7\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nexus .sp Module for fetching artifacts from Nexus 3.x .sp New in version 2018.3.0. .INDENT 0.0 .TP .B salt.modules.nexus.get_latest_release(nexus_url, repository, group_id, artifact_id, packaging, target_dir=\(aq/tmp\(aq, target_file=None, classifier=None, username=None, password=None) Gets the latest release of the artifact .INDENT 7.0 .TP .B nexus_url URL of nexus instance .TP .B repository Release repository in nexus 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 nexus username. Optional parameter. .TP .B password nexus password. Optional parameter. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nexus.get_latest_snapshot(nexus_url, repository, group_id, artifact_id, packaging, target_dir=\(aq/tmp\(aq, target_file=None, classifier=None, username=None, password=None) Gets latest snapshot of the given artifact .INDENT 7.0 .TP .B nexus_url URL of nexus instance .TP .B repository Snapshot repository in nexus 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 nexus username. Optional parameter. .TP .B password nexus password. Optional parameter. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nexus.get_release(nexus_url, repository, group_id, artifact_id, packaging, version, target_dir=\(aq/tmp\(aq, target_file=None, classifier=None, username=None, password=None) Gets the specified release of the artifact .INDENT 7.0 .TP .B nexus_url URL of nexus instance .TP .B repository Release repository in nexus 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 nexus username. Optional parameter. .TP .B password nexus password. Optional parameter. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nexus.get_snapshot(nexus_url, repository, group_id, artifact_id, packaging, version, snapshot_version=None, target_dir=\(aq/tmp\(aq, target_file=None, classifier=None, username=None, password=None) Gets snapshot of the desired version of the artifact .INDENT 7.0 .TP .B nexus_url URL of nexus instance .TP .B repository Snapshot repository in nexus 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 nexus username. Optional parameter. .TP .B password nexus password. Optional parameter. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nexus.get_snapshot_version_string(nexus_url, repository, group_id, artifact_id, packaging, version, classifier=None, username=None, password=None) Gets the specific version string of a snapshot of the desired version of the artifact .INDENT 7.0 .TP .B nexus_url URL of nexus instance .TP .B repository Snapshot repository in nexus 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 classifier Artifact classifier name (ex: sources,javadoc,etc). Optional parameter. .TP .B username nexus username. Optional parameter. .TP .B password nexus password. Optional parameter. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B exception salt.modules.nexus.nexusError(value) .UNINDENT .SS salt.modules.nfs3 .sp Module for managing NFS version 3. .INDENT 0.0 .TP .B salt.modules.nfs3.add_export(exports=\(aq/etc/exports\(aq, path=None, hosts=None, options=None) Add an export .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nfs3.add_export path=\(aq/srv/test\(aq hosts=\(aq127.0.0.1\(aq options=[\(aqrw\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nfs3.del_export(exports=\(aq/etc/exports\(aq, path=None) Remove an export .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nfs.del_export /media/storage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nfs3.list_exports(exports=\(aq/etc/exports\(aq) List configured exports .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nfs.list_exports .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nfs3.reload_exports() Trigger a reload of the exports file to apply changes .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nfs3.reload_exports .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nftables .sp Support for nftables .INDENT 0.0 .TP .B salt.modules.nftables.append(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq) Append a rule to the specified table & chain. .INDENT 7.0 .TP .B This function accepts a rule in a standard nftables command format, starting with the chain. Trying to force users to adapt to a new method of creating rules would be irritating at best, and we already have a parser that can handle it. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.append filter input \e rule=\(aqtcp dport 22 log accept\(aq IPv6: salt \(aq*\(aq nftables.append filter input \e rule=\(aqtcp dport 22 log accept\(aq \e family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.build_rule(table=None, chain=None, command=None, position=\(aq\(aq, full=None, family=\(aqipv4\(aq, **kwargs) Build a well\-formatted nftables rule based on kwargs. A \fItable\fP and \fIchain\fP are not required, unless \fIfull\fP is True. .sp If \fIfull\fP is \fITrue\fP, then \fItable\fP, \fIchain\fP and \fIcommand\fP are required. \fIcommand\fP may be specified as either insert, append, or delete. This will return the nftables command, exactly as it would be used from the command line. .sp If a position is required (as with \fIinsert\fP or \fIdelete\fP), it may be specified as \fIposition\fP\&. This will only be useful if \fIfull\fP is True. .sp If \fIconnstate\fP is passed in, it will automatically be changed to \fIstate\fP\&. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.build_rule match=state \e connstate=RELATED,ESTABLISHED jump=ACCEPT salt \(aq*\(aq nftables.build_rule filter input command=insert position=3 \e full=True match=state state=related,established jump=accept IPv6: salt \(aq*\(aq nftables.build_rule match=state \e connstate=related,established jump=accept \e family=ipv6 salt \(aq*\(aq nftables.build_rule filter input command=insert position=3 \e full=True match=state state=related,established jump=accept \e family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.check(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq) Check for the existence of a rule in the table and chain .INDENT 7.0 .TP .B This function accepts a rule in a standard nftables command format, starting with the chain. Trying to force users to adapt to a new method of creating rules would be irritating at best, and we already have a parser that can handle it. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.check filter input \e rule=\(aqtcp dport 22 log accept\(aq IPv6: salt \(aq*\(aq nftables.check filter input \e rule=\(aqtcp dport 22 log accept\(aq \e family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.check_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) New in version 2014.7.0. .sp Check for the existence of a chain in the table .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.check_chain filter input IPv6: salt \(aq*\(aq nftables.check_chain filter input family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.check_table(table=None, family=\(aqipv4\(aq) Check for the existence of a table .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.check_table nat .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.delete(table, chain=None, position=None, rule=None, family=\(aqipv4\(aq) .INDENT 7.0 .TP .B Delete a rule from the specified table & chain, specifying either the rule in its entirety, or the rule\(aqs position in the chain. .TP .B This function accepts a rule in a standard nftables command format, starting with the chain. Trying to force users to adapt to a new method of creating rules would be irritating at best, and we already have a parser that can handle it. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.delete filter input position=3 salt \(aq*\(aq nftables.delete filter input \e rule=\(aqtcp dport 22 log accept\(aq IPv6: salt \(aq*\(aq nftables.delete filter input position=3 family=ipv6 salt \(aq*\(aq nftables.delete filter input \e rule=\(aqtcp dport 22 log accept\(aq \e family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.delete_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) New in version 2014.7.0. .sp Delete the chain from the specified table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.delete_chain filter input salt \(aq*\(aq nftables.delete_chain filter foo IPv6: salt \(aq*\(aq nftables.delete_chain filter input family=ipv6 salt \(aq*\(aq nftables.delete_chain filter foo family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.delete_table(table, family=\(aqipv4\(aq) New in version 2014.7.0. .sp Create new custom table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.delete_table filter IPv6: salt \(aq*\(aq nftables.delete_table filter family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.flush(table=\(aqfilter\(aq, chain=\(aq\(aq, family=\(aqipv4\(aq) Flush the chain in the specified table, flush all chains in the specified table if chain is not specified. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.flush filter salt \(aq*\(aq nftables.flush filter input IPv6: salt \(aq*\(aq nftables.flush filter input family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.get_policy(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) New in version 3002. .sp Return the current policy for the specified table/chain .INDENT 7.0 .TP .B table Name of the table containing the chain to check .TP .B chain Name of the chain to get the policy for .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.get_policy filter input IPv6: salt \(aq*\(aq nftables.get_policy filter input family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.get_rule_handle(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq) Get the handle for a particular rule .INDENT 7.0 .TP .B This function accepts a rule in a standard nftables command format, starting with the chain. Trying to force users to adapt to a new method of creating rules would be irritating at best, and we already have a parser that can handle it. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.get_rule_handle filter input \e rule=\(aqtcp dport 22 log accept\(aq IPv6: salt \(aq*\(aq nftables.get_rule_handle filter input \e rule=\(aqtcp dport 22 log accept\(aq \e family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.get_rules(family=\(aqipv4\(aq) Return a data structure of the current, in\-memory rules .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.get_rules salt \(aq*\(aq nftables.get_rules family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.get_rules_json(family=\(aqipv4\(aq) New in version 3002. .sp Return a list of dictionaries comprising the current, in\-memory rules .INDENT 7.0 .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.get_rules_json salt \(aq*\(aq nftables.get_rules_json family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.get_saved_rules(conf_file=None) Return a data structure of the rules in the conf file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.get_saved_rules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.insert(table=\(aqfilter\(aq, chain=None, position=None, rule=None, family=\(aqipv4\(aq) Insert a rule into the specified table & chain, at the specified position. .sp If position is not specified, rule will be inserted in first position. .INDENT 7.0 .TP .B This function accepts a rule in a standard nftables command format, starting with the chain. Trying to force users to adapt to a new method of creating rules would be irritating at best, and we already have a parser that can handle it. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.insert filter input \e rule=\(aqtcp dport 22 log accept\(aq salt \(aq*\(aq nftables.insert filter input position=3 \e rule=\(aqtcp dport 22 log accept\(aq IPv6: salt \(aq*\(aq nftables.insert filter input \e rule=\(aqtcp dport 22 log accept\(aq \e family=ipv6 salt \(aq*\(aq nftables.insert filter input position=3 \e rule=\(aqtcp dport 22 log accept\(aq \e family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.list_tables(family=\(aqipv4\(aq) Return a data structure of the current, in\-memory tables .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.list_tables salt \(aq*\(aq nftables.list_tables family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.new_chain(table=\(aqfilter\(aq, chain=None, table_type=None, hook=None, priority=None, family=\(aqipv4\(aq) New in version 2014.7.0. .sp Create new chain to the specified table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.new_chain filter input salt \(aq*\(aq nftables.new_chain filter input \e table_type=filter hook=input priority=0 salt \(aq*\(aq nftables.new_chain filter foo IPv6: salt \(aq*\(aq nftables.new_chain filter input family=ipv6 salt \(aq*\(aq nftables.new_chain filter input \e table_type=filter hook=input priority=0 family=ipv6 salt \(aq*\(aq nftables.new_chain filter foo family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.new_table(table, family=\(aqipv4\(aq) New in version 2014.7.0. .sp Create new custom table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.new_table filter IPv6: salt \(aq*\(aq nftables.new_table filter family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.save(filename=None, family=\(aqipv4\(aq) Changed in version 3002. .sp Save the current in\-memory rules to disk. On systems where /etc/nftables is a directory, a file named salt\-all\-in\-one.nft will be dropped inside by default. The main nftables configuration will need to include this file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.save /etc/nftables .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.set_policy(table=\(aqfilter\(aq, chain=None, policy=None, family=\(aqipv4\(aq) New in version 3002. .sp Set the current policy for the specified table/chain. This only works on chains with an existing base chain. .INDENT 7.0 .TP .B table Name of the table containing the chain to modify .TP .B chain Name of the chain to set the policy for .TP .B policy accept or drop .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.set_policy filter input accept IPv6: salt \(aq*\(aq nftables.set_policy filter input accept family=ipv6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nftables.version() Return version from nftables \-\-version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nftables.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nginx .sp Support for nginx .INDENT 0.0 .TP .B salt.modules.nginx.build_info() Return server and build arguments .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nginx.build_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nginx.configtest() test configuration and exit .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nginx.configtest .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nginx.signal(signal=None) Signals nginx to start, reload, reopen or stop. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nginx.signal reload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nginx.status(url=\(aqhttp://127.0.0.1/status\(aq) Return the data from an Nginx status page as a dictionary. \fI\%http://wiki.nginx.org/HttpStubStatusModule\fP .INDENT 7.0 .TP .B url The URL of the status page. Defaults to \(aq\fI\%http://127.0.0.1/status\fP\(aq .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nginx.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nginx.version() Return server version from nginx \-v .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nginx.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nilrt_ip .sp The networking module for NI Linux Real\-Time distro .INDENT 0.0 .TP .B salt.modules.nilrt_ip.apply_network_settings(**settings) Apply global network configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.apply_network_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.build_interface(iface, iface_type, enabled, **settings) Build an interface script for a network interface. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_interface eth0 eth <settings> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.build_network_settings(**settings) Build the global network script. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_network_settings <settings> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.disable(interface) Disable the specified interface .sp Change adapter mode to Disabled. If previous adapter mode was EtherCAT, the target will need reboot. .INDENT 7.0 .TP .B Parameters \fBinterface\fP (\fI\%str\fP) \-\- interface label .TP .B Returns True if the service was disabled, otherwise an exception will be thrown. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.disable interface\-label .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.down(interface, iface_type=None) Disable the specified interface .sp Change adapter mode to Disabled. If previous adapter mode was EtherCAT, the target will need reboot. .INDENT 7.0 .TP .B Parameters \fBinterface\fP (\fI\%str\fP) \-\- interface label .TP .B Returns True if the service was disabled, otherwise an exception will be thrown. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.down interface\-label .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.enable(interface) Enable the specified interface .sp Change adapter mode to TCP/IP. If previous adapter mode was EtherCAT, the target will need reboot. .INDENT 7.0 .TP .B Parameters \fBinterface\fP (\fI\%str\fP) \-\- interface label .TP .B Returns True if the service was enabled, otherwise an exception will be thrown. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.enable interface\-label .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.get_interface(iface) Returns details about given interface. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_interface eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.get_interfaces_details() Get details about all the interfaces on the minion .INDENT 7.0 .TP .B Returns information about all interfaces omitting loopback .TP .B Return type dictionary .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_interfaces_details .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.get_network_settings() Return the contents of the global network script. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_network_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.set_dhcp_linklocal_all(interface) Configure specified adapter to use DHCP with linklocal fallback .sp Change adapter mode to TCP/IP. If previous adapter mode was EtherCAT, the target will need reboot. .INDENT 7.0 .TP .B Parameters \fBinterface\fP (\fI\%str\fP) \-\- interface label .TP .B Returns True if the settings were applied, otherwise an exception will be thrown. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.set_dhcp_linklocal_all interface\-label .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.set_dhcp_only_all(interface) Configure specified adapter to use DHCP only .sp Change adapter mode to TCP/IP. If previous adapter mode was EtherCAT, the target will need reboot. .INDENT 7.0 .TP .B Parameters \fBinterface\fP (\fI\%str\fP) \-\- interface label .TP .B Returns True if the settings were applied, otherwise an exception will be thrown. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.dhcp_only_all interface\-label .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.set_ethercat(interface, master_id) Configure specified adapter to use EtherCAT adapter mode. If successful, the target will need reboot if it doesn\(aqt already use EtherCAT adapter mode, otherwise will return true. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBinterface\fP \-\- interface label .IP \(bu 2 \fBmaster_id\fP \-\- EtherCAT Master ID .UNINDENT .TP .B Returns True if the settings were applied, otherwise an exception will be thrown. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.set_ethercat interface\-label master\-id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.set_linklocal_only_all(interface) Configure specified adapter to use linklocal only .sp Change adapter mode to TCP/IP. If previous adapter mode was EtherCAT, the target will need reboot. .INDENT 7.0 .TP .B Parameters \fBinterface\fP (\fI\%str\fP) \-\- interface label .TP .B Returns True if the settings were applied, otherwise an exception will be thrown. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.linklocal_only_all interface\-label .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.set_static_all(interface, address, netmask, gateway, nameservers=None) Configure specified adapter to use ipv4 manual settings .sp Change adapter mode to TCP/IP. If previous adapter mode was EtherCAT, the target will need reboot. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBinterface\fP (\fI\%str\fP) \-\- interface label .IP \(bu 2 \fBaddress\fP (\fI\%str\fP) \-\- ipv4 address .IP \(bu 2 \fBnetmask\fP (\fI\%str\fP) \-\- ipv4 netmask .IP \(bu 2 \fBgateway\fP (\fI\%str\fP) \-\- ipv4 gateway .IP \(bu 2 \fBnameservers\fP (\fI\%str\fP) \-\- list of nameservers servers separated by spaces (Optional) .UNINDENT .TP .B Returns True if the settings were applied, otherwise an exception will be thrown. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.set_static_all interface\-label address netmask gateway nameservers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nilrt_ip.up(interface, iface_type=None) Enable the specified interface .sp Change adapter mode to TCP/IP. If previous adapter mode was EtherCAT, the target will need reboot. .INDENT 7.0 .TP .B Parameters \fBinterface\fP (\fI\%str\fP) \-\- interface label .TP .B Returns True if the service was enabled, otherwise an exception will be thrown. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.up interface\-label .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nix .SS Work with Nix packages .sp New in version 2017.7.0. .sp Does not require the machine to be Nixos, just have Nix installed and available to use for the user running this command. Their profile must be located in their home, under \fB$HOME/.nix\-profile/\fP, and the nix store, unless specially set up, should be in \fB/nix\fP\&. To easily use this with multiple users or a root user, set up the \fI\%nix\-daemon\fP\&. .sp This module exposes most of the common nix operations. Currently not meant to be run as a \fBpkg\fP module, but explicitly as \fBnix.*\fP\&. .sp For more information on nix, see the \fI\%nix documentation\fP\&. .INDENT 0.0 .TP .B salt.modules.nix.collect_garbage() Completely removed all currently \(aquninstalled\(aq packages in the nix store. .sp Tells the user how many store paths were removed and how much space was freed. .INDENT 7.0 .TP .B Returns How much space was freed and how many derivations were removed .TP .B Return type \fI\%str\fP .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This is a destructive action on the nix store. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nix.collect_garbage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nix.install(*pkgs, **kwargs) Installs a single or multiple packages via nix .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpkgs\fP (\fI\%list\fP\fI(\fP\fI\%str\fP\fI)\fP) \-\- packages to update .IP \(bu 2 \fBattributes\fP (\fI\%bool\fP) \-\- Pass the list of packages or single package as attribues, not package names. default: False .UNINDENT .TP .B Returns Installed packages. Example element: \fBgcc\-3.3.2\fP .TP .B Return type \fI\%list\fP(\fI\%str\fP) .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nix.install package [package2 ...] salt \(aq*\(aq nix.install attributes=True attr.name [attr.name2 ...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nix.list_pkgs(installed=True, attributes=True) Lists installed packages. Due to how nix works, it defaults to just doing a \fBnix\-env \-q\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBinstalled\fP (\fI\%bool\fP) \-\- list only installed packages. This can be a very long list (12,000+ elements), so caution is advised. Default: True .IP \(bu 2 \fBattributes\fP (\fI\%bool\fP) \-\- show the attributes of the packages when listing all packages. Default: True .UNINDENT .TP .B Returns Packages installed or available, along with their attributes. .TP .B Return type \fI\%list\fP(\fI\%list\fP(\fI\%str\fP)) .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nix.list_pkgs salt \(aq*\(aq nix.list_pkgs installed=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nix.uninstall(*pkgs) Erases a package from the current nix profile. Nix uninstalls work differently than other package managers, and the symlinks in the profile are removed, while the actual package remains. There is also a \fBnix.purge\fP function, to clear the package cache of unused packages. .INDENT 7.0 .TP .B Parameters \fBpkgs\fP (\fI\%list\fP\fI(\fP\fI\%str\fP\fI)\fP) \-\- List, single package to uninstall .TP .B Returns Packages that have been uninstalled .TP .B Return type \fI\%list\fP(\fI\%str\fP) .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nix.uninstall pkg1 [pkg2 ...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nix.upgrade(*pkgs) Runs an update operation on the specified packages, or all packages if none is specified. .INDENT 7.0 .TP .B Parameters \fBpkgs\fP (\fI\%list\fP\fI(\fP\fI\%str\fP\fI)\fP) \-\- List of packages to update .TP .B Returns The upgraded packages. Example element: \fB[\(aqlibxslt\-1.1.0\(aq, \(aqlibxslt\-1.1.10\(aq]\fP .TP .B Return type \fI\%list\fP(\fI\%tuple\fP(\fI\%str\fP, \fI\%str\fP)) .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nix.update salt \(aq*\(aq nix.update pkgs=one,two .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nova .sp Module for handling OpenStack Nova calls .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 novaclient Python module .UNINDENT .TP .B configuration This module is not usable until the user, password, tenant, and auth URL are specified either in a pillar or in the minion\(aqs config file. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C keystone.user: admin keystone.password: verybadpass keystone.tenant: admin keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq # Optional keystone.region_name: \(aqRegionOne\(aq .ft P .fi .UNINDENT .UNINDENT .sp If configuration for multiple OpenStack accounts is required, they can be set up as different configuration profiles: For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C openstack1: keystone.user: admin keystone.password: verybadpass keystone.tenant: admin keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq openstack2: keystone.user: admin keystone.password: verybadpass keystone.tenant: admin keystone.auth_url: \(aqhttp://127.0.0.2:5000/v2.0/\(aq .ft P .fi .UNINDENT .UNINDENT .sp With this configuration in place, any of the nova functions can make use of a configuration profile by declaring it explicitly. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.flavor_list profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .sp To use keystoneauth1 instead of keystoneclient, include the \fIuse_keystoneauth\fP option in the pillar or minion config. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is required to use keystone v3 as for authentication. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C keystone.user: admin keystone.password: verybadpass keystone.tenant: admin keystone.auth_url: \(aqhttp://127.0.0.1:5000/v3/\(aq keystone.use_keystoneauth: true keystone.verify: \(aq/path/to/custom/certs/ca\-bundle.crt\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 By default the nova module will attempt to verify its connection utilizing the system certificates. If you need to verify against another bundle of CA certificates or want to skip verification altogether you will need to specify the \fIverify\fP option. You can specify True or False to verify (or not) against system certificates, a path to a bundle or CA certs to check against, or None to allow keystoneauth to search for the certificates on its own. (defaults to True) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.boot(name, flavor_id=0, image_id=0, profile=None, timeout=300) Boot (create) a new instance .INDENT 7.0 .TP .B name Name of the new instance (must be first) .TP .B flavor_id Unique integer ID for the flavor .TP .B image_id Unique integer ID for the image .TP .B timeout How long to wait, after creating the instance, for the provider to return information about it (default 300 seconds). .sp New in version 2014.1.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.boot myinstance flavor_id=4596 image_id=2 .ft P .fi .UNINDENT .UNINDENT .sp The flavor_id and image_id are obtained from nova.flavor_list and nova.image_list .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.flavor_list salt \(aq*\(aq nova.image_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.delete(instance_id, profile=None) Delete an instance .INDENT 7.0 .TP .B instance_id ID of the instance to be deleted .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.delete 1138 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.flavor_create(name, flavor_id=0, ram=0, disk=0, vcpus=1, profile=None) Add a flavor to nova (nova flavor\-create). The following parameters are required: .INDENT 7.0 .TP .B name Name of the new flavor (must be first) .TP .B flavor_id Unique integer ID for the new flavor .TP .B ram Memory size in MB .TP .B disk Disk size in GB .TP .B vcpus Number of vcpus .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.flavor_create myflavor flavor_id=6 ram=4096 disk=10 vcpus=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.flavor_delete(flavor_id, profile=None) Delete a flavor from nova by id (nova flavor\-delete) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.flavor_delete 7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.flavor_list(profile=None) Return a list of available flavors (nova flavor\-list) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.flavor_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.image_list(name=None, profile=None) Return a list of available images (nova images\-list + nova image\-show) If a name is provided, only that image will be displayed. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.image_list salt \(aq*\(aq nova.image_list myimage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.image_meta_delete(image_id=None, name=None, keys=None, profile=None) Delete a key=value pair from the metadata for an image (nova image\-meta set) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.image_meta_delete 6f52b2ff\-0b31\-4d84\-8fd1\-af45b84824f6 keys=cheese salt \(aq*\(aq nova.image_meta_delete name=myimage keys=salad,beans .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.image_meta_set(image_id=None, name=None, profile=None, **kwargs) Sets a key=value pair in the metadata for an image (nova image\-meta set) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.image_meta_set 6f52b2ff\-0b31\-4d84\-8fd1\-af45b84824f6 cheese=gruyere salt \(aq*\(aq nova.image_meta_set name=myimage salad=pasta beans=baked .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.keypair_add(name, pubfile=None, pubkey=None, profile=None) Add a keypair to nova (nova keypair\-add) .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.keypair_add mykey pubfile=/home/myuser/.ssh/id_rsa.pub salt \(aq*\(aq nova.keypair_add mykey pubkey=\(aqssh\-rsa <key> myuser@mybox\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.keypair_delete(name, profile=None) Add a keypair to nova (nova keypair\-delete) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.keypair_delete mykey .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.keypair_list(profile=None) Return a list of available keypairs (nova keypair\-list) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.keypair_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.list_(profile=None) To maintain the feel of the nova command line, this function simply calls the server_list function. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.lock(instance_id, profile=None) Lock an instance .INDENT 7.0 .TP .B instance_id ID of the instance to be locked .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.lock 1138 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.resume(instance_id, profile=None) Resume an instance .INDENT 7.0 .TP .B instance_id ID of the instance to be resumed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.resume 1138 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.secgroup_create(name, description, profile=None) Add a secgroup to nova (nova secgroup\-create) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.secgroup_create mygroup \(aqThis is my security group\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.secgroup_delete(name, profile=None) Delete a secgroup to nova (nova secgroup\-delete) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.secgroup_delete mygroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.secgroup_list(profile=None) Return a list of available security groups (nova items\-list) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.secgroup_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.server_by_name(name, profile=None) Return information about a server .INDENT 7.0 .TP .B name Server Name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.server_by_name myserver profile=openstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.server_list(profile=None) Return list of active servers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.server_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.server_list_detailed(profile=None) Return detailed list of active servers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.server_list_detailed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.server_show(server_id, profile=None) Return detailed information for an active server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.server_show <server_id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.show(server_id, profile=None) To maintain the feel of the nova command line, this function simply calls the server_show function. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.show .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.suspend(instance_id, profile=None) Suspend an instance .INDENT 7.0 .TP .B instance_id ID of the instance to be suspended .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.suspend 1138 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.volume_attach(name, server_name, device=\(aq/dev/xvdb\(aq, profile=None, timeout=300) Attach a block storage volume .INDENT 7.0 .TP .B name Name of the new volume to attach .TP .B server_name Name of the server to attach to .TP .B device Name of the device on the server .TP .B profile Profile to build on .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.volume_attach myblock slice.example.com profile=openstack salt \(aq*\(aq nova.volume_attach myblock server.example.com device=\(aq/dev/xvdb\(aq profile=openstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.volume_create(name, size=100, snapshot=None, voltype=None, profile=None) Create a block storage volume .INDENT 7.0 .TP .B name Name of the new volume (must be first) .TP .B size Volume size .TP .B snapshot Block storage snapshot id .TP .B voltype Type of storage .TP .B profile Profile to build on .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.volume_create myblock size=300 profile=openstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.volume_delete(name, profile=None) Destroy the volume .INDENT 7.0 .TP .B name Name of the volume .TP .B profile Profile to build on .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.volume_delete myblock profile=openstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.volume_detach(name, profile=None, timeout=300) Attach a block storage volume .INDENT 7.0 .TP .B name Name of the new volume to attach .TP .B server_name Name of the server to detach from .TP .B profile Profile to build on .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.volume_detach myblock profile=openstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.volume_list(search_opts=None, profile=None) List storage volumes .INDENT 7.0 .TP .B search_opts Dictionary of search options .TP .B profile Profile to use .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.volume_list search_opts=\(aq{\(dqdisplay_name\(dq: \(dqmyblock\(dq}\(aq profile=openstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nova.volume_show(name, profile=None) Create a block storage volume .INDENT 7.0 .TP .B name Name of the volume .TP .B profile Profile to use .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nova.volume_show myblock profile=openstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.npm .sp Manage and query NPM packages. .INDENT 0.0 .TP .B salt.modules.npm.cache_clean(path=None, runas=None, env=None, force=False) Clean cached NPM packages. .sp If no path for a specific package is provided the entire cache will be cleared. .INDENT 7.0 .TP .B path The cache subpath to delete, or None to clear the entire cache .TP .B runas The user to run NPM with .TP .B env Environment variables to set when invoking npm. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function. .TP .B force Force cleaning of cache. Required for npm@5 and greater .sp New in version 2016.11.6. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq npm.cache_clean force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.npm.cache_list(path=None, runas=None, env=None) List NPM cached packages. .sp If no path for a specific package is provided this will list all the cached packages. .INDENT 7.0 .TP .B path The cache subpath to list, or None to list the entire cache .TP .B runas The user to run NPM with .TP .B env Environment variables to set when invoking npm. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq npm.cache_clean .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.npm.cache_path(runas=None, env=None) List path of the NPM cache directory. .INDENT 7.0 .TP .B runas The user to run NPM with .TP .B env Environment variables to set when invoking npm. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq npm.cache_path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.npm.install(pkg=None, pkgs=None, dir=None, runas=None, registry=None, env=None, dry_run=False, silent=True) Install an NPM package. .sp If no directory is specified, the package will be installed globally. If no package is specified, the dependencies (from package.json) of the package in the given directory will be installed. .INDENT 7.0 .TP .B pkg A package name in any format accepted by NPM, including a version identifier .TP .B pkgs A list of package names in the same format as the \fBname\fP parameter .sp New in version 2014.7.0. .TP .B dir The target directory in which to install the package, or None for global installation .TP .B runas The user to run NPM with .TP .B registry The NPM registry to install the package from. .sp New in version 2014.7.0. .TP .B env Environment variables to set when invoking npm. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function. .sp New in version 2014.7.0. .TP .B silent Whether or not to run NPM install with \-\-silent flag. .sp New in version 2016.3.0. .TP .B dry_run Whether or not to run NPM install with \-\-dry\-run flag. .sp New in version 2015.8.4. .TP .B silent Whether or not to run NPM install with \-\-silent flag. .sp New in version 2015.8.5. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq npm.install coffee\-script salt \(aq*\(aq npm.install coffee\-script@1.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.npm.list_(pkg=None, dir=None, runas=None, env=None, depth=None) List installed NPM packages. .sp If no directory is specified, this will return the list of globally\- installed packages. .INDENT 7.0 .TP .B pkg Limit package listing by name .TP .B dir The directory whose packages will be listed, or None for global installation .TP .B runas The user to run NPM with .sp New in version 2014.7.0. .TP .B env Environment variables to set when invoking npm. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function. .sp New in version 2014.7.0. .TP .B depth Limit the depth of the packages listed .sp New in version 2016.11.6,2017.7.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq npm.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.npm.uninstall(pkg, dir=None, runas=None, env=None) Uninstall an NPM package. .sp If no directory is specified, the package will be uninstalled globally. .INDENT 7.0 .TP .B pkg A package name in any format accepted by NPM .TP .B dir The target directory from which to uninstall the package, or None for global installation .TP .B runas The user to run NPM with .TP .B env Environment variables to set when invoking npm. Uses the same \fBenv\fP format as the \fI\%cmd.run\fP execution function. .sp New in version 2015.5.3. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq npm.uninstall coffee\-script .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nspawn .sp Manage nspawn containers .sp New in version 2015.8.0. .sp \fI\%systemd\-nspawn(1)\fP is a tool used to manage lightweight namespace containers. This execution module provides several functions to help manage these containers. .sp Minions running systemd >= 219 will place new containers in \fB/var/lib/machines\fP, while those running systemd < 219 will place them in \fB/var/lib/container\fP\&. .INDENT 0.0 .TP .B salt.modules.nspawn.bootstrap_container(name, dist=None, version=None) Bootstrap a container from package servers, if dist is None the os the minion is running as will be created, otherwise the needed bootstrapping tools will need to be available on the host. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.bootstrap_container <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.bootstrap_salt(name, config=None, approve_key=True, install=True, pub_key=None, priv_key=None, bootstrap_url=None, force_install=False, unconditional_install=False, bootstrap_delay=None, bootstrap_args=None, bootstrap_shell=None) Bootstrap a container from package servers, if dist is None the os the minion is running as will be created, otherwise the needed bootstrapping tools will need to be available on the host. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nspawn.bootstrap_salt arch1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.copy_to(name, source, dest, overwrite=False, makedirs=False) Copy a file from the host into a container .INDENT 7.0 .TP .B name Container name .TP .B source File to be copied to the container .TP .B dest Destination on the container. Must be an absolute path. .TP .B overwrite False Unless this option is set to \fBTrue\fP, then if a file exists at the location specified by the \fBdest\fP argument, an error will be raised. .UNINDENT .sp makedirs : False .INDENT 7.0 .INDENT 3.5 Create the parent directory on the container if it does not already exist. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq nspawn.copy_to /tmp/foo /root/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.cp(name, source, dest, overwrite=False, makedirs=False) This function is an alias of \fBcopy_to\fP\&. .INDENT 7.0 .INDENT 3.5 Copy a file from the host into a container .INDENT 0.0 .TP .B name Container name .TP .B source File to be copied to the container .TP .B dest Destination on the container. Must be an absolute path. .TP .B overwrite False Unless this option is set to \fBTrue\fP, then if a file exists at the location specified by the \fBdest\fP argument, an error will be raised. .UNINDENT .sp makedirs : False .INDENT 0.0 .INDENT 3.5 Create the parent directory on the container if it does not already exist. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq nspawn.copy_to /tmp/foo /root/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.destroy(name, stop=False) This function is an alias of \fBremove\fP\&. .INDENT 7.0 .INDENT 3.5 Remove the named container .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This function will remove all data associated with the container. It will not, however, remove the btrfs subvolumes created by pulling container images (\fI\%nspawn.pull_raw\fP, \fI\%nspawn.pull_tar\fP, \fI\%nspawn.pull_dkr\fP). .UNINDENT .UNINDENT .INDENT 0.0 .TP .B stop False If \fBTrue\fP, the container will be destroyed even if it is running/frozen. .UNINDENT .sp CLI Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nspawn.remove foo salt \(aq*\(aq nspawn.remove foo stop=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.disable(name) Set the named container to \fInot\fP be launched at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.enable <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.enable(name) Set the named container to be launched at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.enable <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.exists(name) Returns true if the named container exists .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.exists <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.info(name, **kwargs) Return info about a container .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The container must be running for \fBmachinectl\fP to gather information about it. If the container is stopped, then this function will start it. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B start False If \fBTrue\fP, then the container will be started to retrieve the info. A \fBStarted\fP key will be in the return data if the container was started. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.info arch1 salt myminion nspawn.info arch1 force_start=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.list_() This function is an alias of \fBlist_running\fP\&. .INDENT 7.0 .INDENT 3.5 Lists running nspawn containers .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBnspawn.list\fP also works to list running containers .UNINDENT .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.list_running salt myminion nspawn.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.list_all() Lists all nspawn containers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.list_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.list_running() Lists running nspawn containers .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBnspawn.list\fP also works to list running containers .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.list_running salt myminion nspawn.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.list_stopped() Lists stopped nspawn containers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.list_stopped .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.pid(name) Returns the PID of a container .INDENT 7.0 .TP .B name Container name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.pid arch1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.poweroff(name) Issue a clean shutdown to the container. Equivalent to running \fBmachinectl poweroff\fP on the named container. .sp For convenience, running \fBnspawn.stop\(ga\(ga(as shown in the CLI examples below) is equivalent to running \(ga\(ganspawn.poweroff\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBmachinectl poweroff\fP is only supported in systemd >= 219. On earlier systemd versions, running this function will simply issue a clean shutdown via \fBsystemctl\fP\&. .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.poweroff arch1 salt myminion nspawn.stop arch1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.pull_dkr(url, name, index) Execute a \fBmachinectl pull\-dkr\fP to download a docker image and add it to /var/lib/machines as a new container. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBRequires systemd >= 219\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B url URL from which to download the container .TP .B name Name for the new container .TP .B index URL of the Docker index server from which to pull (must be an \fBhttp://\fP or \fBhttps://\fP URL). .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.pull_dkr centos/centos6 cent6 index=https://get.docker.com salt myminion nspawn.pull_docker centos/centos6 cent6 index=https://get.docker.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.pull_docker(url, name, index) This function is an alias of \fBpull_dkr\fP\&. .INDENT 7.0 .INDENT 3.5 Execute a \fBmachinectl pull\-dkr\fP to download a docker image and add it to /var/lib/machines as a new container. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBRequires systemd >= 219\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B url URL from which to download the container .TP .B name Name for the new container .TP .B index URL of the Docker index server from which to pull (must be an \fBhttp://\fP or \fBhttps://\fP URL). .UNINDENT .sp CLI Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.pull_dkr centos/centos6 cent6 index=https://get.docker.com salt myminion nspawn.pull_docker centos/centos6 cent6 index=https://get.docker.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.pull_raw(url, name, verify=False) Execute a \fBmachinectl pull\-raw\fP to download a .qcow2 or raw disk image, and add it to /var/lib/machines as a new container. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBRequires systemd >= 219\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B url URL from which to download the container .TP .B name Name for the new container .TP .B verify False Perform signature or checksum verification on the container. See the \fBmachinectl(1)\fP man page (section titled \(dqImage Transfer Commands\(dq) for more information on requirements for image verification. To perform signature verification, use \fBverify=signature\fP\&. For checksum verification, use \fBverify=checksum\fP\&. By default, no verification will be performed. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.pull_raw http://ftp.halifax.rwth\-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora\-Cloud\-Base\-20141203\-21.x86_64.raw.xz fedora21 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.pull_tar(url, name, verify=False) Execute a \fBmachinectl pull\-raw\fP to download a .tar container image, and add it to /var/lib/machines as a new container. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBRequires systemd >= 219\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B url URL from which to download the container .TP .B name Name for the new container .TP .B verify False Perform signature or checksum verification on the container. See the \fBmachinectl(1)\fP man page (section titled \(dqImage Transfer Commands\(dq) for more information on requirements for image verification. To perform signature verification, use \fBverify=signature\fP\&. For checksum verification, use \fBverify=checksum\fP\&. By default, no verification will be performed. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.pull_tar http://foo.domain.tld/containers/archlinux\-2015.02.01.tar.gz arch2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.reboot(name, kill=False) Reboot the container by sending a SIGINT to its init process. Equivalent to running \fBmachinectl reboot\fP on the named container. .sp For convenience, running \fBnspawn.restart\fP (as shown in the CLI examples below) is equivalent to running \fBnspawn.reboot\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBmachinectl reboot\fP is only supported in systemd >= 219. On earlier systemd versions, running this function will instead restart the container via \fBsystemctl\fP\&. .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.reboot arch1 salt myminion nspawn.restart arch1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.remove(name, stop=False) Remove the named container .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This function will remove all data associated with the container. It will not, however, remove the btrfs subvolumes created by pulling container images (\fI\%nspawn.pull_raw\fP, \fI\%nspawn.pull_tar\fP, \fI\%nspawn.pull_dkr\fP). .UNINDENT .UNINDENT .INDENT 7.0 .TP .B stop False If \fBTrue\fP, the container will be destroyed even if it is running/frozen. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nspawn.remove foo salt \(aq*\(aq nspawn.remove foo stop=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.restart(name) This is a compatibility function which simply calls nspawn.reboot. .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.retcode(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, ignore_retcode=False, keep_env=None) Run \fI\%cmd.retcode\fP within a container .INDENT 7.0 .TP .B name Name of the container in which to run the command .TP .B cmd Command to run .TP .B no_start False If the container is not running, don\(aqt start it .TP .B preserve_state True After running the command, return the container to its previous state .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. Assumes \fBoutput=all\fP\&. .TP .B keep_env None If not passed, only a sane default PATH environment variable will be set. If \fBTrue\fP, all environment variables from the container\(aqs host will be kept. Otherwise, a comma\-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.retcode mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.run(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, ignore_retcode=False, keep_env=None) Run \fI\%cmd.run\fP within a container .INDENT 7.0 .TP .B name Name of the container in which to run the command .TP .B cmd Command to run .TP .B no_start False If the container is not running, don\(aqt start it .TP .B preserve_state True After running the command, return the container to its previous state .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. .TP .B keep_env None If not passed, only a sane default PATH environment variable will be set. If \fBTrue\fP, all environment variables from the container\(aqs host will be kept. Otherwise, a comma\-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.run mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.run_all(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, ignore_retcode=False, keep_env=None) Run \fI\%cmd.run_all\fP within a container .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 While the command is run within the container, it is initiated from the host. Therefore, the PID in the return dict is from the host, not from the container. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the container in which to run the command .TP .B cmd Command to run .TP .B no_start False If the container is not running, don\(aqt start it .TP .B preserve_state True After running the command, return the container to its previous state .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. Assumes \fBoutput=all\fP\&. .TP .B keep_env None If not passed, only a sane default PATH environment variable will be set. If \fBTrue\fP, all environment variables from the container\(aqs host will be kept. Otherwise, a comma\-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.run_all mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.run_stderr(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, ignore_retcode=False, keep_env=None) Run \fI\%cmd.run_stderr\fP within a container .INDENT 7.0 .TP .B name Name of the container in which to run the command .TP .B cmd Command to run .TP .B no_start False If the container is not running, don\(aqt start it .TP .B preserve_state True After running the command, return the container to its previous state .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. Assumes \fBoutput=all\fP\&. .TP .B keep_env None If not passed, only a sane default PATH environment variable will be set. If \fBTrue\fP, all environment variables from the container\(aqs host will be kept. Otherwise, a comma\-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.run_stderr mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.run_stdout(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel=\(aqdebug\(aq, use_vt=False, ignore_retcode=False, keep_env=None) Run \fI\%cmd.run_stdout\fP within a container .INDENT 7.0 .TP .B name Name of the container in which to run the command .TP .B cmd Command to run .TP .B no_start False If the container is not running, don\(aqt start it .TP .B preserve_state True After running the command, return the container to its previous state .TP .B stdin None Standard input to be used for the command .TP .B output_loglevel debug Level at which to log the output from the command. Set to \fBquiet\fP to suppress logging. .TP .B use_vt False Use SaltStack\(aqs utils.vt to stream output to console. Assumes \fBoutput=all\fP\&. .TP .B keep_env None If not passed, only a sane default PATH environment variable will be set. If \fBTrue\fP, all environment variables from the container\(aqs host will be kept. Otherwise, a comma\-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.run_stdout mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.start(name) Start the named container .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.start <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.state(name) Return state of container (running or stopped) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.state <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.stop(name, kill=False) This is a compatibility function which provides the logic for nspawn.poweroff and nspawn.terminate. .UNINDENT .INDENT 0.0 .TP .B salt.modules.nspawn.terminate(name) Kill all processes in the container without issuing a clean shutdown. Equivalent to running \fBmachinectl terminate\fP on the named container. .sp For convenience, running \fBnspawn.stop\fP and passing \fBkill=True\fP (as shown in the CLI examples below) is equivalent to running \fBnspawn.terminate\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBmachinectl terminate\fP is only supported in systemd >= 219. On earlier systemd versions, running this function will simply issue a clean shutdown via \fBsystemctl\fP\&. .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion nspawn.terminate arch1 salt myminion nspawn.stop arch1 kill=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nxos .sp Execution module for Cisco NX OS Switches. .sp New in version 2016.11.0. .INDENT 0.0 .TP .B This module supports execution using a Proxy Minion or Native Minion: 1) Proxy Minion: Connect over SSH or NX\-API HTTP(S). See \fI\%salt.proxy.nxos\fP for proxy minion setup details. 2) Native Minion: Connect over NX\-API Unix Domain Socket (UDS). Install the minion inside the GuestShell running on the NX\-OS device. .UNINDENT .INDENT 0.0 .TP .B maturity new .TP .B platform nxos .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To use this module over remote NX\-API the feature must be enabled on the NX\-OS device by executing \fBfeature nxapi\fP in configuration mode. .sp This is not required for NX\-API over UDS. .sp Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C switch# conf t switch(config)# feature nxapi .ft P .fi .UNINDENT .UNINDENT .sp To check that NX\-API is properly enabled, execute \fBshow nxapi\fP\&. .sp Output example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C switch# show nxapi nxapi enabled HTTPS Listen on port 443 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Native minion configuration options: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nxos: cookie: \(aqusername\(aq save_config: False .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B cookie Use the option to override the default cookie \(aqadmin:local\(aq when connecting over UDS and use \(aqusername:local\(aq instead. This is needed when running the salt\-minion in the GuestShell using a non\-admin user. .sp This option is ignored for SSH and NX\-API Proxy minions. .TP .B save_config: If True, \(aqcopy running\-config starting\-config\(aq is issues for every configuration command. If False, Running config is not saved to startup config Default: True .sp The recommended approach is to use the \fIsave_running_config\fP function instead of this option to improve performance. The default behavior controlled by this option is preserved for backwards compatibility. .UNINDENT .sp The APIs defined in this execution module can also be executed using salt\-call from the GuestShell environment as follows. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local nxos.sendline \(aqshow lldp neighbors\(aq raw_text .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The functions in this module should be executed like so: .sp salt \(aq*\(aq nxos.<function> salt \(aq*\(aq nxos.get_user username=admin .sp For backwards compatibility, the following syntax will be supported until the 3001 release. .sp salt \(aq*\(aq nxos.cmd <function> salt \(aq*\(aq nxos.cmd get_user username=admin .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.add_config(lines, **kwargs) Add one or more config lines to the NX\-OS device running config. .INDENT 7.0 .TP .B lines Configuration lines to add .TP .B save_config If False, don\(aqt save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.add_config \(aqsnmp\-server community TESTSTRINGHERE group network\-operator\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For more than one config added per command, lines should be a list. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.check_password(username, password, encrypted=False, **kwargs) Verify user password. .INDENT 7.0 .TP .B username Username on which to perform password check .TP .B password Password to check .TP .B encrypted Whether or not the password is encrypted Default: False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.check_role(username, role, **kwargs) Verify role assignment for user. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.check_role username=admin role=network\-admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.cmd(command, *args, **kwargs) NOTE: This function is preserved for backwards compatibility. This allows commands to be executed using either of the following syntactic forms. .sp salt \(aq*\(aq nxos.cmd <function> .sp or .sp salt \(aq*\(aq nxos.<function> .INDENT 7.0 .TP .B command function from \fIsalt.modules.nxos\fP to run .TP .B args positional args to pass to \fIcommand\fP function .TP .B kwargs key word arguments to pass to \fIcommand\fP function .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.cmd sendline \(aqshow ver\(aq salt \(aq*\(aq nxos.cmd show_run salt \(aq*\(aq nxos.cmd check_password username=admin password=\(aq$5$lkjsdfoi$blahblahblah\(aq encrypted=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.config(commands=None, config_file=None, template_engine=\(aqjinja\(aq, context=None, defaults=None, saltenv=\(aqbase\(aq, **kwargs) Configures the Nexus switch with the specified commands. .sp This method is used to send configuration commands to the switch. It will take either a string or a list and prepend the necessary commands to put the session into config mode. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 All the commands will be applied directly to the running\-config. .UNINDENT .UNINDENT .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 switch 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 context_dict. .TP .B save_config If False, don\(aqt save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.config commands=\(dq[\(aqspanning\-tree mode mstp\(aq]\(dq salt \(aq*\(aq nxos.config config_file=salt://config.txt salt \(aq*\(aq nxos.config config_file=https://bit.ly/2LGLcDy context=\(dq{\(aqservers\(aq: [\(aq1.2.3.4\(aq]}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.delete_config(lines, **kwargs) Delete one or more config lines to the switch running config. .INDENT 7.0 .TP .B lines Configuration lines to remove. .TP .B save_config If False, don\(aqt save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.delete_config \(aqsnmp\-server community TESTSTRINGHERE group network\-operator\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For more than one config deleted per command, lines should be a list. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.find(pattern, **kwargs) Find all instances where the pattern is in the running configuration. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.find \(aq^snmp\-server.*$\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This uses the \fIre.MULTILINE\fP regex format for python, and runs the regex against the whole show_run output. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.get_roles(username, **kwargs) Get roles assigned to a username. .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.get_user(username, **kwargs) Get username line from switch. .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.grains(**kwargs) Get grains for minion. .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.grains_refresh(**kwargs) Refresh the grains for the NX\-OS device. .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.ping(**kwargs) Ping the device on the other end of the connection. .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.remove_user(username, **kwargs) Remove user from switch. .INDENT 7.0 .TP .B username Username to remove .TP .B save_config If False, don\(aqt save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.remove_user username=daniel .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.replace(old_value, new_value, full_match=False, **kwargs) Replace string or full line matches in switch\(aqs running config. .sp If full_match is set to True, then the whole line will need to be matched as part of the old value. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.replace \(aqTESTSTRINGHERE\(aq \(aqNEWTESTSTRINGHERE\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.save_running_config(**kwargs) Save the running configuration to startup configuration. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.save_running_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.sendline(command, method=\(aqcli_show_ascii\(aq, **kwargs) Send arbitrary commands to the NX\-OS device. .INDENT 7.0 .TP .B command The command or list of commands to be sent. [\(aqcmd1\(aq, \(aqcmd2\(aq] is converted to \(aqcmd1 ; cmd2\(aq. .TP .B method: \fBcli_show_ascii\fP: Return raw test or unstructured output. \fBcli_show\fP: Return structured output. \fBcli_conf\fP: Send configuration commands to the device. Defaults to \fBcli_show_ascii\fP\&. NOTE: method is ignored for SSH proxy minion. All data is returned unstructured. .TP .B error_pattern Use the option to pass in a regular expression to search for in the returned output of the command that indicates an error has occurred. This option is only used when proxy minion connection type is ssh and otherwise ignored. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.set_password(username, password, encrypted=False, role=None, crypt_salt=None, algorithm=\(aqsha256\(aq, **kwargs) Set users password on switch. .INDENT 7.0 .TP .B username Username to configure .TP .B password Password to configure for username .TP .B encrypted Whether or not to encrypt the password Default: False .TP .B role Configure role for the username Default: None .TP .B crypt_salt Configure crypt_salt setting Default: None .TP .B algorithm Encryption algorithm Default: sha256 .TP .B save_config If False, don\(aqt save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.set_password admin TestPass salt \(aq*\(aq nxos.set_password admin \e password=\(aq$5$2fWwO2vK$s7.Hr3YltMNHuhywQQ3nfOd.gAPHgs3SOBYYdGT3E.A\(aq \e encrypted=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.set_role(username, role, **kwargs) Assign role to username. .INDENT 7.0 .TP .B username Username for role configuration .TP .B role Configure role for username .TP .B save_config If False, don\(aqt save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.set_role username=daniel role=vdc\-admin. .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.show(commands, raw_text=True, **kwargs) Execute one or more show (non\-configuration) commands. .INDENT 7.0 .TP .B commands The commands to be executed. .TP .B raw_text: \fBTrue\fP Whether to return raw text or structured data. NOTE: raw_text option is ignored for SSH proxy minion. Data is returned unstructured. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local nxos.show \(aqshow version\(aq salt \(aq*\(aq nxos.show \(aqshow bgp sessions ; show processes\(aq raw_text=False salt \(aqregular\-minion\(aq nxos.show \(aqshow interfaces\(aq host=sw01.example.com username=test password=test .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.show_run(**kwargs) Shortcut to run \fIshow running\-config\fP on the NX\-OS device. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.show_run .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.show_ver(**kwargs) Shortcut to run \fIshow version\fP on the NX\-OS device. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.show_ver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.system_info(**kwargs) Return system information for grains of the minion. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.system_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos.unset_role(username, role, **kwargs) Remove role from username. .INDENT 7.0 .TP .B username Username for role removal .TP .B role Role to remove .TP .B save_config If False, don\(aqt save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos.unset_role username=daniel role=vdc\-admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nxos_api .sp Execution module to manage Cisco Nexus Switches (NX\-OS) over the NX\-API .sp New in version 2019.2.0. .sp Execution module used to interface the interaction with a remote or local Nexus switch whether we\(aqre running in a Proxy Minion or regular Minion (or regular Minion running directly on the Nexus switch). .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> .TP .B maturity new .TP .B platform any .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To be able to use this module you need to enable to NX\-API on your switch, by executing \fBfeature nxapi\fP in configuration mode. .sp Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C switch# conf t switch(config)# feature nxapi .ft P .fi .UNINDENT .UNINDENT .sp To check that NX\-API is properly enabled, execute \fBshow nxapi\fP\&. .sp Output example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C switch# show nxapi nxapi enabled HTTPS Listen on port 443 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 NX\-API requires modern NXOS distributions, typically at least 7.0 depending on the hardware. Due to reliability reasons it is recommended to run the most recent version. .sp Check \fI\%https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus7000/sw/programmability/guide/b_Cisco_Nexus_7000_Series_NX\-OS_Programmability_Guide/b_Cisco_Nexus_7000_Series_NX\-OS_Programmability_Guide_chapter_0101.html\fP for more details. .UNINDENT .UNINDENT .SS Usage .sp This module can equally be used via the \fI\%nxos_api\fP Proxy module or directly from an arbitrary (Proxy) Minion that is running on a machine having access to the network device API. Given that there are no external dependencies, this module can very well used when using the regular Salt Minion directly installed on the switch. .sp When running outside of the \fI\%nxos_api Proxy\fP (i.e., from another Proxy Minion type, or regular Minion), the NX\-API connection arguments can be either specified from the CLI when executing the command, or in a configuration block under the \fBnxos_api\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 \fBnxos_api\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 \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 NX\-API connection. .TP .B password The password to pass to the device to authenticate the NX\-API connection. .TP .B port The TCP port of the endpoint for the NX\-API 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 timeout: \fB60\fP Time in seconds to wait for the device to respond. Default: 60 seconds. .TP .B verify: \fBTrue\fP Either a boolean, in which case it controls whether we verify the NX\-API TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to \fBTrue\fP\&. .sp When there is no certificate configuration on the device and this option is set as \fBTrue\fP (default), the commands will fail with the following error: \fBSSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:581)\fP\&. In this case, you either need to configure a proper certificate on the device (\fIrecommended\fP), or bypass the checks setting this argument as \fBFalse\fP with all the security risks considered. .sp Check \fI\%https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus3000/sw/programmability/6_x/b_Cisco_Nexus_3000_Series_NX\-OS_Programmability_Guide/b_Cisco_Nexus_3000_Series_NX\-OS_Programmability_Guide_chapter_01.html\fP to see how to properly configure the certificate. .UNINDENT .sp Example (when not running in a \fBnxos_api\fP Proxy Minion): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nxos_api: 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 \fBnxos_api\fP Proxy, e.g.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local nxos_api.show \(aqshow lldp neighbors\(aq raw_text # The command above is available when running in a regular Minion where Salt is installed salt \(aq*\(aq nxos_api.show \(aqshow version\(aq raw_text=False .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 \fBnxos_api\fP Proxy Minion. If you want to use the \fI\%nxos_api Proxy\fP, please follow the documentation notes for a proper setup. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos_api.config(commands=None, config_file=None, template_engine=\(aqjinja\(aq, context=None, defaults=None, saltenv=\(aqbase\(aq, **kwargs) Configures the Nexus switch with the specified commands. .sp This method is used to send configuration commands to the switch. It will take either a string or a list and prepend the necessary commands to put the session into config mode. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 All the commands will be applied directly into the running\-config. .UNINDENT .UNINDENT .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 switch 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 context_dict. .TP .B transport: \fBhttps\fP Specifies the type of connection transport to use. Valid values for the connection are \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 NX\-API connection. .TP .B password The password to pass to the device to authenticate the NX\-API connection. .TP .B port The TCP port of the endpoint for the NX\-API 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 timeout: \fB60\fP Time in seconds to wait for the device to respond. Default: 60 seconds. .TP .B verify: \fBTrue\fP Either a boolean, in which case it controls whether we verify the NX\-API TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to \fBTrue\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nxos_api.config commands=\(dq[\(aqspanning\-tree mode mstp\(aq]\(dq salt \(aq*\(aq nxos_api.config config_file=salt://config.txt salt \(aq*\(aq nxos_api.config config_file=https://bit.ly/2LGLcDy context=\(dq{\(aqservers\(aq: [\(aq1.2.3.4\(aq]}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos_api.rpc(commands, method=\(aqcli\(aq, **kwargs) Execute an arbitrary RPC request via the Nexus API. .INDENT 7.0 .TP .B commands The commands to be executed. .TP .B method: \fBcli\fP The type of the response, i.e., raw text (\fBcli_ascii\fP) or structured document (\fBcli\fP). Defaults to \fBcli\fP (structured data). .TP .B transport: \fBhttps\fP Specifies the type of connection transport to use. Valid values for the connection are \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 NX\-API connection. .TP .B password The password to pass to the device to authenticate the NX\-API connection. .TP .B port The TCP port of the endpoint for the NX\-API 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 timeout: \fB60\fP Time in seconds to wait for the device to respond. Default: 60 seconds. .TP .B verify: \fBTrue\fP Either a boolean, in which case it controls whether we verify the NX\-API TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to \fBTrue\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local nxos_api.rpc \(aqshow version\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos_api.show(commands, raw_text=True, **kwargs) Execute one or more show (non\-configuration) commands. .INDENT 7.0 .TP .B commands The commands to be executed. Multiple commands should be specified as a list. .TP .B raw_text: \fBTrue\fP Whether to return raw text or structured data. .TP .B transport: \fBhttps\fP Specifies the type of connection transport to use. Valid values for the connection are \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 NX\-API connection. .TP .B password The password to pass to the device to authenticate the NX\-API connection. .TP .B port The TCP port of the endpoint for the NX\-API 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 timeout: \fB60\fP Time in seconds to wait for the device to respond. Default: 60 seconds. .TP .B verify: \fBTrue\fP Either a boolean, in which case it controls whether we verify the NX\-API TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to \fBTrue\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local nxos_api.show \(aqshow version\(aq salt \(aq*\(aq nxos_api.show \(dq[\(aqshow bgp sessions\(aq,\(aqshow processes\(aq]\(dq raw_text=False salt \(aqregular\-minion\(aq nxos_api.show \(aqshow interfaces\(aq host=sw01.example.com username=test password=test .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.nxos_upgrade .sp Execution module to upgrade Cisco NX\-OS Switches. .sp New in version 3001. .INDENT 0.0 .TP .B This module supports execution using a Proxy Minion or Native Minion: .INDENT 7.0 .IP 1. 3 Proxy Minion: Connect over SSH or NX\-API HTTP(S). See \fI\%salt.proxy.nxos\fP for proxy minion setup details. .IP 2. 3 Native Minion: Connect over NX\-API Unix Domain Socket (UDS). Install the minion inside the GuestShell running on the NX\-OS device. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B maturity new .TP .B platform nxos .TP .B codeauthor Michael G Wiebe .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To use this module over remote NX\-API the feature must be enabled on the NX\-OS device by executing \fBfeature nxapi\fP in configuration mode. .sp This is not required for NX\-API over UDS. .sp Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C switch# conf t switch(config)# feature nxapi .ft P .fi .UNINDENT .UNINDENT .sp To check that NX\-API is properly enabled, execute \fBshow nxapi\fP\&. .sp Output example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C switch# show nxapi nxapi enabled HTTPS Listen on port 443 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos_upgrade.check_upgrade_impact(system_image, kickstart_image=None, issu=True, **kwargs) Display upgrade impact information without actually upgrading the device. .INDENT 7.0 .TP .B system_image (Mandatory Option) Path on bootflash: to system image upgrade file. .TP .B kickstart_image Path on bootflash: to kickstart image upgrade file. (Not required if using combined system/kickstart image file) Default: None .TP .B issu In Service Software Upgrade (non\-disruptive). When True, the upgrade will abort if issu is not possible. When False: Force (disruptive) Upgrade/Downgrade. Default: True .TP .B timeout Timeout in seconds for long running \(aqinstall all\(aq impact command. Default: 900 .TP .B error_pattern Use the option to pass in a regular expression to search for in the output of the \(aqinstall all impact\(aq command that indicates an error has occurred. This option is only used when proxy minion connection type is ssh and otherwise ignored. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqn9k\(aq nxos.check_upgrade_impact system_image=nxos.9.2.1.bin salt \(aqn7k\(aq nxos.check_upgrade_impact system_image=n7000\-s2\-dk9.8.1.1.bin \e kickstart_image=n7000\-s2\-kickstart.8.1.1.bin issu=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.nxos_upgrade.upgrade(system_image, kickstart_image=None, issu=True, **kwargs) Upgrade NX\-OS switch. .INDENT 7.0 .TP .B system_image (Mandatory Option) Path on bootflash: to system image upgrade file. .TP .B kickstart_image Path on bootflash: to kickstart image upgrade file. (Not required if using combined system/kickstart image file) Default: None .TP .B issu Set this option to True when an In Service Software Upgrade or non\-disruptive upgrade is required. The upgrade will abort if issu is not possible. Default: True .TP .B timeout Timeout in seconds for long running \(aqinstall all\(aq upgrade command. Default: 900 .TP .B error_pattern Use the option to pass in a regular expression to search for in the output of the \(aqinstall all upgrade command that indicates an error has occurred. This option is only used when proxy minion connection type is ssh and otherwise ignored. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqn9k\(aq nxos.upgrade system_image=nxos.9.2.1.bin salt \(aqn7k\(aq nxos.upgrade system_image=n7000\-s2\-dk9.8.1.1.bin \e kickstart_image=n7000\-s2\-kickstart.8.1.1.bin issu=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.omapi .sp This module interacts with an ISC DHCP Server via OMAPI. server_ip and server_port params may be set in the minion config or pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C omapi.server_ip: 127.0.0.1 omapi.server_port: 7991 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends pypureomapi Python module .UNINDENT .INDENT 0.0 .TP .B salt.modules.omapi.add_host(mac, name=None, ip=None, ddns=False, group=None, supersede_host=False) Add a host object for the given mac. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dhcp\-server omapi.add_host ab:ab:ab:ab:ab:ab name=host1 .ft P .fi .UNINDENT .UNINDENT .sp Add ddns\-hostname and a fixed\-ip statements: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dhcp\-server omapi.add_host ab:ab:ab:ab:ab:ab name=host1 ip=10.1.1.1 ddns=true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.omapi.delete_host(mac=None, name=None) Delete the host with the given mac or name. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dhcp\-server omapi.delete_host name=host1 salt dhcp\-server omapi.delete_host mac=ab:ab:ab:ab:ab:ab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.openbsd_sysctl .sp Module for viewing and modifying OpenBSD sysctl parameters .INDENT 0.0 .TP .B salt.modules.openbsd_sysctl.assign(name, value) Assign a single sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.assign net.inet.ip.forwarding 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsd_sysctl.get(name) Return a single sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.get hw.physmem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsd_sysctl.persist(name, value, config=\(aq/etc/sysctl.conf\(aq) Assign and persist a simple sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.persist net.inet.ip.forwarding 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsd_sysctl.show(config_file=False) Return a list of sysctl parameters for this minion .INDENT 7.0 .TP .B config: Pull the data from the system configuration file instead of the live data. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.show .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.openbsdpkg .sp Package support for OpenBSD .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The package repository is configured on each host using \fB/etc/installurl\fP from OpenBSD 6.1 onwards. Earlier releases relied on \fB/etc/pkg.conf\fP\&. .UNINDENT .UNINDENT .sp Changed in version 2016.3.5: Package versions on OpenBSD are not normally specified explicitly; instead packages may be available in multiple \fIflavors\fP, and \fIbranches\fP which are specified by the format of the package name. This module allows you to use the same formatting as \fBpkg_add(1)\fP, and will select the empty flavor and default branch by default. Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- rsync \- vim\-\-no_x11 \- ruby%2.3 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdpkg.install(name=None, pkgs=None, sources=None, **kwargs) Install the passed package .sp Return a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example, Install one package: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .UNINDENT .sp CLI Example, Install more than one package: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq[\(dq<package name>\(dq, \(dq<package name>\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example, Install more than one package from a alternate source (e.g. salt file\-server, HTTP, FTP, local filesystem): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sources=\(aq[{\(dq<pkg name>\(dq: \(dqsalt://pkgs/<pkg filename>\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdpkg.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 <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdpkg.list_pkgs(versions_as_list=False, **kwargs) List the packages currently installed as a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(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.openbsdpkg.purge(name=None, pkgs=None, **kwargs) Remove a package and extra 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 <package name> salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3> salt \(aq*\(aq pkg.purge pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdpkg.remove(name=None, pkgs=None, purge=False, **kwargs) Remove a single package with pkg_delete .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 <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdpkg.upgrade(name=None, pkgs=None, **kwargs) Run a full package upgrade (\fBpkg_add \-u\fP), or upgrade a specific package if \fBname\fP or \fBpkgs\fP is provided. \fBname\fP is ignored when \fBpkgs\fP is specified. .sp Returns a dictionary containing the changes: .sp New in version 2019.2.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade salt \(aq*\(aq pkg.upgrade python%2.7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdpkg.upgrade_available(name, **kwargs) Check whether or not an upgrade is available for a given package .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdpkg.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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.openbsdrcctl_service.py .sp The rcctl service module for OpenBSD .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.available(name) Return True if the named service is available. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.disable(name, **kwargs) Disable the named service to not start at boot. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.disabled(name) Return True if the named service is disabled at boot, False otherwise. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.enable(name, **kwargs) Enable the named service to start at boot. .INDENT 7.0 .TP .B flags None Set optional flags to run the service with. .UNINDENT .sp service.flags can be used to change the default flags. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable <service name> salt \(aq*\(aq service.enable <service name> flags=<flags> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.enabled(name, **kwargs) Return True if the named service is enabled at boot and the provided flags match the configured ones (if any). Return False otherwise. .INDENT 7.0 .TP .B name Service name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> salt \(aq*\(aq service.enabled <service name> flags=<flags> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.get_all() Return all installed services. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.get_disabled() Return what services are available but not enabled to start at boot. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.get_enabled() Return what services are set to run on boot. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.missing(name) The inverse of service.available. Return True if the named service is not available. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.reload_(name) Reload the named service. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.restart(name) Restart the named service. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.start(name) Start the named service. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.status(name, sig=None) Return the status for a service, returns a bool whether the service is running. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdrcctl_service.stop(name) Stop the named service. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.openbsdservice .sp The service module for OpenBSD .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage services on a minion, and it is using a different module (or gives an error similar to \fI\(aqservice.start\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdservice.available(name) New in version 2014.7.0. .sp Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdservice.disabled(name) New in version 2014.7.0. .sp Return True if the named service is disabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdservice.enabled(name, **kwargs) New in version 2014.7.0. .sp Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdservice.get_all() New in version 2014.7.0. .sp Return all available boot services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdservice.get_disabled() New in version 2014.7.0. .sp Return a set of services that are installed but disabled .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdservice.get_enabled() New in version 2014.7.0. .sp Return a list of service that are enabled on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdservice.missing(name) New in version 2014.7.0. .sp The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdservice.reload_(name) New in version 2014.7.0. .sp Reload the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdservice.restart(name) Restart the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdservice.start(name) Start the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdservice.status(name, sig=None) Return the status for a service. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Signature to use to find the service via ps .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> [service signature] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openbsdservice.stop(name) Stop the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.openscap .sp Module for OpenSCAP Management .INDENT 0.0 .TP .B salt.modules.openscap.xccdf(params) Run \fBoscap xccdf\fP commands on minions. It uses cp.push_dir to upload the generated files to the salt master in the master\(aqs minion files cachedir (defaults to \fB/var/cache/salt/master/minions/minion\-id/files\fP) .sp It needs \fBfile_recv\fP set to \fBTrue\fP in the master configuration file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openscap.xccdf \(dqeval \-\-profile Default /usr/share/openscap/scap\-yast2sec\-xccdf.xml\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openscap.xccdf_eval(xccdffile, ovalfiles=None, profile=None, rule=None, oval_results=None, results=None, report=None, fetch_remote_resources=None, tailoring_file=None, tailoring_id=None, remediate=None) Run \fBoscap xccdf eval\fP commands on minions. .sp New in version 3007.0. .sp It uses cp.push_dir to upload the generated files to the salt master in the master\(aqs minion files cachedir (defaults to \fB/var/cache/salt/master/minions/minion\-id/files\fP) .sp It needs \fBfile_recv\fP set to \fBTrue\fP in the master configuration file. .INDENT 7.0 .TP .B xccdffile the path to the xccdf file to evaluate .TP .B ovalfiles additional oval definition files .TP .B profile the name of Profile to be evaluated .TP .B rule the name of a single rule to be evaluated .TP .B oval_results save OVAL results as well (True or False) .TP .B results write XCCDF Results into given file .TP .B report write HTML report into given file .TP .B fetch_remote_resources download remote content referenced by XCCDF (True or False) .TP .B tailoring_file use given XCCDF Tailoring file .TP .B tailoring_id use given DS component as XCCDF Tailoring file .TP .B remediate automatically execute XCCDF fix elements for failed rules. Use of this option is always at your own risk. (True or False) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openscap.xccdf_eval /usr/share/openscap/scap\-yast2sec\-xccdf.xml profile=Default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.openstack_config .sp Modify, retrieve, or delete values from OpenStack configuration files. .INDENT 0.0 .TP .B maintainer Jeffrey C. Ollie <\fI\%jeff@ocjtech.us\fP> .TP .B maturity new .TP .B depends .TP .B platform linux .UNINDENT .INDENT 0.0 .TP .B salt.modules.openstack_config.delete(filename, section, parameter) Delete a value from an OpenStack configuration file. .INDENT 7.0 .TP .B filename The full path to the configuration file .TP .B section The section from which to delete the parameter .TP .B parameter The parameter to delete .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call openstack_config.delete /etc/keystone/keystone.conf sql connection .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openstack_config.get(filename, section, parameter) Get a value from an OpenStack configuration file. .INDENT 7.0 .TP .B filename The full path to the configuration file .TP .B section The section from which to search for the parameter .TP .B parameter The parameter to return .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call openstack_config.get /etc/keystone/keystone.conf sql connection .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openstack_config.set_(filename, section, parameter, value) Set a value in an OpenStack configuration file. .INDENT 7.0 .TP .B filename The full path to the configuration file .TP .B section The section in which the parameter will be set .TP .B parameter The parameter to change .TP .B value The value to set .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call openstack_config.set /etc/keystone/keystone.conf sql connection foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.openstack_mng .sp Module for OpenStack Management .INDENT 0.0 .TP .B codeauthor Konrad Mosoń <\fI\%mosonkonrad@gmail.com\fP> .TP .B maturity new .TP .B depends openstack\-utils .TP .B platform linux .UNINDENT .INDENT 0.0 .TP .B salt.modules.openstack_mng.restart_service(service_name, minimum_running_time=None) Restart OpenStack service immediately, or only if it\(aqs running longer than specified value .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openstack_mng.restart_service neutron salt \(aq*\(aq openstack_mng.restart_service neutron minimum_running_time=600 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openstack_mng.start_service(service_name) Start OpenStack service immediately .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openstack_mng.start_service neutron .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openstack_mng.stop_service(service_name) Stop OpenStack service immediately .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openstack_mng.stop_service neutron .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.openvswitch .sp Support for Open vSwitch \- module with basic Open vSwitch commands. .sp Suitable for setting up Openstack Neutron. .INDENT 0.0 .TP .B codeauthor Jiri Kotlin <\fI\%jiri.kotlin@ultimum.io\fP> .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.bridge_create(br, may_exist=True, parent=None, vlan=None) Creates a new bridge. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbr\fP \-\- string bridge name .IP \(bu 2 \fBmay_exist\fP \-\- bool if False \- attempting to create a bridge that exists returns False. .IP \(bu 2 \fBparent\fP \-\- string name of the parent bridge (if the bridge shall be created as a fake bridge). If specified, vlan must also be specified. .IP \(bu 2 \fBversionadded:\fP (\fI\&..\fP) \-\- 3006.0: .IP \(bu 2 \fBvlan\fP \-\- int VLAN ID of the bridge (if the bridge shall be created as a fake bridge). If specified, parent must also be specified. .IP \(bu 2 \fBversionadded:\fP \-\- 3006.0: .UNINDENT .TP .B Returns True on success, else False. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.bridge_create br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.bridge_delete(br, if_exists=True) Deletes bridge and all of its ports. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbr\fP \-\- A string \- bridge name .IP \(bu 2 \fBif_exists\fP \-\- Bool, if False \- attempting to delete a bridge that does not exist returns False. .UNINDENT .TP .B Returns True on success, else False. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.bridge_delete br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.bridge_exists(br) Tests whether bridge exists as a real or fake bridge. .INDENT 7.0 .TP .B Returns True if Bridge exists, else False. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.bridge_exists br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.bridge_list() Lists all existing real and fake bridges. .INDENT 7.0 .TP .B Returns List of bridges (or empty list), False on failure. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.bridge_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.bridge_to_parent(br) New in version 3006.0. .sp Returns the parent bridge of a bridge. .INDENT 7.0 .TP .B Parameters \fBbr\fP \-\- string bridge name .TP .B Returns Name of the parent bridge. This is the same as the bridge name if the bridge is not a fake bridge. If the bridge does not exist, False is returned. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.bridge_to_parent br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.bridge_to_vlan(br) New in version 3006.0. .sp Returns the VLAN ID of a bridge. .INDENT 7.0 .TP .B Parameters \fBbr\fP \-\- string bridge name .TP .B Returns VLAN ID of the bridge. The VLAN ID is 0 if the bridge is not a fake bridge. If the bridge does not exist, False is returned. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.bridge_to_parent br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.db_get(table, record, column, if_exists=False) New in version 3006.0. .sp Gets a column\(aqs value for a specific record. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- string name of the database table .IP \(bu 2 \fBrecord\fP \-\- string identifier of the record .IP \(bu 2 \fBcolumn\fP \-\- string name of the column .IP \(bu 2 \fBif_exists\fP \-\- boolean if True, it is not an error if the record does not exist. .UNINDENT .TP .B Returns The column\(aqs value. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.db_get Port br0 vlan_mode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.db_set(table, record, column, value, if_exists=False) New in version 3006.0. .sp Sets a column\(aqs value for a specific record. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP \-\- string name of the database table .IP \(bu 2 \fBrecord\fP \-\- string identifier of the record .IP \(bu 2 \fBcolumn\fP \-\- string name of the column .IP \(bu 2 \fBvalue\fP \-\- string the value to be set .IP \(bu 2 \fBif_exists\fP \-\- boolean if True, it is not an error if the record does not exist. .UNINDENT .TP .B Returns None on success and an error message on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.db_set Interface br0 mac 02:03:04:05:06:07 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.interface_get_options(port) Port\(aqs interface\(aqs optional parameters. .INDENT 7.0 .TP .B Parameters \fBport\fP \-\- A string \- port name. .TP .B Returns String containing optional parameters of port\(aqs interface, False on failure. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.interface_get_options tap0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.interface_get_type(port) Type of port\(aqs interface. .INDENT 7.0 .TP .B Parameters \fBport\fP \-\- A string \- port name. .TP .B Returns String \- type of interface or empty string, False on failure. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.interface_get_type tap0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.port_add(br, port, may_exist=False, internal=False) Creates on bridge a new port named port. .INDENT 7.0 .TP .B Returns True on success, else False. .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbr\fP \-\- A string \- bridge name .IP \(bu 2 \fBport\fP \-\- A string \- port name .IP \(bu 2 \fBmay_exist\fP \-\- Bool, if False \- attempting to create a port that exists returns False. .IP \(bu 2 \fBinternal\fP \-\- A boolean to create an internal interface if one does not exist. .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.port_add br0 8080 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.port_create_gre(br, port, id, remote) Generic Routing Encapsulation \- creates GRE tunnel between endpoints. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbr\fP \-\- A string \- bridge name. .IP \(bu 2 \fBport\fP \-\- A string \- port name. .IP \(bu 2 \fBid\fP \-\- An integer \- unsigned 32\-bit number, tunnel\(aqs key. .IP \(bu 2 \fBremote\fP \-\- A string \- remote endpoint\(aqs IP address. .UNINDENT .TP .B Returns True on success, else False. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.port_create_gre br0 gre1 5001 192.168.1.10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.port_create_vlan(br, port, id, internal=False) Isolate VM traffic using VLANs. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbr\fP \-\- A string \- bridge name. .IP \(bu 2 \fBport\fP \-\- A string \- port name. .IP \(bu 2 \fBid\fP \-\- An integer in the valid range 0 to 4095 (inclusive), name of VLAN. .IP \(bu 2 \fBinternal\fP \-\- A boolean to create an internal interface if one does not exist. .UNINDENT .TP .B Returns True on success, else False. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.port_create_vlan br0 tap0 100 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.port_create_vxlan(br, port, id, remote, dst_port=None) Virtual eXtensible Local Area Network \- creates VXLAN tunnel between endpoints. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbr\fP \-\- A string \- bridge name. .IP \(bu 2 \fBport\fP \-\- A string \- port name. .IP \(bu 2 \fBid\fP \-\- An integer \- unsigned 64\-bit number, tunnel\(aqs key. .IP \(bu 2 \fBremote\fP \-\- A string \- remote endpoint\(aqs IP address. .IP \(bu 2 \fBdst_port\fP \-\- An integer \- port to use when creating tunnelport in the switch. .UNINDENT .TP .B Returns True on success, else False. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.port_create_vxlan br0 vx1 5001 192.168.1.10 8472 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.port_get_tag(port) Lists tags of the port. .INDENT 7.0 .TP .B Parameters \fBport\fP \-\- A string \- port name. .TP .B Returns List of tags (or empty list), False on failure. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.port_get_tag tap0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.port_list(br) Lists all of the ports within bridge. .INDENT 7.0 .TP .B Parameters \fBbr\fP \-\- A string \- bridge name. .TP .B Returns List of bridges (or empty list), False on failure. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.port_list br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.openvswitch.port_remove(br, port, if_exists=True) .INDENT 7.0 .INDENT 3.5 Deletes port. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbr\fP \-\- A string \- bridge name (If bridge is None, port is removed from whatever bridge contains it) .IP \(bu 2 \fBport\fP \-\- A string \- port name. .IP \(bu 2 \fBif_exists\fP \-\- Bool, if False \- attempting to delete a por that does not exist returns False. (Default True) .UNINDENT .TP .B Returns True on success, else False. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq openvswitch.port_remove br0 8080 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.opkg .sp Support for Opkg .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For version comparison support on opkg < 0.3.4, the \fBopkg\-utils\fP package must be installed. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.available_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 <package name> salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.check_extra_requirements(pkgname, pkgver) Check if the installed package already has the given requirements. There\(aqs nothing do to here for nipkg.py, therefore it will always return True. .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.del_repo(repo, **kwargs) Delete a repo from \fB/etc/opkg/*.conf\fP .sp If the file does not contain any other repo configuration, the file itself will be deleted. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.del_repo repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.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.opkg.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.opkg.get_repo(repo, **kwargs) Display a repo from the \fB/etc/opkg/*.conf\fP .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.get_repo repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.hold(name=None, pkgs=None, sources=None, **kwargs) 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 <package name> .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[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.info_installed(*names, **kwargs) Return the information of the named package(s), installed on the system. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnames\fP \-\- Names of the packages to get information about. If none are specified, will return information for all installed packages. .IP \(bu 2 \fBattr\fP \-\- .sp Comma\-separated package attributes. If no \(aqattr\(aq is specified, all available attributes returned. .INDENT 2.0 .TP .B Valid attributes are: arch, conffiles, conflicts, depends, description, filename, group, install_date_time_t, md5sum, packager, provides, recommends, replaces, size, source, suggests, url, version .UNINDENT .UNINDENT .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 attr=version,packager salt \(aq*\(aq pkg.info_installed <package1> salt \(aq*\(aq pkg.info_installed <package1> <package2> <package3> ... salt \(aq*\(aq pkg.info_installed <package1> attr=version,packager salt \(aq*\(aq pkg.info_installed <package1> <package2> <package3> ... attr=version,packager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.install(name=None, refresh=False, pkgs=None, sources=None, reinstall=False, **kwargs) Install the passed package, add refresh=True to update the opkg database. .INDENT 7.0 .TP .B name The name of the package to be installed. Note that this parameter is ignored if either \(dqpkgs\(dq or \(dqsources\(dq 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 \(dqsources\(dq option. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B refresh Whether or not to refresh the package database before installing. .TP .B version Install a specific version of the package, e.g. 1.2.3~0ubuntu0. Ignored if \(dqpkgs\(dq or \(dqsources\(dq is passed. .sp New in version 2017.7.0. .TP .B reinstall False Specifying reinstall=True will use \fBopkg install \-\-force\-reinstall\fP rather than simply \fBopkg install\fP for requested packages that are already installed. .sp If a version is specified with the requested package, then \fBopkg install \-\-force\-reinstall\fP will only be used if the installed version matches the requested version. .sp New in version 2017.7.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[\(dqfoo\(dq, \(dqbar\(dq]\(aq salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, {\(dqbar\(dq: \(dq1.2.3\-0ubuntu0\(dq}]\(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[{\(dqfoo\(dq: \(dqsalt://foo.deb\(dq},{\(dqbar\(dq: \(dqsalt://bar.deb\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B install_recommends Whether to install the packages marked as recommended. Default is True. .TP .B only_upgrade Only upgrade the packages (disallow downgrades), if they are already installed. Default is False. .sp New in version 2017.7.0. .UNINDENT .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.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 <package name> salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.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<package_name>\(aq: \(aq<version>\(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.opkg.list_repos(**kwargs) Lists all repos on \fB/etc/opkg/*.conf\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_repos .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.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.opkg.mod_repo(repo, **kwargs) Modify one or more values for a repo. If the repo does not exist, it will be created, so long as uri is defined. .sp The following options are available to modify a repo definition: .INDENT 7.0 .TP .B repo alias by which opkg refers to the repo. .TP .B uri the URI to the repo. .TP .B compressed defines (True or False) if the index file is compressed .TP .B enabled enable or disable (True or False) repository but do not remove if disabled. .TP .B refresh enable or disable (True or False) auto\-refresh of the repositories .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.mod_repo repo uri=http://new/uri salt \(aq*\(aq pkg.mod_repo repo enabled=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.owner(*paths, **kwargs) Return the name of the package that owns the file. Multiple file paths can be passed. Like \fBpkg.version <salt.modules.opkg.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.opkg.purge(name=None, pkgs=None, **kwargs) Package purges are not supported by opkg, this function is identical to \fI\%pkg.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 Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.purge <package name> salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3> salt \(aq*\(aq pkg.purge pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.refresh_db(failhard=False, **kwargs) Updates the opkg 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 .UNINDENT .INDENT 7.0 .TP .B failhard If False, return results of failed 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. .sp New in version 2018.3.0. .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.opkg.remove(name=None, pkgs=None, **kwargs) Remove packages using \fBopkg 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. .TP .B remove_dependencies Remove package and all dependencies .sp New in version 2019.2.0. .TP .B auto_remove_deps Remove packages that were installed automatically to satisfy dependencies .sp New in version 2019.2.0. .UNINDENT .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 <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq remove_dependencies=True auto_remove_deps=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.unhold(name=None, pkgs=None, sources=None, **kwargs) 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 <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B pkgs A list of packages to hold. Must be passed as a python list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unhold pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.upgrade(refresh=True, **kwargs) Upgrades all packages via \fBopkg upgrade\fP .sp Returns a dictionary containing the changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.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 <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.version_clean(version) Clean the version string removing extra data. There\(aqs nothing do to here for nipkg.py, therefore it will always return the given version. .UNINDENT .INDENT 0.0 .TP .B salt.modules.opkg.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 2016.3.4. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.opsgenie .sp Module for sending data to OpsGenie .sp New in version 2018.3.0. .INDENT 0.0 .TP .B configuration This module can be used in Reactor System for posting data to OpsGenie as a remote\-execution function. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C opsgenie_event_poster: local.opsgenie.post_data: \- tgt: \(aqsalt\-minion\(aq \- kwarg: name: event.reactor api_key: XXXXXXXX\-XXXX\-XXXX\-XXXX\-XXXXXXXXXXXX reason: {{ data[\(aqdata\(aq][\(aqreason\(aq] }} action_type: Create .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.opsgenie.post_data(api_key=None, name=\(aqOpsGenie Execution Module\(aq, reason=None, action_type=None) Post data to OpsGenie. It\(aqs designed for Salt\(aqs Event Reactor. .sp After configuring the sls reaction file as shown above, you can trigger the module with your designated tag (og\-tag in this case). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call event.send \(aqog\-tag\(aq \(aq{\(dqreason\(dq : \(dqOverheating CPU!\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp Required parameters: .INDENT 7.0 .TP .B api_key It\(aqs the API Key you\(aqve copied while adding integration in OpsGenie. .TP .B reason It will be used as alert\(aqs default message in OpsGenie. .TP .B action_type OpsGenie supports the default values Create/Close for action_type. You can customize this field with OpsGenie\(aqs custom actions for other purposes like adding notes or acknowledging alerts. .UNINDENT .sp Optional parameters: .INDENT 7.0 .TP .B name It will be used as alert\(aqs alias. If you want to use the close functionality you must provide name field for both states like in this case. .UNINDENT .UNINDENT .SS salt.modules.oracle .sp Oracle DataBase connection module .INDENT 0.0 .TP .B maintainer Vladimir Bormotov <\fI\%bormotov@gmail.com\fP> .TP .B maturity new .TP .B depends cx_Oracle .TP .B platform all .TP .B configuration module provide connections for multiple Oracle DB instances. .sp \fBOS Environment\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ORACLE_HOME: path to oracle product PATH: path to Oracle Client libs need to be in PATH .ft P .fi .UNINDENT .UNINDENT .sp \fBpillar\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C oracle: dbs: <db>: uri: connection credentials in format: user/password@host[:port]/sid[ servicename as {sysdba|sysoper}] optional keyword servicename will determine whether it is a sid or service_name <db>: uri: ..... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.oracle.client_version() Oracle Client Version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq oracle.client_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.oracle.run_query(db, query) Run SQL query and return result .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq oracle.run_query my_db \(dqselect * from my_table\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.oracle.show_dbs(*dbs) Show databases configuration from pillar. Filter by \fI*args\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq oracle.show_dbs salt \(aq*\(aq oracle.show_dbs my_db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.oracle.show_env() Show Environment used by Oracle Client .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq oracle.show_env .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 at first _connect() \fBNLS_LANG\fP will forced to \(aq.AL32UTF8\(aq .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.oracle.show_pillar(item=None) Show Pillar segment oracle.* and subitem with notation \(dqitem:subitem\(dq .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq oracle.show_pillar salt \(aq*\(aq oracle.show_pillar dbs:my_db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.oracle.version(*dbs) Server Version (select banner from v$version) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq oracle.version salt \(aq*\(aq oracle.version my_db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.osquery .sp Support for OSQuery \- \fI\%https://osquery.io\fP\&. .sp New in version 2015.8.0. .INDENT 0.0 .TP .B salt.modules.osquery.acpi_tables(attrs=None, where=None) Return acpi_tables information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.acpi_tables .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.alf(attrs=None, where=None) Return alf information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.alf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.alf_exceptions(attrs=None, where=None) Return alf_exceptions information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.alf_exceptions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.alf_explicit_auths(attrs=None, where=None) Return alf_explicit_auths information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.alf_explicit_auths .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.alf_services(attrs=None, where=None) Return alf_services information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.alf_services .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.apps(attrs=None, where=None) Return apps information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.apps .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.apt_sources(attrs=None, where=None) Return apt_sources information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.apt_sources .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.arp_cache(attrs=None, where=None) Return arp_cache information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.arp_cache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.block_devices(attrs=None, where=None) Return block_devices information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.block_devices .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.certificates(attrs=None, where=None) Return certificates information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.certificates .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.chrome_extensions(attrs=None, where=None) Return chrome_extensions information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.chrome_extensions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.cpuid(attrs=None, where=None) Return cpuid information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.cpuid .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.crontab(attrs=None, where=None) Return crontab information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.crontab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.deb_packages(attrs=None, where=None) Return deb_packages information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.deb_packages .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.etc_hosts(attrs=None, where=None) Return etc_hosts information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.etc_hosts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.etc_services(attrs=None, where=None) Return etc_services information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.etc_services .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.file_(attrs=None, where=None) Return file information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.file_changes(attrs=None, where=None) Return file_changes information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.file_changes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.firefox_addons(attrs=None, where=None) Return firefox_addons information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.firefox_addons .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.groups(attrs=None, where=None) Return groups information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.groups .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.hardware_events(attrs=None, where=None) Return hardware_events information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.hardware_events .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.hash_(attrs=None, where=None) Return hash information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.hash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.homebrew_packages(attrs=None, where=None) Return homebrew_packages information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.homebrew_packages .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.interface_addresses(attrs=None, where=None) Return interface_addresses information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.interface_addresses .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.interface_details(attrs=None, where=None) Return interface_details information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.interface_details .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.iokit_devicetree(attrs=None, where=None) Return iokit_devicetree information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.iokit_devicetree .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.iokit_registry(attrs=None, where=None) Return iokit_registry information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.iokit_registry .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.kernel_extensions(attrs=None, where=None) Return kernel_extensions information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.kernel_extensions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.kernel_info(attrs=None, where=None) Return kernel_info information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.kernel_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.kernel_integrity(attrs=None, where=None) Return kernel_integrity information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.kernel_integrity .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.kernel_modules(attrs=None, where=None) Return kernel_modules information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.kernel_modules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.keychain_items(attrs=None, where=None) Return keychain_items information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.keychain_items .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.last(attrs=None, where=None) Return last information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.last .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.launchd(attrs=None, where=None) Return launchd information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.launchd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.listening_ports(attrs=None, where=None) Return listening_ports information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.listening_ports .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.logged_in_users(attrs=None, where=None) Return logged_in_users information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.logged_in_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.memory_map(attrs=None, where=None) Return memory_map information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.memory_map .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.mounts(attrs=None, where=None) Return mounts information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.mounts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.nfs_shares(attrs=None, where=None) Return nfs_shares information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.nfs_shares .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.nvram(attrs=None, where=None) Return nvram information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.nvram .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.os_version(attrs=None, where=None) Return os_version information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.os_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.osquery_extensions(attrs=None, where=None) Return osquery_extensions information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.osquery_extensions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.osquery_flags(attrs=None, where=None) Return osquery_flags information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.osquery_flags .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.osquery_info(attrs=None, where=None) Return osquery_info information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.osquery_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.osquery_registry(attrs=None, where=None) Return osquery_registry information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.osquery_registry .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.passwd_changes(attrs=None, where=None) Return passwd_changes information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.passwd_changes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.pci_devices(attrs=None, where=None) Return pci_devices information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.pci_devices .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.preferences(attrs=None, where=None) Return preferences information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.preferences .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.process_envs(attrs=None, where=None) Return process_envs information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.process_envs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.process_memory_map(attrs=None, where=None) Return process_memory_map information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.process_memory_map .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.process_open_files(attrs=None, where=None) Return process_open_files information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.process_open_files .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.process_open_sockets(attrs=None, where=None) Return process_open_sockets information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.process_open_sockets .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.processes(attrs=None, where=None) Return processes information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.processes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.quarantine(attrs=None, where=None) Return quarantine information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.quarantine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.query(sql=None) Return time information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.query \(dqselect * from users;\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.routes(attrs=None, where=None) Return routes information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.routes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.rpm_packages(attrs=None, where=None) Return cpuid information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.rpm_packages .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.safari_extensions(attrs=None, where=None) Return safari_extensions information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.safari_extensions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.shared_memory(attrs=None, where=None) Return shared_memory information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.shared_memory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.shell_history(attrs=None, where=None) Return shell_history information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.shell_history .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.smbios_tables(attrs=None, where=None) Return smbios_tables information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.smbios_tables .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.startup_items(attrs=None, where=None) Return startup_items information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.startup_items .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.suid_bin(attrs=None, where=None) Return suid_bin information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.suid_bin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.system_controls(attrs=None, where=None) Return system_controls information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.system_controls .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.time_(attrs=None) Return time information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.time .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.usb_devices(attrs=None, where=None) Return usb_devices information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.usb_devices .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.users(attrs=None, where=None) Return users information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.version() Return version of osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.xattr_where_from(attrs=None, where=None) Return xattr_where_from information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.xattr_where_from .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.xprotect_entries(attrs=None, where=None) Return xprotect_entries information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.xprotect_entries .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.osquery.xprotect_reports(attrs=None, where=None) Return xprotect_reports information from osquery .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq osquery.xprotect_reports .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.out .SS Output Module .sp New in version 2018.3.0. .sp Execution module that processes JSON serializable data and returns string having the format as processed by the outputters. .sp Although this does not bring much value on the CLI, it turns very handy in applications that require human readable data rather than Python objects. .sp For example, inside a Jinja template: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ salt.out.string_format(complex_object, out=\(aqhighstate\(aq) }} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.out.html_format(data, out=\(aqnested\(aq, opts=None, **kwargs) Return the formatted string as HTML. .INDENT 7.0 .TP .B data The JSON serializable object. .TP .B out: \fBnested\fP The name of the output to use to transform the data. Default: \fBnested\fP\&. .TP .B opts Dictionary of configuration options. Default: \fB__opts__\fP\&. .TP .B kwargs Arguments to sent to the outputter module. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq out.html_format \(dq{\(aqkey\(aq: \(aqvalue\(aq}\(dq out=yaml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.out.out_format(data, out=\(aqnested\(aq, opts=None, **kwargs) Return the formatted outputter string for the Python object. .INDENT 7.0 .TP .B data The JSON serializable object. .TP .B out: \fBnested\fP The name of the output to use to transform the data. Default: \fBnested\fP\&. .TP .B opts Dictionary of configuration options. Default: \fB__opts__\fP\&. .TP .B kwargs Arguments to sent to the outputter module. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq out.out_format \(dq{\(aqkey\(aq: \(aqvalue\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.out.string_format(data, out=\(aqnested\(aq, opts=None, **kwargs) Return the outputter formatted string, removing the ANSI escape sequences. .INDENT 7.0 .TP .B data The JSON serializable object. .TP .B out: \fBnested\fP The name of the output to use to transform the data. Default: \fBnested\fP\&. .TP .B opts Dictionary of configuration options. Default: \fB__opts__\fP\&. .TP .B kwargs Arguments to sent to the outputter module. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq out.string_format \(dq{\(aqkey\(aq: \(aqvalue\(aq}\(dq out=table .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pacmanpkg .sp A module to wrap pacman calls, since Arch is the best (\fI\%https://wiki.archlinux.org/index.php/Arch_is_the_best\fP) .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.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 CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.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.pacmanpkg.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.pacmanpkg.group_diff(name) New in version 2016.11.0. .sp Lists which of a group\(aqs packages are installed and which are not installed .sp Compatible with yumpkg.group_diff for easy support of state.pkg.group_installed .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.group_diff \(aqxorg\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.group_info(name) New in version 2016.11.0. .sp Lists all packages in the specified group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.group_info \(aqxorg\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.group_list() New in version 2016.11.0. .sp Lists all groups known by pacman on this system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.group_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.install(name=None, refresh=False, sysupgrade=None, pkgs=None, sources=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 pacman 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Install (\fBpacman \-S\fP) the specified packag(s). Add \fBrefresh=True\fP to install with \fB\-y\fP, add \fBsysupgrade=True\fP to install with \fB\-u\fP\&. .INDENT 7.0 .TP .B name The name of the package to be installed. Note that this parameter is ignored if either \fBpkgs\fP or \fBsources\fP 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 \fBsources\fP option. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B refresh Whether or not to refresh the package database before installing. .TP .B sysupgrade Whether or not to upgrade the system packages before installing. If refresh is set to \fBTrue\fP but sysupgrade is not specified, \fB\-u\fP will be applied .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. A specific version number can be specified by using a single\-element dict representing the package and its version. As with the \fBversion\fP parameter above, comparison operators can be used to target a specific version of a package. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, {\(dqbar\(dq: \(dq1.2.3\-4\(dq}]\(aq salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, {\(dqbar\(dq: \(dq<1.2.3\-4\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B sources A list of packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sources=\(aq[{\(dqfoo\(dq: \(dqsalt://foo.pkg.tar.xz\(dq}, {\(dqbar\(dq: \(dqsalt://bar.pkg.tar.xz\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.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 <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.list_pkgs(versions_as_list=False, **kwargs) List the packages currently installed as a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(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.pacmanpkg.list_repo_pkgs(*args, **kwargs) 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 \fI\%pkg.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. If \fBbyrepo\fP is set to \fBTrue\fP, then the return dictionary will contain repository names at the top level, and each repository will map packages to lists of version numbers. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # With byrepo=False (default) { \(aqbash\(aq: [\(aq4.4.005\-2\(aq], \(aqnginx\(aq: [\(aq1.10.2\-2\(aq] } # With byrepo=True { \(aqcore\(aq: { \(aqbash\(aq: [\(aq4.4.005\-2\(aq] }, \(aqextra\(aq: { \(aqnginx\(aq: [\(aq1.10.2\-2\(aq] } } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B fromrepo None Only include results from the specified repo(s). Multiple repos can be specified, comma\-separated. .TP .B byrepo False When \fBTrue\fP, the return data for each package will be organized by repository. .TP .B refresh False When \fBTrue\fP, the package database will be refreshed (i.e. \fBpacman \-Sy\fP) before checking for available versions. .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 salt \(aq*\(aq pkg.list_repo_pkgs \(aqsamba4*\(aq fromrepo=base,updates salt \(aq*\(aq pkg.list_repo_pkgs \(aqpython2\-*\(aq byrepo=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.list_upgrades(refresh=False, root=None, **kwargs) List all available package upgrades on this system .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.pacmanpkg.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/zsh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.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 pacman 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Recursively remove a package and all dependencies which were installed with it, this will call a \fBpacman \-Rsc\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.purge <package name> salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3> salt \(aq*\(aq pkg.purge pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.refresh_db(root=None, **kwargs) Just run a \fBpacman \-Sy\fP, return a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<database name>\(aq: Bool} .ft P .fi .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.pacmanpkg.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 pacman 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Remove packages with \fBpacman \-R\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 <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.upgrade(refresh=False, root=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 pacman 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Run a full system upgrade, a pacman \-Syu .INDENT 7.0 .TP .B refresh Whether or not to refresh the package database before installing. .UNINDENT .sp Returns a dictionary containing the changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.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 <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacmanpkg.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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pagerduty .sp Module for Firing Events via PagerDuty .sp New in version 2014.1.0. .INDENT 0.0 .TP .B configuration This module can be used by specifying the name of a configuration profile in the minion config, minion pillar, or master config. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my\-pagerduty\-account: pagerduty.api_key: F3Rbyjbve43rfFWf2214 pagerduty.subdomain: mysubdomain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty.create_event(service_key=None, description=None, details=None, incident_key=None, profile=None) Create an event in PagerDuty. Designed for use in states. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.create_event <service_key> <description> <details> profile=my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B service_key This key can be found by using pagerduty.list_services. .TP .B description This is a short description of the event. .TP .B details This can be a more detailed description of the event. .TP .B profile This refers to the configuration profile to use to connect to the PagerDuty service. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty.list_escalation_policies(profile=None, api_key=None) This function is an alias of \fBlist_policies\fP\&. .INDENT 7.0 .INDENT 3.5 List escalation policies belonging to this account .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.list_policies my\-pagerduty\-account salt myminion pagerduty.list_escalation_policies my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty.list_incidents(profile=None, api_key=None) List incidents belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.list_incidents my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty.list_maintenance_windows(profile=None, api_key=None) This function is an alias of \fBlist_windows\fP\&. .INDENT 7.0 .INDENT 3.5 List maintenance windows belonging to this account .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.list_windows my\-pagerduty\-account salt myminion pagerduty.list_maintenance_windows my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty.list_policies(profile=None, api_key=None) List escalation policies belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.list_policies my\-pagerduty\-account salt myminion pagerduty.list_escalation_policies my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty.list_schedules(profile=None, api_key=None) List schedules belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.list_schedules my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty.list_services(profile=None, api_key=None) List services belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.list_services my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty.list_users(profile=None, api_key=None) List users belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.list_users my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty.list_windows(profile=None, api_key=None) List maintenance windows belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.list_windows my\-pagerduty\-account salt myminion pagerduty.list_maintenance_windows my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pagerduty_util .sp Module for manageing PagerDuty resource .INDENT 0.0 .TP .B configuration This module can be used by specifying the name of a configuration profile in the minion config, minion pillar, or master config. The default configuration profile name is \(aqpagerduty.\(aq .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pagerduty: pagerduty.api_key: F3Rbyjbve43rfFWf2214 pagerduty.subdomain: mysubdomain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp For PagerDuty API details, see \fI\%https://developer.pagerduty.com/documentation/rest\fP .INDENT 0.0 .TP .B salt.modules.pagerduty_util.create_or_update_resource(resource_name, identifier_fields, data, diff=None, profile=\(aqpagerduty\(aq, subdomain=None, api_key=None) create or update any pagerduty resource Helper method for present(). .sp Determining if two resources are the same is different for different PD resource, so this method accepts a diff function. The diff function will be invoked as diff(state_information, object_returned_from_pagerduty), and should return a dict of data to pass to the PagerDuty update API method, or None if no update is to be performed. If no diff method is provided, the default behavor is to scan the keys in the state_information, comparing the matching values in the object_returned_from_pagerduty, and update any values that differ. .sp Examples .sp create_or_update_resource(\(dquser\(dq, [\(dqid\(dq,\(dqname\(dq,\(dqemail\(dq]) create_or_update_resource(\(dqescalation_policies\(dq, [\(dqid\(dq,\(dqname\(dq], diff=my_diff_function) .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty_util.delete_resource(resource_name, key, identifier_fields, profile=\(aqpagerduty\(aq, subdomain=None, api_key=None) delete any pagerduty resource .sp Helper method for absent() .sp Example .sp delete_resource(\(dqusers\(dq, key, [\(dqid\(dq,\(dqname\(dq,\(dqemail\(dq]) # delete by id or name or email .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty_util.get_escalation_policies(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None) List escalation_policies belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.get_escalation_policies .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty_util.get_resource(resource_name, key, identifier_fields, profile=\(aqpagerduty\(aq, subdomain=None, api_key=None) Get any single pagerduty resource by key. .sp We allow flexible lookup by any of a list of identifier_fields. So, for example, you can look up users by email address or name by calling: .INDENT 7.0 .INDENT 3.5 get_resource(\(aqusers\(aq, key, [\(aqname\(aq, \(aqemail\(aq], ...) .UNINDENT .UNINDENT .sp This method is mainly used to translate state sls into pagerduty id\(aqs for dependent objects. For example, a pagerduty escalation policy contains one or more schedules, which must be passed by their pagerduty id. We look up the schedules by name (using this method), and then translate the names into id\(aqs. .sp This method is implemented by getting all objects of the resource type (cached into __context__), then brute force searching through the list and trying to match any of the identifier_fields. The __context__ cache is purged after any create, update or delete to the resource. .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty_util.get_schedules(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None) List schedules belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.get_schedules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty_util.get_services(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None) List services belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.get_services .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty_util.get_users(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None) List users belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pagerduty.get_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty_util.resource_absent(resource, identifier_fields, profile=\(aqpagerduty\(aq, subdomain=None, api_key=None, **kwargs) Generic resource.absent state method. Pagerduty state modules should be a thin wrapper over this method, with a custom diff function. .sp This method calls delete_resource() and formats the result as a salt state return value. .sp Example .sp resource_absent(\(dqusers\(dq, [\(dqid\(dq,\(dqname\(dq,\(dqemail\(dq]) .UNINDENT .INDENT 0.0 .TP .B salt.modules.pagerduty_util.resource_present(resource, identifier_fields, diff=None, profile=\(aqpagerduty\(aq, subdomain=None, api_key=None, **kwargs) Generic resource.present state method. Pagerduty state modules should be a thin wrapper over this method, with a custom diff function. .sp This method calls create_or_update_resource() and formats the result as a salt state return value. .sp Example .sp resource_present(\(dqusers\(dq, [\(dqid\(dq,\(dqname\(dq,\(dqemail\(dq]) .UNINDENT .SS salt.modules.pam .sp Support for pam .INDENT 0.0 .TP .B salt.modules.pam.read_file(file_name) This is just a test function, to make sure parsing works .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pam.read_file /etc/pam.d/login .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.panos .sp Module to provide Palo Alto compatibility to Salt .INDENT 0.0 .TP .B codeauthor \fBSpencer Ervin <spencer_ervin@hotmail.com>\fP .TP .B maturity new .TP .B depends none .TP .B platform unix .UNINDENT .sp New in version 2018.3.0. .SS Configuration .sp This module accepts connection configuration details either as parameters, or as configuration settings in pillar as a Salt proxy. Options passed into opts will be ignored if options are passed into pillar. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Palo Alto Proxy Module\fP .UNINDENT .UNINDENT .SS About .sp This execution module was designed to handle connections to a Palo Alto based firewall. This module adds support to send connections directly to the device through the XML API or through a brokered connection to Panorama. .INDENT 0.0 .TP .B salt.modules.panos.add_config_lock() Prevent other users from changing configuration until the lock is released. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.add_config_lock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.check_antivirus() Get anti\-virus information from PaloAlto Networks server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.check_antivirus .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.check_software() Get software information from PaloAlto Networks server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.check_software .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.clear_commit_tasks() Clear all commit tasks. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.clear_commit_tasks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.commit() Commits the candidate configuration to the running configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.commit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.deactivate_license(key_name=None) Deactivates an installed license. Required version 7.0.0 or greater. .sp key_name(str): The file name of the license key installed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.deactivate_license key_name=License_File_Name.key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.delete_license(key_name=None) Remove license keys on disk. .sp key_name(str): The file name of the license key to be deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.delete_license key_name=License_File_Name.key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.download_antivirus() Download the most recent anti\-virus package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.download_antivirus .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.download_software_file(filename=None, synch=False) Download software packages by filename. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfilename\fP (\fI\%str\fP) \-\- The filename of the PANOS file to download. .IP \(bu 2 \fBsynch\fP (\fI\%bool\fP) \-\- If true then the file will synch to the peer unit. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.download_software_file PanOS_5000\-8.0.0 salt \(aq*\(aq panos.download_software_file PanOS_5000\-8.0.0 True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.download_software_version(version=None, synch=False) Download software packages by version number. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- The version of the PANOS file to download. .IP \(bu 2 \fBsynch\fP (\fI\%bool\fP) \-\- If true then the file will synch to the peer unit. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.download_software_version 8.0.0 salt \(aq*\(aq panos.download_software_version 8.0.0 True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.fetch_license(auth_code=None) Get new license(s) using from the Palo Alto Network Server. .INDENT 7.0 .TP .B auth_code The license authorization code. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.fetch_license salt \(aq*\(aq panos.fetch_license auth_code=foobar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_address(address=None, vsys=\(aq1\(aq) Get the candidate configuration for the specified get_address object. This will not return address objects that are marked as pre\-defined objects. .sp address(str): The name of the address object. .sp vsys(str): The string representation of the VSYS ID. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_address myhost salt \(aq*\(aq panos.get_address myhost 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_address_group(addressgroup=None, vsys=\(aq1\(aq) Get the candidate configuration for the specified address group. This will not return address groups that are marked as pre\-defined objects. .sp addressgroup(str): The name of the address group. .sp vsys(str): The string representation of the VSYS ID. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_address_group foobar salt \(aq*\(aq panos.get_address_group foobar 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_admins_active() Show active administrators. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_admins_active .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_admins_all() Show all administrators. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_admins_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_antivirus_info() Show information about available anti\-virus packages. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_antivirus_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_arp() Show ARP information. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_arp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_cli_idle_timeout() Show timeout information for this administrative session. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_cli_idle_timeout .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_cli_permissions() Show cli administrative permissions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_cli_permissions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_disk_usage() Report filesystem disk space usage. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_disk_usage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_dns_server_config() Get the DNS server configuration from the candidate configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_dns_server_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_domain_config() Get the domain name configuration from the candidate configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_domain_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_dos_blocks() Show the DoS block\-ip table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_dos_blocks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_fqdn_cache() Print FQDNs used in rules and their IPs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_fqdn_cache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_ha_config() Get the high availability configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_ha_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_ha_link() .INDENT 7.0 .INDENT 3.5 Show high\-availability link\-monitoring state. .sp CLI Example: .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_ha_link .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_ha_path() Show high\-availability path\-monitoring state. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_ha_path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_ha_state() Show high\-availability state information. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_ha_state .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_ha_transitions() Show high\-availability transition statistic information. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_ha_transitions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_hostname() Get the hostname of the device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_hostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_interface_counters(name=\(aqall\(aq) Get the counter statistics for interfaces. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the interface to view. By default, all interface statistics are viewed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_interface_counters salt \(aq*\(aq panos.get_interface_counters ethernet1/1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_interfaces(name=\(aqall\(aq) Show interface information. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the interface to view. By default, all interface statistics are viewed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_interfaces salt \(aq*\(aq panos.get_interfaces ethernet1/1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_job(jid=None) List all a single job by ID. .INDENT 7.0 .TP .B jid The ID of the job to retrieve. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_job jid=15 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_jobs(state=\(aqall\(aq) List all jobs on the device. .INDENT 7.0 .TP .B state The state of the jobs to display. Valid options are all, pending, or processed. Pending jobs are jobs that are currently in a running or waiting state. Processed jobs are jobs that have completed execution. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_jobs salt \(aq*\(aq panos.get_jobs state=pending .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_lacp() Show LACP state. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_lacp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_license_info() Show information about owned license(s). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_license_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_license_tokens() Show license token files for manual license deactivation. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_license_tokens .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_lldp_config() Show lldp config for interfaces. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_lldp_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_lldp_counters() Show lldp counters for interfaces. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_lldp_counters .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_lldp_local() Show lldp local info for interfaces. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_lldp_local .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_lldp_neighbors() Show lldp neighbors info for interfaces. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_lldp_neighbors .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_local_admins() Show all local administrator accounts. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_local_admins .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_logdb_quota() Report the logdb quotas. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_logdb_quota .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_master_key() Get the master key properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_master_key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_ntp_config() Get the NTP configuration from the candidate configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_ntp_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_ntp_servers() Get list of configured NTP servers. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_ntp_servers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_operational_mode() Show device operational mode setting. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_operational_mode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_panorama_status() Show panorama connection status. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_panorama_status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_permitted_ips() Get the IP addresses that are permitted to establish management connections to the device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_permitted_ips .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_platform() Get the platform model information and limitations. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_platform .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_predefined_application(application=None) Get the configuration for the specified pre\-defined application object. This will only return pre\-defined application objects. .sp application(str): The name of the pre\-defined application object. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_predefined_application saltstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_security_rule(rulename=None, vsys=\(aq1\(aq) Get the candidate configuration for the specified security rule. .sp rulename(str): The name of the security rule. .sp vsys(str): The string representation of the VSYS ID. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_security_rule rule01 salt \(aq*\(aq panos.get_security_rule rule01 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_service(service=None, vsys=\(aq1\(aq) Get the candidate configuration for the specified service object. This will not return services that are marked as pre\-defined objects. .sp service(str): The name of the service object. .sp vsys(str): The string representation of the VSYS ID. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_service tcp\-443 salt \(aq*\(aq panos.get_service tcp\-443 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_service_group(servicegroup=None, vsys=\(aq1\(aq) Get the candidate configuration for the specified service group. This will not return service groups that are marked as pre\-defined objects. .sp servicegroup(str): The name of the service group. .sp vsys(str): The string representation of the VSYS ID. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_service_group foobar salt \(aq*\(aq panos.get_service_group foobar 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_session_info() Show device session statistics. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_session_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_snmp_config() Get the SNMP configuration from the device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_snmp_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_software_info() Show information about available software packages. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_software_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_system_date_time() Get the system date/time. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_system_date_time .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_system_files() List important files in the system. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_system_files .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_system_info() Get the system information. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_system_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_system_services() Show system services. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_system_services .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_system_state(mask=None) Show the system state variables. .INDENT 7.0 .TP .B mask Filters by a subtree or a wildcard. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_system_state salt \(aq*\(aq panos.get_system_state mask=cfg.ha.config.enabled salt \(aq*\(aq panos.get_system_state mask=cfg.ha.* .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_uncommitted_changes() Retrieve a list of all uncommitted changes on the device. Requires PANOS version 8.0.0 or greater. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_uncommitted_changes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_users_config() Get the local administrative user account configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_users_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_vlans() Show all VLAN information. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_vlans .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_xpath(xpath=\(aq\(aq) Retrieve a specified xpath from the candidate configuration. .sp xpath(str): The specified xpath in the candidate configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_xpath /config/shared/service .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_zone(zone=\(aq\(aq, vsys=\(aq1\(aq) Get the candidate configuration for the specified zone. .sp zone(str): The name of the zone. .sp vsys(str): The string representation of the VSYS ID. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_zone trust salt \(aq*\(aq panos.get_zone trust 2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.get_zones(vsys=\(aq1\(aq) Get all the zones in the candidate configuration. .sp vsys(str): The string representation of the VSYS ID. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.get_zones salt \(aq*\(aq panos.get_zones 2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.install_antivirus(version=None, latest=False, synch=False, skip_commit=False) Install anti\-virus packages. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- The version of the PANOS file to install. .IP \(bu 2 \fBlatest\fP (\fI\%bool\fP) \-\- If true, the latest anti\-virus file will be installed. The specified version option will be ignored. .IP \(bu 2 \fBsynch\fP (\fI\%bool\fP) \-\- If true, the anti\-virus will synch to the peer unit. .IP \(bu 2 \fBskip_commit\fP (\fI\%bool\fP) \-\- If true, the install will skip committing to the device. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.install_antivirus 8.0.0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.install_license() Install the license key(s). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.install_license .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.install_software(version=None) Upgrade to a software package by version. .INDENT 7.0 .TP .B Parameters \fBversion\fP (\fI\%str\fP) \-\- The version of the PANOS file to install. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.install_license 8.0.0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.reboot() Reboot a running system. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.reboot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.refresh_fqdn_cache(force=False) Force refreshes all FQDNs used in rules. .INDENT 7.0 .TP .B force Forces all fqdn refresh .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.refresh_fqdn_cache salt \(aq*\(aq panos.refresh_fqdn_cache force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.remove_config_lock() Release config lock previously held. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.remove_config_lock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.resolve_address(address=None, vsys=None) Resolve address to ip address. Required version 7.0.0 or greater. .INDENT 7.0 .TP .B address Address name you want to resolve. .TP .B vsys The vsys name. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.resolve_address foo.bar.com salt \(aq*\(aq panos.resolve_address foo.bar.com vsys=2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.save_device_config(filename=None) Save device configuration to a named file. .INDENT 7.0 .TP .B filename The filename to save the configuration to. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.save_device_config foo.xml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.save_device_state() Save files needed to restore device to local disk. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.save_device_state .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_authentication_profile(profile=None, deploy=False) Set the authentication profile of the Palo Alto proxy minion. A commit will be required before this is processed. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fI\%str\fP) \-\- The name of the authentication profile to set. .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.set_authentication_profile foo salt \(aq*\(aq panos.set_authentication_profile foo deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_hostname(hostname=None, deploy=False) Set the hostname of the Palo Alto proxy minion. A commit will be required before this is processed. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhostname\fP (\fI\%str\fP) \-\- The hostname to set .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.set_hostname newhostname salt \(aq*\(aq panos.set_hostname newhostname deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_management_http(enabled=True, deploy=False) Enables or disables the HTTP management service on the device. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBenabled\fP (\fI\%bool\fP) \-\- If true the service will be enabled. If false the service will be disabled. .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.set_management_http salt \(aq*\(aq panos.set_management_http enabled=False deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_management_https(enabled=True, deploy=False) Enables or disables the HTTPS management service on the device. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBenabled\fP (\fI\%bool\fP) \-\- If true the service will be enabled. If false the service will be disabled. .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.set_management_https salt \(aq*\(aq panos.set_management_https enabled=False deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_management_icmp(enabled=True, deploy=False) Enables or disables the ICMP management service on the device. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBenabled\fP (\fI\%bool\fP) \-\- If true the service will be enabled. If false the service will be disabled. .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.set_management_icmp salt \(aq*\(aq panos.set_management_icmp enabled=False deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_management_ocsp(enabled=True, deploy=False) Enables or disables the HTTP OCSP management service on the device. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBenabled\fP (\fI\%bool\fP) \-\- If true the service will be enabled. If false the service will be disabled. .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.set_management_ocsp salt \(aq*\(aq panos.set_management_ocsp enabled=False deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_management_snmp(enabled=True, deploy=False) Enables or disables the SNMP management service on the device. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBenabled\fP (\fI\%bool\fP) \-\- If true the service will be enabled. If false the service will be disabled. .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.set_management_snmp salt \(aq*\(aq panos.set_management_snmp enabled=False deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_management_ssh(enabled=True, deploy=False) Enables or disables the SSH management service on the device. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBenabled\fP (\fI\%bool\fP) \-\- If true the service will be enabled. If false the service will be disabled. .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.set_management_ssh salt \(aq*\(aq panos.set_management_ssh enabled=False deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_management_telnet(enabled=True, deploy=False) Enables or disables the Telnet management service on the device. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBenabled\fP (\fI\%bool\fP) \-\- If true the service will be enabled. If false the service will be disabled. .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.set_management_telnet salt \(aq*\(aq panos.set_management_telnet enabled=False deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_ntp_authentication(target=None, authentication_type=None, key_id=None, authentication_key=None, algorithm=None, deploy=False) Set the NTP authentication of the Palo Alto proxy minion. A commit will be required before this is processed. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtarget\fP (\fI\%str\fP) \-\- Determines the target of the authentication. Valid options are primary, secondary, or both. .IP \(bu 2 \fBauthentication_type\fP (\fI\%str\fP) \-\- The authentication type to be used. Valid options are symmetric, autokey, and none. .IP \(bu 2 \fBkey_id\fP (\fI\%int\fP) \-\- The NTP authentication key ID. .IP \(bu 2 \fBauthentication_key\fP (\fI\%str\fP) \-\- The authentication key. .IP \(bu 2 \fBalgorithm\fP (\fI\%str\fP) \-\- The algorithm type to be used for a symmetric key. Valid options are md5 and sha1. .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ntp.set_authentication target=both authentication_type=autokey salt \(aq*\(aq ntp.set_authentication target=primary authentication_type=none salt \(aq*\(aq ntp.set_authentication target=both authentication_type=symmetric key_id=15 authentication_key=mykey algorithm=md5 salt \(aq*\(aq ntp.set_authentication target=both authentication_type=symmetric key_id=15 authentication_key=mykey algorithm=md5 deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_ntp_servers(primary_server=None, secondary_server=None, deploy=False) Set the NTP servers of the Palo Alto proxy minion. A commit will be required before this is processed. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprimary_server\fP (\fI\%str\fP) \-\- The primary NTP server IP address or FQDN. .IP \(bu 2 \fBsecondary_server\fP (\fI\%str\fP) \-\- The secondary NTP server IP address or FQDN. .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ntp.set_servers 0.pool.ntp.org 1.pool.ntp.org salt \(aq*\(aq ntp.set_servers primary_server=0.pool.ntp.org secondary_server=1.pool.ntp.org salt \(aq*\(aq ntp.ser_servers 0.pool.ntp.org 1.pool.ntp.org deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_permitted_ip(address=None, deploy=False) Add an IPv4 address or network to the permitted IP list. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBaddress\fP (\fI\%str\fP) \-\- The IPv4 address or network to allow access to add to the Palo Alto device. .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.set_permitted_ip 10.0.0.1 salt \(aq*\(aq panos.set_permitted_ip 10.0.0.0/24 salt \(aq*\(aq panos.set_permitted_ip 10.0.0.1 deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.set_timezone(tz=None, deploy=False) Set the timezone of the Palo Alto proxy minion. A commit will be required before this is processed. .sp CLI Example: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtz\fP (\fI\%str\fP) \-\- The name of the timezone to set. .IP \(bu 2 \fBdeploy\fP (\fI\%bool\fP) \-\- If true then commit the full candidate configuration, if false only set pending change. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.set_timezone UTC salt \(aq*\(aq panos.set_timezone UTC deploy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.shutdown() Shutdown a running system. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.shutdown .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.test_fib_route(ip=None, vr=\(aqvr1\(aq) Perform a route lookup within active route table (fib). .sp ip (str): The destination IP address to test. .sp vr (str): The name of the virtual router to test. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.test_fib_route 4.2.2.2 salt \(aq*\(aq panos.test_fib_route 4.2.2.2 my\-vr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.test_security_policy(sourcezone=None, destinationzone=None, source=None, destination=None, protocol=None, port=None, application=None, category=None, vsys=\(aq1\(aq, allrules=False) Checks which security policy as connection will match on the device. .sp sourcezone (str): The source zone matched against the connection. .sp destinationzone (str): The destination zone matched against the connection. .sp source (str): The source address. This must be a single IP address. .sp destination (str): The destination address. This must be a single IP address. .sp protocol (int): The protocol number for the connection. This is the numerical representation of the protocol. .sp port (int): The port number for the connection. .sp application (str): The application that should be matched. .sp category (str): The category that should be matched. .sp vsys (int): The numerical representation of the VSYS ID. .sp allrules (bool): Show all potential match rules until first allow rule. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.test_security_policy sourcezone=trust destinationzone=untrust protocol=6 port=22 salt \(aq*\(aq panos.test_security_policy sourcezone=trust destinationzone=untrust protocol=6 port=22 vsys=2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.panos.unlock_admin(username=None) Unlocks a locked administrator account. .INDENT 7.0 .TP .B username Username of the administrator. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq panos.unlock_admin username=bob .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.parallels .sp Manage Parallels Desktop VMs with \fBprlctl\fP and \fBprlsrvctl\fP\&. Only some of the prlctl commands implemented so far. Of those that have been implemented, not all of the options may have been provided yet. For a complete reference, see the \fI\%Parallels Desktop Reference Guide\fP\&. .sp This module requires the prlctl binary to be installed to run most functions. To run parallels.prlsrvctl, the prlsrvctl binary is required. .sp What has not been implemented yet can be accessed through \fBparallels.prlctl\fP and \fBparallels.prlsrvctl\fP (note the preceding double dash \fB\-\-\fP as necessary): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.prlctl installtools macvm runas=macdev salt \-\- \(aq*\(aq parallels.prlctl capture \(aqmacvm \-\-file macvm.display.png\(aq runas=macdev salt \-\- \(aq*\(aq parallels.prlsrvctl set \(aq\-\-mem\-limit auto\(aq runas=macdev .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.modules.parallels.clone(name, new_name, linked=False, template=False, runas=None) Clone a VM .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM to clone .IP \(bu 2 \fBnew_name\fP (\fI\%str\fP) \-\- Name of the new VM .IP \(bu 2 \fBlinked\fP (\fI\%bool\fP) \-\- Create a linked virtual machine. .IP \(bu 2 \fBtemplate\fP (\fI\%bool\fP) \-\- Create a virtual machine template instead of a real virtual machine. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.clone macvm macvm_new runas=macdev salt \(aq*\(aq parallels.clone macvm macvm_templ template=True runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.delete(name, runas=None) Delete a VM .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM to clone .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.exec macvm \(aqfind /etc/paths.d\(aq runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.delete_snapshot(name, snap_name, runas=None, all=False) Delete a snapshot .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Deleting a snapshot from which other snapshots are dervied will not delete the derived snapshots .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM whose snapshot will be deleted .IP \(bu 2 \fBsnap_name\fP (\fI\%str\fP) \-\- Name/ID of snapshot to delete .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .IP \(bu 2 \fBall\fP (\fI\%bool\fP) \-\- .sp Delete all snapshots having the name given .sp New in version 2016.11.0. .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.delete_snapshot macvm \(aqunneeded snapshot\(aq runas=macdev salt \(aq*\(aq parallels.delete_snapshot macvm \(aqSnapshot for linked clone\(aq all=True runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.exec_(name, command, runas=None) Run a command on a VM .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM whose exec will be returned .IP \(bu 2 \fBcommand\fP (\fI\%str\fP) \-\- Command to run on the VM .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.exec macvm \(aqfind /etc/paths.d\(aq runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.exists(name, runas=None) Query whether a VM exists .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.exists macvm runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.list_snapshots(name, snap_name=None, tree=False, names=False, runas=None) List the snapshots .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM whose snapshots will be listed .IP \(bu 2 \fBsnap_id\fP (\fI\%str\fP) \-\- Name/ID of snapshot to display information about. If \fBtree=True\fP is also specified, display the snapshot subtree having this snapshot as the root snapshot .IP \(bu 2 \fBtree\fP (\fI\%bool\fP) \-\- List snapshots in tree format rather than tabular format .IP \(bu 2 \fBnames\fP (\fI\%bool\fP) \-\- List snapshots as ID, name pairs .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.list_snapshots macvm runas=macdev salt \(aq*\(aq parallels.list_snapshots macvm tree=True runas=macdev salt \(aq*\(aq parallels.list_snapshots macvm snap_name=original runas=macdev salt \(aq*\(aq parallels.list_snapshots macvm names=True runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.list_vms(name=None, info=False, all=False, args=None, runas=None, template=False) List information about the VMs .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- .sp Name/ID of VM to list .sp Changed in version 2016.11.0: No longer implies \fBinfo=True\fP .IP \(bu 2 \fBinfo\fP (\fI\%str\fP) \-\- List extra information .IP \(bu 2 \fBall\fP (\fI\%bool\fP) \-\- List all non\-template VMs .IP \(bu 2 \fBargs\fP (\fI\%tuple\fP) \-\- Additional arguments given to \fBprctl list\fP .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .IP \(bu 2 \fBtemplate\fP (\fI\%bool\fP) \-\- .sp List the available virtual machine templates. The real virtual machines will not be included in the output .sp New in version 2016.11.0. .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.list_vms runas=macdev salt \(aq*\(aq parallels.list_vms name=macvm info=True runas=macdev salt \(aq*\(aq parallels.list_vms info=True runas=macdev salt \(aq*\(aq parallels.list_vms \(aq \-o uuid,status\(aq all=True runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.prlctl(sub_cmd, args=None, runas=None) Execute a prlctl command .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsub_cmd\fP (\fI\%str\fP) \-\- prlctl subcommand to execute .IP \(bu 2 \fBargs\fP (\fI\%str\fP) \-\- The arguments supplied to \fBprlctl <sub_cmd>\fP .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.prlctl user list runas=macdev salt \(aq*\(aq parallels.prlctl exec \(aqmacvm uname\(aq runas=macdev salt \-\- \(aq*\(aq parallels.prlctl capture \(aqmacvm \-\-file macvm.display.png\(aq runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.prlsrvctl(sub_cmd, args=None, runas=None) Execute a prlsrvctl command .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsub_cmd\fP (\fI\%str\fP) \-\- prlsrvctl subcommand to execute .IP \(bu 2 \fBargs\fP (\fI\%str\fP) \-\- The arguments supplied to \fBprlsrvctl <sub_cmd>\fP .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlsrvctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.prlsrvctl info runas=macdev salt \(aq*\(aq parallels.prlsrvctl usb list runas=macdev salt \-\- \(aq*\(aq parallels.prlsrvctl set \(aq\-\-mem\-limit auto\(aq runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.reset(name, runas=None) Reset a VM by performing a hard shutdown and then a restart .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM to reset .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.reset macvm runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.restart(name, runas=None) Restart a VM by gracefully shutting it down and then restarting it .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM to restart .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.restart macvm runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.revert_snapshot(name, snap_name, runas=None) Revert a VM to a snapshot .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM to revert to a snapshot .IP \(bu 2 \fBsnap_name\fP (\fI\%str\fP) \-\- Name/ID of snapshot to revert to .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.revert_snapshot macvm base\-with\-updates runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.snapshot(name, snap_name=None, desc=None, runas=None) Create a snapshot .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM to take a snapshot of .IP \(bu 2 \fBsnap_name\fP (\fI\%str\fP) \-\- Name of snapshot .IP \(bu 2 \fBdesc\fP (\fI\%str\fP) \-\- Description of snapshot .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.create_snapshot macvm snap_name=macvm\-original runas=macdev salt \(aq*\(aq parallels.create_snapshot macvm snap_name=macvm\-updates desc=\(aqclean install with updates\(aq runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.snapshot_id_to_name(name, snap_id, strict=False, runas=None) Attempt to convert a snapshot ID to a snapshot name. If the snapshot has no name or if the ID is not found or invalid, an empty string will be returned .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM whose snapshots are inspected .IP \(bu 2 \fBsnap_id\fP (\fI\%str\fP) \-\- ID of the snapshot .IP \(bu 2 \fBstrict\fP (\fI\%bool\fP) \-\- Raise an exception if a name cannot be found for the given \fBsnap_id\fP .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example data .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ID: {a5b8999f\-5d95\-4aff\-82de\-e515b0101b66} Name: original Date: 2016\-03\-04 10:50:34 Current: yes State: poweroff Description: original state .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.snapshot_id_to_name macvm a5b8999f\-5d95\-4aff\-82de\-e515b0101b66 runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.snapshot_name_to_id(name, snap_name, strict=False, runas=None) Attempt to convert a snapshot name to a snapshot ID. If the name is not found an empty string is returned. If multiple snapshots share the same name, a list will be returned .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM whose snapshots are inspected .IP \(bu 2 \fBsnap_name\fP (\fI\%str\fP) \-\- Name of the snapshot .IP \(bu 2 \fBstrict\fP (\fI\%bool\fP) \-\- Raise an exception if multiple snapshot IDs are found .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.snapshot_id_to_name macvm original runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.start(name, runas=None) Start a VM .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM to start .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.start macvm runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.status(name, runas=None) Status of a VM .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM whose status will be returned .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.status macvm runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parallels.stop(name, kill=False, runas=None) Stop a VM .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name/ID of VM to stop .IP \(bu 2 \fBkill\fP (\fI\%bool\fP) \-\- Perform a hard shutdown .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The user that the prlctl command will be run as .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq parallels.stop macvm runas=macdev salt \(aq*\(aq parallels.stop macvm kill=True runas=macdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.parted_partition .sp Module for managing partitions on POSIX\-like systems. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 parted, partprobe, lsblk (usually parted and util\-linux packages) .UNINDENT .UNINDENT .sp Some functions may not be available, depending on your version of parted. .sp Check the manpage for \fBparted(8)\fP for more information, or the online docs at: .sp \fI\%http://www.gnu.org/software/parted/manual/html_chapter/parted_2.html\fP .sp In light of parted not directly supporting partition IDs, some of this module has been written to utilize sfdisk instead. For further information, please reference the man page for \fBsfdisk(8)\fP\&. .INDENT 0.0 .TP .B salt.modules.parted_partition.align_check(device, part_type, partition) Check if partition satisfies the alignment constraint of part_type. Type must be \(dqminimal\(dq or \(dqoptimal\(dq. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.align_check /dev/sda minimal 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.check(device, minor) Checks if the file system on partition <minor> has any errors. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.check 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.cp(device, from_minor, to_minor) Copies the file system on the partition <from\-minor> to partition <to\-minor>, deleting the original contents of the destination partition. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.cp /dev/sda 2 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.disk_set(device, flag, state) Changes a flag on selected device. .sp A flag can be either \(dqon\(dq or \(dqoff\(dq (make sure to use proper quoting, see \fI\%YAML Idiosyncrasies\fP). Some or all of these flags will be available, depending on what disk label you are using. .INDENT 7.0 .TP .B Valid flags are: .INDENT 7.0 .IP \(bu 2 cylinder_alignment .IP \(bu 2 pmbr_boot .IP \(bu 2 implicit_partition_table .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.disk_set /dev/sda pmbr_boot \(aq\(dqon\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.disk_toggle(device, flag) Toggle the state of <flag> on <device>. Valid flags are the same as the disk_set command. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.disk_toggle /dev/sda pmbr_boot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.exists(device=\(aq\(aq) Check to see if the partition exists .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.exists /dev/sdb1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.get_block_device() Retrieve a list of disk devices .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.get_block_device .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.get_id(device, minor) Prints the system ID for the partition. Some typical values are: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C b: FAT32 (vfat) 7: HPFS/NTFS 82: Linux Swap 83: Linux 8e: Linux LVM fd: Linux RAID Auto .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.get_id /dev/sda 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.list_(device, unit=None) Prints partition information of given <device> .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.list /dev/sda salt \(aq*\(aq partition.list /dev/sda unit=s salt \(aq*\(aq partition.list /dev/sda unit=kB .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.mkfs(device, fs_type) Makes a file system <fs_type> on partition <device>, destroying all data that resides on that partition. <fs_type> must be one of \(dqext2\(dq, \(dqfat32\(dq, \(dqfat16\(dq, \(dqlinux\-swap\(dq or \(dqreiserfs\(dq (if libreiserfs is installed) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.mkfs /dev/sda2 fat32 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.mklabel(device, label_type) Create a new disklabel (partition table) of label_type. .sp Type should be one of \(dqaix\(dq, \(dqamiga\(dq, \(dqbsd\(dq, \(dqdvh\(dq, \(dqgpt\(dq, \(dqloop\(dq, \(dqmac\(dq, \(dqmsdos\(dq, \(dqpc98\(dq, or \(dqsun\(dq. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.mklabel /dev/sda msdos .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.mkpart(device, part_type, fs_type=None, start=None, end=None) Make a part_type partition for filesystem fs_type, beginning at start and ending at end (by default in megabytes). part_type should be one of \(dqprimary\(dq, \(dqlogical\(dq, or \(dqextended\(dq. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.mkpart /dev/sda primary fs_type=fat32 start=0 end=639 salt \(aq*\(aq partition.mkpart /dev/sda primary start=0 end=639 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.mkpartfs(device, part_type, fs_type=None, start=None, end=None) The mkpartfs actually is an alias to mkpart and is kept for compatibility. To know the valid options and usage syntax read mkpart documentation. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.mkpartfs /dev/sda primary fs_type=fat32 start=0 end=639 salt \(aq*\(aq partition.mkpartfs /dev/sda primary start=0 end=639 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.name(device, partition, name) Set the name of partition to name. This option works only on Mac, PC98, and GPT disklabels. The name can be placed in quotes, if necessary. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.name /dev/sda 1 \(aqMy Documents\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.probe(*devices) Ask the kernel to update its local partition data. When no args are specified all block devices are tried. .sp Caution: Generally only works on devices with no mounted partitions and may take a long time to return if specified devices are in use. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.probe salt \(aq*\(aq partition.probe /dev/sda salt \(aq*\(aq partition.probe /dev/sda /dev/sdb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.rescue(device, start, end) Rescue a lost partition that was located somewhere between start and end. If a partition is found, parted will ask if you want to create an entry for it in the partition table. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.rescue /dev/sda 0 8056 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.resize(device, minor, start, end) Resizes the partition with number <minor>. .sp The partition will start <start> from the beginning of the disk, and end <end> from the beginning of the disk. resize never changes the minor number. Extended partitions can be resized, so long as the new extended partition completely contains all logical partitions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.resize /dev/sda 3 200 850 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.rm(device, minor) Removes the partition with number <minor>. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.rm /dev/sda 5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.set_(device, minor, flag, state) Changes a flag on the partition with number <minor>. .sp A flag can be either \(dqon\(dq or \(dqoff\(dq (make sure to use proper quoting, see \fI\%YAML Idiosyncrasies\fP). Some or all of these flags will be available, depending on what disk label you are using. .INDENT 7.0 .TP .B Valid flags are: .INDENT 7.0 .IP \(bu 2 boot .IP \(bu 2 root .IP \(bu 2 swap .IP \(bu 2 hidden .IP \(bu 2 raid .IP \(bu 2 lvm .IP \(bu 2 lba .IP \(bu 2 hp\-service .IP \(bu 2 palo .IP \(bu 2 prep .IP \(bu 2 msftres .IP \(bu 2 bios_grub .IP \(bu 2 atvrecv .IP \(bu 2 diag .IP \(bu 2 legacy_boot .IP \(bu 2 msftdata .IP \(bu 2 irst .IP \(bu 2 esp .IP \(bu 2 type .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.set /dev/sda 1 boot \(aq\(dqon\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.set_id(device, minor, system_id) Sets the system ID for the partition. Some typical values are: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C b: FAT32 (vfat) 7: HPFS/NTFS 82: Linux Swap 83: Linux 8e: Linux LVM fd: Linux RAID Auto .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.set_id /dev/sda 1 83 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.system_types() List the system types that are supported by the installed version of sfdisk .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.system_types .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.parted_partition.toggle(device, partition, flag) .INDENT 7.0 .TP .B Toggle the state of <flag> on <partition>. Valid flags are the same as the set command. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq partition.toggle /dev/sda 1 boot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pcs .SS Configure a Pacemaker/Corosync cluster with PCS .sp Configure Pacemaker/Cororsync clusters with the Pacemaker/Cororsync conifguration system (PCS) .INDENT 0.0 .TP .B depends pcs .UNINDENT .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.modules.pcs.auth(nodes, pcsuser=\(aqhacluster\(aq, pcspasswd=\(aqhacluster\(aq, extra_args=None) Authorize nodes to the cluster .INDENT 7.0 .TP .B nodes a list of nodes which should be authorized to the cluster .TP .B pcsuser user for communitcation with PCS (default: hacluster) .TP .B pcspasswd password for pcsuser (default: hacluster) .TP .B extra_args list of extra option for the \(aqpcs cluster auth\(aq command. The newer cluster host command has no extra args and so will ignore it. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.auth nodes=\(aq[ node1.example.org, node2.example.org ]\(aq pcsuser=hacluster pcspasswd=hoonetorg extra_args=[ \(aq\-\-force\(aq ] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.cib_create(cibfile, scope=\(aqconfiguration\(aq, extra_args=None) Create a CIB\-file from the current CIB of the cluster .INDENT 7.0 .TP .B cibfile name/path of the file containing the CIB .TP .B scope specific section of the CIB (default: configuration) .TP .B extra_args additional options for creating the CIB\-file .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.cib_create cibfile=\(aq/tmp/VIP_apache_1.cib\(aq scope=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.cib_push(cibfile, scope=\(aqconfiguration\(aq, extra_args=None) Push a CIB\-file as the new CIB to the cluster .INDENT 7.0 .TP .B cibfile name/path of the file containing the CIB .TP .B scope specific section of the CIB (default: configuration) .TP .B extra_args additional options for creating the CIB\-file .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.cib_push cibfile=\(aq/tmp/VIP_apache_1.cib\(aq scope=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.cluster_destroy(extra_args=None) Destroy corosync cluster using the pcs command .INDENT 7.0 .TP .B extra_args list of extra option for the \(aqpcs cluster destroy\(aq command (only really \-\-all) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.cluster_destroy extra_args=\-\-all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.cluster_node_add(node, extra_args=None) Add a node to the pacemaker cluster via pcs command .INDENT 7.0 .TP .B node node that should be added .TP .B extra_args list of extra option for the \(aqpcs cluster node add\(aq command .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.cluster_node_add node=node2.example.org .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.cluster_setup(nodes, pcsclustername=\(aqpcscluster\(aq, extra_args=None) Setup pacemaker cluster via pcs command .INDENT 7.0 .TP .B nodes a list of nodes which should be set up .TP .B pcsclustername Name of the Pacemaker cluster (default: pcscluster) .TP .B extra_args list of extra option for the \(aqpcs cluster setup\(aq command .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.cluster_setup nodes=\(aq[ node1.example.org, node2.example.org ]\(aq pcsclustername=pcscluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.config_show(cibfile=None) Show config of cluster .INDENT 7.0 .TP .B cibfile name/path of the file containing the CIB .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.config_show cibfile=\(aq/tmp/cib_for_galera\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.is_auth(nodes, pcsuser=\(aqhacluster\(aq, pcspasswd=\(aqhacluster\(aq) Check if nodes are already authorized .INDENT 7.0 .TP .B nodes a list of nodes to be checked for authorization to the cluster .TP .B pcsuser user for communitcation with PCS (default: hacluster) .TP .B pcspasswd password for pcsuser (default: hacluster) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.is_auth nodes=\(aq[node1.example.org, node2.example.org]\(aq pcsuser=hacluster pcspasswd=hoonetorg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.item_create(item, item_id, item_type, create=\(aqcreate\(aq, extra_args=None, cibfile=None) Create an item via pcs command (mainly for use with the pcs state module) .INDENT 7.0 .TP .B item config, property, resource, constraint etc. .TP .B item_id id of the item .TP .B item_type item type .TP .B create create command (create or set f.e., default: create) .TP .B extra_args additional options for the pcs command .TP .B cibfile use cibfile instead of the live CIB .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.item_show(item, item_id=None, item_type=None, show=\(aqshow\(aq, extra_args=None, cibfile=None) Show an item via pcs command (mainly for use with the pcs state module) .INDENT 7.0 .TP .B item config, property, resource, constraint etc. .TP .B item_id id of the item .TP .B item_type item type .TP .B show show command (probably None, default: show or status for newer implementation) .TP .B extra_args additional options for the pcs command .TP .B cibfile use cibfile instead of the live CIB .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.prop_set(prop, value, extra_args=None, cibfile=None) Set the value of a cluster property .INDENT 7.0 .TP .B prop name of the property .TP .B value value of the property prop .TP .B extra_args additional options for the pcs property command .TP .B cibfile use cibfile instead of the live CIB .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.prop_set prop=\(aqno\-quorum\-policy\(aq value=\(aqignore\(aq cibfile=\(aq/tmp/2_node_cluster.cib\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.prop_show(prop, extra_args=None, cibfile=None) Show the value of a cluster property .INDENT 7.0 .TP .B prop name of the property .TP .B extra_args additional options for the pcs property command .TP .B cibfile use cibfile instead of the live CIB .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.prop_show cibfile=\(aq/tmp/2_node_cluster.cib\(aq prop=\(aqno\-quorum\-policy\(aq cibfile=\(aq/tmp/2_node_cluster.cib\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.resource_create(resource_id, resource_type, resource_options=None, cibfile=None) Create a resource via pcs command .INDENT 7.0 .TP .B resource_id name for the resource .TP .B resource_type resource type (f.e. ocf:heartbeat:IPaddr2 or VirtualIP) .TP .B resource_options additional options for creating the resource .TP .B cibfile use cibfile instead of the live CIB for manipulation .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.resource_create resource_id=\(aqgalera\(aq resource_type=\(aqocf:heartbeat:galera\(aq resource_options=\(dq[\(aqwsrep_cluster_address=gcomm://node1.example.org,node2.example.org,node3.example.org\(aq, \(aq\-\-master\(aq]\(dq cibfile=\(aq/tmp/cib_for_galera.cib\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.resource_show(resource_id, extra_args=None, cibfile=None) Show a resource via pcs command .INDENT 7.0 .TP .B resource_id name of the resource .TP .B extra_args additional options for the pcs command .TP .B cibfile use cibfile instead of the live CIB .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.resource_show resource_id=\(aqgalera\(aq cibfile=\(aq/tmp/cib_for_galera.cib\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.stonith_create(stonith_id, stonith_device_type, stonith_device_options=None, cibfile=None) Create a stonith resource via pcs command .INDENT 7.0 .TP .B stonith_id name for the stonith resource .TP .B stonith_device_type name of the stonith agent fence_eps, fence_xvm f.e. .TP .B stonith_device_options additional options for creating the stonith resource .TP .B cibfile use cibfile instead of the live CIB for manipulation .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.stonith_create stonith_id=\(aqeps_fence\(aq stonith_device_type=\(aqfence_eps\(aq stonith_device_options=\(dq[\(aqpcmk_host_map=node1.example.org:01;node2.example.org:02\(aq, \(aqipaddr=myepsdevice.example.org\(aq, \(aqaction=reboot\(aq, \(aqpower_wait=5\(aq, \(aqverbose=1\(aq, \(aqdebug=/var/log/pcsd/eps_fence.log\(aq, \(aqlogin=hidden\(aq, \(aqpasswd=hoonetorg\(aq]\(dq cibfile=\(aq/tmp/cib_for_stonith.cib\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pcs.stonith_show(stonith_id, extra_args=None, cibfile=None) Show the value of a cluster stonith .INDENT 7.0 .TP .B stonith_id name for the stonith resource .TP .B extra_args additional options for the pcs stonith command .TP .B cibfile use cibfile instead of the live CIB .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pcs.stonith_show stonith_id=\(aqeps_fence\(aq cibfile=\(aq/tmp/2_node_cluster.cib\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pdbedit .sp Manage accounts in Samba\(aqs passdb using pdbedit .INDENT 0.0 .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B platform posix .UNINDENT .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.modules.pdbedit.create(login, password, password_hashed=False, machine_account=False) Create user account .INDENT 7.0 .TP .B login string login name .TP .B password string password .TP .B password_hashed boolean set if password is a nt hash instead of plain text .TP .B machine_account boolean set to create a machine trust account instead .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pdbedit.create zoe 9764951149F84E770889011E1DC4A927 nthash salt \(aq*\(aq pdbedit.create river 1sw4ll0w3d4bug .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pdbedit.delete(login) Delete user account .INDENT 7.0 .TP .B login string login name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pdbedit.delete wash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pdbedit.generate_nt_hash(password) Generate a NT HASH .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pdbedit.generate_nt_hash my_passwd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pdbedit.get_user(login, hashes=False) Get user account details .INDENT 7.0 .TP .B login string login name .TP .B hashes boolean include NTHASH and LMHASH in verbose output .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pdbedit.get kaylee .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pdbedit.list_users(verbose=True, hashes=False) List user accounts .INDENT 7.0 .TP .B verbose boolean return all information .TP .B hashes boolean include NT HASH and LM HASH in verbose output .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pdbedit.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pdbedit.modify(login, password=None, password_hashed=False, domain=None, profile=None, script=None, drive=None, homedir=None, fullname=None, account_desc=None, account_control=None, machine_sid=None, user_sid=None, reset_login_hours=False, reset_bad_password_count=False) Modify user account .INDENT 7.0 .TP .B login string login name .TP .B password string password .TP .B password_hashed boolean set if password is a nt hash instead of plain text .TP .B domain string users domain .TP .B profile string profile path .TP .B script string logon script .TP .B drive string home drive .TP .B homedir string home directory .TP .B fullname string full name .TP .B account_desc string account description .TP .B machine_sid string specify the machines new primary group SID or rid .TP .B user_sid string specify the users new primary group SID or rid .TP .B account_control string specify user account control properties .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Only the following can be set: \- N: No password required \- D: Account disabled \- H: Home directory required \- L: Automatic Locking \- X: Password does not expire .UNINDENT .UNINDENT .TP .B reset_login_hours boolean reset the users allowed logon hours .TP .B reset_bad_password_count boolean reset the stored bad login counter .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 if user is absent and password is provided, the user will be created .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pdbedit.modify inara fullname=\(aqInara Serra\(aq salt \(aq*\(aq pdbedit.modify simon password=r1v3r salt \(aq*\(aq pdbedit.modify jane drive=\(aqV:\(aq homedir=\(aq\e\eserenity\ejane\eprofile\(aq salt \(aq*\(aq pdbedit.modify mal account_control=NX .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pecl .sp Manage PHP pecl extensions. .INDENT 0.0 .TP .B salt.modules.pecl.install(pecls, defaults=False, force=False, preferred_state=\(aqstable\(aq) New in version 0.17.0. .sp Installs one or several pecl extensions. .INDENT 7.0 .TP .B pecls The pecl extensions to install. .TP .B defaults Use default answers for extensions such as pecl_http which ask questions before installation. Without this option, the pecl.installed state will hang indefinitely when trying to install these extensions. .TP .B force Whether to force the installed version or not .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pecl.install fuse .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pecl.list_(channel=None) List installed pecl extensions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pecl.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pecl.uninstall(pecls) Uninstall one or several pecl extensions. .INDENT 7.0 .TP .B pecls The pecl extensions to uninstall. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pecl.uninstall fuse .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pecl.update(pecls) Update one or several pecl extensions. .INDENT 7.0 .TP .B pecls The pecl extensions to update. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pecl.update fuse .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.peeringdb .SS PeeringDB Module .sp New in version 2019.2.0. .sp Execution module for the basic interaction with the \fI\%PeeringDB\fP API. .sp While for GET operations (the functions prefixed by \fBget_\fP) the credentials are optional, there are some specific details that are visible only to authenticated users. Moreover, the credentials are required when adding or updating information. That means, the module can equally work out of the box without any further configuration with the limitations imposed by the PeeringDB API. .sp For complete API documentation, please refer to \fI\%https://www.peeringdb.com/apidocs/\fP\&. .sp Configuration (in the opts or Pillar): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peeringdb: username: salt password: 5@1t .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.peeringdb.get_fac(**kwargs) Return the details of the facility identified using the search filters specified in the query. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no \fBid\fP or filter arguments are specified, it will return all the possible facilities registered in PeeringDB. .sp The available filters are documented at: \fI\%https://www.peeringdb.com/apidocs/#!/netfac/netfac_list\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq peeringdb.get_fac id=1774 salt \(aq*\(aq peeringdb.get_fac state=UT .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.peeringdb.get_ix(**kwargs) Return the details of an IX (Internet Exchange) using the search filters specified in the query. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no \fBid\fP or filter arguments are specified, it will return all the possible IXs registered in PeeringDB. .sp The available filters are documented at: \fI\%https://www.peeringdb.com/apidocs/#!/ix/ix_list\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq peeringdb.get_ix id=1 salt \(aq*\(aq peeringdb.get_ix city=\(aqMilwaukee\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.peeringdb.get_ixfac(**kwargs) Return the details of an IX (Internet Exchange) facility using the search filters specified in the query. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no \fBid\fP or filter arguments are specified, it will return all the possible IX facilities registered in PeeringDB. .sp The available filters are documented at: \fI\%https://www.peeringdb.com/apidocs/#!/ixfac/ixfac_list\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq peeringdb.get_ixfac id=1 salt \(aq*\(aq peeringdb.get_ixfac city=\(aqMilwaukee\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.peeringdb.get_ixlan(**kwargs) Return the details of an IX (Internet Exchange) together with the networks available in this location (and their details), using the search filters specified in the query. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no \fBid\fP or filter arguments are specified, it will return all the possible IX LAN facilities registered in PeeringDB. .sp The available filters are documented at: \fI\%https://www.peeringdb.com/apidocs/#!/ixlan/ixlan_list\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq peeringdb.get_ixlan id=780 salt \(aq*\(aq peeringdb.get_ixlan city=\(aqMilwaukee\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.peeringdb.get_ixpfx(**kwargs) Return the details of an IX (Internet Exchange) together with the PeeringDB IDs of the networks available in this location, using the search filters specified in the query. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no \fBid\fP or filter arguments are specified, it will return all the possible IX LAN facilities registered in PeeringDB. .sp The available filters are documented at: \fI\%https://www.peeringdb.com/apidocs/#!/ixpfx/ixpfx_list\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq peeringdb.get_ixpfx id=780 salt \(aq*\(aq peeringdb.get_ixpfx city=\(aqMilwaukee\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.peeringdb.get_net(**kwargs) Return the details of a network identified using the search filters specified in the query. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no \fBid\fP or filter arguments are specified, it will return all the possible networks registered in PeeringDB. .sp The available filters are documented at: \fI\%https://www.peeringdb.com/apidocs/#!/net/net_list\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq peeringdb.get_net id=4224 salt \(aq*\(aq peeringdb.get_net asn=13335 salt \(aq*\(aq peeringdb.get_net city=\(aqSalt Lake City\(aq salt \(aq*\(aq peeringdb.get_net name__startswith=GTT .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.peeringdb.get_netfac(**kwargs) Return the list of facilities used by a particular network, given the \fBid\fP or other filters specified in the query. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no \fBid\fP or filter arguments are specified, it will return all the possible network facilities registered in PeeringDB. .sp The available filters are documented at: \fI\%https://www.peeringdb.com/apidocs/#!/netfac/netfac_list\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq peeringdb.get_netfac id=780 salt \(aq*\(aq peeringdb.get_netfac city=\(aqMilwaukee\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.peeringdb.get_netixlan(**kwargs) Return the IP addresses used by a particular network at all the IXs where it is available. The network is selected either via the \fBid\fP argument or the other filters specified in the query. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no \fBid\fP or filter arguments are specified, it will return all the possible IP addresses, of all networks, at all IXs, registered in PeeringDB. .sp The available filters are documented at: \fI\%https://www.peeringdb.com/apidocs/#!/netixlan/netixlan_list\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq peeringdb.get_netixlan asn=13335 salt \(aq*\(aq peeringdb.get_netixlan ipaddr4=185.1.114.25 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.peeringdb.get_org(**kwargs) Return the details of an organisation together with the networks available in this location, using the search filters specified in the query. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no \fBid\fP or filter arguments are specified, it will return all the possible organisations registered in PeeringDB. .sp The available filters are documented at: \fI\%https://www.peeringdb.com/apidocs/#!/org/org_list\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq peeringdb.get_org id=2 salt \(aq*\(aq peeringdb.get_org city=Duesseldorf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.peeringdb.get_poc(**kwargs) Return the details of a person of contact together using the search filters specified in the query. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no \fBid\fP or filter arguments are specified, it will return all the possible contacts registered in PeeringDB. .sp The available filters are documented at: \fI\%https://www.peeringdb.com/apidocs/#!/poc/poc_list\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq peeringdb.get_poc id=6721 salt \(aq*\(aq peeringdb.get_poc email__contains=\(aq@cloudflare.com\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pf .sp Control the OpenBSD packet filter (PF). .INDENT 0.0 .TP .B codeauthor Jasper Lievisse Adriaanse <\fI\%j@jasper.la\fP> .UNINDENT .sp New in version 2019.2.0. .INDENT 0.0 .TP .B salt.modules.pf.disable() Disable the Packet Filter. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pf.disable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pf.enable() Enable the Packet Filter. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pf.enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pf.flush(modifier) Flush the specified packet filter parameters. .INDENT 7.0 .TP .B modifier: Should be one of the following: .INDENT 7.0 .IP \(bu 2 all .IP \(bu 2 info .IP \(bu 2 osfp .IP \(bu 2 rules .IP \(bu 2 sources .IP \(bu 2 states .IP \(bu 2 tables .UNINDENT .sp Please refer to the OpenBSD \fI\%pfctl(8)\fP documentation for a detailed explanation of each command. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pf.flush states .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pf.load(file=\(aq/etc/pf.conf\(aq, noop=False) Load a ruleset from the specific file, overwriting the currently loaded ruleset. .INDENT 7.0 .TP .B file: Full path to the file containing the ruleset. .TP .B noop: Don\(aqt actually load the rules, just parse them. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pf.load /etc/pf.conf.d/lockdown.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pf.loglevel(level) Set the debug level which limits the severity of log messages printed by \fBpf(4)\fP\&. .INDENT 7.0 .TP .B level: Log level. Should be one of the following: emerg, alert, crit, err, warning, notice, info or debug (OpenBSD); or none, urgent, misc, loud (FreeBSD). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pf.loglevel emerg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pf.show(modifier) Show filter parameters. .INDENT 7.0 .TP .B modifier: Modifier to apply for filtering. Only a useful subset of what pfctl supports can be used with Salt. .INDENT 7.0 .IP \(bu 2 rules .IP \(bu 2 states .IP \(bu 2 tables .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pf.show rules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pf.table(command, table, **kwargs) Apply a command on the specified table. .INDENT 7.0 .TP .B table: Name of the table. .TP .B command: Command to apply to the table. Supported commands are: .INDENT 7.0 .IP \(bu 2 add .IP \(bu 2 delete .IP \(bu 2 expire .IP \(bu 2 flush .IP \(bu 2 kill .IP \(bu 2 replace .IP \(bu 2 show .IP \(bu 2 test .IP \(bu 2 zero .UNINDENT .sp Please refer to the OpenBSD \fI\%pfctl(8)\fP documentation for a detailed explanation of each command. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pf.table expire table=spam_hosts number=300 salt \(aq*\(aq pf.table add table=local_hosts addresses=\(aq[\(dq127.0.0.1\(dq, \(dq::1\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.philips_hue .sp Philips HUE lamps module for proxy. .sp New in version 2015.8.3. .SS salt.modules.pillar .sp Extract the pillar data for this minion .INDENT 0.0 .TP .B salt.modules.pillar.data(*args, pillar=None, pillar_enc=None, pillarenv=None, saltenv=None) Calls the master for a fresh pillar, generates the pillar data on the fly (same as \fI\%items()\fP) .INDENT 7.0 .TP .B pillar If specified, allows for a dictionary of pillar data to be made available to pillar and ext_pillar rendering. these pillar variables will also override any variables of the same name in pillar or ext_pillar. .TP .B pillar_enc If specified, the data passed in the \fBpillar\fP argument will be passed through this renderer to decrypt it. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This will decrypt on the minion side, so the specified renderer must be set up on the minion for this to work. Alternatively, pillar data can be decrypted master\-side. For more information, see the \fI\%Pillar Encryption\fP documentation. Pillar data that is decrypted master\-side, is not decrypted until the end of pillar compilation though, so minion\-side decryption will be necessary if the encrypted pillar data must be made available in an decrypted state pillar/ext_pillar rendering. .UNINDENT .UNINDENT .TP .B pillarenv Pass a specific pillar environment from which to compile pillar data. If not specified, then the minion\(aqs \fI\%pillarenv\fP option is not used, and if that also is not specified then all configured pillar environments will be merged into a single pillar dictionary and returned. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.data .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pillar.ext(external, pillar=None) Changed in version 2016.3.6,2016.11.3,2017.7.0: The supported ext_pillar types are now tunable using the \fI\%on_demand_ext_pillar\fP config option. Earlier releases used a hard\-coded default. .sp Generate the pillar and apply an explicit external pillar .INDENT 7.0 .TP .B external A single ext_pillar to add to the ext_pillar configuration. This must be passed as a single section from the ext_pillar configuration (see CLI examples below). For more complicated \fBext_pillar\fP configurations, it can be helpful to use the Python shell to load YAML configuration into a dictionary, and figure out .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C >>> import salt.utils.yaml >>> ext_pillar = salt.utils.yaml.safe_load(\(dq\(dq\(dq \&... ext_pillar: \&... \- git: \&... \- issue38440 https://github.com/terminalmage/git_pillar: \&... \- env: base \&... \(dq\(dq\(dq) >>> ext_pillar {\(aqext_pillar\(aq: [{\(aqgit\(aq: [{\(aqmybranch https://github.com/myuser/myrepo\(aq: [{\(aqenv\(aq: \(aqbase\(aq}]}]}]} >>> ext_pillar[\(aqext_pillar\(aq][0] {\(aqgit\(aq: [{\(aqmybranch https://github.com/myuser/myrepo\(aq: [{\(aqenv\(aq: \(aqbase\(aq}]}]} .ft P .fi .UNINDENT .UNINDENT .sp In the above example, the value to pass would be \fB{\(aqgit\(aq: [{\(aqmybranch https://github.com/myuser/myrepo\(aq: [{\(aqenv\(aq: \(aqbase\(aq}]}]}\fP\&. Note that this would need to be quoted when passing on the CLI (as in the CLI examples below). .TP .B pillar None If specified, allows for a dictionary of pillar data to be made available to pillar and ext_pillar rendering. These pillar variables will also override any variables of the same name in pillar or ext_pillar. .sp New in version 2015.5.0. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.ext \(aq{libvirt: _}\(aq salt \(aq*\(aq pillar.ext \(dq{\(aqgit\(aq: [\(aqmaster https://github.com/myuser/myrepo\(aq]}\(dq salt \(aq*\(aq pillar.ext \(dq{\(aqgit\(aq: [{\(aqmybranch https://github.com/myuser/myrepo\(aq: [{\(aqenv\(aq: \(aqbase\(aq}]}]}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pillar.fetch(key, default=<Constant.NOT_SET>, merge=False, merge_nested_lists=None, delimiter=\(aq:\(aq, pillarenv=None, saltenv=None) New in version 0.14.0. .sp Attempt to retrieve the named value from \fI\%in\-memory pillar data\fP\&. If the pillar key is not present in the in\-memory pillar, then the value specified in the \fBdefault\fP option (described below) will be returned. .sp If the merge parameter is set to \fBTrue\fP, the default will be recursively merged into the returned pillar data. .sp The value can also represent a value in a nested dict using a \(dq:\(dq delimiter for the dict. This means that if a dict in pillar looks like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqpkg\(aq: {\(aqapache\(aq: \(aqhttpd\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp To retrieve the value associated with the \fBapache\fP key in the \fBpkg\fP dict this key can be passed as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pkg:apache .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B key The pillar key to get value from .TP .B default The value specified by this option will be returned if the desired pillar key does not exist. .sp If a default value is not specified, then it will be an empty string, unless \fI\%pillar_raise_on_missing\fP is set to \fBTrue\fP, in which case an error will be raised. .TP .B merge \fBFalse\fP If \fBTrue\fP, the retrieved values will be merged into the passed default. When the default and the retrieved value are both dictionaries, the dictionaries will be recursively merged. .sp New in version 2014.7.0. .sp Changed in version 2016.3.7,2016.11.4,2017.7.0: If the default and the retrieved value are not of the same type, then merging will be skipped and the retrieved value will be returned. Earlier releases raised an error in these cases. .TP .B merge_nested_lists If set to \fBFalse\fP, lists nested within the retrieved pillar dictionary will \fIoverwrite\fP lists in \fBdefault\fP\&. If set to \fBTrue\fP, nested lists will be \fImerged\fP into lists in \fBdefault\fP\&. If unspecified (the default), this option is inherited from the \fBpillar_merge_lists\fP minion config option. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is ignored when \fBmerge\fP is set to \fBFalse\fP\&. .UNINDENT .UNINDENT .sp New in version 2016.11.6. .TP .B delimiter Specify an alternate delimiter to use when traversing a nested dict. This is useful for when the desired key contains a colon. See CLI example below for usage. .sp New in version 2014.7.0. .TP .B pillarenv If specified, this function will query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. Note that this can produce different pillar data than executing this function without an environment, as its normal behavior is just to return a value from minion\(aqs pillar data in memory (which can be sourced from more than one pillar environment). .sp Using this argument will not affect the pillar data in memory. It will however be slightly slower and use more resources on the master due to the need for the master to generate and send the minion fresh pillar data. This tradeoff in performance however allows for the use case where pillar data is desired only from a single environment. .sp New in version 2017.7.0. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .sp New in version 2017.7.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.get pkg:apache salt \(aq*\(aq pillar.get abc::def|ghi delimiter=\(aq|\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pillar.file_exists(path, saltenv=None) New in version 2016.3.0. .sp This is a master\-only function. Calling from the minion is not supported. .sp Use the given path and search relative to the pillar environments to see if a file exists at that path. .sp If the \fBsaltenv\fP argument is given, restrict search to that environment only. .sp Will only work with \fBpillar_roots\fP, not external pillars. .sp Returns True if the file is found, and False otherwise. .INDENT 7.0 .TP .B path The path to the file in question. Will be treated as a relative path .TP .B saltenv Optional argument to restrict the search to a specific saltenv .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.file_exists foo/bar.sls .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pillar.filter_by(lookup_dict, pillar, merge=None, default=\(aqdefault\(aq, base=None) New in version 2017.7.0. .sp Look up the given pillar in a given dictionary and return the result .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBlookup_dict\fP \-\- .sp A dictionary, keyed by a pillar, containing a value or values relevant to systems matching that pillar. For example, a key could be a pillar for a role and the value could the name of a package on that particular OS. .sp The dictionary key can be a globbing pattern. The function will return the corresponding \fBlookup_dict\fP value where the pillar value matches the pattern. For example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C # this will render \(aqgot some salt\(aq if \(ga\(garole\(ga\(ga begins with \(aqsalt\(aq salt \(aq*\(aq pillar.filter_by \(aq{salt*: got some salt, default: salt is not here}\(aq role .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBpillar\fP \-\- .sp The name of a pillar to match with the system\(aqs pillar. For example, the value of the \(dqrole\(dq pillar could be used to pull values from the \fBlookup_dict\fP dictionary. .sp The pillar value can be a list. The function will return the \fBlookup_dict\fP value for a first found item in the list matching one of the \fBlookup_dict\fP keys. .IP \(bu 2 \fBmerge\fP \-\- A dictionary to merge with the results of the pillar selection from \fBlookup_dict\fP\&. This allows another dictionary to override the values in the \fBlookup_dict\fP\&. .IP \(bu 2 \fBdefault\fP \-\- default lookup_dict\(aqs key used if the pillar does not exist or if the pillar value has no match on lookup_dict. If unspecified the value is \(dqdefault\(dq. .IP \(bu 2 \fBbase\fP \-\- A lookup_dict key to use for a base dictionary. The pillar\-selected \fBlookup_dict\fP is merged over this and then finally the \fBmerge\fP dictionary is merged. This allows common values for each case to be collected in the base and overridden by the pillar selection dictionary and the merge dictionary. Default is unset. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.filter_by \(aq{web: Serve it up, db: I query, default: x_x}\(aq role .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pillar.get(key, default=<Constant.NOT_SET>, merge=False, merge_nested_lists=None, delimiter=\(aq:\(aq, pillarenv=None, saltenv=None) New in version 0.14.0. .sp Attempt to retrieve the named value from \fI\%in\-memory pillar data\fP\&. If the pillar key is not present in the in\-memory pillar, then the value specified in the \fBdefault\fP option (described below) will be returned. .sp If the merge parameter is set to \fBTrue\fP, the default will be recursively merged into the returned pillar data. .sp The value can also represent a value in a nested dict using a \(dq:\(dq delimiter for the dict. This means that if a dict in pillar looks like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqpkg\(aq: {\(aqapache\(aq: \(aqhttpd\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp To retrieve the value associated with the \fBapache\fP key in the \fBpkg\fP dict this key can be passed as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pkg:apache .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B key The pillar key to get value from .TP .B default The value specified by this option will be returned if the desired pillar key does not exist. .sp If a default value is not specified, then it will be an empty string, unless \fI\%pillar_raise_on_missing\fP is set to \fBTrue\fP, in which case an error will be raised. .TP .B merge \fBFalse\fP If \fBTrue\fP, the retrieved values will be merged into the passed default. When the default and the retrieved value are both dictionaries, the dictionaries will be recursively merged. .sp New in version 2014.7.0. .sp Changed in version 2016.3.7,2016.11.4,2017.7.0: If the default and the retrieved value are not of the same type, then merging will be skipped and the retrieved value will be returned. Earlier releases raised an error in these cases. .TP .B merge_nested_lists If set to \fBFalse\fP, lists nested within the retrieved pillar dictionary will \fIoverwrite\fP lists in \fBdefault\fP\&. If set to \fBTrue\fP, nested lists will be \fImerged\fP into lists in \fBdefault\fP\&. If unspecified (the default), this option is inherited from the \fBpillar_merge_lists\fP minion config option. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is ignored when \fBmerge\fP is set to \fBFalse\fP\&. .UNINDENT .UNINDENT .sp New in version 2016.11.6. .TP .B delimiter Specify an alternate delimiter to use when traversing a nested dict. This is useful for when the desired key contains a colon. See CLI example below for usage. .sp New in version 2014.7.0. .TP .B pillarenv If specified, this function will query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. Note that this can produce different pillar data than executing this function without an environment, as its normal behavior is just to return a value from minion\(aqs pillar data in memory (which can be sourced from more than one pillar environment). .sp Using this argument will not affect the pillar data in memory. It will however be slightly slower and use more resources on the master due to the need for the master to generate and send the minion fresh pillar data. This tradeoff in performance however allows for the use case where pillar data is desired only from a single environment. .sp New in version 2017.7.0. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .sp New in version 2017.7.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.get pkg:apache salt \(aq*\(aq pillar.get abc::def|ghi delimiter=\(aq|\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pillar.item(*args, default=None, delimiter=None, pillarenv=None, saltenv=None) New in version 0.16.2. .sp Return one or more pillar entries from the \fI\%in\-memory pillar data\fP\&. .INDENT 7.0 .TP .B delimiter Delimiter used to traverse nested dictionaries. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is different from \fI\%pillar.get\fP in that no default value can be specified. \fI\%pillar.get\fP should probably still be used in most cases to retrieve nested pillar values, as it is a bit more flexible. One reason to use this function instead of \fI\%pillar.get\fP however is when it is desirable to retrieve the values of more than one key, since \fI\%pillar.get\fP can only retrieve one key at a time. .UNINDENT .UNINDENT .sp New in version 2015.8.0. .TP .B pillarenv If specified, this function will query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. Note that this can produce different pillar data than executing this function without an environment, as its normal behavior is just to return a value from minion\(aqs pillar data in memory (which can be sourced from more than one pillar environment). .sp Using this argument will not affect the pillar data in memory. It will however be slightly slower and use more resources on the master due to the need for the master to generate and send the minion fresh pillar data. This tradeoff in performance however allows for the use case where pillar data is desired only from a single environment. .sp New in version 2017.7.6,2018.3.1. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .sp New in version 2017.7.6,2018.3.1. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.item foo salt \(aq*\(aq pillar.item foo:bar salt \(aq*\(aq pillar.item foo bar baz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pillar.items(*args, pillar=None, pillar_enc=None, pillarenv=None, saltenv=None) Calls the master for a fresh pillar and generates the pillar data on the fly .sp Contrast with \fI\%raw()\fP which returns the pillar data that is currently loaded into the minion. .INDENT 7.0 .TP .B pillar If specified, allows for a dictionary of pillar data to be made available to pillar and ext_pillar rendering. these pillar variables will also override any variables of the same name in pillar or ext_pillar. .sp New in version 2015.5.0. .TP .B pillar_enc If specified, the data passed in the \fBpillar\fP argument will be passed through this renderer to decrypt it. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This will decrypt on the minion side, so the specified renderer must be set up on the minion for this to work. Alternatively, pillar data can be decrypted master\-side. For more information, see the \fI\%Pillar Encryption\fP documentation. Pillar data that is decrypted master\-side, is not decrypted until the end of pillar compilation though, so minion\-side decryption will be necessary if the encrypted pillar data must be made available in an decrypted state pillar/ext_pillar rendering. .UNINDENT .UNINDENT .sp New in version 2017.7.0. .TP .B pillarenv Pass a specific pillar environment from which to compile pillar data. If not specified, then the minion\(aqs \fI\%pillarenv\fP option is not used, and if that also is not specified then all configured pillar environments will be merged into a single pillar dictionary and returned. .sp New in version 2016.11.2. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.items .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pillar.keys(key, delimiter=\(aq:\(aq) New in version 2015.8.0. .sp Attempt to retrieve a list of keys from the named value from the pillar. .sp The value can also represent a value in a nested dict using a \(dq:\(dq delimiter for the dict, similar to how pillar.get works. .INDENT 7.0 .TP .B delimiter Specify an alternate delimiter to use when traversing a nested dict .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.keys web:sites .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pillar.ls(*args, pillar=None, pillar_enc=None, pillarenv=None, saltenv=None) New in version 2015.8.0. .sp Calls the master for a fresh pillar, generates the pillar data on the fly (same as \fI\%items()\fP), but only shows the available main keys. .INDENT 7.0 .TP .B pillar If specified, allows for a dictionary of pillar data to be made available to pillar and ext_pillar rendering. these pillar variables will also override any variables of the same name in pillar or ext_pillar. .TP .B pillar_enc If specified, the data passed in the \fBpillar\fP argument will be passed through this renderer to decrypt it. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This will decrypt on the minion side, so the specified renderer must be set up on the minion for this to work. Alternatively, pillar data can be decrypted master\-side. For more information, see the \fI\%Pillar Encryption\fP documentation. Pillar data that is decrypted master\-side, is not decrypted until the end of pillar compilation though, so minion\-side decryption will be necessary if the encrypted pillar data must be made available in an decrypted state pillar/ext_pillar rendering. .UNINDENT .UNINDENT .TP .B pillarenv Pass a specific pillar environment from which to compile pillar data. If not specified, then the minion\(aqs \fI\%pillarenv\fP option is not used, and if that also is not specified then all configured pillar environments will be merged into a single pillar dictionary and returned. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.ls .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pillar.obfuscate(*args, pillar=None, pillar_enc=None, pillarenv=None, saltenv=None) New in version 2015.8.0. .sp Same as \fI\%items()\fP, but replace pillar values with a simple type indication. .sp This is useful to avoid displaying sensitive information on console or flooding the console with long output, such as certificates. For many debug or control purposes, the stakes lie more in dispatching than in actual values. .sp In case the value is itself a collection type, obfuscation occurs within the value. For mapping types, keys are not obfuscated. Here are some examples: .INDENT 7.0 .IP \(bu 2 \fB\(aqsecret password\(aq\fP becomes \fB\(aq<str>\(aq\fP .IP \(bu 2 \fB[\(aqsecret\(aq, 1]\fP becomes \fB[\(aq<str>\(aq, \(aq<int>\(aq]\fP .IP \(bu 2 \fB{\(aqlogin\(aq: \(aqsomelogin\(aq, \(aqpwd\(aq: \(aqsecret\(aq}\fP becomes \fB{\(aqlogin\(aq: \(aq<str>\(aq, \(aqpwd\(aq: \(aq<str>\(aq}\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.obfuscate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pillar.raw(key=None) Return the raw pillar data that is currently loaded into the minion. .sp Contrast with \fI\%items()\fP which calls the master to fetch the most up\-to\-date Pillar. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.raw .ft P .fi .UNINDENT .UNINDENT .sp With the optional key argument, you can select a subtree of the pillar raw data.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.raw key=\(aqroles\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pip .sp Install Python packages with pip to either the system or a virtualenv .SS Windows Support .sp New in version 2014.7.4. .sp Salt now uses a portable python. As a result the entire pip module is now functional on the salt installation itself. You can pip install dependencies for your custom modules. You can even upgrade salt itself using pip. For this to work properly, you must specify the Current Working Directory (\fBcwd\fP) and the Pip Binary (\fBbin_env\fP) salt should use. The variable \fBpip_bin\fP can be either a virtualenv path or the path to the pip binary itself. .sp For example, the following command will list all software installed using pip to your current salt environment: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <minion> pip.list cwd=\(aqC:\esalt\ebin\eScripts\(aq bin_env=\(aqC:\esalt\ebin\eScripts\epip.exe\(aq .ft P .fi .UNINDENT .UNINDENT .sp Specifying the \fBcwd\fP and \fBbin_env\fP options ensures you\(aqre modifying the salt environment. If these are omitted, it will default to the local installation of python. If python is not installed locally it will fail saying it couldn\(aqt find pip. .SS State File Support .sp This functionality works in states as well. If you need to pip install colorama with a state, for example, the following will work: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install_colorama: pip.installed: \- name: colorama \- cwd: \(aqC:\esalt\ebin\escripts\(aq \- bin_env: \(aqC:\esalt\ebin\escripts\epip.exe\(aq \- upgrade: True .ft P .fi .UNINDENT .UNINDENT .SS Upgrading Salt using Pip .sp You can now update salt using pip to any version from the 2014.7 branch forward. Previous version require recompiling some of the dependencies which is painful in windows. .sp To do this you just use pip with git to update to the version you want and then restart the service. Here is a sample state file that upgrades salt to the head of the 2015.5 branch: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install_salt: pip.installed: \- cwd: \(aqC:\esalt\ebin\escripts\(aq \- bin_env: \(aqC:\esalt\ebin\escripts\epip.exe\(aq \- editable: git+https://github.com/saltstack/salt@2015.5#egg=salt \- upgrade: True restart_service: service.running: \- name: salt\-minion \- enable: True \- watch: \- pip: install_salt .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you\(aqre having problems, you might try doubling the back slashes. For example, cwd: \(aqC:\esalt\ebin\escripts\(aq. Sometimes python thinks the single back slash is an escape character. .sp There is a known incompatibility between Python2 pip>=10.* and Salt <=2018.3.0. The issue is described here: \fI\%https://github.com/saltstack/salt/issues/46163\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.freeze(bin_env=None, user=None, cwd=None, use_vt=False, env_vars=None, **kwargs) Return a list of installed packages either globally or in the specified virtualenv .INDENT 7.0 .TP .B bin_env Path to pip (or to a virtualenv). This can be used to specify the path to the pip to use when more than one Python release is installed (e.g. \fB/usr/bin/pip\-2.7\fP or \fB/usr/bin/pip\-2.6\fP\&. If a directory path is specified, it is assumed to be a virtualenv. .TP .B user The user under which to run pip .TP .B cwd Directory from which to run pip .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the version of pip available is older than 8.0.3, the list will not include the packages \fBpip\fP, \fBwheel\fP, \fBsetuptools\fP, or \fBdistribute\fP even if they are installed. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.freeze bin_env=/home/code/path/to/virtualenv .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.install(pkgs=None, requirements=None, bin_env=None, use_wheel=False, no_use_wheel=False, log=None, proxy=None, timeout=None, editable=None, find_links=None, index_url=None, extra_index_url=None, no_index=False, mirrors=None, build=None, target=None, download=None, download_cache=None, source=None, upgrade=False, force_reinstall=False, ignore_installed=False, exists_action=None, no_deps=False, no_install=False, no_download=False, global_options=None, install_options=None, user=None, cwd=None, pre_releases=False, cert=None, allow_all_external=False, allow_external=None, allow_unverified=None, process_dependency_links=False, saltenv=\(aqbase\(aq, env_vars=None, use_vt=False, trusted_host=None, no_cache_dir=False, extra_args=None, cache_dir=None, no_binary=None, disable_version_check=False, **kwargs) Install packages with pip .sp Install packages individually or from a pip requirements file. Install packages globally or to a virtualenv. .INDENT 7.0 .TP .B pkgs Comma separated list of packages to install .TP .B requirements Path to requirements .TP .B bin_env Path to pip (or to a virtualenv). This can be used to specify the path to the pip to use when more than one Python release is installed (e.g. \fB/usr/bin/pip\-2.7\fP or \fB/usr/bin/pip\-2.6\fP\&. If a directory path is specified, it is assumed to be a virtualenv. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For Windows, if the pip module is being used to upgrade the pip package, bin_env should be the path to the virtualenv or to the python binary that should be used. The pip command is unable to upgrade itself in Windows. .UNINDENT .UNINDENT .TP .B use_wheel Prefer wheel archives (requires pip>=1.4) .TP .B no_use_wheel Force to not use wheel archives (requires pip>=1.4,<10.0.0) .TP .B no_binary Force to not use binary packages (requires pip >= 7.0.0) Accepts either :all: to disable all binary packages, :none: to empty the set, or one or more package names with commas between them .TP .B log Log file where a complete (maximum verbosity) record will be kept. If this file doesn\(aqt exist and the parent directory is writeable, it will be created. .TP .B proxy Specify a proxy in the form \fBuser:passwd@proxy.server:port\fP\&. Note that the \fBuser:password@\fP is optional and required only if you are behind an authenticated proxy. If you provide \fBuser@proxy.server:port\fP then you will be prompted for a password. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the Minion has a globaly configured proxy \- it will be used even if no proxy was set here. To explicitly disable proxy for pip you should pass \fBFalse\fP as a value. .UNINDENT .UNINDENT .TP .B timeout Set the socket timeout (default 15 seconds) .TP .B editable install something editable (e.g. \fBgit+https://github.com/worldcompany/djangoembed.git#egg=djangoembed\fP) .TP .B find_links URL to search for packages .TP .B index_url Base URL of Python Package Index .TP .B extra_index_url Extra URLs of package indexes to use in addition to \fBindex_url\fP .TP .B no_index Ignore package index .TP .B mirrors Specific mirror URL(s) to query (automatically adds \-\-use\-mirrors) .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This option has been deprecated and removed in pip version 7.0.0. Please use \fBindex_url\fP and/or \fBextra_index_url\fP instead. .UNINDENT .UNINDENT .TP .B build Unpack packages into \fBbuild\fP dir .TP .B target Install packages into \fBtarget\fP dir .TP .B download Download packages into \fBdownload\fP instead of installing them .TP .B download_cache | cache_dir Cache downloaded packages in \fBdownload_cache\fP or \fBcache_dir\fP dir .TP .B source Check out \fBeditable\fP packages into \fBsource\fP dir .TP .B upgrade Upgrade all packages to the newest available version .TP .B force_reinstall When upgrading, reinstall all packages even if they are already up\-to\-date. .TP .B ignore_installed Ignore the installed packages (reinstalling instead) .TP .B exists_action Default action when a path already exists: (s)witch, (i)gnore, (w)ipe, (b)ackup .TP .B no_deps Ignore package dependencies .TP .B no_install Download and unpack all packages, but don\(aqt actually install them .TP .B no_download Don\(aqt download any packages, just install the ones already downloaded (completes an install run with \fB\-\-no\-install\fP) .TP .B install_options Extra arguments to be supplied to the setup.py install command (e.g. like \fB\-\-install\-option=\(aq\-\-install\-scripts=/usr/local/bin\(aq\fP). Use multiple \-\-install\-option options to pass multiple options to setup.py install. If you are using an option with a directory path, be sure to use absolute path. .TP .B global_options Extra global options to be supplied to the setup.py call before the install command. .TP .B user The user under which to run pip .TP .B cwd Directory from which to run pip .TP .B pre_releases Include pre\-releases in the available versions .TP .B cert Provide a path to an alternate CA bundle .TP .B allow_all_external Allow the installation of all externally hosted files .TP .B allow_external Allow the installation of externally hosted files (comma separated list) .TP .B allow_unverified Allow the installation of insecure and unverifiable files (comma separated list) .TP .B process_dependency_links Enable the processing of dependency links .TP .B env_vars Set environment variables that some builds will depend on. For example, a Python C\-module may have a Makefile that needs INCLUDE_PATH set to pick up a header file while compiling. This must be in the form of a dictionary or a mapping. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.install django_app env_vars=\(dq{\(aqCUSTOM_PATH\(aq: \(aq/opt/django_app\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .TP .B trusted_host Mark this host as trusted, even though it does not have valid or any HTTPS. .TP .B use_vt Use VT terminal emulation (see output while installing) .TP .B no_cache_dir Disable the cache. .TP .B extra_args pip keyword and positional arguments not yet implemented in salt .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.install pandas extra_args=\(dq[{\(aq\-\-latest\-pip\-kwarg\(aq:\(aqparam\(aq}, \(aq\-\-latest\-pip\-arg\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 If unsupported options are passed here that are not supported in a minion\(aqs version of pip, a \fINo such option error\fP will be thrown. .UNINDENT .UNINDENT .UNINDENT .sp Will be translated into the following pip command: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pip install pandas \-\-latest\-pip\-kwarg param \-\-latest\-pip\-arg .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B disable_version_check Pip may periodically check PyPI to determine whether a new version of pip is available to download. Passing True for this option disables that check. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.install <package name>,<package2 name> salt \(aq*\(aq pip.install requirements=/path/to/requirements.txt salt \(aq*\(aq pip.install <package name> bin_env=/path/to/virtualenv salt \(aq*\(aq pip.install <package name> bin_env=/path/to/pip_bin .ft P .fi .UNINDENT .UNINDENT .sp Complicated CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.install markdown,django editable=git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed upgrade=True no_deps=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.is_installed(pkgname, bin_env=None, user=None, cwd=None) New in version 2018.3.0. .sp Changed in version 3006.0. .sp Filter list of installed modules and return True if \fBpkgname\fP exists in the list of packages installed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.is_installed salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.list_(prefix=None, bin_env=None, user=None, cwd=None, env_vars=None, **kwargs) Changed in version 3006.0. .sp Output list of installed apps from \fBpip list\fP in JSON format and check to see if \fBprefix\fP exists in the list of packages installed. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the version of pip available is older than 9.0.0, parsing the \fBfreeze\fP function output will be used to determine the name and version of installed modules. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.list salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.list_all_versions(pkg, bin_env=None, include_alpha=False, include_beta=False, include_rc=False, user=None, cwd=None, index_url=None, extra_index_url=None) New in version 2017.7.3. .sp List all available versions of a pip package .INDENT 7.0 .TP .B pkg The package to check .TP .B bin_env Path to pip (or to a virtualenv). This can be used to specify the path to the pip to use when more than one Python release is installed (e.g. \fB/usr/bin/pip\-2.7\fP or \fB/usr/bin/pip\-2.6\fP\&. If a directory path is specified, it is assumed to be a virtualenv. .TP .B include_alpha Include alpha versions in the list .TP .B include_beta Include beta versions in the list .TP .B include_rc Include release candidates versions in the list .TP .B user The user under which to run pip .TP .B cwd Directory from which to run pip .TP .B index_url Base URL of Python Package Index \&.. versionadded:: 2019.2.0 .TP .B extra_index_url Additional URL of Python Package Index \&.. versionadded:: 2019.2.0 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.list_all_versions <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.list_freeze_parse(prefix=None, bin_env=None, user=None, cwd=None, env_vars=None, **kwargs) New in version 3006.0. .sp Filter list of installed apps from \fBfreeze\fP and check to see if \fBprefix\fP exists in the list of packages installed. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the version of pip available is older than 8.0.3, the packages \fBwheel\fP, \fBsetuptools\fP, and \fBdistribute\fP will not be reported by this function even if they are installed. Unlike \fI\%pip.freeze\fP, this function always reports the version of pip which is installed. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.list_freeze_parse salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.list_upgrades(bin_env=None, user=None, cwd=None) Check whether or not an upgrade is available for all packages .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.list_upgrades .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.uninstall(pkgs=None, requirements=None, bin_env=None, log=None, proxy=None, timeout=None, user=None, cwd=None, saltenv=\(aqbase\(aq, use_vt=False) Uninstall packages individually or from a pip requirements file .INDENT 7.0 .TP .B pkgs comma separated list of packages to install .TP .B requirements Path to requirements file .TP .B bin_env Path to pip (or to a virtualenv). This can be used to specify the path to the pip to use when more than one Python release is installed (e.g. \fB/usr/bin/pip\-2.7\fP or \fB/usr/bin/pip\-2.6\fP\&. If a directory path is specified, it is assumed to be a virtualenv. .TP .B log Log file where a complete (maximum verbosity) record will be kept .TP .B proxy Specify a proxy in the format \fBuser:passwd@proxy.server:port\fP\&. Note that the \fBuser:password@\fP is optional and required only if you are behind an authenticated proxy. If you provide \fBuser@proxy.server:port\fP then you will be prompted for a password. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the Minion has a globaly configured proxy \- it will be used even if no proxy was set here. To explicitly disable proxy for pip you should pass \fBFalse\fP as a value. .UNINDENT .UNINDENT .TP .B timeout Set the socket timeout (default 15 seconds) .TP .B user The user under which to run pip .TP .B cwd Directory from which to run pip .TP .B use_vt Use VT terminal emulation (see output while installing) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.uninstall <package name>,<package2 name> salt \(aq*\(aq pip.uninstall requirements=/path/to/requirements.txt salt \(aq*\(aq pip.uninstall <package name> bin_env=/path/to/virtualenv salt \(aq*\(aq pip.uninstall <package name> bin_env=/path/to/pip_bin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.upgrade(bin_env=None, user=None, cwd=None, use_vt=False) New in version 2015.5.0. .sp Upgrades outdated pip packages. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On Windows you can\(aqt update salt from pip using salt, so salt will be skipped .UNINDENT .UNINDENT .sp Returns a dict containing the changes. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.upgrade .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.upgrade_available(pkg, bin_env=None, user=None, cwd=None) New in version 2015.5.0. .sp 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 pip.upgrade_available <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.version(bin_env=None, cwd=None, user=None) New in version 0.17.0. .sp Returns the version of pip. Use \fBbin_env\fP to specify the path to a virtualenv and get the version of pip in that virtualenv. .sp If unable to detect the pip version, returns \fBNone\fP\&. .sp Changed in version 3001.1: The \fBuser\fP parameter was added, to allow specifying the user who runs the version command. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pkg_resource .sp Resources needed by pkg providers .INDENT 0.0 .TP .B salt.modules.pkg_resource.add_pkg(pkgs, name, pkgver) Add a package to a dict of installed packages. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg_resource.add_pkg \(aq{}\(aq bind 9 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkg_resource.check_extra_requirements(pkgname, pkgver) Check if the installed package already has the given requirements. This function will return the result of \fBpkg.check_extra_requirements\fP if this function exists for the minion, otherwise it will return True. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg_resource.check_extra_requirements <pkgname> <extra_requirements> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkg_resource.format_pkg_list(packages, versions_as_list, attr) Formats packages according to parameters for list_pkgs. .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkg_resource.format_version(epoch, version, release) Formats a version string for list_pkgs. .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkg_resource.pack_sources(sources, normalize=True) Accepts list of dicts (or a string representing a list of dicts) and packs the key/value pairs into a single dict. .sp \fB\(aq[{\(dqfoo\(dq: \(dqsalt://foo.rpm\(dq}, {\(dqbar\(dq: \(dqsalt://bar.rpm\(dq}]\(aq\fP would become \fB{\(dqfoo\(dq: \(dqsalt://foo.rpm\(dq, \(dqbar\(dq: \(dqsalt://bar.rpm\(dq}\fP .INDENT 7.0 .TP .B normalize True Normalize the package name by removing the architecture, if the architecture of the package is different from the architecture of the operating system. The ability to disable this behavior is useful for poorly\-created packages which include the architecture as an actual part of the name, such as kernel modules which match a specific kernel version. .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_resource.pack_sources \(aq[{\(dqfoo\(dq: \(dqsalt://foo.rpm\(dq}, {\(dqbar\(dq: \(dqsalt://bar.rpm\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkg_resource.parse_targets(name=None, pkgs=None, sources=None, saltenv=\(aqbase\(aq, normalize=True, **kwargs) Parses the input to pkg.install and returns back the package(s) to be installed. Returns a list of packages, as well as a string noting whether the packages are to come from a repository or a binary package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg_resource.parse_targets .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkg_resource.sort_pkglist(pkgs) Accepts a dict obtained from pkg.list_pkgs() and sorts in place the list of versions for any packages that have multiple versions installed, so that two package lists can be compared to one another. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg_resource.sort_pkglist \(aq[\(dq3.45\(dq, \(dq2.13\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkg_resource.stringify(pkgs) Takes a dict of package name/version information and joins each list of installed versions into a string. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg_resource.stringify \(aqvim: 7.127\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkg_resource.version(*names, **kwargs) Common interface for obtaining the version of installed packages. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg_resource.version vim salt \(aq*\(aq pkg_resource.version foo bar baz salt \(aq*\(aq pkg_resource.version \(aqpython*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkg_resource.version_clean(verstr) Clean the version string removing extra data. This function will simply try to call \fBpkg.version_clean\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg_resource.version_clean <version_string> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkg_resource.version_compare(ver1, oper, ver2, ignore_epoch=False) New in version 3001. .sp Perform a version comparison, using (where available) platform\-specific version comparison tools to make the comparison. .INDENT 7.0 .TP .B ver1 The first version to be compared .TP .B oper One of \fI==\fP, \fI!=\fP, \fI>=\fP, \fI<=\fP, \fI>\fP, \fI<\fP .TP .B ver2 The second version to be compared .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To avoid shell interpretation, each of the above values should be quoted when this function is used on the CLI. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B ignore_epoch False If \fBTrue\fP, both package versions will have their epoch prefix stripped before comparison. .UNINDENT .sp This function is useful in Jinja templates, to perform specific actions when a package\(aqs version meets certain criteria. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set postfix_version = salt.pkg.version(\(aqpostfix\(aq) %} {%\- if postfix_version and salt.pkg_resource.version_compare(postfix_version, \(aq>=\(aq, \(aq3.3\(aq, ignore_epoch=True) %} {#\- do stuff #} {%\- endif %} .ft P .fi .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pkg_resource.version_compare \(aq3.5\(aq \(aq<=\(aq \(aq2.4\(aq salt myminion pkg_resource.version_compare \(aq3.5\(aq \(aq<=\(aq \(aq2.4\(aq ignore_epoch=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pkgin .sp Package support for pkgin based systems, inspired from freebsdpkg module .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgin.available_version(*names, **kwargs) This function is an alias of \fBlatest_version\fP\&. .INDENT 7.0 .INDENT 3.5 Changed in version 2016.3.0. .sp Return the latest version of the named package available for upgrade or installation. .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 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgin.file_dict(*packages, **kwargs) Changed in version 2016.3.0. .sp List the files that belong to a package. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.file_dict nginx salt \(aq*\(aq pkg.file_dict nginx varnish .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgin.file_list(package, **kwargs) List the files that belong to a package. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.file_list nginx .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgin.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs) Install the passed package .INDENT 7.0 .TP .B name The name of the package to be installed. .TP .B refresh Whether or not to refresh the package database before installing. .TP .B fromrepo Specify a package repository to install from. .UNINDENT .sp Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of packages to install from a software repository. Must be passed as a python list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq,\(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B sources A list of packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sources=\(aq[{\(dqfoo\(dq: \(dqsalt://foo.deb\(dq},{\(dqbar\(dq: \(dqsalt://bar.deb\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Return a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgin.latest_version(*names, **kwargs) Changed in version 2016.3.0. .sp Return the latest version of the named package available for upgrade or installation. .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 <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgin.list_pkgs(versions_as_list=False, **kwargs) Changed in version 2016.3.0. .sp List the packages currently installed as a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(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.pkgin.list_upgrades(refresh=True, **kwargs) List all available package upgrades. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B refresh Whether or not to refresh the package database before installing. .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.pkgin.normalize_name(pkgs, **kwargs) Normalize package names .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Nothing special to do to normalize, just return the original. (We do need it to be compatible with the pkg_resource provider.) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgin.purge(name=None, pkgs=None, **kwargs) Package purges are not supported, this function is identical to \fBremove()\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.purge <package name> salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3> salt \(aq*\(aq pkg.purge pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgin.refresh_db(force=False, **kwargs) Use pkg update to get latest pkg_summary .INDENT 7.0 .TP .B force Pass \-f so that the cache is always refreshed. .sp New in version 2018.3.0. .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.pkgin.remove(name=None, pkgs=None, **kwargs) .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 list containing the removed packages. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgin.search(pkg_name, **kwargs) Searches for an exact match using pkgin ^package$ .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search \(aqmysql\-server\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgin.upgrade(refresh=True, pkgs=None, **kwargs) Run pkg upgrade, if pkgin used. Otherwise do nothing .INDENT 7.0 .TP .B refresh Whether or not to refresh the package database before installing. .UNINDENT .sp Multiple Package Upgrade Options: .INDENT 7.0 .TP .B pkgs A list of packages to upgrade 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.upgrade pkgs=\(aq[\(dqfoo\(dq,\(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Returns a dictionary containing the changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgin.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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pkgng .sp Support for \fBpkgng\fP, the new package manager for FreeBSD .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module has been completely rewritten. Up to and including version 0.17.x, it was available as the \fBpkgng\fP module, (\fBpkgng.install\fP, \fBpkgng.delete\fP, etc.), but moving forward this module will no longer be available as \fBpkgng\fP, as it will behave like a normal Salt \fBpkg\fP provider. The documentation below should not be considered to apply to this module in versions <= 0.17.x. If your minion is running a 0.17.x release or older, then the documentation for this module can be viewed using the \fBsys.doc\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt bsdminion sys.doc pkgng .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp This module provides an interface to \fBpkg(8)\fP\&. It acts as the default package provider for FreeBSD 10 and newer. For FreeBSD hosts which have been upgraded to use pkgng, you will need to override the \fBpkg\fP provider by setting the \fI\%providers\fP parameter in your Minion config file, in order to use this module to manage packages, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C providers: pkg: pkgng .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.audit(jail=None, chroot=None, root=None) Audits installed packages against known vulnerabilities .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.audit .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Audit packages within the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.audit jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Audit packages within the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Audit packages within the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.audit chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.autoremove(jail=None, chroot=None, root=None, dryrun=False) Delete packages which were automatically installed as dependencies and are not required anymore. .INDENT 7.0 .TP .B dryrun Dry\-run mode. The list of changes to packages is always printed, but no changes are actually made. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.autoremove salt \(aq*\(aq pkg.autoremove jail=<jail name or id> salt \(aq*\(aq pkg.autoremove dryrun=True salt \(aq*\(aq pkg.autoremove jail=<jail name or id> dryrun=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.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 CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package name> jail=<jail name or id> salt \(aq*\(aq pkg.latest_version <package name> chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.backup(file_name, jail=None, chroot=None, root=None) Export installed packages into yaml+mtree file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.backup /tmp/pkg .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Backup packages from the specified jail. Note that this will run the command within the jail, and so the path to the backup file will be relative to the root of the jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.backup /tmp/pkg jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Backup packages from the specified chroot (ignored if \fBjail\fP is specified). Note that this will run the command within the chroot, and so the path to the backup file will be relative to the root of the chroot. .TP .B root Backup packages from the specified root (ignored if \fBjail\fP is specified). Note that this will run the command within the root, and so the path to the backup file will be relative to the root of the root. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.backup /tmp/pkg chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.check(jail=None, chroot=None, root=None, depends=False, recompute=False, checksum=False, checklibs=False) Sanity checks installed packages .INDENT 7.0 .TP .B jail Perform the sanity check in the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.check jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Perform the sanity check in the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Perform the sanity check in the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.check chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Of the below, at least one must be set to \fBTrue\fP\&. .INDENT 7.0 .TP .B depends Check for and install missing dependencies. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.check depends=True .ft P .fi .UNINDENT .UNINDENT .TP .B recompute Recompute sizes and checksums of installed packages. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.check recompute=True .ft P .fi .UNINDENT .UNINDENT .TP .B checksum Find invalid checksums for installed packages. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.check checksum=True .ft P .fi .UNINDENT .UNINDENT .TP .B checklibs Regenerates the library dependency metadata for a package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.check checklibs=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.clean(jail=None, chroot=None, root=None, clean_all=False, dryrun=False) Cleans the local cache of fetched remote packages .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.clean .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Cleans the package cache in the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.clean jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Cleans the package cache in the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Cleans the package cache in the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.clean chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .TP .B clean_all Clean all packages from the local cache (not just those that have been superseded by newer versions). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .sp salt \(aq*\(aq pkg.clean clean_all=True .TP .B dryrun Dry\-run mode. This list of changes to the local cache is always printed, but no changes are actually made. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.clean dryrun=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.delete(name=None, pkgs=None, jail=None, chroot=None, root=None, all_installed=False, force=False, glob=False, dryrun=False, recurse=False, regex=False, pcre=False, **kwargs) This function is an alias of \fBremove\fP\&. .INDENT 7.0 .INDENT 3.5 Remove a package from the database and system .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This function can accessed using \fBpkg.delete\fP in addition to \fBpkg.remove\fP, to more closely match the CLI usage of \fBpkg(8)\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B name The package to remove .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B jail Delete the package from the specified jail .TP .B chroot Delete the package from the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Delete the package from the specified root (ignored if \fBjail\fP is specified) .TP .B all_installed Deletes all installed packages from the system and empties the database. USE WITH CAUTION! .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove all all_installed=True force=True .ft P .fi .UNINDENT .UNINDENT .TP .B force Forces packages to be removed despite leaving unresolved dependencies. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> force=True .ft P .fi .UNINDENT .UNINDENT .TP .B glob Treat the package names as shell glob patterns. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> glob=True .ft P .fi .UNINDENT .UNINDENT .TP .B dryrun Dry run mode. The list of packages to delete is always printed, but no packages are actually deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> dryrun=True .ft P .fi .UNINDENT .UNINDENT .TP .B recurse Delete all packages that require the listed package as well. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> recurse=True .ft P .fi .UNINDENT .UNINDENT .TP .B regex Treat the package names as regular expressions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <regular expression> regex=True .ft P .fi .UNINDENT .UNINDENT .TP .B pcre Treat the package names as extended regular expressions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <extended regular expression> pcre=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.fetch(name, jail=None, chroot=None, root=None, fetch_all=False, quiet=False, fromrepo=None, glob=True, regex=False, pcre=False, local=False, depends=False) Fetches remote packages .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.fetch <package name> .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Fetch package in the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.fetch <package name> jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Fetch package in the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Fetch package in the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.fetch <package name> chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .TP .B fetch_all Fetch all packages. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.fetch <package name> fetch_all=True .ft P .fi .UNINDENT .UNINDENT .TP .B quiet Quiet mode. Show less output. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.fetch <package name> quiet=True .ft P .fi .UNINDENT .UNINDENT .TP .B fromrepo Fetches packages from the given repo if multiple repo support is enabled. See \fBpkg.conf(5)\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.fetch <package name> fromrepo=repo .ft P .fi .UNINDENT .UNINDENT .TP .B glob Treat pkg_name as a shell glob pattern. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.fetch <package name> glob=True .ft P .fi .UNINDENT .UNINDENT .TP .B regex Treat pkg_name as a regular expression. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.fetch <regular expression> regex=True .ft P .fi .UNINDENT .UNINDENT .TP .B pcre Treat pkg_name is an extended regular expression. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.fetch <extended regular expression> pcre=True .ft P .fi .UNINDENT .UNINDENT .TP .B local Skip updating the repository catalogs with pkg\-update(8). Use the local cache only. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.fetch <package name> local=True .ft P .fi .UNINDENT .UNINDENT .TP .B depends Fetch the package and its dependencies as well. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.fetch <package name> depends=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.hold(name=None, pkgs=None, **kwargs) Version\-lock packages .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function is provided primarily for compatibility with some parts of \fI\%states.pkg\fP\&. Consider using Consider using \fI\%pkg.lock\fP instead. instead. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the package to be held. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to hold. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .UNINDENT .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.hold <package name> salt \(aq*\(aq pkg.hold pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.info(*names, **kwargs) This function is an alias of \fBversion\fP\&. .INDENT 7.0 .INDENT 3.5 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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This function can accessed using \fBpkg.info\fP in addition to \fBpkg.version\fP, to more closely match the CLI usage of \fBpkg(8)\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B jail Get package version information for the specified jail .TP .B chroot Get package version information for the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Get package version information for the specified root (ignored if \fBjail\fP is specified) .TP .B with_origin False Return a nested dictionary containing both the origin name and version for each specified package. .sp New in version 2014.1.0. .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version <package name> salt \(aq*\(aq pkg.version <package name> jail=<jail name or id> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.install(name=None, fromrepo=None, pkgs=None, sources=None, jail=None, chroot=None, root=None, orphan=False, force=False, glob=False, local=False, dryrun=False, quiet=False, reinstall_requires=False, regex=False, pcre=False, batch=False, **kwargs) Install package(s) from a repository .INDENT 7.0 .TP .B name The name of the package to install .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B jail Install the package into the specified jail .TP .B chroot Install the package into the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Install the package into the specified root (ignored if \fBjail\fP is specified) .TP .B orphan Mark the installed package as orphan. Will be automatically removed if no other packages depend on them. For more information please refer to \fBpkg\-autoremove(8)\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> orphan=True .ft P .fi .UNINDENT .UNINDENT .TP .B force Force the reinstallation of the package if already installed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> force=True .ft P .fi .UNINDENT .UNINDENT .TP .B glob Treat the package names as shell glob patterns. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> glob=True .ft P .fi .UNINDENT .UNINDENT .TP .B local Do not update the repository catalogs with \fBpkg\-update(8)\fP\&. A value of \fBTrue\fP here is equivalent to using the \fB\-U\fP flag with \fBpkg install\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> local=True .ft P .fi .UNINDENT .UNINDENT .TP .B dryrun Dru\-run mode. The list of changes to packages is always printed, but no changes are actually made. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> dryrun=True .ft P .fi .UNINDENT .UNINDENT .TP .B quiet Force quiet output, except when dryrun is used, where pkg install will always show packages to be installed, upgraded or deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> quiet=True .ft P .fi .UNINDENT .UNINDENT .TP .B reinstall_requires When used with force, reinstalls any packages that require the given package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> reinstall_requires=True force=True .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.7.0: \fBrequire\fP kwarg renamed to \fBreinstall_requires\fP .TP .B fromrepo In multi\-repo mode, override the pkg.conf ordering and only attempt to download packages from the named repository. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> fromrepo=repo .ft P .fi .UNINDENT .UNINDENT .TP .B regex Treat the package names as a regular expression .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <regular expression> regex=True .ft P .fi .UNINDENT .UNINDENT .TP .B pcre Treat the package names as extended regular expressions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .TP .B batch Use BATCH=true for pkg install, skipping all questions. Be careful when using in production. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> batch=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.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 <package name> salt \(aq*\(aq pkg.latest_version <package name> jail=<jail name or id> salt \(aq*\(aq pkg.latest_version <package name> chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.list_locked(**kwargs) Query the package database those packages which are locked against reinstallation, modification or deletion. .sp Returns returns a list of package names with version strings .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_locked .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail List locked packages within the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_locked jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot List locked packages within the specified chroot (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_locked chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .TP .B root List locked packages within the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_locked root=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.list_pkgs(versions_as_list=False, jail=None, chroot=None, root=None, with_origin=False, **kwargs) List the packages currently installed as a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(aq} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail List the packages in the specified jail .TP .B chroot List the packages in the specified chroot (ignored if \fBjail\fP is specified) .TP .B root List the packages in the specified root (ignored if \fBjail\fP is specified) .TP .B with_origin False Return a nested dictionary containing both the origin name and version for each installed package. .sp New in version 2014.1.0. .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 jail=<jail name or id> salt \(aq*\(aq pkg.list_pkgs chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.list_upgrades(refresh=True, **kwargs) List those packages for which an upgrade is available .sp The \fBfromrepo\fP argument is also supported, as used in pkg states. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail List upgrades within the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot List upgrades within the specified chroot (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .TP .B root List upgrades within the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades root=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.lock(name, **kwargs) Lock the named package against reinstallation, modification or deletion. .sp Returns True if the named package was successfully locked. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.lock <package name> .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Lock packages within the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.lock <package name> jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Lock packages within the specified chroot (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.lock <package name> chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .TP .B root Lock packages within the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.lock <package name> root=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.locked(name, **kwargs) Query the package database to determine if the named package is locked against reinstallation, modification or deletion. .sp Returns True if the named package is locked, False otherwise. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.locked <package name> .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Test if a package is locked within the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.locked <package name> jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Test if a package is locked within the specified chroot (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.locked <package name> chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .TP .B root Test if a package is locked within the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.locked <package name> root=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.parse_config(file_name=\(aq/usr/local/etc/pkg.conf\(aq) Return dict of uncommented global variables. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.parse_config .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP not working properly right now .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.purge(name=None, pkgs=None, jail=None, chroot=None, root=None, all_installed=False, force=False, glob=False, dryrun=False, recurse=False, regex=False, pcre=False, **kwargs) This function is an alias of \fBremove\fP\&. .INDENT 7.0 .INDENT 3.5 Remove a package from the database and system .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This function can accessed using \fBpkg.delete\fP in addition to \fBpkg.remove\fP, to more closely match the CLI usage of \fBpkg(8)\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B name The package to remove .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B jail Delete the package from the specified jail .TP .B chroot Delete the package from the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Delete the package from the specified root (ignored if \fBjail\fP is specified) .TP .B all_installed Deletes all installed packages from the system and empties the database. USE WITH CAUTION! .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove all all_installed=True force=True .ft P .fi .UNINDENT .UNINDENT .TP .B force Forces packages to be removed despite leaving unresolved dependencies. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> force=True .ft P .fi .UNINDENT .UNINDENT .TP .B glob Treat the package names as shell glob patterns. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> glob=True .ft P .fi .UNINDENT .UNINDENT .TP .B dryrun Dry run mode. The list of packages to delete is always printed, but no packages are actually deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> dryrun=True .ft P .fi .UNINDENT .UNINDENT .TP .B recurse Delete all packages that require the listed package as well. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> recurse=True .ft P .fi .UNINDENT .UNINDENT .TP .B regex Treat the package names as regular expressions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <regular expression> regex=True .ft P .fi .UNINDENT .UNINDENT .TP .B pcre Treat the package names as extended regular expressions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <extended regular expression> pcre=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.refresh_db(jail=None, chroot=None, root=None, force=False, **kwargs) Refresh PACKAGESITE contents .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function can accessed using \fBpkg.update\fP in addition to \fBpkg.refresh_db\fP, to more closely match the CLI usage of \fBpkg(8)\fP\&. .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 .INDENT 7.0 .TP .B jail Refresh the pkg database within the specified jail .TP .B chroot Refresh the pkg database within the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Refresh the pkg database within the specified root (ignored if \fBjail\fP is specified) .TP .B force Force a full download of the repository catalog without regard to the respective ages of the local and remote copies of the catalog. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.remove(name=None, pkgs=None, jail=None, chroot=None, root=None, all_installed=False, force=False, glob=False, dryrun=False, recurse=False, regex=False, pcre=False, **kwargs) Remove a package from the database and system .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function can accessed using \fBpkg.delete\fP in addition to \fBpkg.remove\fP, to more closely match the CLI usage of \fBpkg(8)\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The package to remove .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B jail Delete the package from the specified jail .TP .B chroot Delete the package from the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Delete the package from the specified root (ignored if \fBjail\fP is specified) .TP .B all_installed Deletes all installed packages from the system and empties the database. USE WITH CAUTION! .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove all all_installed=True force=True .ft P .fi .UNINDENT .UNINDENT .TP .B force Forces packages to be removed despite leaving unresolved dependencies. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> force=True .ft P .fi .UNINDENT .UNINDENT .TP .B glob Treat the package names as shell glob patterns. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> glob=True .ft P .fi .UNINDENT .UNINDENT .TP .B dryrun Dry run mode. The list of packages to delete is always printed, but no packages are actually deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> dryrun=True .ft P .fi .UNINDENT .UNINDENT .TP .B recurse Delete all packages that require the listed package as well. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> recurse=True .ft P .fi .UNINDENT .UNINDENT .TP .B regex Treat the package names as regular expressions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <regular expression> regex=True .ft P .fi .UNINDENT .UNINDENT .TP .B pcre Treat the package names as extended regular expressions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <extended regular expression> pcre=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.restore(file_name, jail=None, chroot=None, root=None) Reads archive created by pkg backup \-d and recreates the database. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.restore /tmp/pkg .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Restore database to the specified jail. Note that this will run the command within the jail, and so the path to the file from which the pkg database will be restored is relative to the root of the jail. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.restore /tmp/pkg jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Restore database to the specified chroot (ignored if \fBjail\fP is specified). Note that this will run the command within the chroot, and so the path to the file from which the pkg database will be restored is relative to the root of the chroot. .TP .B root Restore database to the specified root (ignored if \fBjail\fP is specified). Note that this will run the command within the root, and so the path to the file from which the pkg database will be restored is relative to the root of the root. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.restore /tmp/pkg chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.search(name, jail=None, chroot=None, root=None, exact=False, glob=False, regex=False, pcre=False, comment=False, desc=False, full=False, depends=False, size=False, quiet=False, origin=False, prefix=False) Searches in remote package repositories .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Perform the search using the \fBpkg.conf(5)\fP from the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Perform the search using the \fBpkg.conf(5)\fP from the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Perform the search using the \fBpkg.conf(5)\fP from the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .TP .B exact Treat pattern as exact pattern. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern exact=True .ft P .fi .UNINDENT .UNINDENT .TP .B glob Treat pattern as a shell glob pattern. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern glob=True .ft P .fi .UNINDENT .UNINDENT .TP .B regex Treat pattern as a regular expression. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern regex=True .ft P .fi .UNINDENT .UNINDENT .TP .B pcre Treat pattern as an extended regular expression. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern pcre=True .ft P .fi .UNINDENT .UNINDENT .TP .B comment Search for pattern in the package comment one\-line description. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern comment=True .ft P .fi .UNINDENT .UNINDENT .TP .B desc Search for pattern in the package description. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern desc=True .ft P .fi .UNINDENT .UNINDENT .TP .B full Displays full information about the matching packages. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern full=True .ft P .fi .UNINDENT .UNINDENT .TP .B depends Displays the dependencies of pattern. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern depends=True .ft P .fi .UNINDENT .UNINDENT .TP .B size Displays the size of the package .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern size=True .ft P .fi .UNINDENT .UNINDENT .TP .B quiet Be quiet. Prints only the requested information without displaying many hints. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern quiet=True .ft P .fi .UNINDENT .UNINDENT .TP .B origin Displays pattern origin. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern origin=True .ft P .fi .UNINDENT .UNINDENT .TP .B prefix Displays the installation prefix for each package matching pattern. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search pattern prefix=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.stats(local=False, remote=False, jail=None, chroot=None, root=None, bytes=False) Return pkgng stats. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.stats .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B local Display stats only for the local package database. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.stats local=True .ft P .fi .UNINDENT .UNINDENT .TP .B remote Display stats only for the remote package database(s). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.stats remote=True .ft P .fi .UNINDENT .UNINDENT .TP .B bytes Display disk space usage in bytes only. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.stats bytes=True .ft P .fi .UNINDENT .UNINDENT .TP .B jail Retrieve stats from the specified jail. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.stats jail=<jail name or id> salt \(aq*\(aq pkg.stats jail=<jail name or id> local=True salt \(aq*\(aq pkg.stats jail=<jail name or id> remote=True .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Retrieve stats from the specified chroot (ignored if \fBjail\fP is specified). .TP .B root Retrieve stats from the specified root (ignored if \fBjail\fP is specified). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.stats chroot=/path/to/chroot salt \(aq*\(aq pkg.stats chroot=/path/to/chroot local=True salt \(aq*\(aq pkg.stats chroot=/path/to/chroot remote=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.unhold(name=None, pkgs=None, **kwargs) Remove version locks .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function is provided primarily for compatibility with some parts of \fI\%states.pkg\fP\&. Consider using \fI\%pkg.unlock\fP instead. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the package to be unheld .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to unhold. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .UNINDENT .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unhold <package name> salt \(aq*\(aq pkg.unhold pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.unlock(name, **kwargs) Unlock the named package against reinstallation, modification or deletion. .sp Returns True if the named package was successfully unlocked. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unlock <package name> .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Unlock packages within the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unlock <package name> jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Unlock packages within the specified chroot (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unlock <package name> chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .TP .B root Unlock packages within the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unlock <package name> root=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.update(jail=None, chroot=None, root=None, force=False, **kwargs) This function is an alias of \fBrefresh_db\fP\&. .INDENT 7.0 .INDENT 3.5 Refresh PACKAGESITE contents .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This function can accessed using \fBpkg.update\fP in addition to \fBpkg.refresh_db\fP, to more closely match the CLI usage of \fBpkg(8)\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B jail Refresh the pkg database within the specified jail .TP .B chroot Refresh the pkg database within the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Refresh the pkg database within the specified root (ignored if \fBjail\fP is specified) .TP .B force Force a full download of the repository catalog without regard to the respective ages of the local and remote copies of the catalog. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.update_package_site(new_url) Updates remote package repo URL, PACKAGESITE var to be exact. .sp Must use \fBhttp://\fP, \fBftp://\fP, or \fBhttps://\fP protocol .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.update_package_site http://127.0.0.1/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.updating(name, jail=None, chroot=None, root=None, filedate=None, filename=None) \(aq Displays UPDATING entries of software packages .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.updating foo .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Perform the action in the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.updating foo jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Perform the action in the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Perform the action in the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.updating foo chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .TP .B filedate Only entries newer than date are shown. Use a YYYYMMDD date format. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.updating foo filedate=20130101 .ft P .fi .UNINDENT .UNINDENT .TP .B filename Defines an alternative location of the UPDATING file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.updating foo filename=/tmp/UPDATING .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.upgrade(*names, **kwargs) Upgrade named or all packages (run a \fBpkg upgrade\fP). If <package name> is omitted, the operation is executed on all packages. .sp Returns a dictionary containing the changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade <package name> .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Audit packages within the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade <package name> jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Audit packages within the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Audit packages within the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade <package name> chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Any of the below options can also be used with \fBjail\fP or \fBchroot\fP\&. .INDENT 7.0 .TP .B force Force reinstalling/upgrading the whole set of packages. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade <package name> force=True .ft P .fi .UNINDENT .UNINDENT .TP .B local Do not update the repository catalogs with \fBpkg\-update(8)\fP\&. A value of \fBTrue\fP here is equivalent to using the \fB\-U\fP flag with \fBpkg upgrade\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade <package name> local=True .ft P .fi .UNINDENT .UNINDENT .TP .B dryrun Dry\-run mode: show what packages have updates available, but do not perform any upgrades. Repository catalogs will be updated as usual unless the local option is also given. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade <package name> dryrun=True .ft P .fi .UNINDENT .UNINDENT .TP .B fromrepo In multi\-repo mode, override the pkg.conf ordering and only attempt to upgrade packages from the named repository. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade <package name> fromrepo=repo .ft P .fi .UNINDENT .UNINDENT .TP .B fetchonly Do not perform installation of packages, merely fetch packages that should be upgraded and detect possible conflicts. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade <package name> fetchonly=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.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 \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function can accessed using \fBpkg.info\fP in addition to \fBpkg.version\fP, to more closely match the CLI usage of \fBpkg(8)\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Get package version information for the specified jail .TP .B chroot Get package version information for the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Get package version information for the specified root (ignored if \fBjail\fP is specified) .TP .B with_origin False Return a nested dictionary containing both the origin name and version for each specified package. .sp New in version 2014.1.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version <package name> salt \(aq*\(aq pkg.version <package name> jail=<jail name or id> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.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. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version_cmp \(aq2.1.11\(aq \(aq2.1.12\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.which(path, jail=None, chroot=None, root=None, origin=False, quiet=False) Displays which package installed a specific file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.which <file name> .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B jail Perform the check in the specified jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.which <file name> jail=<jail name or id> .ft P .fi .UNINDENT .UNINDENT .TP .B chroot Perform the check in the specified chroot (ignored if \fBjail\fP is specified) .TP .B root Perform the check in the specified root (ignored if \fBjail\fP is specified) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.which <file name> chroot=/path/to/chroot .ft P .fi .UNINDENT .UNINDENT .TP .B origin Shows the origin of the package instead of name\-version. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.which <file name> origin=True .ft P .fi .UNINDENT .UNINDENT .TP .B quiet Quiet output. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.which <file name> quiet=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pkgutil .sp Pkgutil support for Solaris .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgutil.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 CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgutil.latest_version CSWpython salt \(aq*\(aq pkgutil.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgutil.install(name=None, refresh=False, version=None, pkgs=None, **kwargs) Install packages using the pkgutil tool. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package_name> salt \(aq*\(aq pkg.install SMClgcc346 .ft P .fi .UNINDENT .UNINDENT .sp Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of packages to install from OpenCSW. 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[\(dqfoo\(dq, \(dqbar\(dq]\(aq salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, {\(dqbar\(dq: \(dq1.2.3\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgutil.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 pkgutil.latest_version CSWpython salt \(aq*\(aq pkgutil.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgutil.list_pkgs(versions_as_list=False, **kwargs) List the packages currently installed as a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(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.pkgutil.list_upgrades(refresh=True, **kwargs) List all available package upgrades on this system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgutil.list_upgrades .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgutil.purge(name=None, pkgs=None, **kwargs) Package purges are not supported, this function is identical to \fBremove()\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.purge <package name> salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3> salt \(aq*\(aq pkg.purge pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgutil.refresh_db() Updates the pkgutil repo database (pkgutil \-U) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgutil.refresh_db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgutil.remove(name=None, pkgs=None, **kwargs) Remove a package and all its dependencies which are not in use by other packages. .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 <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgutil.upgrade(refresh=True) Upgrade all of the packages to the latest available version. .sp Returns a dict containing the changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgutil.upgrade .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgutil.upgrade_available(name) Check if there is an upgrade available for a certain package .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgutil.upgrade_available CSWpython .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgutil.version(*names, **kwargs) Returns a version if the package is installed, else returns an empty string .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgutil.version CSWpython .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.portage_config .sp Configure \fBportage(5)\fP .INDENT 0.0 .TP .B salt.modules.portage_config.append_to_package_conf(conf, atom=\(aq\(aq, flags=None, string=\(aq\(aq, overwrite=False) Append a string or a list of flags for a given package or DEPEND atom to a given configuration file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq portage_config.append_to_package_conf use string=\(dqapp\-admin/salt ldap \-libvirt\(dq salt \(aq*\(aq portage_config.append_to_package_conf use atom=\(dq> = app\-admin/salt\-0.14.1\(dq flags=\(dq[\(aqldap\(aq, \(aq\-libvirt\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.append_use_flags(atom, uses=None, overwrite=False) Append a list of use flags for a given package or DEPEND atom .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq portage_config.append_use_flags \(dqapp\-admin/salt[ldap, \-libvirt]\(dq salt \(aq*\(aq portage_config.append_use_flags \(dq>=app\-admin/salt\-0.14.1\(dq \(dq[\(aqldap\(aq, \(aq\-libvirt\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.enforce_nice_config() Enforce a nice tree structure for /etc/portage/package.* configuration files. .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBsalt.modules.ebuild.ex_mod_init()\fP for information on automatically running this when pkg is used. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq portage_config.enforce_nice_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.filter_flags(use, use_expand_hidden, usemasked, useforced) New in version 2015.8.0. .sp Filter function to remove hidden or otherwise not normally visible USE flags from a list. .sp @type use: list @param use: the USE flag list to be filtered. @type use_expand_hidden: list @param use_expand_hidden: list of flags hidden. @type usemasked: list @param usemasked: list of masked USE flags. @type useforced: list @param useforced: the forced USE flags. @rtype: list @return the filtered USE flags. .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.get_all_cpv_use(cp) New in version 2015.8.0. .sp Uses portage to determine final USE flags and settings for an emerge. .sp @type cp: string @param cp: eg cat/pkg @rtype: lists @return use, use_expand_hidden, usemask, useforce .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.get_cleared_flags(cp) New in version 2015.8.0. .sp Uses portage for compare use flags which is used for installing package and use flags which now exist int /etc/portage/package.use/ .sp @type cp: string @param cp: eg cat/pkg @rtype: tuple @rparam: tuple with two lists \- list of used flags and list of flags which will be used .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.get_flags_from_package_conf(conf, atom) Get flags for a given package or DEPEND atom. Warning: This only works if the configuration files tree is in the correct format (the one enforced by enforce_nice_config) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq portage_config.get_flags_from_package_conf license salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.get_installed_use(cp, use=\(aqUSE\(aq) New in version 2015.8.0. .sp Gets the installed USE flags from the VARDB. .sp @type: cp: string @param cp: cat/pkg @type use: string @param use: 1 of [\(dqUSE\(dq, \(dqPKGUSE\(dq] @rtype list @returns [] or the list of IUSE flags .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.get_iuse(cp) New in version 2015.8.0. .sp Gets the current IUSE flags from the tree. .sp @type: cpv: string @param cpv: cat/pkg @rtype list @returns [] or the list of IUSE flags .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.get_missing_flags(conf, atom, flags) Find out which of the given flags are currently not set. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq portage_config.get_missing_flags use salt \(dq[\(aqldap\(aq, \(aq\-libvirt\(aq, \(aqopenssl\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.has_flag(conf, atom, flag) Verify if the given package or DEPEND atom has the given flag. Warning: This only works if the configuration files tree is in the correct format (the one enforced by enforce_nice_config) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq portage_config.has_flag license salt Apache\-2.0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.has_use(atom, use) Verify if the given package or DEPEND atom has the given use flag. Warning: This only works if the configuration files tree is in the correct format (the one enforced by enforce_nice_config) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq portage_config.has_use salt libvirt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.is_changed_uses(cp) New in version 2015.8.0. .sp Uses portage for determine if the use flags of installed package is compatible with use flags in portage configs. .sp @type cp: string @param cp: eg cat/pkg .UNINDENT .INDENT 0.0 .TP .B salt.modules.portage_config.is_present(conf, atom) Tell if a given package or DEPEND atom is present in the configuration files tree. Warning: This only works if the configuration files tree is in the correct format (the one enforced by enforce_nice_config) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq portage_config.is_present unmask salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.postfix .sp Support for Postfix .sp This module is currently little more than a config file viewer and editor. It is able to read the master.cf file (which is one style) and files in the style of main.cf (which is a different style, that is used in multiple postfix configuration files). .sp The design of this module is such that when files are edited, a minimum of changes are made to them. Each file should look as if it has been edited by hand; order, comments and whitespace are all preserved. .INDENT 0.0 .TP .B salt.modules.postfix.delete(queue_id) Delete message(s) from the mail queue .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postfix.delete 5C33CA0DEA salt \(aq*\(aq postfix.delete ALL .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postfix.hold(queue_id) Put message(s) on hold from the mail queue .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postfix.hold 5C33CA0DEA salt \(aq*\(aq postfix.hold ALL .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postfix.requeue(queue_id) Requeue message(s) in the mail queue .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postfix.requeue 5C33CA0DEA salt \(aq*\(aq postfix.requeue ALL .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postfix.set_main(key, value, path=\(aq/etc/postfix/main.cf\(aq) Set a single config value in the main.cf file. If the value does not already exist, it will be appended to the end. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <minion> postfix.set_main mailq_path /usr/bin/mailq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postfix.set_master(service, conn_type, private=\(aqy\(aq, unpriv=\(aqy\(aq, chroot=\(aqy\(aq, wakeup=\(aqn\(aq, maxproc=\(aq100\(aq, command=\(aq\(aq, write_conf=True, path=\(aq/etc/postfix/master.cf\(aq) Set a single config value in the master.cf file. If the value does not already exist, it will be appended to the end. .sp Because of shell parsing issues, \(aq\-\(aq cannot be set as a value, as is normal in the master.cf file; either \(aqy\(aq, \(aqn\(aq or a number should be used when calling this function from the command line. If the value used matches the default, it will internally be converted to a \(aq\-\(aq. Calling this function from the Python API is not affected by this limitation .sp The settings and their default values, in order, are: service (required), conn_type (required), private (y), unpriv (y), chroot (y), wakeup (n), maxproc (100), command (required). .sp By default, this function will write out the changes to the master.cf file, and then returns the full contents of the file. By setting the \fBwrite_conf\fP option to \fBFalse\fP, it will skip writing the file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <minion> postfix.set_master smtp inet n y n n 100 smtpd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postfix.show_main(path=\(aq/etc/postfix/main.cf\(aq) Return a dict of active config values. This does not include comments, spacing or order. Bear in mind that order is functionally important in the main.cf file, since keys can be referred to as variables. This means that the data returned from this function should not be used for direct modification of the main.cf file; other functions are available for that. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <minion> postfix.show_main salt <minion> postfix.show_main path=/path/to/main.cf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postfix.show_master(path=\(aq/etc/postfix/master.cf\(aq) Return a dict of active config values. This does not include comments, spacing or order. .sp The data returned from this function should not be used for direct modification of the main.cf file; other functions are available for that. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <minion> postfix.show_master salt <minion> postfix.show_master path=/path/to/master.cf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postfix.show_queue() Show contents of the mail queue .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postfix.show_queue .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postfix.unhold(queue_id) Set held message(s) in the mail queue to unheld .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postfix.unhold 5C33CA0DEA salt \(aq*\(aq postfix.unhold ALL .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.postgres .sp Module to provide Postgres compatibility to salt. .INDENT 0.0 .TP .B configuration In order to connect to Postgres, certain configuration is required in /etc/salt/minion on the relevant minions. Some sample configs might look like: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C postgres.host: \(aqlocalhost\(aq postgres.port: \(aq5432\(aq postgres.user: \(aqpostgres\(aq \-> db user postgres.pass: \(aq\(aq postgres.maintenance_db: \(aqpostgres\(aq .ft P .fi .UNINDENT .UNINDENT .sp The default for the maintenance_db is \(aqpostgres\(aq and in most cases it can be left at the default setting. This data can also be passed into pillar. Options passed into opts will overwrite options passed into pillar .UNINDENT .sp To prevent Postgres commands from running arbitrarily long, a timeout (in seconds) can be set .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C postgres.timeout: 60 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3006.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B note This module uses MD5 hashing which may not be compliant with certain security audits. .TP .B note When installing postgres from the official postgres repos, on certain linux distributions, either the psql or the initdb binary is \fInot\fP automatically placed on the path. Add a configuration to the location of the postgres bin\(aqs path to the relevant minion for this module: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C postgres.bins_dir: \(aq/usr/pgsql\-9.5/bin/\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.available_extensions(user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) List available postgresql extensions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.available_extensions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.create_extension(name, if_not_exists=None, schema=None, ext_version=None, from_version=None, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Install a postgresql extension .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.create_extension \(aqadminpack\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.create_metadata(name, ext_version=None, schema=None, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Get lifecycle information about an extension .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.create_metadata adminpack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.datadir_exists(name) New in version 2016.3.0. .sp Checks if postgres data directory has been initialized .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.datadir_exists \(aq/var/lib/pgsql/data\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the directory to check .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.datadir_init(name, auth=\(aqpassword\(aq, user=None, password=None, encoding=\(aqUTF8\(aq, locale=None, waldir=None, checksums=False, runas=None) New in version 2016.3.0. .sp Initializes a postgres data directory .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.datadir_init \(aq/var/lib/pgsql/data\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the directory to initialize .TP .B auth The default authentication method for local connections .TP .B password The password to set for the postgres user .TP .B user The database superuser name .TP .B encoding The default encoding for new databases .TP .B locale The default locale for new databases .TP .B waldir The transaction log (WAL) directory (default is to keep WAL inside the data directory) .sp New in version 2019.2.0. .TP .B checksums If True, the cluster will be created with data page checksums. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Data page checksums are supported since PostgreSQL 9.3. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B runas The system user the operation should be performed on behalf of .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.db_alter(name, user=None, host=None, port=None, maintenance_db=None, password=None, tablespace=None, owner=None, owner_recurse=False, runas=None) Change tablespace or/and owner of database. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.db_alter dbname owner=otheruser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.db_create(name, user=None, host=None, port=None, maintenance_db=None, password=None, tablespace=None, encoding=None, lc_collate=None, lc_ctype=None, owner=None, template=None, runas=None) Adds a databases to the Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.db_create \(aqdbname\(aq salt \(aq*\(aq postgres.db_create \(aqdbname\(aq template=template_postgis .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.db_exists(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Checks if a database exists on the Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.db_exists \(aqdbname\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.db_list(user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Return dictionary with information about databases of a Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.db_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.db_remove(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Removes a databases from the Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.db_remove \(aqdbname\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.drop_extension(name, if_exists=None, restrict=None, cascade=None, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Drop an installed postgresql extension .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.drop_extension \(aqadminpack\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.get_available_extension(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Get info about an available postgresql extension .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.get_available_extension plpgsql .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.get_installed_extension(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Get info about an installed postgresql extension .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.get_installed_extension plpgsql .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.group_create(groupname, user=None, host=None, port=None, maintenance_db=None, password=None, createdb=None, createroles=None, encrypted=None, login=None, inherit=None, superuser=None, replication=None, rolepassword=None, groups=None, runas=None) Creates a Postgres group. A group is postgres is similar to a user, but cannot login. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.group_create \(aqgroupname\(aq user=\(aquser\(aq \e host=\(aqhostname\(aq port=\(aqport\(aq password=\(aqpassword\(aq \e rolepassword=\(aqrolepassword\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.group_remove(groupname, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Removes a group from the Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.group_remove \(aqgroupname\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.group_update(groupname, user=None, host=None, port=None, maintenance_db=None, password=None, createdb=None, createroles=None, encrypted=None, inherit=None, login=None, superuser=None, replication=None, rolepassword=None, groups=None, runas=None) Updates a postgres group .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.group_update \(aqusername\(aq user=\(aquser\(aq \e host=\(aqhostname\(aq port=\(aqport\(aq password=\(aqpassword\(aq \e rolepassword=\(aqrolepassword\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.has_privileges(name, object_name, object_type, privileges=None, grant_option=None, prepend=\(aqpublic\(aq, maintenance_db=None, user=None, host=None, port=None, password=None, runas=None) New in version 2016.3.0. .sp Check if a role has the specified privileges on an object .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.has_privileges user_name table_name table \e SELECT,INSERT maintenance_db=db_name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the role whose privileges should be checked on object_type .TP .B object_name Name of the object on which the check is to be performed .TP .B object_type The object type, which can be one of the following: .INDENT 7.0 .IP \(bu 2 table .IP \(bu 2 sequence .IP \(bu 2 schema .IP \(bu 2 tablespace .IP \(bu 2 language .IP \(bu 2 database .IP \(bu 2 group .IP \(bu 2 function .UNINDENT .TP .B privileges Comma separated list of privileges to check, from the list below: .INDENT 7.0 .IP \(bu 2 INSERT .IP \(bu 2 CREATE .IP \(bu 2 TRUNCATE .IP \(bu 2 CONNECT .IP \(bu 2 TRIGGER .IP \(bu 2 SELECT .IP \(bu 2 USAGE .IP \(bu 2 TEMPORARY .IP \(bu 2 UPDATE .IP \(bu 2 EXECUTE .IP \(bu 2 REFERENCES .IP \(bu 2 DELETE .IP \(bu 2 ALL .UNINDENT .TP .B grant_option If grant_option is set to True, the grant option check is performed .TP .B prepend Table and Sequence object types live under a schema so this should be provided if the object is not under the default \fIpublic\fP schema .TP .B maintenance_db The database to connect to .TP .B user database username if different from config or default .TP .B password user password if any password for a specified user .TP .B host Database host if different from config or default .TP .B port Database port if different from config or default .TP .B runas System user all operations should be performed on behalf of .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.installed_extensions(user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) List installed postgresql extensions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.installed_extensions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.is_available_extension(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Test if a specific extension is available .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.is_available_extension .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.is_installed_extension(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Test if a specific extension is installed .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.is_installed_extension .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.language_create(name, maintenance_db, user=None, host=None, port=None, password=None, runas=None) New in version 2016.3.0. .sp Installs a language into a database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.language_create plpgsql dbname .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Language to install .TP .B maintenance_db The database to install the language in .TP .B user database username if different from config or default .TP .B password user password if any password for a specified user .TP .B host Database host if different from config or default .TP .B port Database port if different from config or default .TP .B runas System user all operations should be performed on behalf of .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.language_exists(name, maintenance_db, user=None, host=None, port=None, password=None, runas=None) New in version 2016.3.0. .sp Checks if language exists in a database. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.language_exists plpgsql dbname .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Language to check for .TP .B maintenance_db The database to check in .TP .B user database username if different from config or default .TP .B password user password if any password for a specified user .TP .B host Database host if different from config or default .TP .B port Database port if different from config or default .TP .B runas System user all operations should be performed on behalf of .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.language_list(maintenance_db, user=None, host=None, port=None, password=None, runas=None) New in version 2016.3.0. .sp Return a list of languages in a database. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.language_list dbname .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B maintenance_db The database to check .TP .B user database username if different from config or default .TP .B password user password if any password for a specified user .TP .B host Database host if different from config or default .TP .B port Database port if different from config or default .TP .B runas System user all operations should be performed on behalf of .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.language_remove(name, maintenance_db, user=None, host=None, port=None, password=None, runas=None) New in version 2016.3.0. .sp Removes a language from a database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.language_remove plpgsql dbname .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Language to remove .TP .B maintenance_db The database to install the language in .TP .B user database username if different from config or default .TP .B password user password if any password for a specified user .TP .B host Database host if different from config or default .TP .B port Database port if different from config or default .TP .B runas System user all operations should be performed on behalf of .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.owner_to(dbname, ownername, user=None, host=None, port=None, password=None, runas=None) Set the owner of all schemas, functions, tables, views and sequences to the given username. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.owner_to \(aqdbname\(aq \(aqusername\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.privileges_grant(name, object_name, object_type, privileges=None, grant_option=None, prepend=\(aqpublic\(aq, maintenance_db=None, user=None, host=None, port=None, password=None, runas=None) New in version 2016.3.0. .sp Grant privileges on a postgres object .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.privileges_grant user_name table_name table \e SELECT,UPDATE maintenance_db=db_name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the role to which privileges should be granted .TP .B object_name Name of the object on which the grant is to be performed .TP .B object_type The object type, which can be one of the following: .INDENT 7.0 .IP \(bu 2 table .IP \(bu 2 sequence .IP \(bu 2 schema .IP \(bu 2 tablespace .IP \(bu 2 language .IP \(bu 2 database .IP \(bu 2 group .IP \(bu 2 function .UNINDENT .TP .B privileges Comma separated list of privileges to grant, from the list below: .INDENT 7.0 .IP \(bu 2 INSERT .IP \(bu 2 CREATE .IP \(bu 2 TRUNCATE .IP \(bu 2 CONNECT .IP \(bu 2 TRIGGER .IP \(bu 2 SELECT .IP \(bu 2 USAGE .IP \(bu 2 TEMPORARY .IP \(bu 2 UPDATE .IP \(bu 2 EXECUTE .IP \(bu 2 REFERENCES .IP \(bu 2 DELETE .IP \(bu 2 ALL .UNINDENT .TP .B grant_option If grant_option is set to True, the recipient of the privilege can in turn grant it to others .TP .B prepend Table and Sequence object types live under a schema so this should be provided if the object is not under the default \fIpublic\fP schema .TP .B maintenance_db The database to connect to .TP .B user database username if different from config or default .TP .B password user password if any password for a specified user .TP .B host Database host if different from config or default .TP .B port Database port if different from config or default .TP .B runas System user all operations should be performed on behalf of .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.privileges_list(name, object_type, prepend=\(aqpublic\(aq, maintenance_db=None, user=None, host=None, port=None, password=None, runas=None) New in version 2016.3.0. .sp Return a list of privileges for the specified object. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.privileges_list table_name table maintenance_db=db_name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the object for which the permissions should be returned .TP .B object_type The object type, which can be one of the following: .INDENT 7.0 .IP \(bu 2 table .IP \(bu 2 sequence .IP \(bu 2 schema .IP \(bu 2 tablespace .IP \(bu 2 language .IP \(bu 2 database .IP \(bu 2 group .IP \(bu 2 function .UNINDENT .TP .B prepend Table and Sequence object types live under a schema so this should be provided if the object is not under the default \fIpublic\fP schema .TP .B maintenance_db The database to connect to .TP .B user database username if different from config or default .TP .B password user password if any password for a specified user .TP .B host Database host if different from config or default .TP .B port Database port if different from config or default .TP .B runas System user all operations should be performed on behalf of .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.privileges_revoke(name, object_name, object_type, privileges=None, prepend=\(aqpublic\(aq, maintenance_db=None, user=None, host=None, port=None, password=None, runas=None) New in version 2016.3.0. .sp Revoke privileges on a postgres object .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.privileges_revoke user_name table_name table \e SELECT,UPDATE maintenance_db=db_name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the role whose privileges should be revoked .TP .B object_name Name of the object on which the revoke is to be performed .TP .B object_type The object type, which can be one of the following: .INDENT 7.0 .IP \(bu 2 table .IP \(bu 2 sequence .IP \(bu 2 schema .IP \(bu 2 tablespace .IP \(bu 2 language .IP \(bu 2 database .IP \(bu 2 group .IP \(bu 2 function .UNINDENT .TP .B privileges Comma separated list of privileges to revoke, from the list below: .INDENT 7.0 .IP \(bu 2 INSERT .IP \(bu 2 CREATE .IP \(bu 2 TRUNCATE .IP \(bu 2 CONNECT .IP \(bu 2 TRIGGER .IP \(bu 2 SELECT .IP \(bu 2 USAGE .IP \(bu 2 TEMPORARY .IP \(bu 2 UPDATE .IP \(bu 2 EXECUTE .IP \(bu 2 REFERENCES .IP \(bu 2 DELETE .IP \(bu 2 ALL .UNINDENT .TP .B maintenance_db The database to connect to .TP .B user database username if different from config or default .TP .B password user password if any password for a specified user .TP .B host Database host if different from config or default .TP .B port Database port if different from config or default .TP .B runas System user all operations should be performed on behalf of .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.psql_query(query, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None, write=False) Run an SQL\-Query and return the results as a list. This command only supports SELECT statements. This limitation can be worked around with a query like this: .sp WITH updated AS (UPDATE pg_authid SET rolconnlimit = 2000 WHERE rolname = \(aqrolename\(aq RETURNING rolconnlimit) SELECT * FROM updated; .INDENT 7.0 .TP .B query The query string. .TP .B user Database username, if different from config or default. .TP .B host Database host, if different from config or default. .TP .B port Database port, if different from the config or default. .TP .B maintenance_db The database to run the query against. .TP .B password User password, if different from the config or default. .TP .B runas User to run the command as. .TP .B write Mark query as READ WRITE transaction. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.psql_query \(aqselect * from pg_stat_activity\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.role_get(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None, return_password=False) Return a dict with information about users of a Postgres server. .sp Set return_password to True to get password hash in the result. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.role_get postgres .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.schema_create(dbname, name, owner=None, user=None, db_user=None, db_password=None, db_host=None, db_port=None) Creates a Postgres schema. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.schema_create dbname name owner=\(aqowner\(aq \e user=\(aquser\(aq \e db_user=\(aquser\(aq db_password=\(aqpassword\(aq db_host=\(aqhostname\(aq db_port=\(aqport\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.schema_exists(dbname, name, user=None, db_user=None, db_password=None, db_host=None, db_port=None) Checks if a schema exists on the Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.schema_exists dbname schemaname .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B dbname Database name we query on .TP .B name Schema name we look for .TP .B user The system user the operation should be performed on behalf of .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.schema_get(dbname, name, user=None, db_user=None, db_password=None, db_host=None, db_port=None) Return a dict with information about schemas in a database. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.schema_get dbname name .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B dbname Database name we query on .TP .B name Schema name we look for .TP .B user The system user the operation should be performed on behalf of .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.schema_list(dbname, user=None, db_user=None, db_password=None, db_host=None, db_port=None) Return a dict with information about schemas in a Postgres database. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.schema_list dbname .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B dbname Database name we query on .TP .B user The system user the operation should be performed on behalf of .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.schema_remove(dbname, name, user=None, db_user=None, db_password=None, db_host=None, db_port=None) Removes a schema from the Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.schema_remove dbname schemaname .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B dbname Database name we work on .TP .B schemaname The schema\(aqs name we\(aqll remove .TP .B user System user all operations should be performed on behalf of .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.tablespace_alter(name, user=None, host=None, port=None, maintenance_db=None, password=None, new_name=None, new_owner=None, set_option=None, reset_option=None, runas=None) Change tablespace name, owner, or options. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.tablespace_alter tsname new_owner=otheruser salt \(aq*\(aq postgres.tablespace_alter index_space new_name=fast_raid salt \(aq*\(aq postgres.tablespace_alter test set_option=\(dq{\(aqseq_page_cost\(aq: \(aq1.1\(aq}\(dq salt \(aq*\(aq postgres.tablespace_alter tsname reset_option=seq_page_cost .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.tablespace_create(name, location, options=None, owner=None, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Adds a tablespace to the Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.tablespace_create tablespacename \(aq/path/datadir\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.tablespace_exists(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Checks if a tablespace exists on the Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.tablespace_exists \(aqdbname\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.tablespace_list(user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Return dictionary with information about tablespaces of a Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.tablespace_list .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.tablespace_remove(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Removes a tablespace from the Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.tablespace_remove tsname .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.user_create(username, user=None, host=None, port=None, maintenance_db=None, password=None, createdb=None, createroles=None, inherit=None, login=None, connlimit=None, encrypted=None, superuser=None, replication=None, rolepassword=None, valid_until=None, groups=None, runas=None) Creates a Postgres user. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.user_create \(aqusername\(aq user=\(aquser\(aq \e host=\(aqhostname\(aq port=\(aqport\(aq password=\(aqpassword\(aq \e rolepassword=\(aqrolepassword\(aq valid_until=\(aqvalid_until\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.user_exists(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Checks if a user exists on the Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.user_exists \(aqusername\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.user_list(user=None, host=None, port=None, maintenance_db=None, password=None, runas=None, return_password=False) Return a dict with information about users of a Postgres server. .sp Set return_password to True to get password hash in the result. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.user_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.user_remove(username, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Removes a user from the Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.user_remove \(aqusername\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.user_update(username, user=None, host=None, port=None, maintenance_db=None, password=None, createdb=None, createroles=None, encrypted=None, superuser=None, inherit=None, login=None, connlimit=None, replication=None, rolepassword=None, valid_until=None, groups=None, runas=None) Updates a Postgres user. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.user_update \(aqusername\(aq user=\(aquser\(aq \e host=\(aqhostname\(aq port=\(aqport\(aq password=\(aqpassword\(aq \e rolepassword=\(aqrolepassword\(aq valid_until=\(aqvalid_until\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.postgres.version(user=None, host=None, port=None, maintenance_db=None, password=None, runas=None) Return the version of a Postgres server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq postgres.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.poudriere .sp Support for poudriere .INDENT 0.0 .TP .B salt.modules.poudriere.bulk_build(jail, pkg_file, keep=False) Run bulk build on poudriere server. .sp Return number of pkg builds, failures, and errors, on error dump to CLI .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-N buildbox_group poudriere.bulk_build 90amd64 /root/pkg_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.poudriere.create_jail(name, arch, version=\(aq9.0\-RELEASE\(aq) Creates a new poudriere jail if one does not exist .sp \fINOTE\fP creating a new jail will take some time the master is not hanging .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq poudriere.create_jail 90amd64 amd64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.poudriere.create_ports_tree() Not working need to run portfetch non interactive .UNINDENT .INDENT 0.0 .TP .B salt.modules.poudriere.delete_jail(name) Deletes poudriere jail with \fIname\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq poudriere.delete_jail 90amd64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.poudriere.info_jail(name) Show information on \fIname\fP poudriere jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq poudriere.info_jail head\-amd64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.poudriere.is_jail(name) Return True if jail exists False if not .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq poudriere.is_jail <jail name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.poudriere.list_jails() Return a list of current jails managed by poudriere .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq poudriere.list_jails .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.poudriere.list_ports() Return a list of current port trees managed by poudriere .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq poudriere.list_ports .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.poudriere.make_pkgng_aware(jname) Make jail \fBjname\fP pkgng aware .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq poudriere.make_pkgng_aware <jail name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.poudriere.parse_config(config_file=None) Returns a dict of poudriere main configuration definitions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq poudriere.parse_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.poudriere.update_jail(name) Run freebsd\-update on \fIname\fP poudriere jail .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq poudriere.update_jail freebsd:10:x86:64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.poudriere.update_ports_tree(ports_tree) Updates the ports tree, either the default or the \fIports_tree\fP specified .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq poudriere.update_ports_tree staging .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.poudriere.version() Return poudriere version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq poudriere.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.powerpath .sp powerpath support. .sp Assumes RedHat .INDENT 0.0 .TP .B salt.modules.powerpath.add_license(key) Add a license .UNINDENT .INDENT 0.0 .TP .B salt.modules.powerpath.has_powerpath() .UNINDENT .INDENT 0.0 .TP .B salt.modules.powerpath.list_licenses() returns a list of applied powerpath license keys .UNINDENT .INDENT 0.0 .TP .B salt.modules.powerpath.remove_license(key) Remove a license .UNINDENT .SS salt.modules.proxy .sp This module allows you to manage proxy settings .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.get_http_proxy .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.proxy.get_ftp_proxy(network_service=\(aqEthernet\(aq) Returns the current ftp proxy settings .INDENT 7.0 .TP .B network_service The network service to apply the changes to, this only necessary on macOS .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq proxy.get_ftp_proxy Ethernet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.proxy.get_http_proxy(network_service=\(aqEthernet\(aq) Returns the current http proxy settings .INDENT 7.0 .TP .B network_service The network service to apply the changes to, this only necessary on macOS .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq proxy.get_http_proxy Ethernet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.proxy.get_https_proxy(network_service=\(aqEthernet\(aq) Returns the current https proxy settings .INDENT 7.0 .TP .B network_service The network service to apply the changes to, this only necessary on macOS .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq proxy.get_https_proxy Ethernet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.proxy.get_proxy_bypass(network_service=\(aqEthernet\(aq) Returns the current domains that can bypass the proxy .INDENT 7.0 .TP .B network_service The network service to get the bypass domains from, this is only necessary on macOS .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq proxy.get_proxy_bypass .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.proxy.get_proxy_win() Gets all of the proxy settings in one call, only available on Windows .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq proxy.get_proxy_win .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.proxy.set_ftp_proxy(server, port, user=None, password=None, network_service=\(aqEthernet\(aq, bypass_hosts=None) Sets the ftp proxy settings .INDENT 7.0 .TP .B server The proxy server to use .TP .B port The port used by the proxy server .TP .B user The username to use for the proxy server if required .TP .B password The password to use if required by the server .TP .B network_service The network service to apply the changes to, this only necessary on macOS .TP .B bypass_hosts The hosts that are allowed to by pass the proxy. Only used on Windows for other OS\(aqs use set_proxy_bypass to edit the bypass hosts. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq proxy.set_ftp_proxy example.com 1080 user=proxy_user password=proxy_pass network_service=Ethernet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.proxy.set_http_proxy(server, port, user=None, password=None, network_service=\(aqEthernet\(aq, bypass_hosts=None) Sets the http proxy settings. Note: On Windows this will override any other proxy settings you have, the preferred method of updating proxies on windows is using set_proxy. .INDENT 7.0 .TP .B server The proxy server to use .TP .B port The port used by the proxy server .TP .B user The username to use for the proxy server if required .TP .B password The password to use if required by the server .TP .B network_service The network service to apply the changes to, this only necessary on macOS .TP .B bypass_hosts The hosts that are allowed to by pass the proxy. Only used on Windows for other OS\(aqs use set_proxy_bypass to edit the bypass hosts. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq proxy.set_http_proxy example.com 1080 user=proxy_user password=proxy_pass network_service=Ethernet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.proxy.set_https_proxy(server, port, user=None, password=None, network_service=\(aqEthernet\(aq, bypass_hosts=None) Sets the https proxy settings. Note: On Windows this will override any other proxy settings you have, the preferred method of updating proxies on windows is using set_proxy. .INDENT 7.0 .TP .B server The proxy server to use .TP .B port The port used by the proxy server .TP .B user The username to use for the proxy server if required .TP .B password The password to use if required by the server .TP .B network_service The network service to apply the changes to, this only necessary on macOS .TP .B bypass_hosts The hosts that are allowed to by pass the proxy. Only used on Windows for other OS\(aqs use set_proxy_bypass to edit the bypass hosts. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq proxy.set_https_proxy example.com 1080 user=proxy_user password=proxy_pass network_service=Ethernet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.proxy.set_proxy_bypass(domains, network_service=\(aqEthernet\(aq) Sets the domains that can bypass the proxy .INDENT 7.0 .TP .B domains An array of domains allowed to bypass the proxy .TP .B network_service The network service to apply the changes to, this only necessary on macOS .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq proxy.set_proxy_bypass \(dq[\(aq127.0.0.1\(aq, \(aqlocalhost\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.proxy.set_proxy_win(server, port, types=None, bypass_hosts=None) Sets the http proxy settings, only works with Windows. .INDENT 7.0 .TP .B server The proxy server to use .TP .B password The password to use if required by the server .TP .B types The types of proxy connections should be setup with this server. Valid types are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBhttp\fP .IP \(bu 2 \fBhttps\fP .IP \(bu 2 \fBftp\fP .UNINDENT .UNINDENT .UNINDENT .TP .B bypass_hosts The hosts that are allowed to by pass the proxy. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq proxy.set_http_proxy example.com 1080 types=\(dq[\(aqhttp\(aq, \(aqhttps\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ps .sp A salt interface to psutil, a system and process library. See \fI\%http://code.google.com/p/psutil\fP\&. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 python\-utmp package (optional) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.boot_time(time_format=None) Return the boot time in number of seconds since the epoch began. .sp CLI Example: .INDENT 7.0 .TP .B time_format Optionally specify a \fI\%strftime\fP format string. Use \fBtime_format=\(aq%c\(aq\fP to get a nicely\-formatted locale specific date and time (i.e. \fBFri May 2 19:08:32 2014\fP). .sp New in version 2014.1.4. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.boot_time .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.cpu_percent(interval=0.1, per_cpu=False) Return the percent of time the CPU is busy. .INDENT 7.0 .TP .B interval the number of seconds to sample CPU usage over .TP .B per_cpu if True return an array of CPU percent busy for each CPU, otherwise aggregate all percents into one number .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.cpu_percent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.cpu_times(per_cpu=False) Return the percent of time the CPU spends in each state, e.g. user, system, idle, nice, iowait, irq, softirq. .INDENT 7.0 .TP .B per_cpu if True return an array of percents for each CPU, otherwise aggregate all percents into one number .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.cpu_times .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.disk_io_counters(device=None) Return disk I/O statistics. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.disk_io_counters salt \(aq*\(aq ps.disk_io_counters device=sda1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.disk_partition_usage(all=False) Return a list of disk partitions plus the mount point, filesystem and usage statistics. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.disk_partition_usage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.disk_partitions(all=False) Return a list of disk partitions and their device, mount point, and filesystem type. .INDENT 7.0 .TP .B all if set to False, only return local, physical partitions (hard disk, USB, CD/DVD partitions). If True, return all filesystems. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.disk_partitions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.disk_usage(path) Given a path, return a dict listing the total available space as well as the free space, and used space. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.disk_usage /home .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.get_pid_list() Return a list of process ids (PIDs) for all running processes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.get_pid_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.get_users() Return logged\-in users. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.get_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.kill_pid(pid, signal=15) Kill a process by PID. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq ps.kill_pid pid [signal=signal_number] .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B pid PID of process to kill. .TP .B signal Signal to send to the process. See manpage entry for kill for possible values. Default: 15 (SIGTERM). .UNINDENT .sp \fBExample:\fP .sp Send SIGKILL to process with PID 2000: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq ps.kill_pid 2000 signal=9 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.lsof(name) Retrieve the lsof information of the given process name. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.lsof apache2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.netstat(name) Retrieve the netstat information of the given process name. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.netstat apache2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.network_io_counters(interface=None) Return network I/O statistics. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.network_io_counters salt \(aq*\(aq ps.network_io_counters interface=eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.num_cpus() Return the number of CPUs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.num_cpus .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.pgrep(pattern, user=None, full=False, pattern_is_regex=False) Return the pids for processes matching a pattern. .sp If full is true, the full command line is searched for a match, otherwise only the name of the command is searched. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.pgrep pattern [user=username] [full=(true|false)] .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B pattern Pattern to search for in the process list. .TP .B user Limit matches to the given username. Default: All users. .TP .B full A boolean value indicating whether only the name of the command or the full command line should be matched against the pattern. .TP .B pattern_is_regex This flag enables ps.pgrep to mirror the regex search functionality found in the pgrep command line utility. .sp New in version 3001. .UNINDENT .sp \fBExamples:\fP .sp Find all httpd processes on all \(aqwww\(aq minions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqwww.*\(aq ps.pgrep httpd .ft P .fi .UNINDENT .UNINDENT .sp Find all bash processes owned by user \(aqtom\(aq: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.pgrep bash user=tom .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.pkill(pattern, user=None, signal=15, full=False) Kill processes matching a pattern. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.pkill pattern [user=username] [signal=signal_number] \e [full=(true|false)] .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B pattern Pattern to search for in the process list. .TP .B user Limit matches to the given username. Default: All users. .TP .B signal Signal to send to the process(es). See manpage entry for kill for possible values. Default: 15 (SIGTERM). .TP .B full A boolean value indicating whether only the name of the command or the full command line should be matched against the pattern. .UNINDENT .sp \fBExamples:\fP .sp Send SIGHUP to all httpd processes on all \(aqwww\(aq minions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqwww.*\(aq ps.pkill httpd signal=1 .ft P .fi .UNINDENT .UNINDENT .sp Send SIGKILL to all bash processes owned by user \(aqtom\(aq: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.pkill bash signal=9 user=tom .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.proc_info(pid, attrs=None) Return a dictionary of information for a process id (PID). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.proc_info 2322 salt \(aq*\(aq ps.proc_info 2322 attrs=\(aq[\(dqpid\(dq, \(dqname\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B pid PID of process to query. .TP .B attrs Optional list of desired process attributes. The list of possible attributes can be found here: \fI\%https://psutil.readthedocs.io/en/latest/#processes\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.psaux(name) Retrieve information corresponding to a \(dqps aux\(dq filtered with the given pattern. It could be just a name or a regular expression (using python search from \(dqre\(dq module). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.psaux www\-data.+apache2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.ss(name) Retrieve the ss information of the given process name. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.ss apache2 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.6. .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.status(status) New in version 3006.0. .sp Returns a list of processes according to their state. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.status STATUS .ft P .fi .UNINDENT .UNINDENT .sp where \fBSTATUS\fP is one of .INDENT 7.0 .IP \(bu 2 running .IP \(bu 2 sleeping .IP \(bu 2 disk_sleep .IP \(bu 2 stopped .IP \(bu 2 tracing_stop .IP \(bu 2 zombie .IP \(bu 2 dead .IP \(bu 2 wake_kill .IP \(bu 2 waking .IP \(bu 2 parked (Linux) .IP \(bu 2 idle (Linux, macOS, FreeBSD) .IP \(bu 2 locked (FreeBSD) .IP \(bu 2 waiting (FreeBSD) .IP \(bu 2 suspended (NetBSD) .UNINDENT .sp See \fI\%https://psutil.readthedocs.io/en/latest/index.html?highlight=status#process\-status\-constants\fP .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.swap_memory() New in version 2014.7.0. .sp Return a dict that describes swap memory statistics. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function is only available in psutil version 0.6.0 and above. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.swap_memory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.top(num_processes=5, interval=3) Return a list of top CPU consuming processes during the interval. num_processes = return the top N CPU consuming processes interval = the number of seconds to sample CPU usage over .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.top salt \(aq*\(aq ps.top 5 10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.total_physical_memory() Return the total number of bytes of physical memory. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.total_physical_memory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.virtual_memory() New in version 2014.7.0. .sp Return a dict that describes statistics about system memory usage. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function is only available in psutil version 0.6.0 and above. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ps.virtual_memory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.publish .sp Publish a command from a minion to a target .INDENT 0.0 .TP .B salt.modules.publish.full_data(tgt, fun, arg=None, tgt_type=\(aqglob\(aq, returner=\(aq\(aq, timeout=5) Return the full data about the publication, this is invoked in the same way as the publish function .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt system.example.com publish.full_data \(aq*\(aq cmd.run \(aqls \-la /tmp\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .IP "Attention" .sp If you need to pass a value to a function argument and that value contains an equal sign, you \fBmust\fP include the argument name. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq publish.full_data test.kwarg arg=\(aqcheese=spam\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.publish.publish(tgt, fun, arg=None, tgt_type=\(aqglob\(aq, returner=\(aq\(aq, timeout=5, via_master=None) Publish a command from the minion out to other minions. .sp Publications need to be enabled on the Salt master and the minion needs to have permission to publish the command. The Salt master will also prevent a recursive publication loop, this means that a minion cannot command another minion to command another minion as that would create an infinite command loop. .sp The \fBtgt_type\fP argument is used to pass a target other than a glob into the execution, the available options are: .INDENT 7.0 .IP \(bu 2 glob .IP \(bu 2 pcre .IP \(bu 2 grain .IP \(bu 2 grain_pcre .IP \(bu 2 pillar .IP \(bu 2 pillar_pcre .IP \(bu 2 ipcidr .IP \(bu 2 range .IP \(bu 2 compound .UNINDENT .sp Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Note that for pillar matches must be exact, both in the pillar matcher and the compound matcher. No globbing is supported. .sp The arguments sent to the minion publish function are separated with commas. This means that for a minion executing a command with multiple args it will look like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt system.example.com publish.publish \(aq*\(aq user.add \(aqfoo,1020,1020\(aq salt system.example.com publish.publish \(aqos:Fedora\(aq network.interfaces \(aq\(aq grain .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt system.example.com publish.publish \(aq*\(aq cmd.run \(aqls \-la /tmp\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .IP "Attention" .sp If you need to pass a value to a function argument and that value contains an equal sign, you \fBmust\fP include the argument name. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq publish.publish test.kwarg arg=\(aqcheese=spam\(aq .ft P .fi .UNINDENT .UNINDENT .sp Multiple keyword arguments should be passed as a list. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq publish.publish test.kwarg arg=\(dq[\(aqcheese=spam\(aq,\(aqspam=cheese\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp When running via salt\-call, the \fIvia_master\fP flag may be set to specific which master the publication should be sent to. Only one master may be specified. If unset, the publication will be sent only to the first master in minion configuration. .UNINDENT .INDENT 0.0 .TP .B salt.modules.publish.runner(fun, arg=None, timeout=5) Execute a runner on the master and return the data from the runner function .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt publish.runner manage.down .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.puppet .sp Execute puppet routines .INDENT 0.0 .TP .B salt.modules.puppet.disable(message=None) New in version 2014.7.0. .sp Disable the puppet agent .INDENT 7.0 .TP .B message New in version 2015.5.2. .sp Disable message to send to puppet .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq puppet.disable salt \(aq*\(aq puppet.disable \(aqDisabled, contact XYZ before enabling\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.puppet.enable() New in version 2014.7.0. .sp Enable the puppet agent .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq puppet.enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.puppet.fact(name, puppet=False) Run facter for a specific fact .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq puppet.fact kernel .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.puppet.facts(puppet=False) Run facter and return the results .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq puppet.facts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.puppet.noop(*args, **kwargs) Execute a puppet noop run and return a dict with the stderr, stdout, return code, etc. Usage is the same as for puppet.run. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq puppet.noop salt \(aq*\(aq puppet.noop tags=basefiles::edit,apache::server salt \(aq*\(aq puppet.noop debug salt \(aq*\(aq puppet.noop apply /a/b/manifest.pp modulepath=/a/b/modules tags=basefiles::edit,apache::server .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.puppet.plugin_sync() Runs a plugin sync between the puppet master and agent .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq puppet.plugin_sync .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.puppet.run(*args, **kwargs) Execute a puppet run and return a dict with the stderr, stdout, return code, etc. The first positional argument given is checked as a subcommand. Following positional arguments should be ordered with arguments required by the subcommand first, followed by non\-keyword arguments. Tags are specified by a tag keyword and comma separated list of values. \-\- \fI\%http://docs.puppetlabs.com/puppet/latest/reference/lang_tags.html\fP .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq puppet.run salt \(aq*\(aq puppet.run tags=basefiles::edit,apache::server salt \(aq*\(aq puppet.run agent onetime no\-daemonize no\-usecacheonfailure no\-splay ignorecache salt \(aq*\(aq puppet.run debug salt \(aq*\(aq puppet.run apply /a/b/manifest.pp modulepath=/a/b/modules tags=basefiles::edit,apache::server .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.puppet.status() New in version 2014.7.0. .sp Display puppet agent status .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq puppet.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.puppet.summary() New in version 2014.7.0. .sp Show a summary of the last puppet agent run .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq puppet.summary .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.purefa .sp Management of Pure Storage FlashArray .SS Installation Prerequisites .INDENT 0.0 .IP \(bu 2 You will need the \fBpurestorage\fP python package in your python installation path that is running salt. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C pip install purestorage .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Configure Pure Storage FlashArray authentication. Use one of the following three methods. .INDENT 2.0 .IP 1. 3 From the minion config .UNINDENT .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C pure_tags: fa: san_ip: management vip or hostname for the FlashArray api_token: A valid api token for the FlashArray being managed .ft P .fi .UNINDENT .UNINDENT .INDENT 2.0 .IP 2. 3 From environment (PUREFA_IP and PUREFA_API) .IP 3. 3 From the pillar (PUREFA_IP and PUREFA_API) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B maintainer Simon Dodsley (\fI\%simon@purestorage.com\fP) .TP .B maturity new .TP .B requires purestorage .TP .B platform all .UNINDENT .sp New in version 2018.3.0. .INDENT 0.0 .TP .B salt.modules.purefa.hg_create(name, host=None, volume=None) Create a hostgroup on a Pure Storage FlashArray. .sp Will return False if hostgroup already exists, or if named host or volume do not exist. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of hostgroup (truncated to 63 characters) .TP .B host string name of host to add to hostgroup .TP .B volume string name of volume to add to hostgroup .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.hg_create foo host=bar volume=vol .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.hg_delete(name) Delete a hostgroup on a Pure Storage FlashArray (removes all volumes and hosts). .sp Will return False is hostgroup is already in a deleted state. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of hostgroup .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.hg_delete foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.hg_remove(name, volume=None, host=None) Remove a host and/or volume from a hostgroup on a Pure Storage FlashArray. .sp Will return False is hostgroup does not exist, or named host or volume are not in the hostgroup. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of hostgroup .TP .B volume string name of volume to remove from hostgroup .TP .B host string name of host to remove from hostgroup .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.hg_remove foo volume=test host=bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.hg_update(name, host=None, volume=None) Adds entries to a hostgroup on a Pure Storage FlashArray. .sp Will return False is hostgroup doesn\(aqt exist, or host or volume do not exist. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of hostgroup .TP .B host string name of host to add to hostgroup .TP .B volume string name of volume to add to hostgroup .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.hg_update foo host=bar volume=vol .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.host_create(name, iqn=None, wwn=None, nqn=None) Add a host on a Pure Storage FlashArray. .sp Will return False if host already exists, or the iSCSI or Fibre Channel parameters are not in a valid format. See Pure Storage FlashArray documentation. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of host (truncated to 63 characters) .TP .B iqn string iSCSI IQN of host .TP .B nqn string NVMeF NQN of host \&.. versionadded:: 3006.0 .TP .B wwn string Fibre Channel WWN of host .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.host_create foo iqn=\(aq<Valid iSCSI IQN>\(aq wwn=\(aq<Valid WWN>\(aq nqn=\(aq<Valid NQN>\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.host_delete(name) Delete a host on a Pure Storage FlashArray (detaches all volumes). .sp Will return False if the host doesn\(aqt exist. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of host .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.host_delete foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.host_update(name, iqn=None, wwn=None, nqn=None) Update a hosts port definitions on a Pure Storage FlashArray. .sp Will return False if new port definitions are already in use by another host, or are not in a valid format. See Pure Storage FlashArray documentation. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of host .TP .B nqn string Additional NVMeF NQN of host \&.. versionadded:: 3006.0 .TP .B iqn string Additional iSCSI IQN of host .TP .B wwn string Additional Fibre Channel WWN of host .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.host_update foo iqn=\(aq<Valid iSCSI IQN>\(aq wwn=\(aq<Valid WWN>\(aq nqn=\(aq<Valid NQN>\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.pg_create(name, hostgroup=None, host=None, volume=None, enabled=True) Create a protection group on a Pure Storage FlashArray. .INDENT 7.0 .TP .B Will return False is the following cases: .INDENT 7.0 .IP \(bu 2 Protection Grop already exists .IP \(bu 2 Protection Group in a deleted state .IP \(bu 2 More than one type is specified \- protection groups are for only hostgroups, hosts or volumes .IP \(bu 2 Named type for protection group does not exist .UNINDENT .UNINDENT .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of protection group .TP .B hostgroup string name of hostgroup to add to protection group .TP .B host string name of host to add to protection group .TP .B volume string name of volume to add to protection group .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.pg_create foo [hostgroup=foo | host=bar | volume=vol] enabled=[true | false] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.pg_delete(name, eradicate=False) Delete a protecton group on a Pure Storage FlashArray. .sp Will return False if protection group is already in a deleted state. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of protection group .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.pg_delete foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.pg_eradicate(name) Eradicate a deleted protecton group on a Pure Storage FlashArray. .sp Will return False if protection group is not in a deleted state. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of protection group .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.pg_eradicate foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.pg_remove(name, hostgroup=None, host=None, volume=None) Remove a hostgroup, host or volume from a protection group on a Pure Storage FlashArray. .INDENT 7.0 .TP .B Will return False in the following cases: .INDENT 7.0 .IP \(bu 2 Protection group does not exist .IP \(bu 2 Specified type is not currently associated with the protection group .UNINDENT .UNINDENT .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of hostgroup .TP .B hostgroup string name of hostgroup to remove from protection group .TP .B host string name of host to remove from hostgroup .TP .B volume string name of volume to remove from hostgroup .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.pg_remove foo [hostgroup=bar | host=test | volume=bar] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.pg_update(name, hostgroup=None, host=None, volume=None) Update a protection group on a Pure Storage FlashArray. .INDENT 7.0 .TP .B Will return False in the following cases: .INDENT 7.0 .IP \(bu 2 Protection group does not exist .IP \(bu 2 Incorrect type selected for current protection group type .IP \(bu 2 Specified type does not exist .UNINDENT .UNINDENT .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of protection group .TP .B hostgroup string name of hostgroup to add to protection group .TP .B host string name of host to add to protection group .TP .B volume string name of volume to add to protection group .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.pg_update foo [hostgroup=foo | host=bar | volume=vol] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.snap_create(name, suffix=None) Create a volume snapshot on a Pure Storage FlashArray. .sp Will return False is volume selected to snap does not exist. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of volume to snapshot .TP .B suffix string if specificed forces snapshot name suffix. If not specified defaults to timestamp. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.snap_create foo salt \(aq*\(aq purefa.snap_create foo suffix=bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.snap_delete(name, suffix=None, eradicate=False) Delete a volume snapshot on a Pure Storage FlashArray. .sp Will return False if selected snapshot does not exist. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of volume .TP .B suffix string name of snapshot .TP .B eradicate boolean Eradicate snapshot after deletion if True. Default is False .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.snap_delete foo suffix=snap eradicate=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.snap_eradicate(name, suffix=None) Eradicate a deleted volume snapshot on a Pure Storage FlashArray. .sp Will return False if snapshot is not in a deleted state. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of volume .TP .B suffix string name of snapshot .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.snap_eradicate foo suffix=snap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.snap_volume_create(name, target, overwrite=False) Create R/W volume from snapshot on a Pure Storage FlashArray. .sp Will return False if target volume already exists and overwrite is not specified, or selected snapshot doesn\(aqt exist. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of volume snapshot .TP .B target string name of clone volume .TP .B overwrite boolean overwrite clone if already exists (default: False) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.snap_volume_create foo.bar clone overwrite=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.volume_attach(name, host) Attach a volume to a host on a Pure Storage FlashArray. .sp Host and volume must exist or else will return False. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of volume .TP .B host string name of host .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.volume_attach foo bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.volume_clone(name, target, overwrite=False) Clone an existing volume on a Pure Storage FlashArray. .sp Will return False if source volume doesn\(aqt exist, or target volume already exists and overwrite not specified. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of volume .TP .B target string name of clone volume .TP .B overwrite boolean overwrite clone if already exists (default: False) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.volume_clone foo bar overwrite=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.volume_create(name, size=None) Create a volume on a Pure Storage FlashArray. .sp Will return False if volume already exists. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of volume (truncated to 63 characters) .TP .B size string if specificed capacity of volume. If not specified default to 1G. Refer to Pure Storage documentation for formatting rules. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.volume_create foo salt \(aq*\(aq purefa.volume_create foo size=10T .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.volume_delete(name, eradicate=False) Delete a volume on a Pure Storage FlashArray. .sp Will return False if volume doesn\(aqt exist is already in a deleted state. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of volume .TP .B eradicate boolean Eradicate volume after deletion if True. Default is False .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.volume_delete foo eradicate=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.volume_detach(name, host) Detach a volume from a host on a Pure Storage FlashArray. .sp Will return False if either host or volume do not exist, or if selected volume isn\(aqt already connected to the host. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of volume .TP .B host string name of host .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.volume_detach foo bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.volume_eradicate(name) Eradicate a deleted volume on a Pure Storage FlashArray. .sp Will return False is volume is not in a deleted state. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of volume .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.volume_eradicate foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefa.volume_extend(name, size) Extend an existing volume on a Pure Storage FlashArray. .sp Will return False if new size is less than or equal to existing size. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name string name of volume .TP .B size string New capacity of volume. Refer to Pure Storage documentation for formatting rules. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefa.volume_extend foo 10T .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.purefb .sp Management of Pure Storage FlashBlade .SS Installation Prerequisites .INDENT 0.0 .IP \(bu 2 You will need the \fBpurity_fb\fP python package in your python installation path that is running salt. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C pip install purity_fb .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Configure Pure Storage FlashBlade authentication. Use one of the following three methods. .INDENT 2.0 .IP 1. 3 From the minion config .UNINDENT .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C pure_tags: fb: san_ip: management vip or hostname for the FlashBlade api_token: A valid api token for the FlashBlade being managed .ft P .fi .UNINDENT .UNINDENT .INDENT 2.0 .IP 2. 3 From environment (PUREFB_IP and PUREFB_API) .IP 3. 3 From the pillar (PUREFB_IP and PUREFB_API) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B maintainer Simon Dodsley (\fI\%simon@purestorage.com\fP) .TP .B maturity new .TP .B requires purity_fb .TP .B platform all .UNINDENT .sp New in version 2019.2.0. .INDENT 0.0 .TP .B salt.modules.purefb.fs_create(name, size=None, proto=\(aqNFS\(aq, nfs_rules=\(aq*(rw,no_root_squash)\(aq, snapshot=False) Create a filesystem on a Pure Storage FlashBlade. .sp Will return False if filesystem already exists. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B name string name of filesystem (truncated to 63 characters) .TP .B proto string (Optional) Sharing protocol (NFS, CIFS or HTTP). If not specified default is NFS .TP .B snapshot: boolean (Optional) Are snapshots enabled on the filesystem. Default is False .TP .B nfs_rules string (Optional) export rules for NFS. If not specified default is \fB*(rw,no_root_squash)\fP\&. Refer to Pure Storage documentation for formatting rules. .TP .B size string if specified capacity of filesystem. If not specified default to 32G. Refer to Pure Storage documentation for formatting rules. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefb.fs_create foo proto=CIFS salt \(aq*\(aq purefb.fs_create foo size=10T .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefb.fs_delete(name, eradicate=False) Delete a share on a Pure Storage FlashBlade. .sp Will return False if filesystem doesn\(aqt exist or is already in a deleted state. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B name string name of filesystem .TP .B eradicate boolean (Optional) Eradicate filesystem after deletion if True. Default is False .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefb.fs_delete foo eradicate=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefb.fs_eradicate(name) Eradicate a deleted filesystem on a Pure Storage FlashBlade. .sp Will return False is filesystem is not in a deleted state. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B name string name of filesystem .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefb.fs_eradicate foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefb.fs_extend(name, size) Resize an existing filesystem on a Pure Storage FlashBlade. .sp Will return False if new size is less than or equal to existing size. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B name string name of filesystem .TP .B size string New capacity of filesystem. Refer to Pure Storage documentation for formatting rules. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefb.fs_extend foo 10T .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefb.fs_update(name, rules, snapshot=False) Update filesystem on a Pure Storage FlashBlade. .sp Allows for change of NFS export rules and enabling/disabled of snapshotting capability. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B name string name of filesystem .TP .B rules string NFS export rules for filesystem Refer to Pure Storage documentation for formatting rules. .TP .B snapshot: boolean (Optional) Enable/Disable snapshots on the filesystem. Default is False .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefb.fs_nfs_update foo rules=\(aq10.234.112.23(ro), 10.234.112.24(rw)\(aq snapshot=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefb.snap_create(name, suffix=None) Create a filesystem snapshot on a Pure Storage FlashBlade. .sp Will return False if filesystem selected to snap does not exist. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B name string name of filesystem to snapshot .TP .B suffix string if specificed forces snapshot name suffix. If not specified defaults to timestamp. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefb.snap_create foo salt \(aq*\(aq purefb.snap_create foo suffix=bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefb.snap_delete(name, suffix=None, eradicate=False) Delete a filesystem snapshot on a Pure Storage FlashBlade. .sp Will return False if selected snapshot does not exist. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B name string name of filesystem .TP .B suffix string name of snapshot .TP .B eradicate boolean Eradicate snapshot after deletion if True. Default is False .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefb.snap_delete foo suffix=snap eradicate=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.purefb.snap_eradicate(name, suffix=None) Eradicate a deleted filesystem snapshot on a Pure Storage FlashBlade. .sp Will return False if snapshot is not in a deleted state. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B name string name of filesystem .TP .B suffix string name of snapshot .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq purefb.snap_eradicate foo suffix=snap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pushbullet .sp Module for sending messages to Pushbullet (\fI\%https://www.pushbullet.com\fP) .sp New in version 2015.8.0. .sp Requires an \fBapi_key\fP in \fB/etc/salt/minion\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pushbullet: api_key: \(aqABC123abc123ABC123abc123ABC123ab\(aq .ft P .fi .UNINDENT .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pushbullet: device: \(dqChrome\(dq title: \(dqExample push message\(dq body: \(dqMessage body.\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pushbullet.push_note(device=None, title=None, body=None) Pushing a text note. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdevice\fP \-\- Pushbullet target device .IP \(bu 2 \fBtitle\fP \-\- Note title .IP \(bu 2 \fBbody\fP \-\- Note body .UNINDENT .TP .B Returns Boolean if message was sent successfully. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq pushbullet.push_note device=\(dqChrome\(dq title=\(dqExample title\(dq body=\(dqExample body.\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pushover_notify .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%pushover Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Module for sending messages to Pushover (\fI\%https://www.pushover.net\fP) .sp New in version 2016.3.0. .INDENT 0.0 .TP .B configuration This module can be used by either passing an api key and version directly or by specifying both in a configuration profile in the salt master/minion config. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pushover: token: abAHuZyCLtdH8P4zhmFZmgUHUsv1ei8 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pushover_notify.post_message(user=None, device=None, message=None, title=None, priority=None, expire=None, retry=None, sound=None, api_version=1, token=None) Send a message to a Pushover user or group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuser\fP \-\- The user or group to send to, must be key of user or group not email address. .IP \(bu 2 \fBmessage\fP \-\- The message to send to the PushOver user or group. .IP \(bu 2 \fBtitle\fP \-\- Specify who the message is from. .IP \(bu 2 \fBpriority\fP \-\- The priority of the message, defaults to 0. .IP \(bu 2 \fBexpire\fP \-\- The message should expire after N number of seconds. .IP \(bu 2 \fBretry\fP \-\- The number of times the message should be retried. .IP \(bu 2 \fBsound\fP \-\- The sound to associate with the message. .IP \(bu 2 \fBapi_version\fP \-\- The PushOver API version, if not specified in the configuration. .IP \(bu 2 \fBtoken\fP \-\- The PushOver token, if not specified in the configuration. .UNINDENT .TP .B Returns Boolean if message was sent successfully. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pushover.post_message user=\(aqxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\(aq title=\(aqMessage from Salt\(aq message=\(aqBuild is done\(aq salt \(aq*\(aq pushover.post_message user=\(aqxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\(aq title=\(aqMessage from Salt\(aq message=\(aqBuild is done\(aq priority=\(aq2\(aq expire=\(aq720\(aq retry=\(aq5\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pw_group .sp Manage groups on FreeBSD .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_group.add(name, gid=None, **kwargs) Changed in version 3006.0. .sp Add the specified group .INDENT 7.0 .TP .B name Name of the new group .TP .B gid Use GID for the new group .UNINDENT .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.pw_group.adduser(name, username) 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.pw_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.pw_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.pw_group.deluser(name, username) 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.pw_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.pw_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.pw_group.members(name, members_list) Replaces members of the group with a provided list. .sp New in version 2015.5.4. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.members foo \(aquser1,user2,user3,...\(aq .ft P .fi .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.pw_user .sp Manage users with the pw command .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage users on a minion, and it is using a different module (or gives an error similar to \fI\(aquser.info\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.add(name, uid=None, gid=None, groups=None, home=None, shell=None, unique=True, fullname=\(aq\(aq, roomnumber=\(aq\(aq, workphone=\(aq\(aq, homephone=\(aq\(aq, createhome=True, loginclass=None, **kwargs) Add a user to the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.add name <uid> <gid> <groups> <home> <shell> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chfullname(name, fullname) Change the user\(aqs Full Name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chfullname foo \(dqFoo Bar\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chgid(name, gid) Change the default group of the user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chgid foo 4376 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chgroups(name, groups, append=False) Change the groups to which a user belongs .INDENT 7.0 .TP .B name Username to modify .TP .B groups List of groups to set for the user. Can be passed as a comma\-separated list or a Python list. .TP .B append False Set to \fBTrue\fP to append these groups to the user\(aqs existing list of groups. Otherwise, the specified groups will replace any existing groups for the user. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chgroups foo wheel,root True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chhome(name, home, persist=False) Set a new home directory for an existing user .INDENT 7.0 .TP .B name Username to modify .TP .B home New home directory to set .TP .B persist False Set to \fBTrue\fP to prevent configuration files in the new home directory from being overwritten by the files from the skeleton directory. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chhome foo /home/users/foo True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chhomephone(name, homephone) Change the user\(aqs Home Phone .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chhomephone foo \(dq7735551234\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chloginclass(name, loginclass, root=None) Change the default login class of the user .sp New in version 2016.3.5. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chloginclass foo staff .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chroomnumber(name, roomnumber) Change the user\(aqs Room Number .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chroomnumber foo 123 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chshell(name, shell) Change the default shell of the user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chshell foo /bin/zsh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chuid(name, uid) Change the uid for a named user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chuid foo 4376 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chworkphone(name, workphone) Change the user\(aqs Work Phone .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chworkphone foo \(dq7735550123\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.delete(name, remove=False, force=False) Remove a user from the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.delete name remove=True force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.get_loginclass(name) Get the login class of the user .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.get_loginclass foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.getent(refresh=False) Return the list of all info for all users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.getent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.info(name) Return user information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.info root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.list_groups(name) Return a list of groups the named user belongs to .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.list_groups foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.list_users() Return a list of all users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.rename(name, new_name) Change the username for a named user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.rename name new_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.pyenv .sp Manage python installations with pyenv. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Git needs to be installed and available via PATH if pyenv is to be installed automatically by the module. .UNINDENT .UNINDENT .sp New in version 2014.4.0. .INDENT 0.0 .TP .B salt.modules.pyenv.default(python=None, runas=None) Returns or sets the currently defined default python. .INDENT 7.0 .TP .B python=None The version to set as the default. Should match one of the versions listed by \fI\%pyenv.versions\fP\&. Leave blank to return the current default. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyenv.default salt \(aq*\(aq pyenv.default 2.0.0\-p0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pyenv.do(cmdline=None, runas=None) Execute a python command with pyenv\(aqs shims from the user or the system. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyenv.do \(aqgem list bundler\(aq salt \(aq*\(aq pyenv.do \(aqgem list bundler\(aq deploy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pyenv.do_with_python(python, cmdline, runas=None) Execute a python command with pyenv\(aqs shims using a specific python version. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyenv.do_with_python 2.0.0\-p0 \(aqgem list bundler\(aq salt \(aq*\(aq pyenv.do_with_python 2.0.0\-p0 \(aqgem list bundler\(aq deploy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pyenv.install(runas=None, path=None) Install pyenv systemwide .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyenv.install .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pyenv.install_python(python, runas=None) Install a python implementation. .INDENT 7.0 .TP .B python The version of python to install, should match one of the versions listed by pyenv.list .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyenv.install_python 2.0.0\-p0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pyenv.is_installed(runas=None) Check if pyenv is installed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyenv.is_installed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pyenv.list_(runas=None) List the installable versions of python. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyenv.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pyenv.rehash(runas=None) Run pyenv rehash to update the installed shims. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyenv.rehash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pyenv.uninstall_python(python, runas=None) Uninstall a python implementation. .INDENT 7.0 .TP .B python The version of python to uninstall. Should match one of the versions listed by \fI\%pyenv.versions\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyenv.uninstall_python 2.0.0\-p0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pyenv.update(runas=None, path=None) Updates the current versions of pyenv and python\-Build .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyenv.update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pyenv.versions(runas=None) List the installed versions of python. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyenv.versions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.qemu_img .SS Qemu\-img Command Wrapper .sp The qemu img command is wrapped for specific functions .INDENT 0.0 .TP .B depends qemu\-img .UNINDENT .INDENT 0.0 .TP .B salt.modules.qemu_img.convert(orig, dest, fmt) Convert an existing disk image to another format using qemu\-img .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq qemu_img.convert /path/to/original.img /path/to/new.img qcow2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.qemu_img.make_image(location, size, fmt) Create a blank virtual machine image file of the specified size in megabytes. The image can be created in any format supported by qemu .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq qemu_img.make_image /tmp/image.qcow 2048 qcow2 salt \(aq*\(aq qemu_img.make_image /tmp/image.raw 10240 raw .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.qemu_nbd .sp Qemu Command Wrapper .sp The qemu system comes with powerful tools, such as qemu\-img and qemu\-nbd which are used here to build up kvm images. .INDENT 0.0 .TP .B salt.modules.qemu_nbd.clear(mnt) Pass in the mnt dict returned from nbd_mount to unmount and disconnect the image from nbd. If all of the partitions are unmounted return an empty dict, otherwise return a dict containing the still mounted partitions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq qemu_nbd.clear \(aq{\(dq/mnt/foo\(dq: \(dq/dev/nbd0p1\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.qemu_nbd.connect(image) Activate nbd for an image file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq qemu_nbd.connect /tmp/image.raw .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.qemu_nbd.init(image, root=None) Mount the named image via qemu\-nbd and return the mounted roots .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq qemu_nbd.init /srv/image.qcow2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.qemu_nbd.mount(nbd, root=None) Pass in the nbd connection device location, mount all partitions and return a dict of mount points .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq qemu_nbd.mount /dev/nbd0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.quota .sp Module for managing quotas on POSIX\-like systems. .INDENT 0.0 .TP .B salt.modules.quota.get_mode(device) Report whether the quota system for this device is on or off .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq quota.get_mode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.quota.off(device) Turns off the quota system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq quota.off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.quota.on(device) Turns on the quota system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq quota.on .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.quota.report(mount) Report on quotas for a specific volume .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq quota.report /media/data .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.quota.set_(device, **kwargs) Calls out to setquota, for a specific user or group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq quota.set /media/data user=larry block\-soft\-limit=1048576 salt \(aq*\(aq quota.set /media/data group=painters file\-hard\-limit=1000 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.quota.stats() Runs the quotastats command, and returns the parsed output .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq quota.stats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.quota.warn() Runs the warnquota command, to send warning emails to users who are over their quota limit. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq quota.warn .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rabbitmq .sp Module to provide RabbitMQ compatibility to Salt. Todo: A lot, need to add cluster support, logging, and minion configuration data. .INDENT 0.0 .TP .B salt.modules.rabbitmq.add_user(name, password=None, runas=None) Add a rabbitMQ user via rabbitmqctl user_add <user> <password> .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.add_user rabbit_user password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.add_vhost(vhost, runas=None) Adds a vhost via rabbitmqctl add_vhost. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq add_vhost \(aq<vhost_name>\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.change_password(name, password, runas=None) Changes a user\(aqs password. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.change_password rabbit_user password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.check_password(name, password, runas=None) New in version 2016.3.0. .sp Checks if a user\(aqs password is valid. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.check_password rabbit_user password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.clear_password(name, runas=None) Removes a user\(aqs password. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.clear_password rabbit_user .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.cluster_status(runas=None) return rabbitmq cluster_status .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.cluster_status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.delete_policy(vhost, name, runas=None) Delete a policy based on rabbitmqctl clear_policy. .sp Reference: \fI\%http://www.rabbitmq.com/ha.html\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.delete_policy / HA .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.delete_upstream(name, runas=None) Deletes an upstream via rabbitmqctl clear_parameter. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the upstream to delete. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The name of the user to run the command as. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.delete_upstream upstream_name .ft P .fi .UNINDENT .UNINDENT .sp New in version 3000. .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.delete_user(name, runas=None) Deletes a user via rabbitmqctl delete_user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.delete_user rabbit_user .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.delete_vhost(vhost, runas=None) Deletes a vhost rabbitmqctl delete_vhost. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.delete_vhost \(aq<vhost_name>\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.disable_plugin(name, runas=None) Disable a RabbitMQ plugin via the rabbitmq\-plugins command. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.disable_plugin foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.enable_plugin(name, runas=None) Enable a RabbitMQ plugin via the rabbitmq\-plugins command. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.enable_plugin foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.force_reset(runas=None) Forcefully Return a RabbitMQ node to its virgin state .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.force_reset .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.join_cluster(host, user=\(aqrabbit\(aq, ram_node=None, runas=None) Join a rabbit cluster .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.join_cluster rabbit.example.com rabbit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.list_available_plugins(runas=None) Returns a list of the names of all available plugins (enabled and disabled). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.list_available_plugins .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.list_enabled_plugins(runas=None) Returns a list of the names of the enabled plugins. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.list_enabled_plugins .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.list_permissions(vhost, runas=None) Lists permissions for vhost via rabbitmqctl list_permissions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.list_permissions /myvhost .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.list_policies(vhost=\(aq/\(aq, runas=None) Return a dictionary of policies nested by vhost and name based on the data returned from rabbitmqctl list_policies. .sp Reference: \fI\%http://www.rabbitmq.com/ha.html\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.list_policies .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.list_queues(runas=None, *args) Returns queue details of the / virtual host .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.list_queues messages consumers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.list_queues_vhost(vhost, runas=None, *args) Returns queue details of specified virtual host. This command will consider first parameter as the vhost name and rest will be treated as queueinfoitem. For getting details on vhost \fB/\fP, use \fI\%list_queues\fP instead). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.list_queues messages consumers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.list_upstreams(runas=None) Returns a dict of upstreams based on rabbitmqctl list_parameters. .INDENT 7.0 .TP .B Parameters \fBrunas\fP (\fI\%str\fP) \-\- The name of the user to run this command as. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.list_upstreams .ft P .fi .UNINDENT .UNINDENT .sp New in version 3000. .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.list_user_permissions(name, runas=None) List permissions for a user via rabbitmqctl list_user_permissions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.list_user_permissions user .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.list_users(runas=None) Return a list of users based off of rabbitmqctl user_list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.list_vhosts(runas=None) Return a list of vhost based on rabbitmqctl list_vhosts. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.list_vhosts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.plugin_is_enabled(name, runas=None) Return whether the plugin is enabled. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.plugin_is_enabled rabbitmq_plugin_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.policy_exists(vhost, name, runas=None) Return whether the policy exists based on rabbitmqctl list_policies. .sp Reference: \fI\%http://www.rabbitmq.com/ha.html\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.policy_exists / HA .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.reset(runas=None) Return a RabbitMQ node to its virgin state .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.reset .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.set_permissions(vhost, user, conf=\(aq.*\(aq, write=\(aq.*\(aq, read=\(aq.*\(aq, runas=None) Sets permissions for vhost via rabbitmqctl set_permissions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.set_permissions myvhost myuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.set_policy(vhost, name, pattern, definition, priority=None, runas=None, apply_to=None) Set a policy based on rabbitmqctl set_policy. .sp Reference: \fI\%http://www.rabbitmq.com/ha.html\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.set_policy / HA \(aq.*\(aq \(aq{\(dqha\-mode\(dq:\(dqall\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.set_upstream(name, uri, prefetch_count=None, reconnect_delay=None, ack_mode=None, trust_user_id=None, exchange=None, max_hops=None, expires=None, message_ttl=None, ha_policy=None, queue=None, runas=None) Configures an upstream via rabbitmqctl set_parameter. This can be an exchange\-upstream, a queue\-upstream or both. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the upstream to configure. .UNINDENT .sp The following parameters apply to federated exchanges and federated queues: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuri\fP (\fI\%str\fP) \-\- The AMQP URI(s) for the upstream. .IP \(bu 2 \fBprefetch_count\fP (\fI\%int\fP) \-\- The maximum number of unacknowledged messages copied over a link at any one time. Default: 1000 .IP \(bu 2 \fBreconnect_delay\fP (\fI\%int\fP) \-\- The duration (in seconds) to wait before reconnecting to the broker after being disconnected. Default: 1 .IP \(bu 2 \fBack_mode\fP (\fI\%str\fP) \-\- Determines how the link should acknowledge messages. If set to \fBon\-confirm\fP (the default), messages are acknowledged to the upstream broker after they have been confirmed downstream. This handles network errors and broker failures without losing messages, and is the slowest option. If set to \fBon\-publish\fP, messages are acknowledged to the upstream broker after they have been published downstream. This handles network errors without losing messages, but may lose messages in the event of broker failures. If set to \fBno\-ack\fP, message acknowledgements are not used. This is the fastest option, but may lose messages in the event of network or broker failures. .IP \(bu 2 \fBtrust_user_id\fP (\fI\%bool\fP) \-\- Determines how federation should interact with the validated user\-id feature. If set to true, federation will pass through any validated user\-id from the upstream, even though it cannot validate it itself. If set to false or not set, it will clear any validated user\-id it encounters. You should only set this to true if you trust the upstream server (and by extension, all its upstreams) not to forge user\-ids. .UNINDENT .UNINDENT .sp The following parameters apply to federated exchanges only: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBexchange\fP (\fI\%str\fP) \-\- The name of the upstream exchange. Default is to use the same name as the federated exchange. .IP \(bu 2 \fBmax_hops\fP (\fI\%int\fP) \-\- The maximum number of federation links that a message published to a federated exchange can traverse before it is discarded. Default is 1. Note that even if max\-hops is set to a value greater than 1, messages will never visit the same node twice due to travelling in a loop. However, messages may still be duplicated if it is possible for them to travel from the source to the destination via multiple routes. .IP \(bu 2 \fBexpires\fP (\fI\%int\fP) \-\- The expiry time (in milliseconds) after which an upstream queue for a federated exchange may be deleted, if a connection to the upstream broker is lost. The default is \(aqnone\(aq, meaning the queue should never expire. This setting controls how long the upstream queue will last before it is eligible for deletion if the connection is lost. This value is used to set the \(dqx\-expires\(dq argument for the upstream queue. .IP \(bu 2 \fBmessage_ttl\fP (\fI\%int\fP) \-\- The expiry time for messages in the upstream queue for a federated exchange (see expires), in milliseconds. Default is \fBNone\fP, meaning messages should never expire. This does not apply to federated queues. This value is used to set the \(dqx\-message\-ttl\(dq argument for the upstream queue. .IP \(bu 2 \fBha_policy\fP (\fI\%str\fP) \-\- Determines the \(dqx\-ha\-policy\(dq argument for the upstream queue for a federated exchange (see expires). This is only of interest when connecting to old brokers which determine queue HA mode using this argument. Default is \fBNone\fP, meaning the queue is not HA. .UNINDENT .UNINDENT .sp The following parameter applies to federated queues only: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBqueue\fP (\fI\%str\fP) \-\- The name of the upstream queue. Default is to use the same name as the federated queue. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The name of the user to run the command as. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.set_upstream upstream_name ack_mode=on\-confirm max_hops=1 trust_user_id=True uri=amqp://hostname .ft P .fi .UNINDENT .UNINDENT .sp New in version 3000. .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.set_user_tags(name, tags, runas=None) Add user tags via rabbitmqctl set_user_tags .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.set_user_tags myadmin administrator .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.start_app(runas=None) Start the RabbitMQ application. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.start_app .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.status(runas=None) return rabbitmq status .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.stop_app(runas=None) Stops the RabbitMQ application, leaving the Erlang node running. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.stop_app .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.upstream_exists(name, runas=None) Return whether the upstreamexists based on rabbitmqctl list_parameters. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the upstream to check for. .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- The name of the user to run the command as. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.upstream_exists rabbit_upstream .ft P .fi .UNINDENT .UNINDENT .sp New in version 3000. .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.user_exists(name, runas=None) Return whether the user exists based on rabbitmqctl list_users. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.user_exists rabbit_user .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rabbitmq.vhost_exists(name, runas=None) Return whether the vhost exists based on rabbitmqctl list_vhosts. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rabbitmq.vhost_exists rabbit_host .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rallydev .sp Support for RallyDev .sp New in version 2015.8.0. .sp Requires a \fBusername\fP and a \fBpassword\fP in \fB/etc/salt/minion\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rallydev: username: myuser@example.com password: 123pass .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rallydev.list_items(name) List items of a particular type .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion rallydev.list_<item name>s salt myminion rallydev.list_users salt myminion rallydev.list_artifacts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rallydev.list_users() List the users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion rallydev.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rallydev.query_item(name, query_string, order=\(aqRank\(aq) Query a type of record for one or more items. Requires a valid query string. See \fI\%https://rally1.rallydev.com/slm/doc/webservice/introduction.jsp\fP for information on query syntax. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion rallydev.query_<item name> <query string> [<order>] salt myminion rallydev.query_task \(aq(Name contains github)\(aq salt myminion rallydev.query_task \(aq(Name contains reactor)\(aq Rank .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rallydev.query_user(query_string, order=\(aqUserName\(aq) Update a user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion rallydev.query_user \(aq(Name contains Jo)\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rallydev.show_artifact(id_) Show an artifact .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion rallydev.show_artifact <artifact id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rallydev.show_item(name, id_) Show an item .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion rallydev.show_<item name> <item id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rallydev.show_user(id_) Show a user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion rallydev.show_user <user id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rallydev.update_item(name, id_, field=None, value=None, postdata=None) Update an item. Either a field and a value, or a chunk of POST data, may be used, but not both. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion rallydev.update_<item name> <item id> field=<field> value=<value> salt myminion rallydev.update_<item name> <item id> postdata=<post data> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rallydev.update_user(id_, field, value) Update a user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion rallydev.update_user <user id> <field> <new value> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.random_org .sp Module for retrieving random information from Random.org .sp New in version 2015.5.0. .INDENT 0.0 .TP .B configuration This module can be used by either passing an api key and version directly or by specifying both in a configuration profile in the salt master/minion config. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C random_org: api_key: 7be1402d\-5719\-5bd3\-a306\-3def9f135da5 api_version: 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.random_org.generateBlobs(api_key=None, api_version=None, **kwargs) List all Slack users. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapi_key\fP \-\- The Random.org api key. .IP \(bu 2 \fBapi_version\fP \-\- The Random.org api version. .IP \(bu 2 \fBformat\fP \-\- Specifies the format in which the blobs will be returned. Values allowed are base64 and hex. .UNINDENT .TP .B Returns The user list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq get_integers number=5 min=1 max=6 salt \(aq*\(aq get_integers number=5 min=1 max=6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.random_org.generateDecimalFractions(api_key=None, api_version=None, **kwargs) Generates true random decimal fractions .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapi_key\fP \-\- The Random.org api key. .IP \(bu 2 \fBapi_version\fP \-\- The Random.org api version. .IP \(bu 2 \fBnumber\fP \-\- How many random decimal fractions you need. Must be within the [1,1e4] range. .IP \(bu 2 \fBdecimalPlaces\fP \-\- The number of decimal places to use. Must be within the [1,20] range. .IP \(bu 2 \fBreplacement\fP \-\- Specifies whether the random numbers should be picked with replacement. The default (true) will cause the numbers to be picked with replacement, i.e., the resulting numbers may contain duplicate values (like a series of dice rolls). If you want the numbers picked to be unique (like raffle tickets drawn from a container), set this value to false. .UNINDENT .TP .B Returns A list of decimal fraction .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random_org.generateDecimalFractions number=10 decimalPlaces=4 salt \(aq*\(aq random_org.generateDecimalFractions number=10 decimalPlaces=4 replacement=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.random_org.generateGaussians(api_key=None, api_version=None, **kwargs) This method generates true random numbers from a Gaussian distribution (also known as a normal distribution). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapi_key\fP \-\- The Random.org api key. .IP \(bu 2 \fBapi_version\fP \-\- The Random.org api version. .IP \(bu 2 \fBnumber\fP \-\- How many random numbers you need. Must be within the [1,1e4] range. .IP \(bu 2 \fBmean\fP \-\- The distribution\(aqs mean. Must be within the [\-1e6,1e6] range. .IP \(bu 2 \fBstandardDeviation\fP \-\- The distribution\(aqs standard deviation. Must be within the [\-1e6,1e6] range. .IP \(bu 2 \fBsignificantDigits\fP \-\- The number of significant digits to use. Must be within the [2,20] range. .UNINDENT .TP .B Returns The user list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random_org.generateGaussians number=10 mean=0.0 standardDeviation=1.0 significantDigits=8 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.random_org.generateIntegers(api_key=None, api_version=None, **kwargs) Generate random integers .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapi_key\fP \-\- The Random.org api key. .IP \(bu 2 \fBapi_version\fP \-\- The Random.org api version. .IP \(bu 2 \fBnumber\fP \-\- The number of integers to generate .IP \(bu 2 \fBminimum\fP \-\- The lower boundary for the range from which the random numbers will be picked. Must be within the [\-1e9,1e9] range. .IP \(bu 2 \fBmaximum\fP \-\- The upper boundary for the range from which the random numbers will be picked. Must be within the [\-1e9,1e9] range. .IP \(bu 2 \fBreplacement\fP \-\- Specifies whether the random numbers should be picked with replacement. The default (true) will cause the numbers to be picked with replacement, i.e., the resulting numbers may contain duplicate values (like a series of dice rolls). If you want the numbers picked to be unique (like raffle tickets drawn from a container), set this value to false. .IP \(bu 2 \fBbase\fP \-\- Specifies the base that will be used to display the numbers. Values allowed are 2, 8, 10 and 16. This affects the JSON types and formatting of the resulting data as discussed below. .UNINDENT .TP .B Returns A list of integers. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random_org.generateIntegers number=5 minimum=1 maximum=6 salt \(aq*\(aq random_org.generateIntegers number=5 minimum=2 maximum=255 base=2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.random_org.generateStrings(api_key=None, api_version=None, **kwargs) Generate random strings. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapi_key\fP \-\- The Random.org api key. .IP \(bu 2 \fBapi_version\fP \-\- The Random.org api version. .IP \(bu 2 \fBnumber\fP \-\- The number of strings to generate. .IP \(bu 2 \fBlength\fP \-\- The length of each string. Must be within the [1,20] range. All strings will be of the same length .IP \(bu 2 \fBcharacters\fP \-\- A string that contains the set of characters that are allowed to occur in the random strings. The maximum number of characters is 80. .IP \(bu 2 \fBreplacement\fP \-\- Specifies whether the random strings should be picked with replacement. The default (true) will cause the strings to be picked with replacement, i.e., the resulting list of strings may contain duplicates (like a series of dice rolls). If you want the strings to be unique (like raffle tickets drawn from a container), set this value to false. .UNINDENT .TP .B Returns A list of strings. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random_org.generateStrings number=5 length=8 characters=\(aqabcdefghijklmnopqrstuvwxyz\(aq salt \(aq*\(aq random_org.generateStrings number=10 length=16 characters\(aqabcdefghijklmnopqrstuvwxyz\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.random_org.generateUUIDs(api_key=None, api_version=None, **kwargs) Generate a list of random UUIDs .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapi_key\fP \-\- The Random.org api key. .IP \(bu 2 \fBapi_version\fP \-\- The Random.org api version. .IP \(bu 2 \fBnumber\fP \-\- How many random UUIDs you need. Must be within the [1,1e3] range. .UNINDENT .TP .B Returns A list of UUIDs .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random_org.generateUUIDs number=5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.random_org.getUsage(api_key=None, api_version=None) Show current usages statistics .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapi_key\fP \-\- The Random.org api key. .IP \(bu 2 \fBapi_version\fP \-\- The Random.org api version. .UNINDENT .TP .B Returns The current usage statistics. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq random_org.getUsage salt \(aq*\(aq random_org.getUsage api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 api_version=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rbac_solaris .sp Module for Solaris\(aq Role\-Based Access Control .INDENT 0.0 .TP .B salt.modules.rbac_solaris.auth_add(user, auth) Add authorization to user .INDENT 7.0 .TP .B user string username .TP .B auth string authorization name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbac.auth_add martine solaris.zone.manage salt \(aq*\(aq rbac.auth_add martine solaris.zone.manage,solaris.mail.mailq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbac_solaris.auth_get(user, computed=True) List authorization for user .INDENT 7.0 .TP .B user string username .TP .B computed boolean merge results from \fIauths\fP command into data from user_attr .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbac.auth_get leo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbac_solaris.auth_list() List all available authorization .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbac.auth_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbac_solaris.auth_rm(user, auth) Remove authorization from user .INDENT 7.0 .TP .B user string username .TP .B auth string authorization name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbac.auth_rm jorge solaris.zone.manage salt \(aq*\(aq rbac.auth_rm jorge solaris.zone.manage,solaris.mail.mailq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbac_solaris.profile_add(user, profile) Add profile to user .INDENT 7.0 .TP .B user string username .TP .B profile string profile name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbac.profile_add martine \(aqPrimary Administrator\(aq salt \(aq*\(aq rbac.profile_add martine \(aqUser Management,User Security\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbac_solaris.profile_get(user, default_hidden=True) List profiles for user .INDENT 7.0 .TP .B user string username .TP .B default_hidden boolean hide default profiles .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbac.profile_get leo salt \(aq*\(aq rbac.profile_get leo default_hidden=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbac_solaris.profile_list(default_only=False) List all available profiles .INDENT 7.0 .TP .B default_only boolean return only default profile .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbac.profile_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbac_solaris.profile_rm(user, profile) Remove profile from user .INDENT 7.0 .TP .B user string username .TP .B profile string profile name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbac.profile_rm jorge \(aqPrimary Administrator\(aq salt \(aq*\(aq rbac.profile_rm jorge \(aqUser Management,User Security\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbac_solaris.role_add(user, role) Add role to user .INDENT 7.0 .TP .B user string username .TP .B role string role name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbac.role_add martine netcfg salt \(aq*\(aq rbac.role_add martine netcfg,zfssnap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbac_solaris.role_get(user) List roles for user .INDENT 7.0 .TP .B user string username .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbac.role_get leo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbac_solaris.role_list() List all available roles .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbac.role_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbac_solaris.role_rm(user, role) Remove role from user .INDENT 7.0 .TP .B user string username .TP .B role string role name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbac.role_rm jorge netcfg salt \(aq*\(aq rbac.role_rm jorge netcfg,zfssnap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rbenv .sp Manage ruby installations with rbenv. rbenv is supported on Linux and macOS. rbenv doesn\(aqt work on Windows (and isn\(aqt really necessary on Windows as there is no system Ruby on Windows). On Windows, the RubyInstaller and/or Pik are both good alternatives to work with multiple versions of Ruby on the same box. .sp \fI\%http://misheska.com/blog/2013/06/15/using\-rbenv\-to\-manage\-multiple\-versions\-of\-ruby/\fP .sp New in version 0.16.0. .INDENT 0.0 .TP .B salt.modules.rbenv.default(ruby=None, runas=None) Returns or sets the currently defined default ruby .INDENT 7.0 .TP .B ruby The version to set as the default. Should match one of the versions listed by \fI\%rbenv.versions\fP\&. Leave blank to return the current default. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbenv.default salt \(aq*\(aq rbenv.default 2.0.0\-p0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbenv.do(cmdline, runas=None, env=None) Execute a ruby command with rbenv\(aqs shims from the user or the system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbenv.do \(aqgem list bundler\(aq salt \(aq*\(aq rbenv.do \(aqgem list bundler\(aq deploy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbenv.do_with_ruby(ruby, cmdline, runas=None) Execute a ruby command with rbenv\(aqs shims using a specific ruby version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbenv.do_with_ruby 2.0.0\-p0 \(aqgem list bundler\(aq salt \(aq*\(aq rbenv.do_with_ruby 2.0.0\-p0 \(aqgem list bundler\(aq runas=deploy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbenv.install(runas=None, path=None) Install rbenv systemwide .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbenv.install .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbenv.install_ruby(ruby, runas=None) Install a ruby implementation. .INDENT 7.0 .TP .B ruby The version of Ruby to install, should match one of the versions listed by \fBrbenv.list\fP .TP .B runas The user under which to run rbenv. If not specified, then rbenv will be run as the user under which Salt is running. .UNINDENT .sp Additional environment variables can be configured in pillar / grains / master: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C rbenv: build_env: \(aqCONFIGURE_OPTS=\(dq\-\-no\-tcmalloc\(dq CFLAGS=\(dq\-fno\-tree\-dce\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbenv.install_ruby 2.0.0\-p0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbenv.is_installed(runas=None) Check if rbenv is installed .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbenv.is_installed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbenv.list_(runas=None) List the installable versions of ruby .INDENT 7.0 .TP .B runas The user under which to run rbenv. If not specified, then rbenv will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbenv.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbenv.rehash(runas=None) Run \fBrbenv rehash\fP to update the installed shims .INDENT 7.0 .TP .B runas The user under which to run rbenv. If not specified, then rbenv will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbenv.rehash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbenv.uninstall_ruby(ruby, runas=None) Uninstall a ruby implementation. .INDENT 7.0 .TP .B ruby The version of ruby to uninstall. Should match one of the versions listed by \fI\%rbenv.versions\fP\&. .TP .B runas The user under which to run rbenv. If not specified, then rbenv will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbenv.uninstall_ruby 2.0.0\-p0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbenv.update(runas=None, path=None) Updates the current versions of rbenv and ruby\-build .INDENT 7.0 .TP .B runas The user under which to run rbenv. If not specified, then rbenv will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbenv.update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rbenv.versions(runas=None) List the installed versions of ruby .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rbenv.versions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rdp .sp Manage RDP Service on Windows servers .INDENT 0.0 .TP .B salt.modules.rdp.disable() Disable RDP the service on the server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rdp.disable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rdp.disconnect_session(session_id) Disconnect a session. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters \fBsession_id\fP \-\- The numeric Id of the session. .TP .B Returns A boolean representing whether the disconnect succeeded. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rdp.disconnect_session session_id salt \(aq*\(aq rdp.disconnect_session 99 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rdp.enable() Enable RDP the service on the server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rdp.enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rdp.get_session(session_id) Get information about a session. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters \fBsession_id\fP \-\- The numeric Id of the session. .TP .B Returns A dictionary of session information. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rdp.get_session session_id salt \(aq*\(aq rdp.get_session 99 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rdp.list_sessions(logged_in_users_only=False) List information about the sessions. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters \fBlogged_in_users_only\fP \-\- If True, only return sessions with users logged in. .TP .B Returns A list containing dictionaries of session information. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rdp.list_sessions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rdp.logoff_session(session_id) Initiate the logoff of a session. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters \fBsession_id\fP \-\- The numeric Id of the session. .TP .B Returns A boolean representing whether the logoff succeeded. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rdp.logoff_session session_id salt \(aq*\(aq rdp.logoff_session 99 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rdp.status() Show if rdp is enabled on the server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rdp.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rebootmgr module .sp Module for rebootmgr :maintainer: Alberto Planas <\fI\%aplanas@suse.com\fP> :maturity: new :depends: None :platform: Linux .sp New in version 3004. .INDENT 0.0 .TP .B salt.modules.rebootmgr.cancel() Cancels an already running reboot. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr cancel .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.get_group() The currently set lock group for etcd. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr get_group .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.get_strategy() The currently used reboot strategy of rebootmgrd will be printed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr get_strategy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.get_window() The currently set maintenance window will be printed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr get_window .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.is_active() Check if the rebootmgrd is running and active or not. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr is_active .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.lock(machine_id=None, group=None) .INDENT 7.0 .TP .B Lock a machine. If no group is specified, the local default group will be used. If no machine\-id is specified, the local machine will be locked. .TP .B machine_id The machine\-id is a network wide, unique ID. Per default the ID from /etc/machine\-id is used. .TP .B group Group name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr lock group=group1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.reboot(order=None) Tells rebootmgr to schedule a reboot. .sp With the [now] option, a forced reboot is done, no lock from etcd is requested and a set maintenance window is ignored. With the [fast] option, a lock from etcd is requested if needed, but a defined maintenance window is ignored. .INDENT 7.0 .TP .B order If specified, can be \(dqnow\(dq or \(dqfast\(dq .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr reboot salt microos rebootmgt reboot order=now .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.set_group(group) .INDENT 7.0 .TP .B Set the group, to which this machine belongs to get a reboot lock from etcd. .TP .B group Group name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr set_group group=group_1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.set_max(max_locks, group=None) .INDENT 7.0 .TP .B Set the maximal number of hosts in a group, which are allowed to reboot at the same time. .TP .B number Maximal number of hosts in a group .TP .B group Group name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr set_max 4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.set_strategy(strategy=None) A new strategy to reboot the machine is set and written into /etc/rebootmgr.conf. .INDENT 7.0 .TP .B strategy If specified, must be one of those options: .INDENT 7.0 .TP .B best\-effort \- This is the default strategy. If etcd is running, etcd\-lock is used. If no etcd is running, but a maintenance window is specified, the strategy will be maint\-window. If no maintenance window is specified, the machine is immediately rebooted (instantly). .TP .B etcd\-lock \- A lock at etcd for the specified lock\-group will be acquired before reboot. If a maintenance window is specified, the lock is only acquired during this window. .TP .B maint\-window \- Reboot does happen only during a specified maintenance window. If no window is specified, the instantly strategy is followed. .TP .B instantly \- Other services will be informed that a reboot will happen. Reboot will be done without getting any locks or waiting for a maintenance window. .TP .B off \- Reboot requests are temporary ignored. /etc/rebootmgr.conf is not modified. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr set_strategy stragegy=off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.set_window(time, duration) Set\(aqs the maintenance window. .INDENT 7.0 .TP .B time The format of time is the same as described in systemd.time(7). .TP .B duration The format of duration is \(dq[XXh][YYm]\(dq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr set_window time=\(dqThu,Fri 2020\-*\-1,5 11:12:13\(dq duration=1h .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.status() Returns the current status of rebootmgrd. .INDENT 7.0 .TP .B Valid returned values are: 0 \- No reboot requested 1 \- Reboot requested 2 \- Reboot requested, waiting for maintenance window 3 \- Reboot requested, waiting for etcd lock. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.unlock(machine_id=None, group=None) .INDENT 7.0 .TP .B Unlock a machine. If no group is specified, the local default group will be used. If no machine\-id is specified, the local machine will be locked. .TP .B machine_id The machine\-id is a network wide, unique ID. Per default the ID from /etc/machine\-id is used. .TP .B group Group name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr unlock group=group1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rebootmgr.version() Return the version of rebootmgrd .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos rebootmgr version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.redis .sp Module to provide redis functionality to Salt .sp New in version 2014.7.0. .INDENT 0.0 .TP .B configuration This module requires the redis python module and uses the following defaults which may be overridden in the minion configuration: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C redis.host: \(aqsalt\(aq redis.port: 6379 redis.db: 0 redis.password: None .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.bgrewriteaof(host=None, port=None, db=None, password=None) Asynchronously rewrite the append\-only file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.bgrewriteaof .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.bgsave(host=None, port=None, db=None, password=None) Asynchronously save the dataset to disk .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.bgsave .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.config_get(pattern=\(aq*\(aq, host=None, port=None, db=None, password=None) Get redis server configuration values .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.config_get salt \(aq*\(aq redis.config_get port .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.config_set(name, value, host=None, port=None, db=None, password=None) Set redis server configuration values .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.config_set masterauth luv_kittens .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.dbsize(host=None, port=None, db=None, password=None) Return the number of keys in the selected database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.dbsize .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.delete(*keys, **connection_args) Deletes the keys from redis, returns number of keys deleted .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.delete foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.exists(key, host=None, port=None, db=None, password=None) Return true if the key exists in redis .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.exists foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.expire(key, seconds, host=None, port=None, db=None, password=None) Set a keys time to live in seconds .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.expire foo 300 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.expireat(key, timestamp, host=None, port=None, db=None, password=None) Set a keys expire at given UNIX time .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.expireat foo 1400000000 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.flushall(host=None, port=None, db=None, password=None) Remove all keys from all databases .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.flushall .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.flushdb(host=None, port=None, db=None, password=None) Remove all keys from the selected database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.flushdb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.get_key(key, host=None, port=None, db=None, password=None) Get redis key value .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.get_key foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.get_master_ip(host=None, port=None, password=None) Get host information about slave .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.get_master_ip .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hdel(key, *fields, **options) Delete one of more hash fields. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hdel foo_hash bar_field1 bar_field2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hexists(key, field, host=None, port=None, db=None, password=None) Determine if a hash fields exists. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hexists foo_hash bar_field .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hget(key, field, host=None, port=None, db=None, password=None) Get specific field value from a redis hash, returns dict .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hget foo_hash bar_field .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hgetall(key, host=None, port=None, db=None, password=None) Get all fields and values from a redis hash, returns dict .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hgetall foo_hash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hincrby(key, field, increment=1, host=None, port=None, db=None, password=None) Increment the integer value of a hash field by the given number. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hincrby foo_hash bar_field 5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hincrbyfloat(key, field, increment=1.0, host=None, port=None, db=None, password=None) Increment the float value of a hash field by the given number. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hincrbyfloat foo_hash bar_field 5.17 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hlen(key, host=None, port=None, db=None, password=None) Returns number of fields of a hash. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hlen foo_hash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hmget(key, *fields, **options) Returns the values of all the given hash fields. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hmget foo_hash bar_field1 bar_field2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hmset(key, **fieldsvals) Sets multiple hash fields to multiple values. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hmset foo_hash bar_field1=bar_value1 bar_field2=bar_value2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hscan(key, cursor=0, match=None, count=None, host=None, port=None, db=None, password=None) Incrementally iterate hash fields and associated values. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hscan foo_hash match=\(aqfield_prefix_*\(aq count=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hset(key, field, value, host=None, port=None, db=None, password=None) Set the value of a hash field. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hset foo_hash bar_field bar_value .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hsetnx(key, field, value, host=None, port=None, db=None, password=None) Set the value of a hash field only if the field does not exist. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hsetnx foo_hash bar_field bar_value .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.hvals(key, host=None, port=None, db=None, password=None) Return all the values in a hash. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.hvals foo_hash bar_field1 bar_value1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.info(host=None, port=None, db=None, password=None) Get information and statistics about the server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.key_type(key, host=None, port=None, db=None, password=None) Get redis key type .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.type foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.keys(pattern=\(aq*\(aq, host=None, port=None, db=None, password=None) Get redis keys, supports glob style patterns .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.keys salt \(aq*\(aq redis.keys test* .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.lastsave(host=None, port=None, db=None, password=None) Get the UNIX time in seconds of the last successful save to disk .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.lastsave .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.llen(key, host=None, port=None, db=None, password=None) Get the length of a list in Redis .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.llen foo_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.lrange(key, start, stop, host=None, port=None, db=None, password=None) Get a range of values from a list in Redis .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.lrange foo_list 0 10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.ping(host=None, port=None, db=None, password=None) Ping the server, returns False on connection errors .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.save(host=None, port=None, db=None, password=None) Synchronously save the dataset to disk .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.save .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.sentinel_get_master_ip(master, host=None, port=None, password=None) Get ip for sentinel master .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.sentinel_get_master_ip \(aqmymaster\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.set_key(key, value, host=None, port=None, db=None, password=None) Set redis key value .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.set_key foo bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.shutdown(host=None, port=None, db=None, password=None) Synchronously save the dataset to disk and then shut down the server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.shutdown .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.slaveof(master_host=None, master_port=None, host=None, port=None, db=None, password=None) Make the server a slave of another instance, or promote it as master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Become slave of redis\-n01.example.com:6379 salt \(aq*\(aq redis.slaveof redis\-n01.example.com 6379 salt \(aq*\(aq redis.slaveof redis\-n01.example.com # Become master salt \(aq*\(aq redis.slaveof .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.smembers(key, host=None, port=None, db=None, password=None) Get members in a Redis set .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.smembers foo_set .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.time(host=None, port=None, db=None, password=None) Return the current server UNIX time in seconds .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.time .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.zcard(key, host=None, port=None, db=None, password=None) Get the length of a sorted set in Redis .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.zcard foo_sorted .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.redismod.zrange(key, start, stop, host=None, port=None, db=None, password=None) Get a range of values from a sorted set in Redis by index .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq redis.zrange foo_sorted 0 10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.reg .sp Manage the Windows registry .SS Hives .sp Hives are the main sections of the registry and all begin with the word HKEY. .INDENT 0.0 .IP \(bu 2 HKEY_LOCAL_MACHINE .IP \(bu 2 HKEY_CURRENT_USER .IP \(bu 2 HKEY_USER .UNINDENT .SS Keys .sp Keys are the folders in the registry. Keys can have many nested subkeys. Keys can have a value assigned to them under the (Default) .sp When passing a key on the CLI it must be quoted correctly depending on the backslashes being used (\fB\e\fP vs \fB\e\e\fP). The following are valid methods of passing the key on the CLI: .INDENT 0.0 .TP .B Using single backslashes: \fB\(dqSOFTWARE\ePython\(dq\fP \fB\(aqSOFTWARE\ePython\(aq\fP (will not work on a Windows Master) .TP .B Using double backslashes: \fBSOFTWARE\e\ePython\fP .UNINDENT .SS Values or Entries .sp Values or Entries are the name/data pairs beneath the keys and subkeys. All keys have a default name/data pair. The name is \fB(Default)\fP with a displayed value of \fB(value not set)\fP\&. The actual value is Null. .sp Example .sp The following example is an export from the Windows startup portion of the registry: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HKEY_LOCAL_MACHINE\eSOFTWARE\eMicrosoft\eWindows\eCurrentVersion\eRun] \(dqRTHDVCPL\(dq=\(dq\e\(dqC:\e\eProgram Files\e\eRealtek\e\eAudio\e\eHDA\e\eRtkNGUI64.exe\e\(dq \-s\(dq \(dqNvBackend\(dq=\(dq\e\(dqC:\e\eProgram Files (x86)\e\eNVIDIA Corporation\e\eUpdate Core\e\eNvBackend.exe\e\(dq\(dq \(dqBTMTrayAgent\(dq=\(dqrundll32.exe \e\(dqC:\e\eProgram Files (x86)\e\eIntel\e\eBluetooth\e\ebtmshellex.dll\e\(dq,TrayApp\(dq .ft P .fi .UNINDENT .UNINDENT .sp In this example these are the values for each: .INDENT 0.0 .TP .B Hive: \fBHKEY_LOCAL_MACHINE\fP .TP .B Key and subkeys: \fBSOFTWARE\e\eMicrosoft\e\eWindows\e\eCurrentVersion\e\eRun\fP .TP .B Value: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B There are 3 value names: .INDENT 7.0 .IP \(bu 2 \fIRTHDVCPL\fP .IP \(bu 2 \fINvBackend\fP .IP \(bu 2 \fIBTMTrayAgent\fP .UNINDENT .UNINDENT .IP \(bu 2 Each value name has a corresponding value .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 salt.utils.win_reg .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.reg.broadcast_change() Refresh the windows environment. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This will only effect new processes and windows. Services will not see the change until the system restarts. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.broadcast_change .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.reg.delete_key_recursive(hive, key, use_32bit_registry=False) New in version 2015.5.4. .sp Delete a registry key to include all subkeys and value/data pairs. .INDENT 7.0 .TP .B Parameters \fBhive\fP (\fI\%str\fP) \-\- .sp The name of the hive. Can be one of the following .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 HKEY_LOCAL_MACHINE or HKLM .IP \(bu 2 HKEY_CURRENT_USER or HKCU .IP \(bu 2 HKEY_USER or HKU .IP \(bu 2 HKEY_CLASSES_ROOT or HKCR .IP \(bu 2 HKEY_CURRENT_CONFIG or HKCC .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B key (str): The key to remove (looks like a path) .TP .B use_32bit_registry (bool): Deletes the 32bit portion of the registry on 64bit installations. On 32bit machines this is ignored. .UNINDENT .TP .B Returns .INDENT 7.0 .TP .B A dictionary listing the keys that deleted successfully as well as those that failed to delete. .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 The following example will remove \fBdelete_me\fP and all its subkeys from the \fBSOFTWARE\fP key in \fBHKEY_LOCAL_MACHINE\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.delete_key_recursive HKLM SOFTWARE\e\edelete_me .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.reg.delete_value(hive, key, vname=None, use_32bit_registry=False) Delete a registry value entry or the default value for a key. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhive\fP (\fI\%str\fP) \-\- .sp The name of the hive. Can be one of the following .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 HKEY_LOCAL_MACHINE or HKLM .IP \(bu 2 HKEY_CURRENT_USER or HKCU .IP \(bu 2 HKEY_USER or HKU .IP \(bu 2 HKEY_CLASSES_ROOT or HKCR .IP \(bu 2 HKEY_CURRENT_CONFIG or HKCC .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The key (looks like a path) to the value name. .IP \(bu 2 \fBvname\fP (\fI\%str\fP) \-\- The value name. These are the individual name/data pairs under the key. If not passed, the key (Default) value will be deleted. .IP \(bu 2 \fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Deletes the 32bit portion of the registry on 64bit installations. On 32bit machines this is ignored. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.delete_value HKEY_CURRENT_USER \(aqSOFTWARE\e\eSalt\(aq \(aqversion\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.reg.import_file(source, use_32bit_registry=False) Import registry settings from a Windows \fBREG\fP file by invoking \fBREG.EXE\fP\&. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- The full path of the \fBREG\fP file. This can be either a local file path or a URL type supported by salt (e.g. \fBsalt://salt_master_path\fP) .IP \(bu 2 \fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- If the value of this parameter is \fBTrue\fP then the \fBREG\fP file will be imported into the Windows 32 bit registry. Otherwise the Windows 64 bit registry will be used. .UNINDENT .TP .B Returns True if successful, otherwise an error is raised .TP .B Return type \fI\%bool\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%ValueError\fP \-\- If the value of \fBsource\fP is an invalid path or otherwise causes \fBcp.cache_file\fP to return \fBFalse\fP .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If \fBreg.exe\fP exits with a non\-0 exit code .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt machine1 reg.import_file salt://win/printer_config/110_Canon/postinstall_config.reg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.reg.key_exists(hive, key, use_32bit_registry=False) Check that the key is found in the registry. This refers to keys and not value/data pairs. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhive\fP (\fI\%str\fP) \-\- The hive to connect to .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The key to check .IP \(bu 2 \fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Look in the 32bit portion of the registry .UNINDENT .TP .B Returns True if exists, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.key_exists HKLM SOFTWARE\eMicrosoft .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.reg.list_keys(hive, key=None, use_32bit_registry=False) Enumerates the subkeys in a registry key or hive. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhive\fP (\fI\%str\fP) \-\- .sp The name of the hive. Can be one of the following: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 HKEY_LOCAL_MACHINE or HKLM .IP \(bu 2 HKEY_CURRENT_USER or HKCU .IP \(bu 2 HKEY_USER or HKU .IP \(bu 2 HKEY_CLASSES_ROOT or HKCR .IP \(bu 2 HKEY_CURRENT_CONFIG or HKCC .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The key (looks like a path) to the value name. If a key is not passed, the keys under the hive will be returned. .IP \(bu 2 \fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Accesses the 32bit portion of the registry on 64 bit installations. On 32bit machines this is ignored. .UNINDENT .TP .B Returns A list of keys/subkeys under the hive or key. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.list_keys HKLM \(aqSOFTWARE\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.reg.list_values(hive, key=None, use_32bit_registry=False) Enumerates the values in a registry key or hive. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fB(Default)\fP value will only be returned if it is set, otherwise it will not be returned in the list of values. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhive\fP (\fI\%str\fP) \-\- .sp The name of the hive. Can be one of the following: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 HKEY_LOCAL_MACHINE or HKLM .IP \(bu 2 HKEY_CURRENT_USER or HKCU .IP \(bu 2 HKEY_USER or HKU .IP \(bu 2 HKEY_CLASSES_ROOT or HKCR .IP \(bu 2 HKEY_CURRENT_CONFIG or HKCC .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The key (looks like a path) to the value name. If a key is not passed, the values under the hive will be returned. .IP \(bu 2 \fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Accesses the 32bit portion of the registry on 64 bit installations. On 32bit machines this is ignored. .UNINDENT .TP .B Returns A list of values under the hive or key. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.list_values HKLM \(aqSYSTEM\e\eCurrentControlSet\e\eServices\e\eTcpip\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.reg.read_value(hive, key, vname=None, use_32bit_registry=False) Reads a registry value entry or the default value for a key. To read the default value, don\(aqt pass \fBvname\fP .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhive\fP (\fI\%str\fP) \-\- .sp The name of the hive. Can be one of the following: .INDENT 2.0 .IP \(bu 2 HKEY_LOCAL_MACHINE or HKLM .IP \(bu 2 HKEY_CURRENT_USER or HKCU .IP \(bu 2 HKEY_USER or HKU .IP \(bu 2 HKEY_CLASSES_ROOT or HKCR .IP \(bu 2 HKEY_CURRENT_CONFIG or HKCC .UNINDENT .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The key (looks like a path) to the value name. .IP \(bu 2 \fBvname\fP (\fI\%str\fP) \-\- The value name. These are the individual name/data pairs under the key. If not passed, the key (Default) value will be returned. .IP \(bu 2 \fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Accesses the 32bit portion of the registry on 64bit installations. On 32bit machines this is ignored. .UNINDENT .TP .B Returns A dictionary containing the passed settings as well as the value_data if successful. If unsuccessful, sets success to False. .sp bool: Returns False if the key is not found .sp If vname is not passed: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Returns the first unnamed value (Default) as a string. .IP \(bu 2 Returns none if first unnamed value is empty. .UNINDENT .UNINDENT .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 The following will get the value of the \fBversion\fP value name in the \fBHKEY_LOCAL_MACHINE\e\eSOFTWARE\e\eSalt\fP key .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.read_value HKEY_LOCAL_MACHINE \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 The following will get the default value of the \fBHKEY_LOCAL_MACHINE\e\eSOFTWARE\e\eSalt\fP key .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.read_value HKEY_LOCAL_MACHINE \(aqSOFTWARE\eSalt\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.reg.set_value(hive, key, vname=None, vdata=None, vtype=\(aqREG_SZ\(aq, use_32bit_registry=False, volatile=False) Sets a value in the registry. If \fBvname\fP is passed, it will be the value for that value name, otherwise it will be the default value for the specified key .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhive\fP (\fI\%str\fP) \-\- .sp The name of the hive. Can be one of the following .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 HKEY_LOCAL_MACHINE or HKLM .IP \(bu 2 HKEY_CURRENT_USER or HKCU .IP \(bu 2 HKEY_USER or HKU .IP \(bu 2 HKEY_CLASSES_ROOT or HKCR .IP \(bu 2 HKEY_CURRENT_CONFIG or HKCC .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The key (looks like a path) to the value name. .IP \(bu 2 \fBvname\fP (\fI\%str\fP) \-\- The value name. These are the individual name/data pairs under the key. If not passed, the key (Default) value will be set. .IP \(bu 2 \fBvdata\fP (\fI\%str\fP\fI, \fP\fI\%int\fP\fI, \fP\fI\%list\fP\fI, \fP\fI\%bytes\fP) \-\- .sp The value you\(aqd like to set. If a value name (vname) is passed, this will be the data for that value name. If not, this will be the (Default) value for the key. .sp The type of data this parameter expects is determined by the value type specified in \fBvtype\fP\&. The correspondence is as follows: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 REG_BINARY: Binary data (str in Py2, bytes in Py3) .IP \(bu 2 REG_DWORD: int .IP \(bu 2 REG_EXPAND_SZ: str .IP \(bu 2 REG_MULTI_SZ: list of str .IP \(bu 2 REG_QWORD: int .IP \(bu 2 REG_SZ: str .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When setting REG_BINARY, string data will be converted to binary. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The type for the (Default) value is always REG_SZ and cannot be changed. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This parameter is optional. If \fBvdata\fP is not passed, the Key will be created with no associated item/value pairs. .UNINDENT .UNINDENT .IP \(bu 2 \fBvtype\fP (\fI\%str\fP) \-\- The value type. The possible values of the vtype parameter are indicated above in the description of the vdata parameter. .IP \(bu 2 \fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Sets the 32bit portion of the registry on 64bit installations. On 32bit machines this is ignored. .IP \(bu 2 \fBvolatile\fP (\fI\%bool\fP) \-\- When this parameter has a value of True, the registry key will be made volatile (i.e. it will not persist beyond a system reset or shutdown). This parameter only has an effect when a key is being created and at no other time. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 This will set the version value to 2015.5.2 in the SOFTWARESalt key in the HKEY_LOCAL_MACHINE hive .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.set_value HKEY_LOCAL_MACHINE \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq \(aq2015.5.2\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 This function is strict about the type of vdata. For instance this example will fail because vtype has a value of REG_SZ and vdata has a type of int (as opposed to str as expected). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.set_value HKEY_LOCAL_MACHINE \(aqSOFTWARE\eSalt\(aq \(aqstr_data\(aq 1.2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 In this next example vdata is properly quoted and should succeed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.set_value HKEY_LOCAL_MACHINE \(aqSOFTWARE\eSalt\(aq \(aqstr_data\(aq vtype=REG_SZ vdata=\(dq\(aq1.2\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 This is an example of using vtype REG_BINARY. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.set_value HKEY_LOCAL_MACHINE \(aqSOFTWARE\eSalt\(aq \(aqbin_data\(aq vtype=REG_BINARY vdata=\(aqSalty Data\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 An example of using vtype REG_MULTI_SZ is as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.set_value HKEY_LOCAL_MACHINE \(aqSOFTWARE\eSalt\(aq \(aqlist_data\(aq vtype=REG_MULTI_SZ vdata=\(aq[\(dqSalt\(dq, \(dqis\(dq, \(dqgreat\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.reg.value_exists(hive, key, vname, use_32bit_registry=False) Check that the value/data pair is found in the registry. .sp New in version 3000. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhive\fP (\fI\%str\fP) \-\- The hive to connect to .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The key to check in .IP \(bu 2 \fBvname\fP (\fI\%str\fP) \-\- The name of the value/data pair you\(aqre checking .IP \(bu 2 \fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Look in the 32bit portion of the registry .UNINDENT .TP .B Returns True if exists, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq reg.value_exists HKLM SOFTWARE\eMicrosoft\eWindows\eCurrentVersion CommonFilesDir .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rest_pkg .sp Package support for the REST example .INDENT 0.0 .TP .B salt.modules.rest_pkg.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_pkg.installed(name, version=None, refresh=False, fromrepo=None, skip_verify=False, pkgs=None, sources=None, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_pkg.list_pkgs(versions_as_list=False, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_pkg.remove(name=None, pkgs=None, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_pkg.upgrade(refresh=True, skip_verify=True, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_pkg.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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rest_sample_utils .sp Utility functions for the rest_sample .INDENT 0.0 .TP .B salt.modules.rest_sample_utils.fix_outage() \(dqFix\(dq the outage .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqrest\-sample\-proxy\(aq rest_sample.fix_outage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_sample_utils.get_test_string() Helper function to test cross\-calling to the __proxy__ dunder. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqrest\-sample\-proxy\(aq rest_sample.get_test_string .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rest_service .sp Provide the service module for the proxy\-minion REST sample .INDENT 0.0 .TP .B salt.modules.rest_service.enabled(name, sig=None) Only the \(aqredbull\(aq service is \(aqenabled\(aq in the test .sp New in version 2015.8.1. .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_service.get_all() Return a list of all available services .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_service.list_() Return a list of all available services. .sp New in version 2015.8.1. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_service.restart(name, sig=None) Restart the specified service with rest_sample .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_service.running(name, sig=None) Return whether this service is running. .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_service.start(name, sig=None) Start the specified service on the rest_sample .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_service.status(name, sig=None) Return the status for a service via rest_sample. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp New in version 2015.8.0. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Not implemented .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rest_service.stop(name, sig=None) Stop the specified service on the rest_sample .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.restartcheck .sp checkrestart functionality for Debian and Red Hat Based systems .sp Identifies services (processes) that are linked against deleted files (for example after downloading an updated binary of a shared library). .sp Based on checkrestart script from debian\-goodies (written by Matt Zimmerman for the Debian GNU/Linux distribution, \fI\%https://packages.debian.org/debian\-goodies\fP) and psdel by Sam Morris. .INDENT 0.0 .TP .B codeauthor Jiri Kotlin <\fI\%jiri.kotlin@ultimum.io\fP> .UNINDENT .INDENT 0.0 .TP .B salt.modules.restartcheck.restartcheck(ignorelist=None, blacklist=None, excludepid=None, **kwargs) Analyzes files openeded by running processes and seeks for packages which need to be restarted. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBignorelist\fP \-\- string or list of packages to be ignored. .IP \(bu 2 \fBblacklist\fP \-\- string or list of file paths to be ignored. .IP \(bu 2 \fBexcludepid\fP \-\- string or list of process IDs to be ignored. .IP \(bu 2 \fBverbose\fP \-\- boolean, enables extensive output. .IP \(bu 2 \fBtimeout\fP \-\- int, timeout in minute. .UNINDENT .TP .B Returns \fB{ \(aqresult\(aq: False, \(aqcomment\(aq: \(aq<reason>\(aq }\fP\&. String with checkrestart output if some package seems to need to be restarted or if no packages need restarting. .TP .B Return type Dict on error .UNINDENT .sp New in version 2015.8.3. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq restartcheck.restartcheck .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.restconf .sp Execution module for RESTCONF Proxy minions .INDENT 0.0 .TP .B codeauthor Jamie (Bear) Murphy <\fI\%jamiemurphyit@gmail.com\fP> .TP .B maturity new .TP .B platform any .UNINDENT .INDENT 0.0 .TP .B salt.modules.restconf.get_data(path) Returns an object containing the content of the request path with a GET request. Data returned will contain a dict with at minimum a key of \(dqstatus\(dq containing the http status code Other keys that should be available error (if http error), body, dict (parsed json to dict) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq restconf.get_data restconf/yang\-library\-version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.restconf.info() Returns the RESTCONF capabilities PATH .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq restconf.info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.restconf.path_check(primary_path, init_path) Used to check which path responds with a 200 status Returns an array of True/False and a dict with keys path + path_method + response data, used in states code. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq restconf.path_check restconf/yang\-library\-version/specifc_item restconf/yang\-library\-version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.restconf.set_data(path, method, dict_payload) Sends a post/patch/other type of rest method to a specified path with the specified method with specified payload .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq restconf.set_data restconf/yang\-library\-version method=PATCH dict_payload=\(dq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ret .sp Module to integrate with the returner system and retrieve data sent to a salt returner .INDENT 0.0 .TP .B salt.modules.ret.get_fun(returner, fun) Return info about last time fun was called on each minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ret.get_fun mysql network.interfaces .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ret.get_jid(returner, jid) Return the information for a specified job id .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ret.get_jid redis 20421104181954700505 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ret.get_jids(returner) Return a list of all job ids .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ret.get_jids mysql .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ret.get_minions(returner) Return a list of all minions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ret.get_minions mysql .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rh_ip .sp The networking module for RHEL/Fedora based distros .INDENT 0.0 .TP .B salt.modules.rh_ip.apply_network_settings(**settings) Apply global network configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.apply_network_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.build_interface(iface, iface_type, enabled, **settings) Build an interface script for a network interface. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_interface eth0 eth <settings> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.build_network_settings(**settings) Build the global network script. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_network_settings <settings> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.build_routes(iface, **settings) Build a route script for a network interface. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_routes eth0 <settings> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.down(iface, iface_type) Shutdown a network interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.down eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.get_interface(iface) Return the contents of an interface script .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_interface eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.get_network_settings() Return the contents of the global network script. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_network_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.get_routes(iface) Return the contents of the interface routes script. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_routes eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.up(iface, iface_type) Start up a network interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.up eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rh_service .sp Service support for RHEL\-based systems, including support for both upstart and sysvinit .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage services on a minion, and it is using a different module (or gives an error similar to \fI\(aqservice.start\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.available(name, limit=\(aq\(aq) Return True if the named service is available. Use the \fBlimit\fP param to restrict results to services of that type. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd salt \(aq*\(aq service.available sshd limit=upstart salt \(aq*\(aq service.available sshd limit=sysvinit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.delete(name, **kwargs) Delete the named service .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.delete <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.disable(name, **kwargs) Disable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.disabled(name) Check to see if the named service is disabled to start on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.enable(name, **kwargs) Enable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.enabled(name, **kwargs) Check to see if the named service is enabled to start on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.get_all(limit=\(aq\(aq) Return all installed services. Use the \fBlimit\fP param to restrict results to services of that type. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all salt \(aq*\(aq service.get_all limit=upstart salt \(aq*\(aq service.get_all limit=sysvinit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.get_disabled(limit=\(aq\(aq) Return the disabled services. Use the \fBlimit\fP param to restrict results to services of that type. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled salt \(aq*\(aq service.get_disabled limit=upstart salt \(aq*\(aq service.get_disabled limit=sysvinit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.get_enabled(limit=\(aq\(aq) Return the enabled services. Use the \fBlimit\fP param to restrict results to services of that type. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled salt \(aq*\(aq service.get_enabled limit=upstart salt \(aq*\(aq service.get_enabled limit=sysvinit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.missing(name, limit=\(aq\(aq) The inverse of service.available. Return True if the named service is not available. Use the \fBlimit\fP param to restrict results to services of that type. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd salt \(aq*\(aq service.missing sshd limit=upstart salt \(aq*\(aq service.missing sshd limit=sysvinit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.reload_(name) Reload the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.restart(name) Restart the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.start(name) Start the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.status(name, sig=None) Return the status for a service. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Signature to use to find the service via ps .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> [service signature] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.stop(name) Stop the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.riak .sp Riak Salt Module .INDENT 0.0 .TP .B salt.modules.riak.cluster_commit() Commit Cluster Changes .sp Changed in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq riak.cluster_commit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.riak.cluster_join(username, hostname) Join a Riak cluster .sp Changed in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq riak.cluster_join <user> <host> .ft P .fi .UNINDENT .UNINDENT .sp username \- The riak username to join the cluster hostname \- The riak hostname you are connecting to .UNINDENT .INDENT 0.0 .TP .B salt.modules.riak.cluster_leave(username, hostname) Leave a Riak cluster .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq riak.cluster_leave <username> <host> .ft P .fi .UNINDENT .UNINDENT .sp username \- The riak username to join the cluster hostname \- The riak hostname you are connecting to .UNINDENT .INDENT 0.0 .TP .B salt.modules.riak.cluster_plan() Review Cluster Plan .sp Changed in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq riak.cluster_plan .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.riak.member_status() Get cluster member status .sp Changed in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq riak.member_status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.riak.services() List available services on a node .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq riak.services .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.riak.start() Start Riak .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq riak.start .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.riak.status() Current node status .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq riak.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.riak.stop() Stop Riak .sp Changed in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq riak.stop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.riak.test() Runs a test of a few standard Riak operations .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq riak.test .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rpm_lowpkg .sp Support for rpm .INDENT 0.0 .TP .B salt.modules.rpm_lowpkg.bin_pkg_info(path, saltenv=\(aqbase\(aq) New in version 2015.8.0. .sp Parses RPM metadata and returns a dictionary of information about the package (name, version, etc.). .INDENT 7.0 .TP .B path Path to the file. Can either be an absolute path to a file on the minion, or a salt fileserver URL (e.g. \fBsalt://path/to/file.rpm\fP). If a salt fileserver URL is passed, the file will be cached to the minion so that it can be examined. .TP .B saltenv base Salt fileserver environment from which to retrieve the package. Ignored if \fBpath\fP is a local file path on the minion. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.bin_pkg_info /root/salt\-2015.5.1\-2.el7.noarch.rpm salt \(aq*\(aq lowpkg.bin_pkg_info salt://salt\-2015.5.1\-2.el7.noarch.rpm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rpm_lowpkg.checksum(*paths, **kwargs) Return if the signature of a RPM file is valid. .INDENT 7.0 .TP .B root use root as top level directory (default: \(dq/\(dq) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.checksum /path/to/package1.rpm salt \(aq*\(aq lowpkg.checksum /path/to/package1.rpm /path/to/package2.rpm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rpm_lowpkg.diff(package_path, path) Return a formatted diff between current file and original in a package. NOTE: this function includes all files (configuration and not), but does not work on binary content. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpackage\fP \-\- Full pack of the RPM file .IP \(bu 2 \fBpath\fP \-\- Full path to the installed file .UNINDENT .TP .B Returns Difference or empty string. For binary files only a notification. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.diff /path/to/apache2.rpm /etc/apache2/httpd.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rpm_lowpkg.file_dict(*packages, **kwargs) List the files that belong to a package, sorted by group. Not specifying any packages will return a list of _every_ file on the system\(aqs rpm database (not generally recommended). .INDENT 7.0 .TP .B root use root as top level directory (default: \(dq/\(dq) .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.file_dict httpd salt \(aq*\(aq lowpkg.file_dict httpd postfix salt \(aq*\(aq lowpkg.file_dict .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rpm_lowpkg.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 rpm database (not generally recommended). .INDENT 7.0 .TP .B root use root as top level directory (default: \(dq/\(dq) .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.file_list httpd salt \(aq*\(aq lowpkg.file_list httpd postfix salt \(aq*\(aq lowpkg.file_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rpm_lowpkg.info(*packages, **kwargs) Return a detailed package(s) summary information. If no packages specified, all packages will be returned. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpackages\fP \-\- .IP \(bu 2 \fBattr\fP \-\- .sp Comma\-separated package attributes. If no \(aqattr\(aq is specified, all available attributes returned. .INDENT 2.0 .TP .B Valid attributes are: version, vendor, release, build_date, build_date_time_t, install_date, install_date_time_t, build_host, group, source_rpm, arch, epoch, size, license, signature, packager, url, summary, description. .UNINDENT .IP \(bu 2 \fBall_versions\fP \-\- Return information for all installed versions of the packages .IP \(bu 2 \fBroot\fP \-\- use root as top level directory (default: \(dq/\(dq) .UNINDENT .TP .B Returns .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.info apache2 bash salt \(aq*\(aq lowpkg.info apache2 bash attr=version salt \(aq*\(aq lowpkg.info apache2 bash attr=version,build_date_iso,size salt \(aq*\(aq lowpkg.info apache2 bash attr=version,build_date_iso,size all_versions=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rpm_lowpkg.list_pkgs(*packages, **kwargs) List the packages currently installed in a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(aq} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B root use root as top level directory (default: \(dq/\(dq) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.list_pkgs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rpm_lowpkg.modified(*packages, **flags) List the modified files that belong to a package. Not specifying any packages will return a list of _all_ modified files on the system\(aqs RPM database. .sp New in version 2015.5.0. .INDENT 7.0 .TP .B root use root as top level directory (default: \(dq/\(dq) .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.modified httpd salt \(aq*\(aq lowpkg.modified httpd postfix salt \(aq*\(aq lowpkg.modified .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rpm_lowpkg.owner(*paths, **kwargs) Return the name of the package that owns the file. Multiple file paths can be passed. 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. .INDENT 7.0 .TP .B root use root as top level directory (default: \(dq/\(dq) .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.owner /usr/bin/apachectl salt \(aq*\(aq lowpkg.owner /usr/bin/apachectl /etc/httpd/conf/httpd.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rpm_lowpkg.verify(*packages, **kwargs) Runs an rpm \-Va on a system, and returns the results in a dict .INDENT 7.0 .TP .B root use root as top level directory (default: \(dq/\(dq) .UNINDENT .sp Files with an attribute of config, doc, ghost, license or readme in the package header can be ignored using the \fBignore_types\fP keyword argument .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.verify salt \(aq*\(aq lowpkg.verify httpd salt \(aq*\(aq lowpkg.verify httpd postfix salt \(aq*\(aq lowpkg.verify httpd postfix ignore_types=[\(aqconfig\(aq,\(aqdoc\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rpm_lowpkg.version_cmp(ver1, ver2, ignore_epoch=False) New in version 2015.8.9. .sp Do a cmp\-style comparison on two packages. Return \-1 if ver1 < ver2, 0 if ver1 == ver2, and 1 if ver1 > ver2. 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\-001\(aq \(aq0.2.0.1\-002\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rpmbuild_pkgbuild .sp RPM Package builder system .sp New in version 2015.8.0. .sp This system allows for all of the components to build rpms safely in chrooted environments. This also provides a function to generate yum repositories .sp This module implements the pkgbuild interface .INDENT 0.0 .TP .B salt.modules.rpmbuild_pkgbuild.build(runas, tgt, dest_dir, spec, sources, deps, env, template, saltenv=\(aqbase\(aq, log_dir=\(aq/var/log/salt/pkgbuild\(aq) Given the package destination directory, the spec file source and package sources, use mock to safely build the rpm defined in the spec file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgbuild.build mock epel\-7\-x86_64 /var/www/html https://raw.githubusercontent.com/saltstack/libnacl/master/pkg/rpm/python\-libnacl.spec https://pypi.python.org/packages/source/l/libnacl/libnacl\-1.3.5.tar.gz .ft P .fi .UNINDENT .UNINDENT .sp This example command should build the libnacl package for rhel 7 using user mock and place it in /var/www/html/ on the minion .UNINDENT .INDENT 0.0 .TP .B salt.modules.rpmbuild_pkgbuild.make_repo(repodir, keyid=None, env=None, use_passphrase=False, gnupghome=\(aq/etc/salt/gpgkeys\(aq, runas=\(aqroot\(aq, timeout=15.0) Make a package repository and optionally sign packages present .sp Given the repodir, create a \fByum\fP repository out of the rpms therein and optionally sign it and packages present, the name is directory to turn into a repo. This state is best used with onchanges linked to your package building states. .INDENT 7.0 .TP .B repodir The directory to find packages that will be in the repository. .TP .B keyid Changed in version 2016.3.0. .sp Optional Key ID to use in signing packages and repository. Utilizes Public and Private keys associated with keyid which have been loaded into the minion\(aqs Pillar data. .sp For example, contents from a Pillar data file with named Public and Private keys as follows: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C gpg_pkg_priv_key: | \-\-\-\-\-BEGIN PGP PRIVATE KEY BLOCK\-\-\-\-\- Version: GnuPG v1 lQO+BFciIfQBCADAPCtzx7I5Rl32escCMZsPzaEKWe7bIX1em4KCKkBoX47IG54b w82PCE8Y1jF/9Uk2m3RKVWp3YcLlc7Ap3gj6VO4ysvVz28UbnhPxsIkOlf2cq8qc . . Ebe+8JCQTwqSXPRTzXmy/b5WXDeM79CkLWvuGpXFor76D+ECMRPv/rawukEcNptn R5OmgHqvydEnO4pWbn8JzQO9YX/Us0SMHBVzLC8eIi5ZIopzalvX =JvW8 \-\-\-\-\-END PGP PRIVATE KEY BLOCK\-\-\-\-\- gpg_pkg_priv_keyname: gpg_pkg_key.pem gpg_pkg_pub_key: | \-\-\-\-\-BEGIN PGP PUBLIC KEY BLOCK\-\-\-\-\- Version: GnuPG v1 mQENBFciIfQBCADAPCtzx7I5Rl32escCMZsPzaEKWe7bIX1em4KCKkBoX47IG54b w82PCE8Y1jF/9Uk2m3RKVWp3YcLlc7Ap3gj6VO4ysvVz28UbnhPxsIkOlf2cq8qc . . bYP7t5iwJmQzRMyFInYRt77wkJBPCpJc9FPNebL9vlZcN4zv0KQta+4alcWivvoP 4QIxE+/+trC6QRw2m2dHk6aAeq/J0Sc7ilZufwnNA71hf9SzRIwcFXMsLx4iLlki inNqW9c= =s1CX \-\-\-\-\-END PGP PUBLIC KEY BLOCK\-\-\-\-\- gpg_pkg_pub_keyname: gpg_pkg_key.pub .ft P .fi .UNINDENT .UNINDENT .TP .B env Changed in version 2016.3.0. .sp A dictionary of environment variables to be utilized in creating the repository. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This parameter is not used for making \fByum\fP repositories. .UNINDENT .UNINDENT .TP .B use_passphrase False New in version 2016.3.0. .sp Use a passphrase with the signing key presented in \fBkeyid\fP\&. Passphrase is received from Pillar data which could be passed on the command line with \fBpillar\fP parameter. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pillar=\(aq{ \(dqgpg_passphrase\(dq : \(dqmy_passphrase\(dq }\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 3001.1. .sp RHEL 8 and above leverages gpg\-agent and gpg\-preset\-passphrase for caching keys, etc. .TP .B gnupghome /etc/salt/gpgkeys New in version 2016.3.0. .sp Location where GPG related files are stored, used with \fBkeyid\fP\&. .TP .B runas root New in version 2016.3.0. .sp User to create the repository as, and optionally sign packages. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Ensure the user has correct permissions to any files and directories which are to be utilized. .UNINDENT .UNINDENT .TP .B timeout 15.0 New in version 2016.3.4. .sp Timeout in seconds to wait for the prompt for inputting the passphrase. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgbuild.make_repo /var/www/html/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rpmbuild_pkgbuild.make_src_pkg(dest_dir, spec, sources, env=None, template=None, saltenv=\(aqbase\(aq, runas=\(aqroot\(aq) Create a source rpm from the given spec file and sources .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkgbuild.make_src_pkg /var/www/html/ https://raw.githubusercontent.com/saltstack/libnacl/master/pkg/rpm/python\-libnacl.spec https://pypi.python.org/packages/source/l/libnacl/libnacl\-1.3.5.tar.gz .ft P .fi .UNINDENT .UNINDENT .sp This example command should build the libnacl SOURCE package and place it in /var/www/html/ on the minion .sp Changed in version 2017.7.0. .INDENT 7.0 .TP .B dest_dir The directory on the minion to place the built package(s) .TP .B spec The location of the spec file (used for rpms) .TP .B sources The list of package sources .TP .B env A dictionary of environment variables to be set prior to execution. .TP .B template Run the spec file through a templating engine Optional argument, allows for no templating engine used to be if none is desired. .TP .B saltenv The saltenv to use for files downloaded from the salt filesever .TP .B runas The user to run the build process as .sp New in version 2018.3.3. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 using SHA256 as digest and minimum level dist el6 .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rsync .sp Wrapper for rsync .sp New in version 2014.1.0. .sp This data can also be passed into \fI\%pillar\fP\&. Options passed into opts will overwrite options passed into pillar. .INDENT 0.0 .TP .B salt.modules.rsync.config(conf_path=\(aq/etc/rsyncd.conf\(aq) Changed in version 2016.3.0: Return data now contains just the contents of the rsyncd.conf as a string, instead of a dictionary as returned from \fI\%cmd.run_all\fP\&. .sp Returns the contents of the rsync config file .INDENT 7.0 .TP .B conf_path /etc/rsyncd.conf Path to the config file .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rsync.config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rsync.rsync(src, dst, delete=False, force=False, update=False, passwordfile=None, exclude=None, excludefrom=None, dryrun=False, rsh=None, additional_opts=None, saltenv=\(aqbase\(aq) Changed in version 2016.3.0: Return data now contains just the output of the rsync command, instead of a dictionary as returned from \fI\%cmd.run_all\fP\&. .sp Rsync files from src to dst .INDENT 7.0 .TP .B src The source location where files will be rsynced from. .TP .B dst The destination location where files will be rsynced to. .TP .B delete False Whether to enable the rsync \fI\-\-delete\fP flag, which will delete extraneous files from dest dirs .TP .B force False Whether to enable the rsync \fI\-\-force\fP flag, which will force deletion of dirs even if not empty. .TP .B update False Whether to enable the rsync \fI\-\-update\fP flag, which forces rsync to skip any files which exist on the destination and have a modified time that is newer than the source file. .TP .B passwordfile A file that contains a password for accessing an rsync daemon. The file should contain just the password. .TP .B exclude Whether to enable the rsync \fI\-\-exclude\fP flag, which will exclude files matching a PATTERN. .TP .B excludefrom Whether to enable the rsync \fI\-\-excludefrom\fP flag, which will read exclude patterns from a file. .TP .B dryrun False Whether to enable the rsync \fI\-\-dry\-run\fP flag, which will perform a trial run with no changes made. .TP .B rsh Whether to enable the rsync \fI\-\-rsh\fP flag, to specify the remote shell to use. .TP .B additional_opts Any additional rsync options, should be specified as a list. .TP .B saltenv Specify a salt fileserver environment to be used. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rsync.rsync /path/to/src /path/to/dest delete=True update=True passwordfile=/etc/pass.crt exclude=exclude/dir salt \(aq*\(aq rsync.rsync /path/to/src delete=True excludefrom=/xx.ini salt \(aq*\(aq rsync.rsync /path/to/src delete=True exclude=\(aq[exclude1/dir,exclude2/dir]\(aq additional_opts=\(aq[\(dq\-\-partial\(dq, \(dq\-\-bwlimit=5000\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rsync.version() Changed in version 2016.3.0: Return data now contains just the version number as a string, instead of a dictionary as returned from \fI\%cmd.run_all\fP\&. .sp Returns rsync version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rsync.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.runit .sp runit service module (\fI\%http://smarden.org/runit\fP) .sp This module is compatible with the \fI\%service\fP states, so it can be used to maintain services using the \fBprovider\fP argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myservice: service: \- running \- provider: runit .ft P .fi .UNINDENT .UNINDENT .sp Provides virtual \fIservice\fP module on systems using runit as init. .sp Service management rules (\fIsv\fP command): .INDENT 0.0 .INDENT 3.5 service $n is ENABLED if file SERVICE_DIR/$n/run exists service $n is AVAILABLE if ENABLED or if file AVAIL_SVR_DIR/$n/run exists service $n is DISABLED if AVAILABLE but not ENABLED .sp SERVICE_DIR/$n is normally a symlink to a AVAIL_SVR_DIR/$n folder .UNINDENT .UNINDENT .sp Service auto\-start/stop mechanism: .INDENT 0.0 .INDENT 3.5 \fIsv\fP (auto)starts/stops service as soon as SERVICE_DIR/<service> is created/deleted, both on service creation or a boot time. .sp autostart feature is disabled if file SERVICE_DIR/<n>/down exists. This does not affect the current\(aqs service status (if already running) nor manual service management. .UNINDENT .UNINDENT .sp Service\(aqs alias: .INDENT 0.0 .INDENT 3.5 Service \fIsva\fP is an alias of service \fIsvc\fP when \fIAVAIL_SVR_DIR/sva\fP symlinks to folder \fIAVAIL_SVR_DIR/svc\fP\&. \fIsvc\fP can\(aqt be enabled if it is already enabled through an alias already enabled, since \fIsv\fP files are stored in folder \fISERVICE_DIR/svc/\fP\&. .sp XBPS package management uses a service\(aqs alias to provides service alternative(s), such as chrony and openntpd both aliased to ntpd. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.add_svc_avail_path(path) Add a path that may contain available services. Return \fBTrue\fP if added (or already present), \fBFalse\fP on error. .INDENT 7.0 .TP .B path directory to add to AVAIL_SVR_DIRS .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .INDENT 7.0 .TP .B name the service\(aqs name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq runit.available <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.disable(name, stop=False, **kwargs) Don\(aqt start service \fBname\fP at boot Returns \fBTrue\fP if operation is successful .INDENT 7.0 .TP .B name the service\(aqs name .TP .B stop if True, also stops the service .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable <name> [stop=True] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.disabled(name) Return \fBTrue\fP if the named service is disabled, \fBFalse\fP otherwise .INDENT 7.0 .TP .B name the service\(aqs name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.enable(name, start=False, **kwargs) Start service \fBname\fP at boot. Returns \fBTrue\fP if operation is successful .INDENT 7.0 .TP .B name the service\(aqs name .TP .B start False If \fBTrue\fP, start the service once enabled. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable <name> [start=True] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.enabled(name) Return \fBTrue\fP if the named service is enabled, \fBFalse\fP otherwise .INDENT 7.0 .TP .B name the service\(aqs name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.full_restart(name) Calls runit.restart() .INDENT 7.0 .TP .B name the service\(aqs name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq runit.full_restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.get_all() Return a list of all available services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq runit.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.get_disabled() Return a list of all disabled services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.get_enabled() Return a list of all enabled services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.get_svc_alias() Returns the list of service\(aqs name that are aliased and their alias path(s) .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.get_svc_avail_path() Return list of paths that may contain available services .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.get_svc_broken_path(name=\(aq*\(aq) Return list of broken path(s) in SERVICE_DIR that match \fBname\fP .sp A path is broken if it is a broken symlink or can not be a runit service .INDENT 7.0 .TP .B name a glob for service name. default is \(aq*\(aq .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq runit.get_svc_broken_path <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.missing(name) The inverse of runit.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .INDENT 7.0 .TP .B name the service\(aqs name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq runit.missing <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.reload_(name) Reload service .INDENT 7.0 .TP .B name the service\(aqs name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq runit.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.remove(name) Remove the service <name> from system. Returns \fBTrue\fP if operation is successful. The service will be also stopped. .INDENT 7.0 .TP .B name the service\(aqs name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.remove <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.restart(name) Restart service .INDENT 7.0 .TP .B name the service\(aqs name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq runit.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.show(name) Show properties of one or more units/jobs or the manager .INDENT 7.0 .TP .B name the service\(aqs name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.show <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.start(name) Start service .INDENT 7.0 .TP .B name the service\(aqs name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq runit.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.status(name, sig=None) Return \fBTrue\fP if service is running .INDENT 7.0 .TP .B name the service\(aqs name .TP .B sig signature to identify with ps .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq runit.status <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.status_autostart(name) Return \fBTrue\fP if service <name> is autostarted by sv (file $service_folder/down does not exist) NB: return \fBFalse\fP if the service is not enabled. .INDENT 7.0 .TP .B name the service\(aqs name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq runit.status_autostart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.runit.stop(name) Stop service .INDENT 7.0 .TP .B name the service\(aqs name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq runit.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.rvm .sp Manage ruby installations and gemsets with RVM, the Ruby Version Manager. .INDENT 0.0 .TP .B salt.modules.rvm.do(ruby, command, runas=None, cwd=None, env=None) Execute a command in an RVM controlled environment. .INDENT 7.0 .TP .B ruby Which ruby to use .TP .B command The rvm command to execute .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .TP .B cwd The directory from which to run the rvm command. Defaults to the user\(aqs home directory. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.do 2.0.0 <command> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.gemset_copy(source, destination, runas=None) Copy all gems from one gemset to another. .INDENT 7.0 .TP .B source The name of the gemset to copy, complete with ruby version .TP .B destination The destination gemset .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.gemset_copy foobar bazquo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.gemset_create(ruby, gemset, runas=None) Creates a gemset. .INDENT 7.0 .TP .B ruby The ruby version for which to create the gemset .TP .B gemset The name of the gemset to create .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.gemset_create 2.0.0 foobar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.gemset_delete(ruby, gemset, runas=None) Delete a gemset .INDENT 7.0 .TP .B ruby The ruby version to which the gemset belongs .TP .B gemset The gemset to delete .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.gemset_delete 2.0.0 foobar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.gemset_empty(ruby, gemset, runas=None) Remove all gems from a gemset. .INDENT 7.0 .TP .B ruby The ruby version to which the gemset belongs .TP .B gemset The gemset to empty .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.gemset_empty 2.0.0 foobar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.gemset_list(ruby=\(aqdefault\(aq, runas=None) List all gemsets for the given ruby. .INDENT 7.0 .TP .B ruby default The ruby version for which to list the gemsets .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.gemset_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.gemset_list_all(runas=None) List all gemsets for all installed rubies. .sp Note that you must have set a default ruby before this can work. .INDENT 7.0 .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.gemset_list_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.get(version=\(aqstable\(aq, runas=None) Update RVM .INDENT 7.0 .TP .B version stable Which version of RVM to install, (e.g. stable or head) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.get .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.install(runas=None) Install RVM system\-wide .INDENT 7.0 .TP .B runas The user under which to run the rvm installer script. If not specified, then it be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.install .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.install_ruby(ruby, runas=None, opts=None, env=None) Install a ruby implementation. .INDENT 7.0 .TP .B ruby The version of ruby to install .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .TP .B env Environment to set for the install command. Useful for exporting compilation flags such as RUBY_CONFIGURE_OPTS .TP .B opts List of options to pass to the RVM installer (ie \-C, \-\-patch, etc) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.install_ruby 1.9.3\-p385 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.is_installed(runas=None) Check if RVM is installed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.is_installed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.list_(runas=None) List all rvm\-installed rubies .INDENT 7.0 .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.reinstall_ruby(ruby, runas=None, env=None) Reinstall a ruby implementation .INDENT 7.0 .TP .B ruby The version of ruby to reinstall .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.reinstall_ruby 1.9.3\-p385 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.rubygems(ruby, version, runas=None) Installs a specific rubygems version in the given ruby .INDENT 7.0 .TP .B ruby The ruby for which to install rubygems .TP .B version The version of rubygems to install, or \(aqremove\(aq to use the version that ships with 1.9 .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.rubygems 2.0.0 1.8.24 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.set_default(ruby, runas=None) Set the default ruby .INDENT 7.0 .TP .B ruby The version of ruby to make the default .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.set_default 2.0.0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.wrapper(ruby_string, wrapper_prefix, runas=None, *binaries) Install RVM wrapper scripts .INDENT 7.0 .TP .B ruby_string Ruby/gemset to install wrappers for .TP .B wrapper_prefix What to prepend to the name of the generated wrapper binaries .TP .B runas The user under which to run rvm. If not specified, then rvm will be run as the user under which Salt is running. .TP .B binaries None The names of the binaries to create wrappers for. When nothing is given, wrappers for ruby, gem, rake, irb, rdoc, ri and testrb are generated. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq rvm.wrapper <ruby_string> <wrapper_prefix> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.s3 .sp Connection module for Amazon S3 .INDENT 0.0 .TP .B configuration This module accepts explicit s3 credentials but 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 7.0 .INDENT 3.5 \fI\%http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html\fP .UNINDENT .UNINDENT .sp If IAM roles are not used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C s3.keyid: GKTADJGHEIQSXMKKRBJ08H s3.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This is literally the pillar key \fBs3.keyid\fP or the config option \fBs3.keyid\fP, not: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s3: keyid: blah .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp A \fBservice_url\fP may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C s3.service_url: s3.amazonaws.com .ft P .fi .UNINDENT .UNINDENT .sp A \fBrole_arn\fP may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C s3.role_arn: arn:aws:iam::111111111111:role/my\-role\-to\-assume .ft P .fi .UNINDENT .UNINDENT .sp If a \fBservice_url\fP is not specified, the default is \fBs3.amazonaws.com\fP\&. This may appear in various documentation as an \(dqendpoint\(dq. A comprehensive list for Amazon S3 may be found at: .INDENT 7.0 .INDENT 3.5 \fI\%http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region\fP .UNINDENT .UNINDENT .sp The \fBservice_url\fP will form the basis for the final endpoint that is used to query the service. .sp Path style can be enabled: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C s3.path_style: True .ft P .fi .UNINDENT .UNINDENT .sp This can be useful if you need to use Salt with a proxy for a S3 compatible storage. .sp You can use either HTTPS protocol or HTTP protocol: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C s3.https_enable: True .ft P .fi .UNINDENT .UNINDENT .sp SSL verification may also be turned off in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C s3.verify_ssl: False .ft P .fi .UNINDENT .UNINDENT .sp This is required if using S3 bucket names that contain a period, as these will not match Amazon\(aqs S3 wildcard certificates. Certificate verification is enabled by default. .sp AWS region may be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C s3.location: eu\-central\-1 .ft P .fi .UNINDENT .UNINDENT .sp Default is \fBus\-east\-1\fP\&. .sp This module should be usable to query other S3\-like services, such as Eucalyptus. .UNINDENT .INDENT 0.0 .TP .B depends requests .UNINDENT .INDENT 0.0 .TP .B salt.modules.s3.delete(bucket, path=None, action=None, key=None, keyid=None, service_url=None, verify_ssl=None, kms_keyid=None, location=None, role_arn=None, path_style=None, https_enable=None) Delete a bucket, or delete an object from a bucket. .sp CLI Example to delete a bucket: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion s3.delete mybucket .ft P .fi .UNINDENT .UNINDENT .sp CLI Example to delete an object from a bucket: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion s3.delete mybucket remoteobject .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.s3.get(bucket=\(aq\(aq, path=\(aq\(aq, return_bin=False, action=None, local_file=None, key=None, keyid=None, service_url=None, verify_ssl=None, kms_keyid=None, location=None, role_arn=None, path_style=None, https_enable=None) List the contents of a bucket, or return an object from a bucket. Set return_bin to True in order to retrieve an object wholesale. Otherwise, Salt will attempt to parse an XML response. .sp CLI Example to list buckets: .INDENT 7.0 .INDENT 3.5 salt myminion s3.get .UNINDENT .UNINDENT .sp CLI Example to list the contents of a bucket: .INDENT 7.0 .INDENT 3.5 salt myminion s3.get mybucket .UNINDENT .UNINDENT .sp CLI Example to return the binary contents of an object: .INDENT 7.0 .INDENT 3.5 salt myminion s3.get mybucket myfile.png return_bin=True .UNINDENT .UNINDENT .sp CLI Example to save the binary contents of an object to a local file: .INDENT 7.0 .INDENT 3.5 salt myminion s3.get mybucket myfile.png local_file=/tmp/myfile.png .UNINDENT .UNINDENT .sp It is also possible to perform an action on a bucket. Currently, S3 supports the following actions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C acl cors lifecycle policy location logging notification tagging versions requestPayment versioning website .ft P .fi .UNINDENT .UNINDENT .sp To perform an action on a bucket: .INDENT 7.0 .INDENT 3.5 salt myminion s3.get mybucket myfile.png action=acl .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.s3.head(bucket, path=\(aq\(aq, key=None, keyid=None, service_url=None, verify_ssl=None, kms_keyid=None, location=None, role_arn=None, path_style=None, https_enable=None) Return the metadata for a bucket, or an object in a bucket. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion s3.head mybucket salt myminion s3.head mybucket myfile.png .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.s3.put(bucket, path=None, return_bin=False, action=None, local_file=None, key=None, keyid=None, service_url=None, verify_ssl=None, kms_keyid=None, location=None, role_arn=None, path_style=None, https_enable=None) Create a new bucket, or upload an object to a bucket. .sp CLI Example to create a bucket: .INDENT 7.0 .INDENT 3.5 salt myminion s3.put mybucket .UNINDENT .UNINDENT .sp CLI Example to upload an object to a bucket: .INDENT 7.0 .INDENT 3.5 salt myminion s3.put mybucket remotepath local_file=/path/to/file .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.s6 .sp s6 service module .sp This module is compatible with the \fI\%service\fP states, so it can be used to maintain services using the \fBprovider\fP argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myservice: service: \- running \- provider: s6 .ft P .fi .UNINDENT .UNINDENT .sp Note that the \fBenabled\fP argument is not available with this provider. .INDENT 0.0 .TP .B codeauthor Marek Skrobacki <\fI\%skrobul@skrobul.com\fP> .UNINDENT .INDENT 0.0 .TP .B salt.modules.s6.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq s6.available foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.s6.full_restart(name) Calls s6.restart() function .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq s6.full_restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.s6.get_all() Return a list of all available services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq s6.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.s6.missing(name) The inverse of s6.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq s6.missing foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.s6.reload_(name) Send a HUP to service via s6 .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq s6.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.s6.restart(name) Restart service via s6. This will stop/start service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq s6.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.s6.start(name) Starts service via s6 .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq s6.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.s6.status(name, sig=None) Return the status for a service via s6, return pid if running .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq s6.status <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.s6.stop(name) Stops service via s6 .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq s6.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.s6.term(name) Send a TERM to service via s6 .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq s6.term <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.salt_proxy .sp Salt proxy module .sp New in version 2015.8.3. .sp Module to deploy and manage salt\-proxy processes on a minion. .INDENT 0.0 .TP .B salt.modules.salt_proxy.configure_proxy(proxyname, start=True) Create the salt proxy file and start the proxy process if required .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBproxyname\fP \-\- Name to be used for this proxy (should match entries in pillar) .IP \(bu 2 \fBstart\fP \-\- Boolean indicating if the process should be started default = True .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt deviceminion salt_proxy.configure_proxy p8000 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.salt_proxy.is_running(proxyname) Check if the salt\-proxy process associated with this proxy (name) is running. .sp Returns True if the process is running False otherwise .INDENT 7.0 .TP .B Parameters \fBproxyname\fP \-\- String name of the proxy (p8000 for example) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt deviceminion salt_proxy.is_running p8000 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.salt_version .sp Access Salt\(aqs elemental release code\-names. .sp New in version 3000. .sp Salt\(aqs feature release schedule is based on the Periodic Table, as described in the \fI\%Version Numbers\fP documentation. .sp When a feature was added (or removed) in a specific release, it can be difficult to build out future\-proof functionality that is dependent on a naming scheme that moves. .sp For example, a state syntax needs to change to support an option that will be removed in the future, but there are many Minion versions in use across an infrastructure. It would be handy to use some Jinja syntax to check for these instances to perform one state syntax over another. .sp A simple example might be something like the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {# a boolean check #} {% set option_deprecated = salt[\(aqsalt_version.less_than\(aq](\(dqSodium\(dq) %} {% if option_deprecated %} <use old syntax> {% else %} <use new syntax> {% endif %} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.salt_version.equal(name) Returns a boolean (True) if the minion\(aqs current version code name matches the named version. .INDENT 7.0 .TP .B name The release code name to check the version against. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq salt_version.equal \(aqOxygen\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.salt_version.get_release_number(name) Returns the release number of a given release code name in a \fBMAJOR.PATCH\fP format (for Salt versions < 3000) or \fBMAJOR\fP for newer Salt versions. .sp If the release name has not been given an assigned release number, the function returns a string. If the release cannot be found, it returns \fBNone\fP\&. .INDENT 7.0 .TP .B name The release code name for which to find a release number. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq salt_version.get_release_number \(aqOxygen\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.salt_version.greater_than(name) Returns a boolean (True) if the minion\(aqs current version code name is greater than the named version. .INDENT 7.0 .TP .B name The release code name to check the version against. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq salt_version.greater_than \(aqOxygen\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.salt_version.less_than(name) Returns a boolean (True) if the minion\(aqs current version code name is less than the named version. .INDENT 7.0 .TP .B name The release code name to check the version against. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq salt_version.less_than \(aqOxygen\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.saltcheck .sp A module for testing the logic of states and highstates on salt minions .INDENT 0.0 .TP .B codeauthor William Cannon <\fI\%william.cannon@gmail.com\fP> .TP .B maturity new .UNINDENT .sp Saltcheck provides unittest like functionality requiring only the knowledge of salt module execution and yaml. Saltcheck uses salt modules to return data, then runs an assertion against that return. This allows for testing with all the features included in salt modules. .sp In order to run state and highstate saltcheck tests, a sub\-folder in the state directory must be created and named \fBsaltcheck\-tests\fP\&. Tests for a state should be created in files ending in \fB*.tst\fP and placed in the \fBsaltcheck\-tests\fP folder. \fBtst\fP files are run through the salt rendering system, enabling tests to be written in yaml (or renderer of choice), and include jinja, as well as the usual grain and pillar information. Like states, multiple tests can be specified in a \fBtst\fP file. Multiple \fBtst\fP files can be created in the \fBsaltcheck\-tests\fP folder, and should be named the same as the associated state. The \fBid\fP of a test works in the same manner as in salt state files and should be unique and descriptive. .sp New in version 3000: The \fBsaltcheck\-tests\fP folder can be customized using the \fBsaltcheck_test_location\fP minion configuration setting. This setting is a relative path from the formula\(aqs \fBsalt://\fP path to the test files. .SS Usage .sp Example Default file system layout: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /srv/salt/apache/ init.sls config.sls saltcheck\-tests/ init.tst config.tst deployment_validation.tst .ft P .fi .UNINDENT .UNINDENT .sp Alternative example file system layout with custom saltcheck_test_location: .SS Minion configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C saltcheck_test_location: tests/integration/saltcheck .ft P .fi .UNINDENT .UNINDENT .SS Filesystem layout: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /srv/salt/apache/ init.sls config.sls tests/integration/saltcheck/ init.tst config.tst deployment_validation.tst .ft P .fi .UNINDENT .UNINDENT .sp Tests can be run for each state by name, for all \fBapache/saltcheck/*.tst\fP files, or for all states assigned to the minion in top.sls. Tests may also be created with no associated state. These tests will be run through the use of \fBsaltcheck.run_state_tests\fP, but will not be automatically run by \fBsaltcheck.run_highstate_tests\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltcheck.run_state_tests apache,apache.config salt \(aq*\(aq saltcheck.run_state_tests apache check_all=True salt \(aq*\(aq saltcheck.run_highstate_tests salt \(aq*\(aq saltcheck.run_state_tests apache.deployment_validation .ft P .fi .UNINDENT .UNINDENT .SS Saltcheck Keywords .INDENT 0.0 .TP \fBmodule_and_function:\fP (str) This is the salt module which will be run locally, the same as \fBsalt\-call \-\-local <module>\fP\&. The \fBsaltcheck.state_apply\fP module name is special as it bypasses the local option in order to resolve state names when run in a master/minion environment. .TP \fBargs:\fP (list) Optional arguments passed to the salt module .TP \fBkwargs:\fP (dict) Optional keyword arguments to be passed to the salt module .TP \fBassertion:\fP (str) One of the supported assertions and required except for \fBsaltcheck.state_apply\fP Tests which fail the assertion and expected_return, cause saltcheck to exit which a non\-zero exit code. .TP \fBexpected_return:\fP (str) Required except by \fBassertEmpty\fP, \fBassertNotEmpty\fP, \fBassertTrue\fP, \fBassertFalse\fP\&. The return of module_and_function is compared to this value in the assertion. .TP \fBassertion_section:\fP (str) Optional keyword used to parse the module_and_function return. If a salt module returns a dictionary as a result, the \fBassertion_section\fP value is used to lookup a specific value in that return for the assertion comparison. .TP \fBassertion_section_delimiter:\fP (str) Optional delimiter to use when splitting a nested structure. Defaults to \(aq:\(aq .TP \fBprint_result:\fP (bool) Optional keyword to show results in the \fBassertEqual\fP, \fBassertNotEqual\fP, \fBassertIn\fP, and \fBassertNotIn\fP output. Defaults to True. .TP \fBoutput_details:\fP (bool) Optional keyword to display \fBmodule_and_function\fP, \fBargs\fP, \fBassertion_section\fP, and assertion results text in the output. If print_result is False, assertion results will be hidden. This is a per test setting, but can be set globally for all tests by adding \fBsaltcheck_output_details: True\fP in the minion configuration file. Defaults to False .TP \fBpillar_data:\fP (dict) Optional keyword for passing in pillar data. Intended for use in potential test setup or teardown with the \fBsaltcheck.state_apply\fP function. .TP \fBskip:\fP (bool) Optional keyword to skip running the individual test .UNINDENT .sp New in version 3000: Multiple assertions can be run against the output of a single \fBmodule_and_function\fP call. The \fBassertion\fP, \fBexpected_return\fP, \fBassertion_section\fP, and \fBassertion_section_delimiter\fP keys can be placed in a list under an \fBassertions\fP key. See the multiple assertions example below. .SS Sample Cases/Examples .SS Basic Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C echo_test_hello: module_and_function: test.echo args: \- \(dqhello\(dq kwargs: assertion: assertEqual expected_return: \(aqhello\(aq .ft P .fi .UNINDENT .UNINDENT .SS Example with jinja .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for package in [\(dqapache2\(dq, \(dqopenssh\(dq] %} {# or another example #} {# for package in salt[\(aqpillar.get\(aq](\(dqpackages\(dq) #} test_{{ package }}_latest: module_and_function: pkg.upgrade_available args: \- {{ package }} assertion: assertFalse {% endfor %} .ft P .fi .UNINDENT .UNINDENT .SS Example with setup state including pillar .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C setup_test_environment: module_and_function: saltcheck.state_apply args: \- common pillar_data: data: value verify_vim: module_and_function: pkg.version args: \- vim assertion: assertNotEmpty .ft P .fi .UNINDENT .UNINDENT .SS Example with jinja .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for package in [\(dqapache2\(dq, \(dqopenssh\(dq] %} {# or another example #} {# for package in salt[\(aqpillar.get\(aq](\(dqpackages\(dq) #} test_{{ package }}_latest: module_and_function: pkg.upgrade_available args: \- {{ package }} assertion: assertFalse {% endfor %} .ft P .fi .UNINDENT .UNINDENT .SS Example with setup state including pillar .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C setup_test_environment: module_and_function: saltcheck.state_apply args: \- common pillar\-data: data: value verify_vim: module_and_function: pkg.version args: \- vim assertion: assertNotEmpty .ft P .fi .UNINDENT .UNINDENT .SS Example with skip .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C package_latest: module_and_function: pkg.upgrade_available args: \- apache2 assertion: assertFalse skip: True .ft P .fi .UNINDENT .UNINDENT .SS Example with assertion_section .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C validate_shell: module_and_function: user.info args: \- root assertion: assertEqual expected_return: /bin/bash assertion_section: shell .ft P .fi .UNINDENT .UNINDENT .SS Example with a nested assertion_section .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C validate_smb_signing: module_and_function: lgpo.get args: \- \(aqMachine\(aq kwargs: return_full_policy_names: True assertion: assertEqual expected_return: Enabled assertion_section: \(aqComputer Configuration|Microsoft network client: Digitally sign communications (always)\(aq assertion_section_delimiter: \(aq|\(aq .ft P .fi .UNINDENT .UNINDENT .SS Example suppressing print results .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C validate_env_nameNode: module_and_function: hadoop.dfs args: \- text \- /oozie/common/env.properties expected_return: nameNode = hdfs://nameservice2 assertion: assertNotIn print_result: False .ft P .fi .UNINDENT .UNINDENT .SS Example with multiple assertions and output_details .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C multiple_validations: module_and_function: network.netstat assertions: \- assertion: assertEqual assertion_section: \(dq0:program\(dq expected_return: \(dqsystemd\-resolve\(dq \- assertion: assertEqual assertion_section: \(dq0:proto\(dq expected_return: \(dqudp\(dq output_details: True .ft P .fi .UNINDENT .UNINDENT .SS Supported assertions .INDENT 0.0 .IP \(bu 2 assertEqual .IP \(bu 2 assertNotEqual .IP \(bu 2 assertTrue .IP \(bu 2 assertFalse .IP \(bu 2 assertIn .IP \(bu 2 assertNotIn .IP \(bu 2 assertGreater .IP \(bu 2 assertGreaterEqual .IP \(bu 2 assertLess .IP \(bu 2 assertLessEqual .IP \(bu 2 assertEmpty .IP \(bu 2 assertNotEmpty .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The saltcheck.state_apply function is an alias for \fBstate.apply\fP\&. If using the \fI\%ACL system\fP \fBsaltcheck.*\fP might provide more capability than intended if only \fBsaltcheck.run_state_tests\fP and \fBsaltcheck.run_highstate_tests\fP are needed. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.saltcheck.SaltCheck(saltenv=\(aqbase\(aq) This class validates and runs the saltchecks .INDENT 7.0 .TP .B run_test(test_dict) Run a single saltcheck test .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.saltcheck.StateTestLoader(saltenv=\(aqbase\(aq) Class loads in test files for a state e.g. state_dir/saltcheck\-tests/[1.tst, 2.tst, 3.tst] .INDENT 7.0 .TP .B add_test_files_for_sls(sls_name, check_all=False) Detects states used, caches needed files, and adds to test list .UNINDENT .INDENT 7.0 .TP .B load_test_suite() Load tests either from one file, or a set of files .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltcheck.parallel_scheck(data) triggers salt\-call in parallel .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltcheck.report_highstate_tests(saltenv=None) Report on tests for states assigned to the minion through highstate. Quits with the exit code for the number of missing tests. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltcheck.report_highstate_tests .ft P .fi .UNINDENT .UNINDENT .sp New in version 3000. .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltcheck.run_highstate_tests(saltenv=None, only_fails=False, junit=False) Execute all tests for states assigned to the minion through highstate and return results .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- optional saltenv. Defaults to base .IP \(bu 2 \fBonly_fails\fP (\fI\%bool\fP) \-\- boolean to only print failure results .IP \(bu 2 \fBjunit\fP (\fI\%bool\fP) \-\- boolean to print results in junit format \&.. versionadded:: 3007.0 .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltcheck.run_highstate_tests .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltcheck.run_state_tests(state, saltenv=None, check_all=False, only_fails=False, junit=False) Execute tests for a salt state and return results Nested states will also be tested .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstate\fP (\fI\%str\fP) \-\- state name for which to run associated .tst test files .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- optional saltenv. Defaults to base .IP \(bu 2 \fBcheck_all\fP (\fI\%bool\fP) \-\- boolean to run all tests in state/saltcheck\-tests directory .IP \(bu 2 \fBonly_fails\fP (\fI\%bool\fP) \-\- boolean to only print failure results .IP \(bu 2 \fBjunit\fP (\fI\%bool\fP) \-\- boolean to print results in junit format \&.. versionadded:: 3007.0 .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltcheck.run_state_tests postfix,common .ft P .fi .UNINDENT .UNINDENT .sp Tests will be run in parallel by adding \(dqsaltcheck_parallel: True\(dq in minion config. When enabled, saltcheck will use up to the number of cores detected. This can be limited by setting the \(dqsaltcheck_processes\(dq value to an integer to set the maximum number of parallel processes. .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltcheck.run_state_tests_ssh(state, saltenv=None, check_all=False, only_fails=False, junit=False) This function is an alias of \fBrun_state_tests\fP\&. .INDENT 7.0 .INDENT 3.5 Execute tests for a salt state and return results Nested states will also be tested .INDENT 0.0 .TP .B param str state state name for which to run associated .tst test files .TP .B param str saltenv optional saltenv. Defaults to base .TP .B param bool check_all boolean to run all tests in state/saltcheck\-tests directory .TP .B param bool only_fails boolean to only print failure results .TP .B param bool junit boolean to print results in junit format \&.. versionadded:: 3007.0 .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltcheck.run_state_tests postfix,common .ft P .fi .UNINDENT .UNINDENT .sp Tests will be run in parallel by adding \(dqsaltcheck_parallel: True\(dq in minion config. When enabled, saltcheck will use up to the number of cores detected. This can be limited by setting the \(dqsaltcheck_processes\(dq value to an integer to set the maximum number of parallel processes. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltcheck.run_test(**kwargs) Execute one saltcheck test and return result .INDENT 7.0 .TP .B Parameters \fBtest\fP (\fIkeyword arg\fP) \-\- .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltcheck.run_test test=\(aq{\(dqmodule_and_function\(dq: \(dqtest.echo\(dq, \(dqassertion\(dq: \(dqassertEqual\(dq, \(dqexpected_return\(dq: \(dqThis works!\(dq, \(dqargs\(dq:[\(dqThis works!\(dq] }\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltcheck.state_apply(state_name, **kwargs) Runs \fBstate.apply\fP with given options to set up test data. Intended to be used for optional test setup or teardown .sp Reference the \fBstate.apply\fP module documentation for arguments and usage options .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltcheck.state_apply postfix .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.saltcloudmod .sp Control a salt cloud system .INDENT 0.0 .TP .B salt.modules.saltcloudmod.create(name, profile) Create the named vm .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <minion\-id> saltcloud.create webserver rackspace_centos_512 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.saltutil .sp The Saltutil module is used to manage the state of the salt minion itself. It is used to manage minion modules as well as automate updates to the salt minion. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 esky Python module for update functionality .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.clear_cache() Forcibly removes all caches on a minion. .sp New in version 2014.7.0. .sp WARNING: The safest way to clear a minion cache is by first stopping the minion and then deleting the cache files before restarting it. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.clear_cache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.clear_job_cache(hours=24) Forcibly removes job cache folders and files on a minion. .sp New in version 2018.3.0. .sp WARNING: The safest way to clear a minion cache is by first stopping the minion and then deleting the cache files before restarting it. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.clear_job_cache hours=12 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.cmd(tgt, fun, arg=(), timeout=None, tgt_type=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, ssh=False, **kwargs) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Assuming this minion is a master, execute a salt command .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.cmd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.cmd_iter(tgt, fun, arg=(), timeout=None, tgt_type=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, ssh=False, **kwargs) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Assuming this minion is a master, execute a salt command .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.cmd_iter .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.find_cached_job(jid) Return the data for a specific cached job id. Note this only works if cache_jobs has previously been set to True on the minion. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.find_cached_job <job id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.find_job(jid) Return the data for a specific job id that is currently running. .INDENT 7.0 .TP .B jid The job id to search for and return data. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.find_job <job id> .ft P .fi .UNINDENT .UNINDENT .sp Note that the find_job function only returns job information when the job is still running. If the job is currently running, the output looks something like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # salt my\-minion saltutil.find_job 20160503150049487736 my\-minion: \-\-\-\-\-\-\-\-\-\- arg: \- 30 fun: test.sleep jid: 20160503150049487736 pid: 9601 ret: tgt: my\-minion tgt_type: glob user: root .ft P .fi .UNINDENT .UNINDENT .sp If the job has already completed, the job cannot be found and therefore the function returns an empty dictionary, which looks like this on the CLI: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # salt my\-minion saltutil.find_job 20160503150049487736 my\-minion: \-\-\-\-\-\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.is_running(fun) If the named function is running return the data associated with it/them. The argument can be a glob .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.is_running state.highstate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.kill_all_jobs() Sends a kill signal (SIGKILL 9) to all currently running jobs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.kill_all_jobs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.kill_job(jid) Sends a kill signal (SIGKILL 9) to the named salt job\(aqs process .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.kill_job <job id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.list_extmods() New in version 2017.7.0. .sp List Salt modules which have been synced externally .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.list_extmods .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.mmodule(saltenv, fun, *args, **kwargs) Loads minion modules from an environment so that they can be used in pillars for that environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.mmodule base test.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.pillar_refresh(wait=False, timeout=30, clean_cache=True) This function is an alias of \fBrefresh_pillar\fP\&. .INDENT 7.0 .INDENT 3.5 Signal the minion to refresh the in\-memory pillar data. See \fI\%In\-Memory Pillar Data vs. On\-Demand Pillar Data\fP\&. .INDENT 0.0 .TP .B param wait Wait for pillar refresh to complete, defaults to False. .TP .B type wait bool, optional .TP .B param timeout How long to wait in seconds, only used when wait is True, defaults to 30. .TP .B type timeout int, optional .TP .B param clean_cache Clean the pillar cache, only used when \fIpillar_cache\fP is True. Defaults to True .TP .B type clean_cache bool, optional \&.. versionadded:: 3005 .TP .B return Boolean status, True when the pillar_refresh event was fired successfully. .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.refresh_pillar salt \(aq*\(aq saltutil.refresh_pillar wait=True timeout=60 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.refresh_beacons() Signal the minion to refresh the beacons. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.refresh_beacons .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.refresh_grains(**kwargs) New in version 2016.3.6,2016.11.4,2017.7.0. .sp Refresh the minion\(aqs grains without syncing custom grains modules from \fBsalt://_grains\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The available execution modules will be reloaded as part of this proceess, as grains can affect which modules are available. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B refresh_pillar True Set to \fBFalse\fP to keep pillar data from being refreshed. .TP .B clean_pillar_cache False Set to \fBTrue\fP to refresh pillar cache. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.refresh_grains .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.refresh_matchers() Signal the minion to refresh its matchers. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.refresh_matchers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.refresh_modules(**kwargs) Signal the minion to refresh the module and grain data .sp The default is to refresh module asynchronously. To block until the module refresh is complete, set the \(aqasync\(aq flag to False. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.refresh_modules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.refresh_pillar(wait=False, timeout=30, clean_cache=True) Signal the minion to refresh the in\-memory pillar data. See \fI\%In\-Memory Pillar Data vs. On\-Demand Pillar Data\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBwait\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- Wait for pillar refresh to complete, defaults to False. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP\fI, \fP\fIoptional\fP) \-\- How long to wait in seconds, only used when wait is True, defaults to 30. .IP \(bu 2 \fBclean_cache\fP (\fI\%bool\fP\fI, \fP\fIoptional \&.. versionadded:: 3005\fP) \-\- Clean the pillar cache, only used when \fIpillar_cache\fP is True. Defaults to True .UNINDENT .TP .B Returns Boolean status, True when the pillar_refresh event was fired successfully. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.refresh_pillar salt \(aq*\(aq saltutil.refresh_pillar wait=True timeout=60 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.regen_keys() Used to regenerate the minion keys. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.regen_keys .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.revoke_auth(preserve_minion_cache=False) The minion sends a request to the master to revoke its own key. Note that the minion session will be revoked and the minion may not be able to return the result of this command back to the master. .sp If the \(aqpreserve_minion_cache\(aq flag is set to True, the master cache for this minion will not be removed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.revoke_auth .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.runner(name, arg=None, kwarg=None, full_return=False, saltenv=\(aqbase\(aq, jid=None, **kwargs) Execute a runner function. This function must be run on the master, either by targeting a minion running on a master or by using salt\-call on a master. .sp New in version 2014.7.0. .INDENT 7.0 .TP .B name The name of the function to run .TP .B kwargs Any keyword arguments to pass to the runner function .UNINDENT .sp CLI Example: .sp In this example, assume that \fImaster_minion\fP is a minion running on a master. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt master_minion saltutil.runner jobs.list_jobs salt master_minion saltutil.runner test.arg arg=\(dq[\(aqbaz\(aq]\(dq kwarg=\(dq{\(aqfoo\(aq: \(aqbar\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.running() Return the data on all running salt processes on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.running .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.signal_job(jid, sig) Sends a signal to the named salt job\(aqs process .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.signal_job <job id> 15 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_all(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None, clean_pillar_cache=False) Changed in version 3007.0: On masterless minions, master top modules are now synced as well. When \fBrefresh\fP is set to \fBTrue\fP, this module\(aqs cache containing the environments from which extension modules are synced when \fBsaltenv\fP is not specified will be refreshed. .sp Changed in version 2015.8.11,2016.3.2: On masterless minions, pillar modules are now synced, and refreshed when \fBrefresh\fP is set to \fBTrue\fP\&. .sp Sync down all of the dynamic modules from the file server for a specific environment. This function synchronizes custom modules, states, beacons, grains, returners, output modules, renderers, and utils. .INDENT 7.0 .TP .B refresh True Also refresh the execution modules and recompile pillar data available to the minion. If this is a masterless minion, also refresh the environments from which extension modules are synced after syncing master tops. This refresh will be performed even if no new dynamic modules are synced. Set to \fBFalse\fP to prevent this refresh. .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 If this function is executed using a \fI\%module.run\fP state, the SLS file will not have access to newly synced execution modules unless a \fBrefresh\fP argument is added to the state, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load_my_custom_module: module.run: \- name: saltutil.sync_all \- refresh: True .ft P .fi .UNINDENT .UNINDENT .sp See \fI\%here\fP for a more detailed explanation of why this is necessary. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B extmod_whitelist None dictionary of modules to sync based on type .TP .B extmod_blacklist None dictionary of modules to blacklist based on type .TP .B clean_pillar_cache False Set to \fBTrue\fP to refresh pillar cache. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_all salt \(aq*\(aq saltutil.sync_all saltenv=dev salt \(aq*\(aq saltutil.sync_all saltenv=base,dev salt \(aq*\(aq saltutil.sync_all extmod_whitelist={\(aqmodules\(aq: [\(aqcustom_module\(aq]} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_beacons(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 2015.5.1. .sp Sync beacons from \fBsalt://_beacons\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for beacons to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available beacons on the minion. This refresh will be performed even if no new beacons are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_beacons salt \(aq*\(aq saltutil.sync_beacons saltenv=dev salt \(aq*\(aq saltutil.sync_beacons saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_clouds(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 2017.7.0. .sp Sync cloud modules from \fBsalt://_cloud\fP to the minion .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new utility modules are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_clouds salt \(aq*\(aq saltutil.sync_clouds saltenv=dev salt \(aq*\(aq saltutil.sync_clouds saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_engines(saltenv=None, refresh=False, extmod_whitelist=None, extmod_blacklist=None) New in version 2016.3.0. .sp Sync engine modules from \fBsalt://_engines\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for engines to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new engine modules are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_engines salt \(aq*\(aq saltutil.sync_engines saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_executors(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 3000. .sp Sync executors from \fBsalt://_executors\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for log handlers to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new log handlers are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-seperated list of modules to sync .TP .B extmod_blacklist None comma\-seperated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_executors salt \(aq*\(aq saltutil.sync_executors saltenv=dev salt \(aq*\(aq saltutil.sync_executors saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_grains(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None, clean_pillar_cache=False) New in version 0.10.0. .sp Sync grains modules from \fBsalt://_grains\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for grains modules to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules and recompile pillar data for the minion. This refresh will be performed even if no new grains modules are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .TP .B clean_pillar_cache False Set to \fBTrue\fP to refresh pillar cache. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_grains salt \(aq*\(aq saltutil.sync_grains saltenv=dev salt \(aq*\(aq saltutil.sync_grains saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_log_handlers(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 2015.8.0. .sp Sync log handlers from \fBsalt://_log_handlers\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for log handlers to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new log handlers are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_log_handlers salt \(aq*\(aq saltutil.sync_log_handlers saltenv=dev salt \(aq*\(aq saltutil.sync_log_handlers saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_matchers(saltenv=None, refresh=False, extmod_whitelist=None, extmod_blacklist=None) New in version 2019.2.0. .sp Sync engine modules from \fBsalt://_matchers\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for engines to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new matcher modules are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_matchers salt \(aq*\(aq saltutil.sync_matchers saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_modules(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 0.10.0. .sp Sync execution modules from \fBsalt://_modules\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for execution modules to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new execution modules are synced. Set to \fBFalse\fP to prevent this refresh. .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 If this function is executed using a \fI\%module.run\fP state, the SLS file will not have access to newly synced execution modules unless a \fBrefresh\fP argument is added to the state, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load_my_custom_module: module.run: \- name: saltutil.sync_modules \- refresh: True .ft P .fi .UNINDENT .UNINDENT .sp See \fI\%here\fP for a more detailed explanation of why this is necessary. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_modules salt \(aq*\(aq saltutil.sync_modules saltenv=dev salt \(aq*\(aq saltutil.sync_modules saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_output(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) Sync outputters from \fBsalt://_output\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for outputters to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new outputters are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_output salt \(aq*\(aq saltutil.sync_output saltenv=dev salt \(aq*\(aq saltutil.sync_output saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_outputters(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) This function is an alias of \fBsync_output\fP\&. .INDENT 7.0 .INDENT 3.5 Sync outputters from \fBsalt://_output\fP to the minion .INDENT 0.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for outputters to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new outputters are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_output salt \(aq*\(aq saltutil.sync_output saltenv=dev salt \(aq*\(aq saltutil.sync_output saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_pillar(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None, clean_pillar_cache=False) New in version 2015.8.11,2016.3.2. .sp Sync pillar modules from the \fBsalt://_pillar\fP directory on the Salt fileserver. This function is environment\-aware, pass the desired environment to grab the contents of the \fB_pillar\fP directory from that environment. The default environment, if none is specified, is \fBbase\fP\&. .INDENT 7.0 .TP .B refresh True Also refresh the execution modules available to the minion, and refresh pillar data. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .TP .B clean_pillar_cache False Set to \fBTrue\fP to refresh pillar cache. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function will raise an error if executed on a traditional (i.e. not masterless) minion .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_pillar salt \(aq*\(aq saltutil.sync_pillar saltenv=dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_proxymodules(saltenv=None, refresh=False, extmod_whitelist=None, extmod_blacklist=None) New in version 2015.8.2. .sp Sync proxy modules from \fBsalt://_proxy\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for proxy modules to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new proxy modules are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_proxymodules salt \(aq*\(aq saltutil.sync_proxymodules saltenv=dev salt \(aq*\(aq saltutil.sync_proxymodules saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_renderers(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 0.10.0. .sp Sync renderers from \fBsalt://_renderers\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for renderers to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new renderers are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_renderers salt \(aq*\(aq saltutil.sync_renderers saltenv=dev salt \(aq*\(aq saltutil.sync_renderers saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_returners(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 0.10.0. .sp Sync returners from \fBsalt://_returners\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for returners to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new returners are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_returners salt \(aq*\(aq saltutil.sync_returners saltenv=dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_sdb(saltenv=None, extmod_whitelist=None, extmod_blacklist=None) New in version 2015.5.8,2015.8.3. .sp Sync sdb modules from \fBsalt://_sdb\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for sdb modules to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_sdb salt \(aq*\(aq saltutil.sync_sdb saltenv=dev salt \(aq*\(aq saltutil.sync_sdb saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_serializers(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 2019.2.0. .sp Sync serializers from \fBsalt://_serializers\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for serializer modules to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new serializer modules are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-seperated list of modules to sync .TP .B extmod_blacklist None comma\-seperated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_serializers salt \(aq*\(aq saltutil.sync_serializers saltenv=dev salt \(aq*\(aq saltutil.sync_serializers saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_states(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 0.10.0. .sp Sync state modules from \fBsalt://_states\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for state modules to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available states on the minion. This refresh will be performed even if no new state modules are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_states salt \(aq*\(aq saltutil.sync_states saltenv=dev salt \(aq*\(aq saltutil.sync_states saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_thorium(saltenv=None, refresh=False, extmod_whitelist=None, extmod_blacklist=None) New in version 2018.3.0. .sp Sync Thorium modules from \fBsalt://_thorium\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for engines to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh: \fBTrue\fP If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new Thorium modules are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist comma\-separated list of modules to sync .TP .B extmod_blacklist comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_thorium salt \(aq*\(aq saltutil.sync_thorium saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_tops(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 3007.0. .sp Sync master tops from \fBsalt://_tops\fP to the minion. .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for master tops to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True Refresh this module\(aqs cache containing the environments from which extension modules are synced when \fBsaltenv\fP is not specified. This refresh will be performed even if no new master tops are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function will raise an error if executed on a traditional (i.e. not masterless) minion .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_tops salt \(aq*\(aq saltutil.sync_tops saltenv=dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_utils(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 2014.7.0. .sp Sync utility modules from \fBsalt://_utils\fP to the minion .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for utility modules to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new utility modules are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_utils salt \(aq*\(aq saltutil.sync_utils saltenv=dev salt \(aq*\(aq saltutil.sync_utils saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_wrapper(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 3007.0. .sp Sync salt\-ssh wrapper modules from \fBsalt://_wrapper\fP to the minion. .INDENT 7.0 .TP .B saltenv The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .sp If not passed, then all environments configured in the \fI\%top files\fP will be checked for wrappers to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP .B refresh True If \fBTrue\fP, refresh the available wrapper modules on the minion. This refresh will be performed even if no wrappers are synced. Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None comma\-seperated list of modules to sync .TP .B extmod_blacklist None comma\-seperated list of modules to blacklist based on type .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function will raise an error if executed on a traditional (i.e. not masterless) minion. .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_wrapper salt \(aq*\(aq saltutil.sync_wrapper saltenv=dev salt \(aq*\(aq saltutil.sync_wrapper saltenv=base,dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.term_all_jobs() Sends a termination signal (SIGTERM 15) to all currently running jobs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.term_all_jobs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.term_job(jid) Sends a termination signal (SIGTERM 15) to the named salt job\(aqs process .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.term_job <job id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.update(version=None) Update the salt minion from the URL defined in opts[\(aqupdate_url\(aq] VMware, Inc provides the latest builds here: update_url: \fI\%https://repo.saltproject.io/windows/\fP .sp Be aware that as of 2014\-8\-11 there\(aqs a bug in esky such that only the latest version available in the update_url can be downloaded and installed. .sp This feature requires the minion to be running a bdist_esky build. .sp The version number is optional and will default to the most recent version available at opts[\(aqupdate_url\(aq]. .sp Returns details about the transaction upon completion. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.update salt \(aq*\(aq saltutil.update 0.10.3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.wheel(name, *args, **kwargs) Execute a wheel module and function. This function must be run against a minion that is local to the master. .sp New in version 2014.7.0. .INDENT 7.0 .TP .B name The name of the function to run .TP .B args Any positional arguments to pass to the wheel function. A common example of this would be the \fBmatch\fP arg needed for key functions. .sp New in version 2015.8.11. .TP .B kwargs Any keyword arguments to pass to the wheel function .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt my\-local\-minion saltutil.wheel key.accept jerry salt my\-local\-minion saltutil.wheel minions.connected .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Since this function must be run against a minion that is running locally on the master in order to get accurate returns, if this function is run against minions that are not local to the master, \(dqempty\(dq returns are expected. The remote minion does not have access to wheel functions and their return data. .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.schedule .sp Module for managing the Salt schedule on a minion .sp Requires that python\-dateutil is installed on the minion. .sp New in version 2014.7.0. .INDENT 0.0 .TP .B salt.modules.schedule.add(name, **kwargs) Add a job to the schedule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.add job1 function=\(aqtest.ping\(aq seconds=3600 # If function have some arguments, use job_args salt \(aq*\(aq schedule.add job2 function=\(aqcmd.run\(aq job_args=\(dq[\(aqdate >> /tmp/date.log\(aq]\(dq seconds=60 # Add job to Salt minion when the Salt minion is not running salt \(aq*\(aq schedule.add job1 function=\(aqtest.ping\(aq seconds=3600 offline=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.build_schedule_item(name, **kwargs) Build a schedule job .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.build_schedule_item job1 function=\(aqtest.ping\(aq seconds=3600 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.copy(name, target, **kwargs) Copy scheduled job to another minion or minions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.copy jobname target .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.delete(name, **kwargs) Delete a job from the minion\(aqs schedule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.delete job1 # Delete job on Salt minion when the Salt minion is not running salt \(aq*\(aq schedule.delete job1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.disable(**kwargs) Disable all scheduled jobs on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.disable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.disable_job(name, **kwargs) Disable a job in the minion\(aqs schedule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.disable_job job1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.enable(**kwargs) Enable all scheduled jobs on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.enable_job(name, **kwargs) Enable a job in the minion\(aqs schedule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.enable_job job1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.is_enabled(name=None) List a Job only if its enabled .sp If job is not specified, indicate if the scheduler is enabled or disabled. .sp New in version 2015.5.3. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.is_enabled name=job_name salt \(aq*\(aq schedule.is_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.job_status(name, time_fmt=\(aq%Y\-%m\-%dT%H:%M:%S\(aq) Show the information for a particular job. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.job_status job_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.list_(show_all=False, show_disabled=True, where=None, return_yaml=True, offline=False) List the jobs currently scheduled on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.list # Show all jobs including hidden internal jobs salt \(aq*\(aq schedule.list show_all=True # Hide disabled jobs from list of jobs salt \(aq*\(aq schedule.list show_disabled=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.modify(name, **kwargs) Modify an existing job in the schedule .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.modify job1 function=\(aqtest.ping\(aq seconds=3600 # Modify job on Salt minion when the Salt minion is not running salt \(aq*\(aq schedule.modify job1 function=\(aqtest.ping\(aq seconds=3600 offline=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.move(name, target, **kwargs) Move scheduled job to another minion or minions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.move jobname target .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.postpone_job(name, current_time, new_time, **kwargs) Postpone a job in the minion\(aqs schedule .sp Current time and new time should be in date string format, default value is %Y\-%m\-%dT%H:%M:%S. .sp New in version 2018.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.postpone_job job current_time new_time salt \(aq*\(aq schedule.postpone_job job current_time new_time time_fmt=\(aq%Y\-%m\-%dT%H:%M:%S\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.purge(**kwargs) Purge all the jobs currently scheduled on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.purge # Purge jobs on Salt minion salt \(aq*\(aq schedule.purge .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.reload_() Reload saved scheduled jobs on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.reload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.run_job(name, force=False) Run a scheduled job on the minion immediately .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.run_job job1 salt \(aq*\(aq schedule.run_job job1 force=True Force the job to run even if it is disabled. .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.save(**kwargs) Save all scheduled jobs on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.save .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.show_next_fire_time(name, **kwargs) Show the next fire time for scheduled job .sp New in version 2018.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.show_next_fire_time job_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.schedule.skip_job(name, current_time, **kwargs) Skip a job in the minion\(aqs schedule at specified time. .sp Time to skip should be specified as date string format, default value is %Y\-%m\-%dT%H:%M:%S. .sp New in version 2018.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq schedule.skip_job job time .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.scp .SS SCP Module .sp New in version 2019.2.0. .sp Module to copy files via \fI\%SCP\fP .INDENT 0.0 .TP .B salt.modules.scp_mod.get(remote_path, local_path=\(aq\(aq, recursive=False, preserve_times=False, **kwargs) Transfer files and directories from remote host to the localhost of the Minion. .INDENT 7.0 .TP .B remote_path Path to retrieve from remote host. Since this is evaluated by scp on the remote host, shell wildcards and environment variables may be used. .TP .B recursive: \fBFalse\fP Transfer files and directories recursively. .TP .B preserve_times: \fBFalse\fP Preserve \fBmtime\fP and \fBatime\fP of transferred files and directories. .TP .B hostname The hostname of the remote device. .TP .B port: \fB22\fP The port of the remote device. .TP .B username The username required for SSH authentication on the device. .TP .B password Used for password authentication. It is also used for private key decryption if \fBpassphrase\fP is not given. .TP .B passphrase Used for decrypting private keys. .TP .B pkey An optional private key to use for authentication. .TP .B key_filename The filename, or list of filenames, of optional private key(s) and/or certificates to try for authentication. .TP .B timeout An optional timeout (in seconds) for the TCP connect. .TP .B socket_timeout: \fB10\fP The channel socket timeout in seconds. .TP .B buff_size: \fB16384\fP The size of the SCP send buffer. .TP .B allow_agent: \fBTrue\fP Set to \fBFalse\fP to disable connecting to the SSH agent. .TP .B look_for_keys: \fBTrue\fP Set to \fBFalse\fP to disable searching for discoverable private key files in \fB~/.ssh/\fP .TP .B banner_timeout An optional timeout (in seconds) to wait for the SSH banner to be presented. .TP .B auth_timeout An optional timeout (in seconds) to wait for an authentication response. .TP .B auto_add_policy: \fBFalse\fP Automatically add the host to the \fBknown_hosts\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq scp.get /var/tmp/file /tmp/file hostname=10.10.10.1 auto_add_policy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.scp_mod.put(files, remote_path=None, recursive=False, preserve_times=False, saltenv=\(aqbase\(aq, **kwargs) Transfer files and directories to remote host. .INDENT 7.0 .TP .B files A single path or a list of paths to be transferred. .TP .B remote_path The path on the remote device where to store the files. .TP .B recursive: \fBTrue\fP Transfer files and directories recursively. .TP .B preserve_times: \fBFalse\fP Preserve \fBmtime\fP and \fBatime\fP of transferred files and directories. .TP .B hostname The hostname of the remote device. .TP .B port: \fB22\fP The port of the remote device. .TP .B username The username required for SSH authentication on the device. .TP .B password Used for password authentication. It is also used for private key decryption if \fBpassphrase\fP is not given. .TP .B passphrase Used for decrypting private keys. .TP .B pkey An optional private key to use for authentication. .TP .B key_filename The filename, or list of filenames, of optional private key(s) and/or certificates to try for authentication. .TP .B timeout An optional timeout (in seconds) for the TCP connect. .TP .B socket_timeout: \fB10\fP The channel socket timeout in seconds. .TP .B buff_size: \fB16384\fP The size of the SCP send buffer. .TP .B allow_agent: \fBTrue\fP Set to \fBFalse\fP to disable connecting to the SSH agent. .TP .B look_for_keys: \fBTrue\fP Set to \fBFalse\fP to disable searching for discoverable private key files in \fB~/.ssh/\fP .TP .B banner_timeout An optional timeout (in seconds) to wait for the SSH banner to be presented. .TP .B auth_timeout An optional timeout (in seconds) to wait for an authentication response. .TP .B auto_add_policy: \fBFalse\fP Automatically add the host to the \fBknown_hosts\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq scp.put /path/to/file /var/tmp/file hostname=server1 auto_add_policy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.scsi .sp SCSI administration module .INDENT 0.0 .TP .B salt.modules.scsi.ls_(get_size=True) List SCSI devices, with details .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq scsi.ls salt \(aq*\(aq scsi.ls get_size=False .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get_size True Get the size information for scsi devices. This option should be set to False for older OS distributions (RHEL6 and older) due to lack of support for the \(aq\-s\(aq option in lsscsi. .sp New in version 2015.5.10. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.scsi.rescan_all(host) List scsi devices .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq scsi.rescan_all 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.sdb .SS Module for Manipulating Data via the Salt DB API .INDENT 0.0 .TP .B salt.modules.sdb.delete(uri) Delete a value from a db, using a uri in the form of \fBsdb://<profile>/<key>\fP\&. If the uri provided does not start with \fBsdb://\fP or the value is not successfully deleted, return \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sdb.delete sdb://mymemcached/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sdb.get(uri, strict=False) Get a value from a db, using a uri in the form of \fBsdb://<profile>/<key>\fP\&. If the uri provided is not valid, then it will be returned as\-is, unless \fBstrict=True\fP was passed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sdb.get sdb://mymemcached/foo strict=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sdb.get_or_set_hash(uri, length=8, chars=\(aqabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(\-_=+)\(aq) Perform a one\-time generation of a hash and write it to sdb. If that value has already been set return the value instead. .sp This is useful for generating passwords or keys that are specific to multiple minions that need to be stored somewhere centrally. .sp State Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C some_mysql_user: mysql_user: \- present \- host: localhost \- password: \(aq{{ salt[\(dqsdb.get_or_set_hash\(dq](\(dqsdb://mymemcached/some_user_pass\(dq) }}\(aq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sdb.get_or_set_hash \(aqsdb://mymemcached/SECRET_KEY\(aq 50 .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This function could return strings which may contain characters which are reserved as directives by the YAML parser, such as strings beginning with \fB%\fP\&. To avoid issues when using the output of this function in an SLS file containing YAML+Jinja, surround the call with single quotes. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sdb.set_(uri, value) Set a value in a db, using a uri in the form of \fBsdb://<profile>/<key>\fP\&. If the uri provided does not start with \fBsdb://\fP or the value is not successfully set, return \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sdb.set sdb://mymemcached/foo bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.seed .sp Virtual machine image management tools .INDENT 0.0 .TP .B salt.modules.seed.apply_(path, id_=None, config=None, approve_key=True, install=True, prep_install=False, pub_key=None, priv_key=None, mount_point=None) Seed a location (disk image, directory, or block device) with the minion config, approve the minion\(aqs key, and/or install salt\-minion. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq seed.apply path id [config=config_data] \e [gen_key=(true|false)] [approve_key=(true|false)] \e [install=(true|false)] .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path Full path to the directory, device, or disk image on the target minion\(aqs file system. .TP .B id Minion id with which to seed the path. .TP .B config Minion configuration options. By default, the \(aqmaster\(aq option is set to the target host\(aqs \(aqmaster\(aq. .TP .B approve_key Request a pre\-approval of the generated minion key. Requires that the salt\-master be configured to either auto\-accept all keys or expect a signing request from the target host. Default: true. .TP .B install Install salt\-minion, if absent. Default: true. .TP .B prep_install Prepare the bootstrap script, but don\(aqt run it. Default: false .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.seed.mkconfig(config=None, tmp=None, id_=None, approve_key=True, pub_key=None, priv_key=None) Generate keys and config and put them in a tmp directory. .INDENT 7.0 .TP .B pub_key absolute path or file content of an optional preseeded salt key .TP .B priv_key absolute path or file content of an optional preseeded salt key .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq seed.mkconfig [config=config_data] [tmp=tmp_dir] \e [id_=minion_id] [approve_key=(true|false)] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.seed.prep_bootstrap(mpt) Update and get the random script to a random place .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq seed.prep_bootstrap /tmp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.selinux .sp Execute calls on selinux .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This module requires the \fBsemanage\fP, \fBsetsebool\fP, and \fBsemodule\fP commands to be available on the minion. On RHEL\-based distributions, ensure that the \fBpolicycoreutils\fP and \fBpolicycoreutils\-python\fP packages are installed. If not on a Fedora or RHEL\-based distribution, consult the selinux documentation for your distribution to ensure that the proper packages are installed. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.fcontext_add_policy(name, filetype=None, sel_type=None, sel_user=None, sel_level=None) New in version 2019.2.0. .sp Adds the SELinux policy for a given filespec and other optional parameters. .sp Returns the result of the call to semanage. .sp Note that you don\(aqt have to remove an entry before setting a new one for a given filespec and filetype, as adding one with semanage automatically overwrites a previously configured SELinux context. .INDENT 7.0 .TP .B name filespec of the file or directory. Regex syntax is allowed. .TP .B file_type The SELinux filetype specification. Use one of [a, f, d, c, b, s, l, p]. See also \fBman semanage\-fcontext\fP\&. Defaults to \(aqa\(aq (all files). .TP .B sel_type SELinux context type. There are many. .TP .B sel_user SELinux user. Use \fBsemanage login \-l\fP to determine which ones are available to you. .TP .B sel_level The MLS range of the SELinux context. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.fcontext_add_policy my\-policy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.fcontext_apply_policy(name, recursive=False) New in version 2017.7.0. .sp Applies SElinux policies to filespec using \fIrestorecon [\-R] filespec\fP\&. Returns dict with changes if successful, the output of the restorecon command otherwise. .INDENT 7.0 .TP .B name filespec of the file or directory. Regex syntax is allowed. .TP .B recursive Recursively apply SELinux policies. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.fcontext_apply_policy my\-policy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.fcontext_delete_policy(name, filetype=None, sel_type=None, sel_user=None, sel_level=None) New in version 2019.2.0. .sp Deletes the SELinux policy for a given filespec and other optional parameters. .sp Returns the result of the call to semanage. .sp Note that you don\(aqt have to remove an entry before setting a new one for a given filespec and filetype, as adding one with semanage automatically overwrites a previously configured SELinux context. .INDENT 7.0 .TP .B name filespec of the file or directory. Regex syntax is allowed. .TP .B file_type The SELinux filetype specification. Use one of [a, f, d, c, b, s, l, p]. See also \fBman semanage\-fcontext\fP\&. Defaults to \(aqa\(aq (all files). .TP .B sel_type SELinux context type. There are many. .TP .B sel_user SELinux user. Use \fBsemanage login \-l\fP to determine which ones are available to you. .TP .B sel_level The MLS range of the SELinux context. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.fcontext_delete_policy my\-policy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.fcontext_get_policy(name, filetype=None, sel_type=None, sel_user=None, sel_level=None) New in version 2017.7.0. .sp Returns the current entry in the SELinux policy list as a dictionary. Returns None if no exact match was found. .sp Returned keys are: .INDENT 7.0 .IP \(bu 2 filespec (the name supplied and matched) .IP \(bu 2 filetype (the descriptive name of the filetype supplied) .IP \(bu 2 sel_user, sel_role, sel_type, sel_level (the selinux context) .UNINDENT .sp For a more in\-depth explanation of the selinux context, go to \fI\%https://access.redhat.com/documentation/en\-US/Red_Hat_Enterprise_Linux/6/html/Security\-Enhanced_Linux/chap\-Security\-Enhanced_Linux\-SELinux_Contexts.html\fP .INDENT 7.0 .TP .B name filespec of the file or directory. Regex syntax is allowed. .TP .B filetype The SELinux filetype specification. Use one of [a, f, d, c, b, s, l, p]. See also \fIman semanage\-fcontext\fP\&. Defaults to \(aqa\(aq (all files). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.fcontext_get_policy my\-policy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.fcontext_policy_is_applied(name, recursive=False) New in version 2017.7.0. .sp Returns an empty string if the SELinux policy for a given filespec is applied, returns string with differences in policy and actual situation otherwise. .INDENT 7.0 .TP .B name filespec of the file or directory. Regex syntax is allowed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.fcontext_policy_is_applied my\-policy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.filetype_id_to_string(filetype=\(aqa\(aq) New in version 2017.7.0. .sp Translates SELinux filetype single\-letter representation to a more human\-readable version (which is also used in \fIsemanage fcontext \-l\fP). .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.getconfig() Return the selinux mode from the config file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.getconfig .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.getenforce() Return the mode selinux is running in .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.getenforce .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.getsebool(boolean) Return the information on a specific selinux boolean .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.getsebool virt_use_usb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.getsemod(module) Return the information on a specific selinux module .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.getsemod mysql .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.install_semod(module_path) Install custom SELinux module from file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.install_semod [salt://]path/to/module.pp .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.6. .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.list_sebool() Return a structure listing all of the selinux booleans on the system and what state they are in .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.list_sebool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.list_semod() Return a structure listing all of the selinux modules on the system and what state they are in .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.list_semod .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.port_add_policy(name, sel_type=None, protocol=None, port=None, sel_range=None) New in version 2019.2.0. .sp Adds the SELinux policy for a given protocol and port. .sp Returns the result of the call to semanage. .INDENT 7.0 .TP .B name The protocol and port spec. Can be formatted as \fB(tcp|udp)/(port|port\-range)\fP\&. .TP .B sel_type The SELinux Type. Required. .TP .B protocol The protocol for the port, \fBtcp\fP or \fBudp\fP\&. Required if name is not formatted. .TP .B port The port or port range. Required if name is not formatted. .TP .B sel_range The SELinux MLS/MCS Security Range. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.port_add_policy tcp/8080 http_port_t salt \(aq*\(aq selinux.port_add_policy foobar http_port_t protocol=tcp port=8091 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.port_delete_policy(name, protocol=None, port=None) New in version 2019.2.0. .sp Deletes the SELinux policy for a given protocol and port. .sp Returns the result of the call to semanage. .INDENT 7.0 .TP .B name The protocol and port spec. Can be formatted as \fB(tcp|udp)/(port|port\-range)\fP\&. .TP .B protocol The protocol for the port, \fBtcp\fP or \fBudp\fP\&. Required if name is not formatted. .TP .B port The port or port range. Required if name is not formatted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.port_delete_policy tcp/8080 salt \(aq*\(aq selinux.port_delete_policy foobar protocol=tcp port=8091 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.port_get_policy(name, sel_type=None, protocol=None, port=None) New in version 2019.2.0. .sp Returns the current entry in the SELinux policy list as a dictionary. Returns None if no exact match was found. .sp Returned keys are: .INDENT 7.0 .IP \(bu 2 sel_type (the selinux type) .IP \(bu 2 proto (the protocol) .IP \(bu 2 port (the port(s) and/or port range(s)) .UNINDENT .INDENT 7.0 .TP .B name The protocol and port spec. Can be formatted as \fB(tcp|udp)/(port|port\-range)\fP\&. .TP .B sel_type The SELinux Type. .TP .B protocol The protocol for the port, \fBtcp\fP or \fBudp\fP\&. Required if name is not formatted. .TP .B port The port or port range. Required if name is not formatted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.port_get_policy tcp/80 salt \(aq*\(aq selinux.port_get_policy foobar protocol=tcp port=80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.port_modify_policy(name, sel_type=None, protocol=None, port=None, sel_range=None) New in version 2019.2.0. .sp Modifies the SELinux policy for a given protocol and port. .sp Returns the result of the call to semanage. .INDENT 7.0 .TP .B name The protocol and port spec. Can be formatted as \fB(tcp|udp)/(port|port\-range)\fP\&. .TP .B sel_type The SELinux Type. Required. .TP .B protocol The protocol for the port, \fBtcp\fP or \fBudp\fP\&. Required if name is not formatted. .TP .B port The port or port range. Required if name is not formatted. .TP .B sel_range The SELinux MLS/MCS Security Range. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.port_modify_policy tcp/8080 http_port_t salt \(aq*\(aq selinux.port_modify_policy foobar http_port_t protocol=tcp port=8091 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.remove_semod(module) Remove SELinux module .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.remove_semod module_name .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.6. .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.selinux_fs_path() Return the location of the SELinux VFS directory .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.selinux_fs_path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.setenforce(mode) Set the SELinux enforcing mode .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.setenforce enforcing .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.setsebool(boolean, value, persist=False) Set the value for a boolean .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.setsebool virt_use_usb off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.setsebools(pairs, persist=False) Set the value of multiple booleans .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.setsebools \(aq{virt_use_usb: on, squid_use_tproxy: off}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.setsemod(module, state) Enable or disable an SELinux module. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq selinux.setsemod nagios Enabled .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .UNINDENT .SS salt.modules.sensehat .sp Module for controlling the LED matrix or reading environment data on 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>, Joachim Werner <\fI\%joe@suse.com\fP> .TP .B maturity new .TP .B depends sense_hat Python module .UNINDENT .sp The rotation of the Pi can be specified in a pillar. This is useful if the Pi is used upside down or sideways to correct the orientation of the image being shown. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sensehat: rotation: 90 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.clear(color=None) Sets the LED matrix to a single color or turns all LEDs off. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqraspberry\(aq sensehat.clear salt \(aqraspberry\(aq sensehat.clear \(aq[255, 0, 0]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.get_humidity() Get the percentage of relative humidity from the humidity sensor. .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.get_pixel(x, y) Returns the color of a single pixel on the LED matrix. .INDENT 7.0 .TP .B x The x coordinate of the pixel. Ranges from 0 on the left to 7 on the right. .TP .B y The y coordinate of the pixel. Ranges from 0 at the top to 7 at the bottom. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Please read the note for \fBget_pixels\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.get_pixels() Returns a list of 64 smaller lists of \fB[R, G, B]\fP pixels representing the the currently displayed image on the LED matrix. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When using \fBset_pixels\fP the pixel values can sometimes change when you read them again using \fBget_pixels\fP\&. This is because we specify each pixel element as 8 bit numbers (0 to 255) but when they\(aqre passed into the Linux frame buffer for the LED matrix the numbers are bit shifted down to fit into RGB 565. 5 bits for red, 6 bits for green and 5 bits for blue. The loss of binary precision when performing this conversion (3 bits lost for red, 2 for green and 3 for blue) accounts for the discrepancies you see. .sp The \fBget_pixels\fP method provides an accurate representation of how the pixels end up in frame buffer memory after you have called \fBset_pixels\fP\&. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.get_pressure() Gets the current pressure in Millibars from the pressure sensor. .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.get_temperature() Gets the temperature in degrees Celsius from the humidity sensor. Equivalent to calling \fBget_temperature_from_humidity\fP\&. .sp If you get strange results try using \fBget_temperature_from_pressure\fP\&. .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.get_temperature_from_humidity() Gets the temperature in degrees Celsius from the humidity sensor. .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.get_temperature_from_pressure() Gets the temperature in degrees Celsius from the pressure sensor. .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.low_light(low_light=True) Sets the LED matrix to low light mode. Useful in a dark environment. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqraspberry\(aq sensehat.low_light salt \(aqraspberry\(aq sensehat.low_light False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.set_pixel(x, y, color) Sets a single pixel on the LED matrix to a specified color. .INDENT 7.0 .TP .B x The x coordinate of the pixel. Ranges from 0 on the left to 7 on the right. .TP .B y The y coordinate of the pixel. Ranges from 0 at the top to 7 at the bottom. .TP .B color The new color of the pixel as a list of \fB[R, G, B]\fP values. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqraspberry\(aq sensehat.set_pixel 0 0 \(aq[255, 0, 0]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.set_pixels(pixels) Sets the entire LED matrix based on a list of 64 pixel values .INDENT 7.0 .TP .B pixels A list of 64 \fB[R, G, B]\fP color values. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.show_image(image) Displays an 8 x 8 image on the LED matrix. .INDENT 7.0 .TP .B image The path to the image to display. The image must be 8 x 8 pixels in size. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqraspberry\(aq sensehat.show_image /tmp/my_image.png .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.show_letter(letter, text_color=None, back_color=None) Displays a single letter on the LED matrix. .INDENT 7.0 .TP .B letter The letter to display .TP .B text_color The color in which the letter is shown. Defaults to \(aq[255, 255, 255]\(aq (white). .TP .B back_color The background color of the display. Defaults to \(aq[0, 0, 0]\(aq (black). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqraspberry\(aq sensehat.show_letter O salt \(aqraspberry\(aq sensehat.show_letter X \(aq[255, 0, 0]\(aq salt \(aqraspberry\(aq sensehat.show_letter B \(aq[0, 0, 255]\(aq \(aq[255, 255, 0]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sensehat.show_message(message, msg_type=None, text_color=None, back_color=None, scroll_speed=0.1) Displays a message on the LED matrix. .INDENT 7.0 .TP .B message The message to display .TP .B msg_type The type of the message. Changes the appearance of the message. .sp Available types are: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C error: red text warning: orange text success: green text info: blue text .ft P .fi .UNINDENT .UNINDENT .TP .B scroll_speed The speed at which the message moves over the LED matrix. This value represents the time paused for between shifting the text to the left by one column of pixels. Defaults to \(aq0.1\(aq. .TP .B text_color The color in which the message is shown. Defaults to \(aq[255, 255, 255]\(aq (white). .TP .B back_color The background color of the display. Defaults to \(aq[0, 0, 0]\(aq (black). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqraspberry\(aq sensehat.show_message \(aqStatus ok\(aq salt \(aqraspberry\(aq sensehat.show_message \(aqSomething went wrong\(aq error salt \(aqraspberry\(aq sensehat.show_message \(aqRed\(aq text_color=\(aq[255, 0, 0]\(aq salt \(aqraspberry\(aq sensehat.show_message \(aqHello world\(aq None \(aq[0, 0, 255]\(aq \(aq[255, 255, 0]\(aq 0.2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.sensors .sp Read lm\-sensors .sp New in version 2014.1.3. .INDENT 0.0 .TP .B salt.modules.sensors.sense(chip, fahrenheit=False) Gather lm\-sensors data from a given chip .sp To determine the chip to query, use the \(aqsensors\(aq command and see the leading line in the block. .sp Example: .sp /usr/bin/sensors .sp coretemp\-isa\-0000 Adapter: ISA adapter Physical id 0: +56.0°C (high = +87.0°C, crit = +105.0°C) Core 0: +52.0°C (high = +87.0°C, crit = +105.0°C) Core 1: +50.0°C (high = +87.0°C, crit = +105.0°C) Core 2: +56.0°C (high = +87.0°C, crit = +105.0°C) Core 3: +53.0°C (high = +87.0°C, crit = +105.0°C) .sp Given the above, the chip is \(aqcoretemp\-isa\-0000\(aq. .UNINDENT .SS salt.modules.serverdensity_device .SS Wrapper around Server Density API .sp New in version 2014.7.0. .INDENT 0.0 .TP .B salt.modules.serverdensity_device.create(name, **params) Function to create device in Server Density. For more info, see the \fI\%API docs\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq serverdensity_device.create lama salt \(aq*\(aq serverdensity_device.create rich_lama group=lama_band installedRAM=32768 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.serverdensity_device.delete(device_id) Delete a device from Server Density. For more information, see the \fI\%API docs\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq serverdensity_device.delete 51f7eafcdba4bb235e000ae4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.serverdensity_device.get_sd_auth(val, sd_auth_pillar_name=\(aqserverdensity\(aq) Returns requested Server Density authentication value from pillar. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq serverdensity_device.get_sd_auth <val> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.serverdensity_device.install_agent(agent_key, agent_version=1) Function downloads Server Density installation agent, and installs sd\-agent with agent_key. Optionally the agent_version would select the series to use (defaults on the v1 one). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq serverdensity_device.install_agent c2bbdd6689ff46282bdaa07555641498 salt \(aq*\(aq serverdensity_device.install_agent c2bbdd6689ff46282bdaa07555641498 2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.serverdensity_device.ls(**params) List devices in Server Density .sp Results will be filtered by any params passed to this function. For more information, see the API docs on \fI\%listing\fP and \fI\%searching\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq serverdensity_device.ls salt \(aq*\(aq serverdensity_device.ls name=lama salt \(aq*\(aq serverdensity_device.ls name=lama group=lama_band installedRAM=32768 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.serverdensity_device.update(device_id, **params) Updates device information in Server Density. For more information see the \fI\%API docs\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq serverdensity_device.update 51f7eafcdba4bb235e000ae4 name=lama group=lama_band salt \(aq*\(aq serverdensity_device.update 51f7eafcdba4bb235e000ae4 name=better_lama group=rock_lamas swapSpace=512 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.servicenow .sp Module for execution of ServiceNow CI (configuration items) .sp New in version 2016.11.0. .INDENT 0.0 .TP .B depends servicenow_rest python module .TP .B configuration Configure this module by specifying the name of a configuration profile in the minion config, minion pillar, or master config. The module will use the \(aqservicenow\(aq key by default, if defined. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C servicenow: instance_name: \(aq\(aq username: \(aq\(aq password: \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.servicenow.delete_record(table, sys_id) Delete an existing record .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP (\fBstr\fP) \-\- The table name, e.g. sys_user .IP \(bu 2 \fBsys_id\fP (\fBstr\fP) \-\- The unique ID of the record .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion servicenow.delete_record sys_computer 2134566 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.servicenow.non_structured_query(table, query=None, **kwargs) Run a non\-structed (not a dict) query on a servicenow table. See \fI\%http://wiki.servicenow.com/index.php?title=Encoded_Query_Strings#gsc.tab=0\fP for help on constructing a non\-structured query string. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP (\fBstr\fP) \-\- The table name, e.g. sys_user .IP \(bu 2 \fBquery\fP (\fBstr\fP) \-\- The query to run (or use keyword arguments to filter data) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion servicenow.non_structured_query sys_computer \(aqrole=web\(aq salt myminion servicenow.non_structured_query sys_computer role=web type=computer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.servicenow.set_change_request_state(change_id, state=\(aqapproved\(aq) Set the approval state of a change request/record .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBchange_id\fP (\fBstr\fP) \-\- The ID of the change request, e.g. CHG123545 .IP \(bu 2 \fBstate\fP (\fBstr\fP) \-\- The target state, e.g. approved .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion servicenow.set_change_request_state CHG000123 declined salt myminion servicenow.set_change_request_state CHG000123 approved .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.servicenow.update_record_field(table, sys_id, field, value) Update the value of a record\(aqs field in a servicenow table .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtable\fP (\fBstr\fP) \-\- The table name, e.g. sys_user .IP \(bu 2 \fBsys_id\fP (\fBstr\fP) \-\- The unique ID of the record .IP \(bu 2 \fBfield\fP (\fBstr\fP) \-\- The new value .IP \(bu 2 \fBvalue\fP (\fBstr\fP) \-\- The new value .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion servicenow.update_record_field sys_user 2348234 first_name jimmy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.slack_notify .sp Module for sending messages to Slack .sp New in version 2015.5.0. .INDENT 0.0 .TP .B configuration This module can be used by either passing an api key and version directly or by specifying both in a configuration profile in the salt master/minion config. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C slack: api_key: peWcBiMOS9HrZG15peWcBiMOS9HrZG15 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slack_notify.call_hook(message, attachment=None, color=\(aqgood\(aq, short=False, identifier=None, channel=None, username=None, icon_emoji=None) Send message to Slack incoming webhook. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmessage\fP \-\- The topic of message. .IP \(bu 2 \fBattachment\fP \-\- The message to send to the Slack WebHook. .IP \(bu 2 \fBcolor\fP \-\- The color of border of left side .IP \(bu 2 \fBshort\fP \-\- An optional flag indicating whether the value is short enough to be displayed side\-by\-side with other values. .IP \(bu 2 \fBidentifier\fP \-\- The identifier of WebHook. .IP \(bu 2 \fBchannel\fP \-\- The channel to use instead of the WebHook default. .IP \(bu 2 \fBusername\fP \-\- Username to use instead of WebHook default. .IP \(bu 2 \fBicon_emoji\fP \-\- Icon to use instead of WebHook default. .UNINDENT .TP .B Returns Boolean if message was sent successfully. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slack.call_hook message=\(aqHello, from SaltStack\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slack_notify.find_room(name, api_key=None) Find a room by name and return it. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The room name. .IP \(bu 2 \fBapi_key\fP \-\- The Slack admin api key. .UNINDENT .TP .B Returns The room object. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slack.find_room name=\(dqrandom\(dq salt \(aq*\(aq slack.find_room name=\(dqrandom\(dq api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slack_notify.find_user(name, api_key=None) Find a user by name and return it. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The user name. .IP \(bu 2 \fBapi_key\fP \-\- The Slack admin api key. .UNINDENT .TP .B Returns The user object. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slack.find_user name=\(dqThomasHatch\(dq salt \(aq*\(aq slack.find_user name=\(dqThomasHatch\(dq api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slack_notify.list_rooms(api_key=None) List all Slack rooms. .INDENT 7.0 .TP .B Parameters \fBapi_key\fP \-\- The Slack admin api key. .TP .B Returns The room list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slack.list_rooms salt \(aq*\(aq slack.list_rooms api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slack_notify.list_users(api_key=None) List all Slack users. .INDENT 7.0 .TP .B Parameters \fBapi_key\fP \-\- The Slack admin api key. .TP .B Returns The user list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slack.list_users salt \(aq*\(aq slack.list_users api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slack_notify.post_message(channel, message, from_name, api_key=None, icon=None, attachments=None, blocks=None) Send a message to a Slack channel. .sp Changed in version 3003: Added \fIattachments\fP and \fIblocks\fP kwargs .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBchannel\fP \-\- The channel name, either will work. .IP \(bu 2 \fBmessage\fP \-\- The message to send to the Slack channel. .IP \(bu 2 \fBfrom_name\fP \-\- Specify who the message is from. .IP \(bu 2 \fBapi_key\fP \-\- The Slack api key, if not specified in the configuration. .IP \(bu 2 \fBicon\fP \-\- URL to an image to use as the icon for this message .IP \(bu 2 \fBattachments\fP \-\- Any attachments to be sent with the message. .IP \(bu 2 \fBblocks\fP \-\- Any blocks to be sent with the message. .UNINDENT .TP .B Returns Boolean if message was sent successfully. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slack.post_message channel=\(dqDevelopment Room\(dq message=\(dqBuild is done\(dq from_name=\(dqBuild Server\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.slackware_service .sp The service module for Slackware .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage services on a minion, and it is using a different module (or gives an error similar to \fI\(aqservice.start\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.disable(name, **kwargs) Disable the named service to start at boot .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.disabled(name) Return True if the named service is enabled, false otherwise .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.enable(name, **kwargs) Enable the named service to start at boot .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.enabled(name, **kwargs) Return True if the named service is enabled, false otherwise .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.force_reload(name) Force\-reload the named service .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.force_reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.get_all() Return all available boot services .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.get_disabled() Return a set of services that are installed but disabled .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.get_enabled() Return a list of service that are enabled on boot .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.missing(name) The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.reload_(name) Reload the named service .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.restart(name) Restart the named service .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.start(name) Start the specified service .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.status(name, sig=None) Return the status for a service. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp New in version 3002. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Signature to use to find the service via ps .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> [service signature] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slackware_service.stop(name) Stop the specified service .sp New in version 3002. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.slsutil .sp Utility functions for use with or in SLS files .INDENT 0.0 .TP .B salt.modules.slsutil.banner(width=72, commentchar=\(aq#\(aq, borderchar=\(aq#\(aq, blockstart=None, blockend=None, title=None, text=None, newline=False) Create a standardized comment block to include in a templated file. .sp A common technique in configuration management is to include a comment block in managed files, warning users not to modify the file. This function simplifies and standardizes those comment blocks. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBwidth\fP \-\- The width, in characters, of the banner. Default is 72. .IP \(bu 2 \fBcommentchar\fP \-\- The character to be used in the starting position of each line. This value should be set to a valid line comment character for the syntax of the file in which the banner is being inserted. Multiple character sequences, like \(aq//\(aq are supported. If the file\(aqs syntax does not support line comments (such as XML), use the \fBblockstart\fP and \fBblockend\fP options. .IP \(bu 2 \fBborderchar\fP \-\- The character to use in the top and bottom border of the comment box. Must be a single character. .IP \(bu 2 \fBblockstart\fP \-\- The character sequence to use at the beginning of a block comment. Should be used in conjunction with \fBblockend\fP .IP \(bu 2 \fBblockend\fP \-\- The character sequence to use at the end of a block comment. Should be used in conjunction with \fBblockstart\fP .IP \(bu 2 \fBtitle\fP \-\- The first field of the comment block. This field appears centered at the top of the box. .IP \(bu 2 \fBtext\fP \-\- The second filed of the comment block. This field appears left\-justified at the bottom of the box. .IP \(bu 2 \fBnewline\fP \-\- Boolean value to indicate whether the comment block should end with a newline. Default is \fBFalse\fP\&. .UNINDENT .UNINDENT .sp \fBExample 1 \- the default banner:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {{ salt[\(aqslsutil.banner\(aq]() }} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ######################################################################## # # # THIS FILE IS MANAGED BY SALT \- DO NOT EDIT # # # # The contents of this file are managed by Salt. Any changes to this # # file may be overwritten automatically and without warning. # ######################################################################## .ft P .fi .UNINDENT .UNINDENT .sp \fBExample 2 \- a Javadoc\-style banner:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {{ salt[\(aqslsutil.banner\(aq](commentchar=\(aq *\(aq, borderchar=\(aq*\(aq, blockstart=\(aq/**\(aq, blockend=\(aq */\(aq) }} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /** *********************************************************************** * * * THIS FILE IS MANAGED BY SALT \- DO NOT EDIT * * * * The contents of this file are managed by Salt. Any changes to this * * file may be overwritten automatically and without warning. * *********************************************************************** */ .ft P .fi .UNINDENT .UNINDENT .sp \fBExample 3 \- custom text:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {{ set copyright=\(aqThis file may not be copied or distributed without permission of VMware, Inc.\(aq }} {{ salt[\(aqslsutil.banner\(aq](title=\(aqCopyright 2019 VMware, Inc.\(aq, text=copyright, width=60) }} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ############################################################ # # # Copyright 2019 VMware, Inc. # # # # This file may not be copied or distributed without # # permission of VMware, Inc. # ############################################################ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slsutil.boolstr(value, true=\(aqtrue\(aq, false=\(aqfalse\(aq) Convert a boolean value into a string. This function is intended to be used from within file templates to provide an easy way to take boolean values stored in Pillars or Grains, and write them out in the appropriate syntax for a particular file template. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvalue\fP \-\- The boolean value to be converted .IP \(bu 2 \fBtrue\fP \-\- The value to return if \fBvalue\fP is \fBTrue\fP .IP \(bu 2 \fBfalse\fP \-\- The value to return if \fBvalue\fP is \fBFalse\fP .UNINDENT .UNINDENT .sp In this example, a pillar named \fBsmtp:encrypted\fP stores a boolean value, but the template that uses that value needs \fByes\fP or \fBno\fP to be written, based on the boolean value. .sp \fINote: this is written on two lines for clarity. The same result could be achieved in one line.\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set encrypted = salt[pillar.get](\(aqsmtp:encrypted\(aq, false) %} use_tls: {{ salt[\(aqslsutil.boolstr\(aq](encrypted, \(aqyes\(aq, \(aqno\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Result (assuming the value is \fBTrue\fP): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C use_tls: yes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slsutil.deserialize(serializer, stream_or_string, **mod_kwargs) Deserialize a Python object using one of the available \fI\%serializer modules\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slsutil.deserialize \(aqjson\(aq \(aq{\(dqfoo\(dq: \(dqFoo!\(dq}\(aq salt \(aq*\(aq \-\-no\-parse=stream_or_string slsutil.deserialize \(aqjson\(aq \e stream_or_string=\(aq{\(dqfoo\(dq: \(dqFoo!\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp Jinja Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set python_object = salt.slsutil.deserialize(\(aqjson\(aq, \(aq{\(dqfoo\(dq: \(dqFoo!\(dq}\(aq) %} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slsutil.dir_exists(path, saltenv=\(aqbase\(aq) Return \fBTrue\fP if a directory exists in the state tree, \fBFalse\fP otherwise. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The fully qualified path to a directory in the state tree. .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- The fileserver environment to search. Default: \fBbase\fP .UNINDENT .UNINDENT .sp New in version 3004. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slsutil.dir_exists nginx/files .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slsutil.file_exists(path, saltenv=\(aqbase\(aq) Return \fBTrue\fP if a file exists in the state tree, \fBFalse\fP otherwise. .sp New in version 3004. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The fully qualified path to a file in the state tree. .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- The fileserver environment to search. Default: \fBbase\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slsutil.file_exists nginx/defaults.yaml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slsutil.findup(startpath, filenames, saltenv=\(aqbase\(aq) Find the first path matching a filename or list of filenames in a specified directory or the nearest ancestor directory. Returns the full path to the first file found. .sp New in version 3004. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstartpath\fP (\fI\%str\fP) \-\- The fileserver path from which to begin the search. An empty string refers to the state tree root. .IP \(bu 2 \fBfilenames\fP \-\- A filename or list of filenames to search for. Searching for directory names is also supported. .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- The fileserver environment to search. Default: \fBbase\fP .UNINDENT .UNINDENT .sp Example: return the path to \fBdefaults.yaml\fP, walking up the tree from the state file currently being processed. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {{ salt[\(dqslsutil.findup\(dq](tplfile, \(dqdefaults.yaml\(dq) }} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slsutil.findup formulas/shared/nginx map.jinja .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slsutil.merge(obj_a, obj_b, strategy=\(aqsmart\(aq, renderer=\(aqyaml\(aq, merge_lists=False) Merge a data structure into another by choosing a merge strategy .sp Strategies: .INDENT 7.0 .IP \(bu 2 aggregate .IP \(bu 2 list .IP \(bu 2 overwrite .IP \(bu 2 recurse .IP \(bu 2 smart .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slsutil.merge \(aq{foo: Foo}\(aq \(aq{bar: Bar}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slsutil.merge_all(lst, strategy=\(aqsmart\(aq, renderer=\(aqyaml\(aq, merge_lists=False) New in version 2019.2.0. .sp Merge a list of objects into each other in order .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBlst\fP (\fIIterable\fP) \-\- List of objects to be merged. .IP \(bu 2 \fBstrategy\fP (\fIString\fP) \-\- Merge strategy. See utils.dictupdate. .IP \(bu 2 \fBrenderer\fP (\fIString\fP) \-\- Renderer type. Used to determine strategy when strategy is \(aqsmart\(aq. .IP \(bu 2 \fBmerge_lists\fP (\fIBool\fP) \-\- Defines whether to merge embedded object lists. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ salt\-call \-\-output=txt slsutil.merge_all \(aq[{foo: Foo}, {foo: Bar}]\(aq local: {u\(aqfoo\(aq: u\(aqBar\(aq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slsutil.path_exists(path, saltenv=\(aqbase\(aq) Return \fBTrue\fP if a path exists in the state tree, \fBFalse\fP otherwise. The path could refer to a file or directory. .sp New in version 3004. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The fully qualified path to a file or directory in the state tree. .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- The fileserver environment to search. Default: \fBbase\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slsutil.path_exists nginx/defaults.yaml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slsutil.renderer(path=None, string=None, default_renderer=\(aqjinja|yaml\(aq, **kwargs) Parse a string or file through Salt\(aqs renderer system .sp Changed in version 2018.3.0: Add support for Salt fileserver URIs. .sp This is an open\-ended function and can be used for a variety of tasks. It makes use of Salt\(aqs \(dqrenderer pipes\(dq system to run a string or file through a pipe of any of the loaded renderer modules. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- The path to a file on Salt\(aqs fileserver (any URIs supported by \fI\%cp.get_url\fP) or on the local file system. .IP \(bu 2 \fBstring\fP \-\- An inline string to be used as the file to send through the renderer system. Note, not all renderer modules can work with strings; the \(aqpy\(aq renderer requires a file, for example. .IP \(bu 2 \fBdefault_renderer\fP \-\- The renderer pipe to send the file through; this is overridden by a \(dqshe\-bang\(dq at the top of the file. .IP \(bu 2 \fBkwargs\fP \-\- Keyword args to pass to Salt\(aqs compile_template() function. .UNINDENT .UNINDENT .sp Keep in mind the goal of each renderer when choosing a render\-pipe; for example, the Jinja renderer processes a text file and produces a string, however the YAML renderer processes a text file and produces a data structure. .sp One possible use is to allow writing \(dqmap files\(dq, as are commonly seen in Salt formulas, but without tying the renderer of the map file to the renderer used in the other sls files. In other words, a map file could use the Python renderer and still be included and used by an sls file that uses the default \(aqjinja|yaml\(aq renderer. .sp For example, the two following map files produce identical results but one is written using the normal \(aqjinja|yaml\(aq and the other is using \(aqpy\(aq: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C #!jinja|yaml {% set apache = salt.grains.filter_by({ ...normal jinja map file here... }, merge=salt.pillar.get(\(aqapache:lookup\(aq)) %} {{ apache | yaml() }} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C #!py def run(): apache = __salt__.grains.filter_by({ ...normal map here but as a python dict... }, merge=__salt__.pillar.get(\(aqapache:lookup\(aq)) return apache .ft P .fi .UNINDENT .UNINDENT .sp Regardless of which of the above map files is used, it can be accessed from any other sls file by calling this function. The following is a usage example in Jinja: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set apache = salt.slsutil.renderer(\(aqmap.sls\(aq) %} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slsutil.renderer salt://path/to/file salt \(aq*\(aq slsutil.renderer /path/to/file salt \(aq*\(aq slsutil.renderer /path/to/file.jinja default_renderer=\(aqjinja\(aq salt \(aq*\(aq slsutil.renderer /path/to/file.sls default_renderer=\(aqjinja|yaml\(aq salt \(aq*\(aq slsutil.renderer string=\(aqInline template! {{ saltenv }}\(aq salt \(aq*\(aq slsutil.renderer string=\(aqHello, {{ name }}.\(aq name=\(aqworld\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slsutil.serialize(serializer, obj, **mod_kwargs) Serialize a Python object using one of the available \fI\%serializer modules\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq \-\-no\-parse=obj slsutil.serialize \(aqjson\(aq obj=\(dq{\(aqfoo\(aq: \(aqFoo!\(aq} .ft P .fi .UNINDENT .UNINDENT .sp Jinja Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set json_string = salt.slsutil.serialize(\(aqjson\(aq, {\(aqfoo\(aq: \(aqFoo!\(aq}) %} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.slsutil.update(dest, upd, recursive_update=True, merge_lists=False) Merge \fBupd\fP recursively into \fBdest\fP .sp If \fBmerge_lists=True\fP, will aggregate list object types instead of replacing. This behavior is only activated when \fBrecursive_update=True\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq slsutil.update \(aq{foo: Foo}\(aq \(aq{bar: Bar}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.smartos_imgadm .sp Module for running imgadm command on SmartOS .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.avail(search=None, verbose=False) Return a list of available images .INDENT 7.0 .TP .B search string search keyword .TP .B verbose boolean (False) toggle verbose output .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq imgadm.avail [percona] salt \(aq*\(aq imgadm.avail verbose=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.delete(uuid) Remove an installed image .INDENT 7.0 .TP .B uuid string Specifies uuid to import .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq imgadm.delete e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.docker_to_uuid(uuid) Get the image uuid from an imported docker image .sp New in version 2019.2.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.get(uuid) Return info on an installed image .INDENT 7.0 .TP .B uuid string uuid of image .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq imgadm.get e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f salt \(aq*\(aq imgadm.get plexinc/pms\-docker:plexpass .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.import_image(uuid, verbose=False) Import an image from the repository .INDENT 7.0 .TP .B uuid string uuid to import .TP .B verbose boolean (False) toggle verbose output .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq imgadm.import e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f [verbose=True] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.list_installed(verbose=False) Return a list of installed images .INDENT 7.0 .TP .B verbose boolean (False) toggle verbose output .UNINDENT .sp Changed in version 2019.2.0: Docker images are now also listed .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq imgadm.list salt \(aq*\(aq imgadm.list docker=True salt \(aq*\(aq imgadm.list verbose=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.show(uuid) Show manifest of a given image .INDENT 7.0 .TP .B uuid string uuid of image .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq imgadm.show e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f salt \(aq*\(aq imgadm.show plexinc/pms\-docker:plexpass .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.source_add(source, source_type=\(aqimgapi\(aq) Add a new source .INDENT 7.0 .TP .B source string source url to add .TP .B source_trype string (imgapi) source type, either imgapi or docker .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq imgadm.source_add https://updates.joyent.com salt \(aq*\(aq imgadm.source_add https://docker.io docker .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.source_delete(source) Delete a source .INDENT 7.0 .TP .B source string source url to delete .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq imgadm.source_delete https://updates.joyent.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.sources(verbose=False) Return a list of available sources .INDENT 7.0 .TP .B verbose boolean (False) toggle verbose output .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq imgadm.sources .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.update_installed(uuid=\(aq\(aq) Gather info on unknown image(s) (locally installed) .INDENT 7.0 .TP .B uuid string optional uuid of image .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq imgadm.update [uuid] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.vacuum(verbose=False) Remove unused images .INDENT 7.0 .TP .B verbose boolean (False) toggle verbose output .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq imgadm.vacuum [verbose=True] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_imgadm.version() Return imgadm version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq imgadm.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.smartos_nictagadm .sp Module for running nictagadm command on SmartOS :maintainer: Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> :maturity: new :depends: nictagadm binary, dladm binary :platform: smartos .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.modules.smartos_nictagadm.add(name, mac, mtu=1500) Add a new nictag .INDENT 7.0 .TP .B name string name of new nictag .TP .B mac string mac of parent interface or \(aqetherstub\(aq to create a ether stub .TP .B mtu int MTU (ignored for etherstubs) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nictagadm.add storage0 etherstub salt \(aq*\(aq nictagadm.add trunk0 \(aqDE:AD:OO:OO:BE:EF\(aq 9000 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_nictagadm.delete(name, force=False) Delete nictag .INDENT 7.0 .TP .B name string nictag to delete .TP .B force boolean force delete even if vms attached .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nictagadm.exists admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_nictagadm.exists(*nictag, **kwargs) Check if nictags exists .INDENT 7.0 .TP .B nictag string one or more nictags to check .TP .B verbose boolean return list of nictags .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nictagadm.exists admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_nictagadm.list_nictags(include_etherstubs=True) List all nictags .INDENT 7.0 .TP .B include_etherstubs boolean toggle include of etherstubs .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nictagadm.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_nictagadm.update(name, mac=None, mtu=None) Update a nictag .INDENT 7.0 .TP .B name string name of nictag .TP .B mac string optional new mac for nictag .TP .B mtu int optional new MTU for nictag .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nictagadm.update trunk mtu=9000 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_nictagadm.vms(nictag) List all vms connect to nictag .INDENT 7.0 .TP .B nictag string name of nictag .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq nictagadm.vms admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.smartos_virt .sp virst compatibility module for managing VMs on SmartOS .INDENT 0.0 .TP .B salt.modules.smartos_virt.get_macs(domain) Return a list off MAC addresses from the named VM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.get_macs <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_virt.init(**kwargs) Initialize a new VM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.init image_uuid=\(aq...\(aq alias=\(aq...\(aq [...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_virt.list_active_vms() Return a list of uuids for active virtual machine on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.list_active_vms .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_virt.list_domains() Return a list of virtual machine names on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.list_domains .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_virt.list_inactive_vms() Return a list of uuids for inactive virtual machine on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.list_inactive_vms .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_virt.reboot(domain) Reboot a domain via ACPI request .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.reboot <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_virt.setmem(domain, memory) Change the amount of memory allocated to VM. <memory> is to be specified in MB. .sp Note for KVM : this would require a restart of the VM. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.setmem <domain> 512 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_virt.shutdown(domain) Send a soft shutdown signal to the named vm .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.shutdown <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_virt.start(domain) Start a defined domain .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.start <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_virt.stop(domain) Hard power down the virtual machine, this is equivalent to powering off the hardware. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.destroy <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_virt.vm_info(domain) Return a dict with information about the specified VM on this CN .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.vm_info <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_virt.vm_virt_type(domain) Return VM virtualization type : OS or KVM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.vm_virt_type <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.smartos_vmadm .sp Module for running vmadm command on SmartOS .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.create(from_file=None, **kwargs) Create a new vm .INDENT 7.0 .TP .B from_file string json file to create the vm from \-\- if present, all other options will be ignored .TP .B kwargs string|int|... options to set for the vm .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.create from_file=/tmp/new_vm.json salt \(aq*\(aq vmadm.create image_uuid=\(aq...\(aq alias=\(aq...\(aq nics=\(aq[{ \(dqnic_tag\(dq: \(dqadmin\(dq, \(dqip\(dq: \(dq198.51.100.123\(dq, ...}, {...}]\(aq [...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.create_snapshot(vm, name, key=\(aquuid\(aq) Create snapshot of a vm .INDENT 7.0 .TP .B vm string vm to be targeted .TP .B name string.INDENT 7.0 .TP .B snapshot name The snapname must be 64 characters or less and must only contain alphanumeric characters and characters in the set [\-_.:%] to comply with ZFS restrictions. .UNINDENT .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.create_snapshot 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 baseline salt \(aq*\(aq vmadm.create_snapshot nacl baseline key=alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.delete(vm, key=\(aquuid\(aq) Delete a vm .INDENT 7.0 .TP .B vm string vm to be deleted .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.delete 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 salt \(aq*\(aq vmadm.delete nacl key=alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.delete_snapshot(vm, name, key=\(aquuid\(aq) Delete snapshot of a vm .INDENT 7.0 .TP .B vm string vm to be targeted .TP .B name string.INDENT 7.0 .TP .B snapshot name The snapname must be 64 characters or less and must only contain alphanumeric characters and characters in the set [\-_.:%] to comply with ZFS restrictions. .UNINDENT .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.delete_snapshot 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 baseline salt \(aq*\(aq vmadm.delete_snapshot nacl baseline key=alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.get(vm, key=\(aquuid\(aq) Output the JSON object describing a VM .INDENT 7.0 .TP .B vm string vm to be targeted .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.get 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 salt \(aq*\(aq vmadm.get nacl key=alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.info(vm, info_type=\(aqall\(aq, key=\(aquuid\(aq) Lookup info on running kvm .INDENT 7.0 .TP .B vm string vm to be targeted .TP .B info_type string [all|block|blockstats|chardev|cpus|kvm|pci|spice|version|vnc] info type to return .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.info 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 salt \(aq*\(aq vmadm.info 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 vnc salt \(aq*\(aq vmadm.info nacl key=alias salt \(aq*\(aq vmadm.info nacl vnc key=alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.list_vms(search=None, sort=None, order=\(aquuid,type,ram,state,alias\(aq, keyed=True) Return a list of VMs .INDENT 7.0 .TP .B search string vmadm filter property .TP .B sort string vmadm sort (\-s) property .TP .B order string vmadm order (\-o) property \-\- Default: uuid,type,ram,state,alias .TP .B keyed boolean.INDENT 7.0 .TP .B specified if the output should be an array (False) or dict (True) For a dict the key is the first item from the order parameter. Note: If key is not unique last vm wins. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.list salt \(aq*\(aq vmadm.list order=alias,ram,cpu_cap sort=\-ram,\-cpu_cap salt \(aq*\(aq vmadm.list search=\(aqtype=KVM\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.lookup(search=None, order=None, one=False) Return a list of VMs using lookup .INDENT 7.0 .TP .B search string vmadm filter property .TP .B order string vmadm order (\-o) property \-\- Default: uuid,type,ram,state,alias .TP .B one boolean return only one result (vmadm\(aqs \-1) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.lookup search=\(aqstate=running\(aq salt \(aq*\(aq vmadm.lookup search=\(aqstate=running\(aq order=uuid,alias,hostname salt \(aq*\(aq vmadm.lookup search=\(aqalias=nacl\(aq one=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.reboot(vm, force=False, key=\(aquuid\(aq) Reboot a vm .INDENT 7.0 .TP .B vm string vm to be rebooted .TP .B force boolean force reboot of vm if true .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.reboot 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 salt \(aq*\(aq vmadm.reboot 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 True salt \(aq*\(aq vmadm.reboot vm=nacl key=alias salt \(aq*\(aq vmadm.reboot vm=nina.example.org key=hostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.receive(uuid, source) Receive a vm from a directory .INDENT 7.0 .TP .B uuid string uuid of vm to be received .TP .B source string source directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.receive 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 /opt/backups .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.reprovision(vm, image, key=\(aquuid\(aq) Reprovision a vm .INDENT 7.0 .TP .B vm string vm to be reprovisioned .TP .B image string uuid of new image .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.reprovision 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 c02a2044\-c1bd\-11e4\-bd8c\-dfc1db8b0182 salt \(aq*\(aq vmadm.reprovision nacl c02a2044\-c1bd\-11e4\-bd8c\-dfc1db8b0182 key=alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.rollback_snapshot(vm, name, key=\(aquuid\(aq) Rollback snapshot of a vm .INDENT 7.0 .TP .B vm string vm to be targeted .TP .B name string.INDENT 7.0 .TP .B snapshot name The snapname must be 64 characters or less and must only contain alphanumeric characters and characters in the set [\-_.:%] to comply with ZFS restrictions. .UNINDENT .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.rollback_snapshot 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 baseline salt \(aq*\(aq vmadm.rollback_snapshot nacl baseline key=alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.send(vm, target, key=\(aquuid\(aq) Send a vm to a directory .INDENT 7.0 .TP .B vm string vm to be sent .TP .B target string target directory .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.send 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 /opt/backups salt \(aq*\(aq vmadm.send vm=nacl target=/opt/backups key=alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.start(vm, options=None, key=\(aquuid\(aq) Start a vm .INDENT 7.0 .TP .B vm string vm to be started .TP .B options string optional additional options .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.start 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 salt \(aq*\(aq vmadm.start 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 \(aqorder=c,once=d cdrom=/path/to/image.iso,ide\(aq salt \(aq*\(aq vmadm.start vm=nacl key=alias salt \(aq*\(aq vmadm.start vm=nina.example.org key=hostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.stop(vm, force=False, key=\(aquuid\(aq) Stop a vm .INDENT 7.0 .TP .B vm string vm to be stopped .TP .B force boolean force stop of vm if true .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.stop 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 salt \(aq*\(aq vmadm.stop 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 True salt \(aq*\(aq vmadm.stop vm=nacl key=alias salt \(aq*\(aq vmadm.stop vm=nina.example.org key=hostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.sysrq(vm, action=\(aqnmi\(aq, key=\(aquuid\(aq) Send non\-maskable interrupt to vm or capture a screenshot .INDENT 7.0 .TP .B vm string vm to be targeted .TP .B action string nmi or screenshot \-\- Default: nmi .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.sysrq 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 nmi salt \(aq*\(aq vmadm.sysrq 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 screenshot salt \(aq*\(aq vmadm.sysrq nacl nmi key=alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smartos_vmadm.update(vm, from_file=None, key=\(aquuid\(aq, **kwargs) Update a new vm .INDENT 7.0 .TP .B vm string vm to be updated .TP .B from_file string json file to update the vm with \-\- if present, all other options will be ignored .TP .B key string [uuid|alias|hostname] value type of \(aqvm\(aq parameter .TP .B kwargs string|int|... options to update for the vm .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmadm.update vm=186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 from_file=/tmp/new_vm.json salt \(aq*\(aq vmadm.update vm=nacl key=alias from_file=/tmp/new_vm.json salt \(aq*\(aq vmadm.update vm=186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 max_physical_memory=1024 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.smbios .sp Interface to SMBIOS/DMI .sp (Parsing through dmidecode) .SS External References .nf \fI\%Desktop Management Interface (DMI)\fP \fI\%System Management BIOS\fP \fI\%DMIdecode\fP .fi .sp .INDENT 0.0 .TP .B salt.modules.smbios.get(string, clean=True) Get an individual DMI string from SMBIOS info .INDENT 7.0 .TP .B string .INDENT 7.0 .TP .B The string to fetch. DMIdecode supports: .INDENT 7.0 .IP \(bu 2 \fBbios\-vendor\fP .IP \(bu 2 \fBbios\-version\fP .IP \(bu 2 \fBbios\-release\-date\fP .IP \(bu 2 \fBsystem\-manufacturer\fP .IP \(bu 2 \fBsystem\-product\-name\fP .IP \(bu 2 \fBsystem\-version\fP .IP \(bu 2 \fBsystem\-serial\-number\fP .IP \(bu 2 \fBsystem\-uuid\fP .IP \(bu 2 \fBbaseboard\-manufacturer\fP .IP \(bu 2 \fBbaseboard\-product\-name\fP .IP \(bu 2 \fBbaseboard\-version\fP .IP \(bu 2 \fBbaseboard\-serial\-number\fP .IP \(bu 2 \fBbaseboard\-asset\-tag\fP .IP \(bu 2 \fBchassis\-manufacturer\fP .IP \(bu 2 \fBchassis\-type\fP .IP \(bu 2 \fBchassis\-version\fP .IP \(bu 2 \fBchassis\-serial\-number\fP .IP \(bu 2 \fBchassis\-asset\-tag\fP .IP \(bu 2 \fBprocessor\-family\fP .IP \(bu 2 \fBprocessor\-manufacturer\fP .IP \(bu 2 \fBprocessor\-version\fP .IP \(bu 2 \fBprocessor\-frequency\fP .UNINDENT .UNINDENT .TP .B clean .nf Don\(aqt return well\-known false information (invalid UUID\(aqs, serial 000000000\(aqs, etcetera) Defaults to \fBTrue\fP .fi .sp .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq smbios.get system\-uuid clean=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smbios.records(rec_type=None, fields=None, clean=True) Return DMI records from SMBIOS .INDENT 7.0 .TP .B type Return only records of type(s) The SMBIOS specification defines the following DMI types: .TS center; |l|l|. _ T{ Type T} T{ Information T} _ T{ 0 T} T{ BIOS T} _ T{ 1 T} T{ System T} _ T{ 2 T} T{ Baseboard T} _ T{ 3 T} T{ Chassis T} _ T{ 4 T} T{ Processor T} _ T{ 5 T} T{ Memory Controller T} _ T{ 6 T} T{ Memory Module T} _ T{ 7 T} T{ Cache T} _ T{ 8 T} T{ Port Connector T} _ T{ 9 T} T{ System Slots T} _ T{ 10 T} T{ On Board Devices T} _ T{ 11 T} T{ OEM Strings T} _ T{ 12 T} T{ System Configuration Options T} _ T{ 13 T} T{ BIOS Language T} _ T{ 14 T} T{ Group Associations T} _ T{ 15 T} T{ System Event Log T} _ T{ 16 T} T{ Physical Memory Array T} _ T{ 17 T} T{ Memory Device T} _ T{ 18 T} T{ 32\-bit Memory Error T} _ T{ 19 T} T{ Memory Array Mapped Address T} _ T{ 20 T} T{ Memory Device Mapped Address T} _ T{ 21 T} T{ Built\-in Pointing Device T} _ T{ 22 T} T{ Portable Battery T} _ T{ 23 T} T{ System Reset T} _ T{ 24 T} T{ Hardware Security T} _ T{ 25 T} T{ System Power Controls T} _ T{ 26 T} T{ Voltage Probe T} _ T{ 27 T} T{ Cooling Device T} _ T{ 28 T} T{ Temperature Probe T} _ T{ 29 T} T{ Electrical Current Probe T} _ T{ 30 T} T{ Out\-of\-band Remote Access T} _ T{ 31 T} T{ Boot Integrity Services T} _ T{ 32 T} T{ System Boot T} _ T{ 33 T} T{ 64\-bit Memory Error T} _ T{ 34 T} T{ Management Device T} _ T{ 35 T} T{ Management Device Component T} _ T{ 36 T} T{ Management Device Threshold Data T} _ T{ 37 T} T{ Memory Channel T} _ T{ 38 T} T{ IPMI Device T} _ T{ 39 T} T{ Power Supply T} _ T{ 40 T} T{ Additional Information T} _ T{ 41 T} T{ Onboard Devices Extended Information T} _ T{ 42 T} T{ Management Controller Host Interface T} _ .TE .TP .B clean .nf Don\(aqt return well\-known false information (invalid UUID\(aqs, serial 000000000\(aqs, etcetera) Defaults to \fBTrue\fP .fi .sp .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq smbios.records clean=False salt \(aq*\(aq smbios.records 14 salt \(aq*\(aq smbios.records 4 core_count,thread_count,current_speed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.smf_service .sp Service support for Solaris 10 and 11, should work with other systems that use SMF also. (e.g. SmartOS) .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage services on a minion, and it is using a different module (or gives an error similar to \fI\(aqservice.start\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp We look up the name with the svcs command to get back the FMRI This allows users to use simpler service names .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available net\-snmp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.disable(name, **kwargs) Disable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.disabled(name) Check to see if the named service is disabled to start on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.enable(name, **kwargs) Enable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.enabled(name, **kwargs) Check to see if the named service is enabled to start on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.get_all() Return all installed services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.get_disabled() Return the disabled services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.get_enabled() Return the enabled services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.get_running() Return the running services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_running .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.get_stopped() Return the stopped services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_stopped .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.missing(name) The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing net\-snmp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.reload_(name) Reload the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.restart(name) Restart the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.start(name) Start the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.status(name, sig=None) Return the status for a service. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Not implemented .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smf_service.stop(name) Stop the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.smtp .sp Module for Sending Messages via SMTP .sp New in version 2014.7.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 smtplib python module .UNINDENT .TP .B configuration This module can be used by either passing a jid and password directly to send_message, or by specifying the name of a configuration profile in the minion config, minion pillar, or master config. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my\-smtp\-login: smtp.server: smtp.domain.com smtp.tls: True smtp.sender: admin@domain.com smtp.username: myuser smtp.password: verybadpass .ft P .fi .UNINDENT .UNINDENT .sp The resourcename refers to the resource that is using this account. It is user\-definable, and optional. The following configurations are both valid: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my\-smtp\-login: smtp.server: smtp.domain.com smtp.tls: True smtp.sender: admin@domain.com smtp.username: myuser smtp.password: verybadpass another\-smtp\-login: smtp.server: smtp.domain.com smtp.tls: True smtp.sender: admin@domain.com smtp.username: myuser smtp.password: verybadpass .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.smtp.send_msg(recipient, message, subject=\(aqMessage from Salt\(aq, sender=None, server=None, use_ssl=\(aqTrue\(aq, username=None, password=None, profile=None, attachments=None) Send a message to an SMTP recipient. To send a message to multiple recipients, the recipients should be in a comma\-seperated Python string. Designed for use in states. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq smtp.send_msg \(aqadmin@example.com\(aq \(aqThis is a salt module test\(aq profile=\(aqmy\-smtp\-account\(aq salt \(aq*\(aq smtp.send_msg \(aqadmin@example.com,admin2@example.com\(aq \(aqThis is a salt module test for multiple recipients\(aq profile=\(aqmy\-smtp\-account\(aq salt \(aq*\(aq smtp.send_msg \(aqadmin@example.com\(aq \(aqThis is a salt module test\(aq username=\(aqmyuser\(aq password=\(aqverybadpass\(aq sender=\(aqadmin@example.com\(aq server=\(aqsmtp.domain.com\(aq salt \(aq*\(aq smtp.send_msg \(aqadmin@example.com\(aq \(aqThis is a salt module test\(aq username=\(aqmyuser\(aq password=\(aqverybadpass\(aq sender=\(aqadmin@example.com\(aq server=\(aqsmtp.domain.com\(aq attachments=\(dq[\(aq/var/log/messages\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.snapper .sp Module to manage filesystem snapshots with snapper .sp New in version 2016.11.0. .INDENT 0.0 .TP .B codeauthor Duncan Mac\-Vicar P. <\fI\%dmacvicar@suse.de\fP> .TP .B codeauthor Pablo Suárez Hernández <\fI\%psuarezhernandez@suse.de\fP> .TP .B depends \fBdbus\fP Python module. .TP .B depends \fBsnapper\fP \fI\%http://snapper.io\fP, available in most distros .TP .B maturity new .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.changed_files(config=\(aqroot\(aq, num_pre=None, num_post=None) Returns the files changed between two snapshots .INDENT 7.0 .TP .B config Configuration name. .TP .B num_pre first snapshot ID to compare. Default is last snapshot .TP .B num_post last snapshot ID to compare. Default is 0 (current state) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.changed_files salt \(aq*\(aq snapper.changed_files num_pre=19 num_post=20 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.create_baseline(tag=\(aqbaseline\(aq, config=\(aqroot\(aq) Creates a snapshot marked as baseline .INDENT 7.0 .TP .B tag Tag name for the baseline .TP .B config Configuration name. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.create_baseline salt \(aq*\(aq snapper.create_baseline my_custom_baseline .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.create_config(name=None, subvolume=None, fstype=None, template=None, extra_opts=None) Creates a new Snapper configuration .INDENT 7.0 .TP .B name Name of the new Snapper configuration. .TP .B subvolume Path to the related subvolume. .TP .B fstype Filesystem type of the subvolume. .TP .B template Configuration template to use. (Default: default) .TP .B extra_opts Extra Snapper configuration opts dictionary. It will override the values provided by the given template (if any). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.create_config name=myconfig subvolume=/foo/bar/ fstype=btrfs salt \(aq*\(aq snapper.create_config name=myconfig subvolume=/foo/bar/ fstype=btrfs template=\(dqdefault\(dq salt \(aq*\(aq snapper.create_config name=myconfig subvolume=/foo/bar/ fstype=btrfs extra_opts=\(aq{\(dqNUMBER_CLEANUP\(dq: False}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.create_snapshot(config=\(aqroot\(aq, snapshot_type=\(aqsingle\(aq, pre_number=None, description=None, cleanup_algorithm=\(aqnumber\(aq, userdata=None, **kwargs) Creates an snapshot .INDENT 7.0 .TP .B config Configuration name. .TP .B snapshot_type Specifies the type of the new snapshot. Possible values are single, pre and post. .TP .B pre_number For post snapshots the number of the pre snapshot must be provided. .TP .B description Description for the snapshot. If not given, the salt job will be used. .TP .B cleanup_algorithm Set the cleanup algorithm for the snapshot. .TP .B number Deletes old snapshots when a certain number of snapshots is reached. .TP .B timeline Deletes old snapshots but keeps a number of hourly, daily, weekly, monthly and yearly snapshots. .TP .B empty\-pre\-post Deletes pre/post snapshot pairs with empty diffs. .TP .B userdata Set userdata for the snapshot (key\-value pairs). .UNINDENT .sp Returns the number of the created snapshot. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.create_snapshot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.delete_snapshot(snapshots_ids=None, config=\(aqroot\(aq) Deletes an snapshot .INDENT 7.0 .TP .B config Configuration name. (Default: root) .TP .B snapshots_ids List of the snapshots IDs to be deleted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.delete_snapshot 54 salt \(aq*\(aq snapper.delete_snapshot config=root 54 salt \(aq*\(aq snapper.delete_snapshot config=root snapshots_ids=[54,55,56] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.diff(config=\(aqroot\(aq, filename=None, num_pre=None, num_post=None) Returns the differences between two snapshots .INDENT 7.0 .TP .B config Configuration name. .TP .B filename if not provided the showing differences between snapshots for all \(dqtext\(dq files .TP .B num_pre first snapshot ID to compare. Default is last snapshot .TP .B num_post last snapshot ID to compare. Default is 0 (current state) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.diff salt \(aq*\(aq snapper.diff filename=/var/log/snapper.log num_pre=19 num_post=20 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.diff_jid(jid, config=\(aqroot\(aq) Returns the changes applied by a \fIjid\fP .INDENT 7.0 .TP .B jid The job id to lookup .TP .B config Configuration name. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.diff_jid jid=20160607130930720112 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.get_config(name=\(aqroot\(aq) Retrieves all values from a given configuration .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.get_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.get_snapshot(number=0, config=\(aqroot\(aq) Get detailed information about a given snapshot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.get_snapshot 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.list_configs() List all available configs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.list_configs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.list_snapshots(config=\(aqroot\(aq) List available snapshots .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.list_snapshots config=myconfig .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.modify_snapshot(snapshot_id=None, description=None, userdata=None, cleanup=None, config=\(aqroot\(aq) Modify attributes of an existing snapshot. .INDENT 7.0 .TP .B config Configuration name. (Default: root) .TP .B snapshot_id ID of the snapshot to be modified. .TP .B cleanup Change the cleanup method of the snapshot. (str) .TP .B description Change the description of the snapshot. (str) .TP .B userdata Change the userdata dictionary of the snapshot. (dict) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.modify_snapshot 54 description=\(dqmy snapshot description\(dq salt \(aq*\(aq snapper.modify_snapshot 54 description=\(dqmy snapshot description\(dq salt \(aq*\(aq snapper.modify_snapshot 54 userdata=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq salt \(aq*\(aq snapper.modify_snapshot snapshot_id=54 cleanup=\(dqnumber\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.run(function, *args, **kwargs) Runs a function from an execution module creating pre and post snapshots and associating the salt job id with those snapshots for easy undo and cleanup. .INDENT 7.0 .TP .B function Salt function to call. .TP .B config Configuration name. (default: \(dqroot\(dq) .TP .B description A description for the snapshots. (default: None) .TP .B userdata Data to include in the snapshot metadata. (default: None) .TP .B cleanup_algorithm Snapper cleanup algorithm. (default: \(dqnumber\(dq) .TP .B \fI*args\fP args for the function to call. (default: None) .TP .B \fI**kwargs\fP kwargs for the function to call (default: None) .UNINDENT .sp This would run append text to /etc/motd using the file.append module, and will create two snapshots, pre and post with the associated metadata. The jid will be available as salt_jid in the userdata of the snapshot. .sp You can immediately see the changes .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.run file.append args=\(aq[\(dq/etc/motd\(dq, \(dqsome text\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.set_config(name=\(aqroot\(aq, **kwargs) Set configuration values .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.set_config SYNC_ACL=True .ft P .fi .UNINDENT .UNINDENT .sp Keys are case insensitive as they will be always uppercased to snapper convention. The above example is equivalent to: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.set_config sync_acl=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.status(config=\(aqroot\(aq, num_pre=None, num_post=None) Returns a comparison between two snapshots .INDENT 7.0 .TP .B config Configuration name. .TP .B num_pre first snapshot ID to compare. Default is last snapshot .TP .B num_post last snapshot ID to compare. Default is 0 (current state) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.status salt \(aq*\(aq snapper.status num_pre=19 num_post=20 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.status_to_string(dbus_status) Converts a numeric dbus snapper status into a string .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.status_to_string <dbus_status> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.undo(config=\(aqroot\(aq, files=None, num_pre=None, num_post=None) Undo all file changes that happened between num_pre and num_post, leaving the files into the state of num_pre. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 If one of the files has changes after num_post, they will be overwritten The snapshots are used to determine the file list, but the current version of the files will be overwritten by the versions in num_pre. .sp You to undo changes between num_pre and the current version of the files use num_post=0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.undo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.snapper.undo_jid(jid, config=\(aqroot\(aq) Undo the changes applied by a salt job .INDENT 7.0 .TP .B jid The job id to lookup .TP .B config Configuration name. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq snapper.undo_jid jid=20160607130930720112 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.solaris_fmadm .sp Module for running fmadm and fmdump on Solaris .INDENT 0.0 .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B platform solaris,illumos .UNINDENT .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.modules.solaris_fmadm.acquit(fmri) Acquit resource or acquit case .INDENT 7.0 .TP .B fmri: string fmri or uuid .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq fmadm.acquit fmri | uuid .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_fmadm.config() Display fault manager configuration .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq fmadm.config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_fmadm.faulty() Display list of faulty resources .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq fmadm.faulty .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_fmadm.flush(fmri) Flush cached state for resource .INDENT 7.0 .TP .B fmri: string fmri .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq fmadm.flush fmri .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_fmadm.healthy() Return whether fmadm is reporting faults .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq fmadm.healthy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_fmadm.list_records(after=None, before=None) Display fault management logs .INDENT 7.0 .TP .B after string filter events after time, see man fmdump for format .TP .B before string filter events before time, see man fmdump for format .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq fmadm.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_fmadm.load(path) Load specified fault manager module .INDENT 7.0 .TP .B path: string path of fault manager module .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq fmadm.load /module/path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_fmadm.repaired(fmri) Notify fault manager that resource has been repaired .INDENT 7.0 .TP .B fmri: string fmri .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq fmadm.repaired fmri .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_fmadm.replaced(fmri) Notify fault manager that resource has been replaced .INDENT 7.0 .TP .B fmri: string fmri .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq fmadm.repaired fmri .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_fmadm.reset(module, serd=None) Reset module or sub\-component .INDENT 7.0 .TP .B module: string module to unload .TP .B serd string serd sub module .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq fmadm.reset software\-response .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_fmadm.show(uuid) Display log details .INDENT 7.0 .TP .B uuid: string uuid of fault .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq fmadm.show 11b4070f\-4358\-62fa\-9e1e\-998f485977e1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_fmadm.unload(module) Unload specified fault manager module .INDENT 7.0 .TP .B module: string module to unload .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq fmadm.unload software\-response .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.solaris_group .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_group.add(name, gid=None, **kwargs) 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.solaris_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.solaris_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.solaris_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.solaris_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 .SS salt.modules.solaris_shadow .sp Manage the password database on Solaris systems .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage passwords on a minion, and it is using a different module (or gives an error similar to \fI\(aqshadow.info\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_shadow.default_hash() Returns the default hash used for unset passwords .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.default_hash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_shadow.del_password(name) New in version 2015.8.8. .sp Delete the password from name user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.del_password username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_shadow.gen_password(password, crypt_salt=None, algorithm=\(aqsha512\(aq) New in version 2015.8.8. .sp Generate hashed password .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When called this function is called directly via remote\-execution, the password argument may be displayed in the system\(aqs process list. This may be a security risk on certain systems. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B password Plaintext password to be hashed. .TP .B crypt_salt Crpytographic salt. If not given, a random 8\-character salt will be generated. .TP .B algorithm The following hash algorithms are supported: .INDENT 7.0 .IP \(bu 2 md5 .IP \(bu 2 blowfish (not in mainline glibc, only available in distros that add it) .IP \(bu 2 sha256 .IP \(bu 2 sha512 (default) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.gen_password \(aqI_am_password\(aq salt \(aq*\(aq shadow.gen_password \(aqI_am_password\(aq crypt_salt=\(aqI_am_salt\(aq algorithm=sha256 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_shadow.info(name) Return information for the specified user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.info root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_shadow.set_maxdays(name, maxdays) Set the maximum number of days during which a password is valid. See man passwd. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_maxdays username 90 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_shadow.set_mindays(name, mindays) Set the minimum number of days between password changes. See man passwd. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_mindays username 7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_shadow.set_password(name, password) Set the password for a named user. The password must be a properly defined hash, the password hash can be generated with this command: \fBopenssl passwd \-1 <plaintext password>\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_password root $1$UYCIxa628.9qXjpQCjM4a.. .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_shadow.set_warndays(name, warndays) Set the number of days of warning before a password change is required. See man passwd. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_warndays username 7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.solaris_system .sp Support for reboot, shutdown, etc .sp This module is assumes we are using solaris\-like shutdown .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.modules.solaris_system.halt() Halt a running system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.halt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_system.init(state) Change the system runlevel on sysV compatible systems .sp CLI Example: .INDENT 7.0 .TP .B state string Init state .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.init 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_system.poweroff() Poweroff a running system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.poweroff .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_system.reboot(delay=0, message=None) Reboot the system .INDENT 7.0 .TP .B delay int Optional wait time in seconds before the system will be rebooted. .TP .B message string Optional message to broadcast before rebooting. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.reboot salt \(aq*\(aq system.reboot 60 \(dq=== system upgraded ===\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_system.shutdown(delay=0, message=None) Shutdown a running system .INDENT 7.0 .TP .B delay int Optional wait time in seconds before the system will be shutdown. .TP .B message string Optional message to broadcast before rebooting. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.shutdown salt \(aq*\(aq system.shutdown 60 \(dq=== disk replacement ===\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.solaris_user .sp Manage users with the useradd command .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage users on a minion, and it is using a different module (or gives an error similar to \fI\(aquser.info\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.add(name, uid=None, gid=None, groups=None, home=None, shell=None, unique=True, fullname=\(aq\(aq, roomnumber=\(aq\(aq, workphone=\(aq\(aq, homephone=\(aq\(aq, createhome=True, **kwargs) Add a user to the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.add name <uid> <gid> <groups> <home> <shell> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.chfullname(name, fullname) Change the user\(aqs Full Name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chfullname foo \(dqFoo Bar\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.chgid(name, gid) Change the default group of the user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chgid foo 4376 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.chgroups(name, groups, append=False) Change the groups to which a user belongs .INDENT 7.0 .TP .B name Username to modify .TP .B groups List of groups to set for the user. Can be passed as a comma\-separated list or a Python list. .TP .B append False Set to \fBTrue\fP to append these groups to the user\(aqs existing list of groups. Otherwise, the specified groups will replace any existing groups for the user. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chgroups foo wheel,root True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.chhome(name, home, persist=False) Set a new home directory for an existing user .INDENT 7.0 .TP .B name Username to modify .TP .B home New home directory to set .TP .B persist False Set to \fBTrue\fP to prevent configuration files in the new home directory from being overwritten by the files from the skeleton directory. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chhome foo /home/users/foo True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.chhomephone(name, homephone) Change the user\(aqs Home Phone .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chhomephone foo \(dq7735551234\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.chroomnumber(name, roomnumber) Change the user\(aqs Room Number .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chroomnumber foo 123 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.chshell(name, shell) Change the default shell of the user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chshell foo /bin/zsh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.chuid(name, uid) Change the uid for a named user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chuid foo 4376 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.chworkphone(name, workphone) Change the user\(aqs Work Phone .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chworkphone foo \(dq7735550123\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.delete(name, remove=False, force=False) Remove a user from the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.delete name remove=True force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.getent(refresh=False) Return the list of all info for all users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.getent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.info(name) Return user information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.info root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.list_groups(name) Return a list of groups the named user belongs to .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.list_groups foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.list_users() Return a list of all users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solaris_user.rename(name, new_name) Change the username for a named user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.rename name new_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.solarisipspkg .sp IPS pkg support for Solaris .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .sp This module provides support for Solaris 11 new package management \- IPS (Image Packaging System). This is the default pkg module for Solaris 11 (and later). .sp If you want to use also other packaging module (e.g. pkgutil) together with IPS, you need to override the \fBpkg\fP provider in sls for each package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mypackage: pkg.installed: \- provider: pkgutil .ft P .fi .UNINDENT .UNINDENT .sp Or you can override it globally by setting the \fI\%providers\fP parameter in your Minion config file like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C providers: pkg: pkgutil .ft P .fi .UNINDENT .UNINDENT .sp Or you can override it globally by setting the \fI\%providers\fP parameter in your Minion config file like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C providers: pkg: pkgutil .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.available_version(*names, **kwargs) This function is an alias of \fBlatest_version\fP\&. .INDENT 7.0 .INDENT 3.5 The available version of packages in the repository. Accepts full or partial FMRI. Partial FMRI is returned if the full FMRI could not be resolved. .sp If the latest version of a given package is already installed, an empty string will be returned for that package. .sp Please use pkg.latest_version as pkg.available_version is being deprecated. .sp Changed in version 2019.2.0: Support for multiple package names added. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version bash salt \(aq*\(aq pkg.latest_version pkg://solaris/entire salt \(aq*\(aq pkg.latest_version postfix sendmail .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.get_fmri(name, **kwargs) Returns FMRI from partial name. Returns empty string (\(aq\(aq) if not found. In case of multiple match, the function returns list of all matched packages. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.get_fmri bash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.install(name=None, refresh=False, pkgs=None, version=None, test=False, **kwargs) Install the named package using the IPS pkg command. Accepts full or partial FMRI. .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of packages to install. Must be passed as a python list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install vim salt \(aq*\(aq pkg.install pkg://solaris/editor/vim salt \(aq*\(aq pkg.install pkg://solaris/editor/vim refresh=True salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.is_installed(name, **kwargs) Returns True if the package is installed. Otherwise returns False. Name can be full or partial FMRI. In case of multiple match from partial FMRI name, it returns True. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.is_installed bash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.latest_version(*names, **kwargs) The available version of packages in the repository. Accepts full or partial FMRI. Partial FMRI is returned if the full FMRI could not be resolved. .sp If the latest version of a given package is already installed, an empty string will be returned for that package. .sp Please use pkg.latest_version as pkg.available_version is being deprecated. .sp Changed in version 2019.2.0: Support for multiple package names added. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version bash salt \(aq*\(aq pkg.latest_version pkg://solaris/entire salt \(aq*\(aq pkg.latest_version postfix sendmail .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.list_pkgs(versions_as_list=False, **kwargs) List the currently installed packages as a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(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.solarisipspkg.list_upgrades(refresh=True, **kwargs) Lists all packages available for update. .sp When run in global zone, it reports only upgradable packages for the global zone. .sp When run in non\-global zone, it can report more upgradable packages than \fBpkg update \-vn\fP, because \fBpkg update\fP hides packages that require newer version of \fBpkg://solaris/entire\fP (which means that they can be upgraded only from the global zone). If \fBpkg://solaris/entire\fP is found in the list of upgrades, then the global zone should be updated to get all possible updates. Use \fBrefresh=True\fP to refresh the package database. .INDENT 7.0 .TP .B refresh True Runs a full package database refresh before listing. Set to \fBFalse\fP to disable running the refresh. .sp Changed in version 2017.7.0. .sp In previous versions of Salt, \fBrefresh\fP defaulted to \fBFalse\fP\&. This was changed to default to \fBTrue\fP in the 2017.7.0 release to make the behavior more consistent with the other package modules, which all default to \fBTrue\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades salt \(aq*\(aq pkg.list_upgrades refresh=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.normalize_name(name, **kwargs) Internal function. Normalizes pkg name to full FMRI before running pkg.install. In case of multiple matches or no match, it returns the name without modifications. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.normalize_name vim .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.purge(name, **kwargs) Remove specified package. Accepts full or partial FMRI. .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.purge <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.refresh_db(full=False, **kwargs) Updates the remote repos database. .sp full : False .INDENT 7.0 .INDENT 3.5 Set to \fBTrue\fP to force a refresh of the pkg DB from all publishers, regardless of the last refresh time. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db salt \(aq*\(aq pkg.refresh_db full=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.remove(name=None, pkgs=None, **kwargs) Remove specified package. Accepts full or partial FMRI. In case of multiple match, the command fails and won\(aqt modify the OS. .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 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 <package name> salt \(aq*\(aq pkg.remove tcsh salt \(aq*\(aq pkg.remove pkg://solaris/shell/tcsh salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.search(name, versions_as_list=False, **kwargs) Searches the repository for given pkg name. The name can be full or partial FMRI. All matches are printed. Globs are also supported. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search bash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.upgrade(refresh=False, **kwargs) Upgrade all packages to the latest possible version. When run in global zone, it updates also all non\-global zones. In non\-global zones upgrade is limited by dependency constrains linked to the version of pkg://solaris/entire. .sp Returns a dictionary containing the changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp When there is a failure, an explanation is also included in the error message, based on the return code of the \fBpkg update\fP command. .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.solarisipspkg.upgrade_available(name, **kwargs) Check if there is an upgrade available for a certain package Accepts full or partial FMRI. Returns all matches found. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available apache\-22 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarisipspkg.version(*names, **kwargs) Common interface for obtaining the version of installed packages. Accepts full or partial FMRI. If called using pkg_resource, full FMRI is required. Partial FMRI is returned if the package is not installed. .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 salt \(aq*\(aq pkg_resource.version pkg://solaris/entire .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.solarispkg .sp Package support for Solaris .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarispkg.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 CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .sp NOTE: As package repositories are not presently supported for Solaris pkgadd, this function will always return an empty string for a given package. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarispkg.install(name=None, sources=None, saltenv=\(aqbase\(aq, **kwargs) Install the passed package. Can install packages from the following sources: .INDENT 7.0 .IP \(bu 2 Locally (package already exists on the minion .IP \(bu 2 HTTP/HTTPS server .IP \(bu 2 FTP server .IP \(bu 2 Salt master .UNINDENT .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Installing a data stream pkg that already exists on the minion salt \(aq*\(aq pkg.install sources=\(aq[{\(dq<pkg name>\(dq: \(dq/dir/on/minion/<pkg filename>\(dq}]\(aq salt \(aq*\(aq pkg.install sources=\(aq[{\(dqSMClgcc346\(dq: \(dq/var/spool/pkg/gcc\-3.4.6\-sol10\-sparc\-local.pkg\(dq}]\(aq # Installing a data stream pkg that exists on the salt master salt \(aq*\(aq pkg.install sources=\(aq[{\(dq<pkg name>\(dq: \(dqsalt://pkgs/<pkg filename>\(dq}]\(aq salt \(aq*\(aq pkg.install sources=\(aq[{\(dqSMClgcc346\(dq: \(dqsalt://pkgs/gcc\-3.4.6\-sol10\-sparc\-local.pkg\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Installing a data stream pkg that exists on a HTTP server salt \(aq*\(aq pkg.install sources=\(aq[{\(dq<pkg name>\(dq: \(dqhttp://packages.server.com/<pkg filename>\(dq}]\(aq salt \(aq*\(aq pkg.install sources=\(aq[{\(dqSMClgcc346\(dq: \(dqhttp://packages.server.com/gcc\-3.4.6\-sol10\-sparc\-local.pkg\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .sp If working with solaris zones and you want to install a package only in the global zone you can pass \(aqcurrent_zone_only=True\(aq to salt to have the package only installed in the global zone. (Behind the scenes this is passing \(aq\-G\(aq to the pkgadd command.) Solaris default when installing a package in the global zone is to install it in all zones. This overrides that and installs the package only in the global. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Installing a data stream package only in the global zone: salt \(aqglobal_zone\(aq pkg.install sources=\(aq[{\(dqSMClgcc346\(dq: \(dq/var/spool/pkg/gcc\-3.4.6\-sol10\-sparc\-local.pkg\(dq}]\(aq current_zone_only=True .ft P .fi .UNINDENT .UNINDENT .sp By default salt automatically provides an adminfile, to automate package installation, with these options set: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C email= instance=quit partial=nocheck runlevel=nocheck idepend=nocheck rdepend=nocheck space=nocheck setuid=nocheck conflict=nocheck action=nocheck basedir=default .ft P .fi .UNINDENT .UNINDENT .sp You can override any of these options in two ways. First you can optionally pass any of the options as a kwarg to the module/state to override the default value or you can optionally pass the \(aqadmin_source\(aq option providing your own adminfile to the minions. .sp Note: You can find all of the possible options to provide to the adminfile by reading the admin man page: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C man \-s 4 admin .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Overriding the \(aqinstance\(aq adminfile option when calling the module directly salt \(aq*\(aq pkg.install sources=\(aq[{\(dq<pkg name>\(dq: \(dqsalt://pkgs/<pkg filename>\(dq}]\(aq instance=\(dqoverwrite\(dq .ft P .fi .UNINDENT .UNINDENT .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Overriding the \(aqinstance\(aq adminfile option when used in a state SMClgcc346: pkg.installed: \- sources: \- SMClgcc346: salt://srv/salt/pkgs/gcc\-3.4.6\-sol10\-sparc\-local.pkg \- instance: overwrite .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The ID declaration is ignored, as the package name is read from the \fBsources\fP parameter. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Providing your own adminfile when calling the module directly salt \(aq*\(aq pkg.install sources=\(aq[{\(dq<pkg name>\(dq: \(dqsalt://pkgs/<pkg filename>\(dq}]\(aq admin_source=\(aqsalt://pkgs/<adminfile filename>\(aq # Providing your own adminfile when using states <pkg name>: pkg.installed: \- sources: \- <pkg name>: salt://pkgs/<pkg filename> \- admin_source: salt://pkgs/<adminfile filename> .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The ID declaration is ignored, as the package name is read from the \fBsources\fP parameter. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarispkg.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 <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .sp NOTE: As package repositories are not presently supported for Solaris pkgadd, this function will always return an empty string for a given package. .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarispkg.list_pkgs(versions_as_list=False, **kwargs) List the packages currently installed as a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(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.solarispkg.purge(name=None, pkgs=None, **kwargs) Package purges are not supported, this function is identical to \fBremove()\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.purge <package name> salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3> salt \(aq*\(aq pkg.purge pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarispkg.remove(name=None, pkgs=None, saltenv=\(aqbase\(aq, **kwargs) Remove packages with pkgrm .INDENT 7.0 .TP .B name The name of the package to be deleted .UNINDENT .sp By default salt automatically provides an adminfile, to automate package removal, with these options set: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C email= instance=quit partial=nocheck runlevel=nocheck idepend=nocheck rdepend=nocheck space=nocheck setuid=nocheck conflict=nocheck action=nocheck basedir=default .ft P .fi .UNINDENT .UNINDENT .sp You can override any of these options in two ways. First you can optionally pass any of the options as a kwarg to the module/state to override the default value or you can optionally pass the \(aqadmin_source\(aq option providing your own adminfile to the minions. .sp Note: You can find all of the possible options to provide to the adminfile by reading the admin man page: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C man \-s 4 admin .ft P .fi .UNINDENT .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 <package name> salt \(aq*\(aq pkg.remove SUNWgit salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarispkg.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 <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solarispkg.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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.solr .sp Apache Solr Salt Module .sp Author: Jed Glazner Version: 0.2.1 Modified: 12/09/2011 .sp This module uses HTTP requests to talk to the apache solr request handlers to gather information and report errors. Because of this the minion doesn\(aqt necessarily need to reside on the actual slave. However if you want to use the signal function the minion must reside on the physical solr host. .sp This module supports multi\-core and standard setups. Certain methods are master/slave specific. Make sure you set the solr.type. If you have questions or want a feature request please ask. .SS Coming Features in 0.3 .INDENT 0.0 .IP 1. 3 Add command for checking for replication failures on slaves .IP 2. 3 Improve match_index_versions since it\(aqs pointless on busy solr masters .IP 3. 3 Add additional local fs checks for backups to make sure they succeeded .UNINDENT .SS Override these in the minion config .INDENT 0.0 .TP .B solr.cores A list of core names e.g. [\(aqcore1\(aq,\(aqcore2\(aq]. An empty list indicates non\-multicore setup. .TP .B solr.baseurl The root level URL to access solr via HTTP .TP .B solr.request_timeout The number of seconds before timing out an HTTP/HTTPS/FTP request. If nothing is specified then the python global timeout setting is used. .TP .B solr.type Possible values are \(aqmaster\(aq or \(aqslave\(aq .TP .B solr.backup_path The path to store your backups. If you are using cores and you can specify to append the core name to the path in the backup method. .TP .B solr.num_backups For versions of solr >= 3.5. Indicates the number of backups to keep. This option is ignored if your version is less. .TP .B solr.init_script The full path to your init script with start/stop options .TP .B solr.dih.options A list of options to pass to the DIH. .UNINDENT .SS Required Options for DIH .INDENT 0.0 .TP .B clean False Clear the index before importing .TP .B commit True Commit the documents to the index upon completion .TP .B optimize True Optimize the index after commit is complete .TP .B verbose True Get verbose output .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.abort_import(handler, host=None, core_name=None, verbose=False) MASTER ONLY Aborts an existing import command to the specified handler. This command can only be run if the minion is configured with solr.type=master .INDENT 7.0 .TP .B handler str The name of the data import handler. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core str (None) The core the handler belongs to. .TP .B verbose boolean (False) Run the command with verbose output. .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.abort_import dataimport None music {\(aqclean\(aq:True} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.backup(host=None, core_name=None, append_core_to_path=False) Tell solr make a backup. This method can be mis\-leading since it uses the backup API. If an error happens during the backup you are not notified. The status: \(aqOK\(aq in the response simply means that solr received the request successfully. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .TP .B append_core_to_path boolean (False) If True add the name of the core to the backup path. Assumes that minion backup path is not None. .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.backup music .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.core_status(host=None, core_name=None) MULTI\-CORE HOSTS ONLY Get the status for a given core or all cores if no core is specified .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str The name of the core to reload .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.core_status None music .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.delta_import(handler, host=None, core_name=None, options=None, extra=None) Submits an import command to the specified handler using specified options. This command can only be run if the minion is configured with solr.type=master .INDENT 7.0 .TP .B handler str The name of the data import handler. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core str (None) The core the handler belongs to. .TP .B options dict (__opts__) A list of options such as clean, optimize commit, verbose, and pause_replication. leave blank to use __opts__ defaults. options will be merged with __opts__ .TP .B extra dict ([]) Extra name value pairs to pass to the handler. e.g. [\(dqname=value\(dq] .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.delta_import dataimport None music {\(aqclean\(aq:True} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.full_import(handler, host=None, core_name=None, options=None, extra=None) MASTER ONLY Submits an import command to the specified handler using specified options. This command can only be run if the minion is configured with solr.type=master .INDENT 7.0 .TP .B handler str The name of the data import handler. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core str (None) The core the handler belongs to. .TP .B options dict (__opts__) A list of options such as clean, optimize commit, verbose, and pause_replication. leave blank to use __opts__ defaults. options will be merged with __opts__ .TP .B extra dict ([]) Extra name value pairs to pass to the handler. e.g. [\(dqname=value\(dq] .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.full_import dataimport None music {\(aqclean\(aq:True} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.import_status(handler, host=None, core_name=None, verbose=False) Submits an import command to the specified handler using specified options. This command can only be run if the minion is configured with solr.type: \(aqmaster\(aq .INDENT 7.0 .TP .B handler str The name of the data import handler. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core str (None) The core the handler belongs to. .TP .B verbose boolean (False) Specifies verbose output .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.import_status dataimport None music False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.is_replication_enabled(host=None, core_name=None) SLAVE CALL Check for errors, and determine if a slave is replicating or not. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.is_replication_enabled music .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.lucene_version(core_name=None) Gets the lucene version that solr is using. If you are running a multi\-core setup you should specify a core name since all the cores run under the same servlet container, they will all have the same version. .INDENT 7.0 .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return: dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.lucene_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.match_index_versions(host=None, core_name=None) SLAVE CALL Verifies that the master and the slave versions are in sync by comparing the index version. If you are constantly pushing updates the index the master and slave versions will seldom match. A solution to this is pause indexing every so often to allow the slave to replicate and then call this method before allowing indexing to resume. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.match_index_versions music .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.optimize(host=None, core_name=None) Search queries fast, but it is a very expensive operation. The ideal process is to run this with a master/slave configuration. Then you can optimize the master, and push the optimized index to the slaves. If you are running a single solr instance, or if you are going to run this on a slave be aware than search performance will be horrible while this command is being run. Additionally it can take a LONG time to run and your HTTP request may timeout. If that happens adjust your timeout settings. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.optimize music .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.ping(host=None, core_name=None) Does a health check on solr, makes sure solr can talk to the indexes. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.ping music .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.reload_core(host=None, core_name=None) MULTI\-CORE HOSTS ONLY Load a new core from the same configuration as an existing registered core. While the \(dqnew\(dq core is initializing, the \(dqold\(dq one will continue to accept requests. Once it has finished, all new request will go to the \(dqnew\(dq core, and the \(dqold\(dq core will be unloaded. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str The name of the core to reload .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.reload_core None music .ft P .fi .UNINDENT .UNINDENT .sp Return data is in the following format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:bool, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.reload_import_config(handler, host=None, core_name=None, verbose=False) MASTER ONLY re\-loads the handler config XML file. This command can only be run if the minion is a \(aqmaster\(aq type .INDENT 7.0 .TP .B handler str The name of the data import handler. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core str (None) The core the handler belongs to. .TP .B verbose boolean (False) Run the command with verbose output. .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.reload_import_config dataimport None music {\(aqclean\(aq:True} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.replication_details(host=None, core_name=None) Get the full replication details. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.replication_details music .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.set_is_polling(polling, host=None, core_name=None) SLAVE CALL Prevent the slaves from polling the master for updates. .INDENT 7.0 .TP .B polling boolean True will enable polling. False will disable it. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.set_is_polling False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.set_replication_enabled(status, host=None, core_name=None) MASTER ONLY Sets the master to ignore poll requests from the slaves. Useful when you don\(aqt want the slaves replicating during indexing or when clearing the index. .INDENT 7.0 .TP .B status boolean Sets the replication status to the specified state. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to set the status on all cores. .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.set_replication_enabled false, None, music .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.signal(signal=None) Signals Apache Solr to start, stop, or restart. Obviously this is only going to work if the minion resides on the solr host. Additionally Solr doesn\(aqt ship with an init script so one must be created. .INDENT 7.0 .TP .B signal str (None) The command to pass to the apache solr init valid values are \(aqstart\(aq, \(aqstop\(aq, and \(aqrestart\(aq .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.signal restart .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.version(core_name=None) Gets the solr version for the core specified. You should specify a core here as all the cores will run under the same servlet container and so will all have the same version. .INDENT 7.0 .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solr.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.solrcloud .sp Module for solrcloud configuration .sp New in version 2017.7.0. .sp For now, module is limited to http\-exposed API. It doesn\(aqt implement config upload via Solr zkCli .INDENT 0.0 .TP .B salt.modules.solrcloud.BOOL_PROPS_LIST = [\(aqtransient\(aq, \(aqloadOnStartup\(aq] Collections options type definition Reference: \fI\%https://cwiki.apache.org/confluence/display/solr/Collections+API#CollectionsAPI\-api1\fP .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.DICT_OPTIONS_LIST = [\(aqproperties\(aq] Collection unmodifiable options Reference: \fI\%https://cwiki.apache.org/confluence/display/solr/Collections+API#CollectionsAPI\-modifycoll\fP .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.alias_exists(alias_name, **kwargs) Check alias existence .sp Additional parameters (kwargs) may be passed, they will be proxied to http.query .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.alias_exists my_alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.alias_get_collections(alias_name, **kwargs) Get collection list for an alias .sp Additional parameters (kwargs) may be passed, they will be proxied to http.query .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.alias_get my_alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.alias_set_collections(alias_name, collections=None, **kwargs) Define an alias .sp Additional parameters (kwargs) may be passed, they will be proxied to http.query .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.alias_set my_alias collections=[collection1, colletion2] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.cluster_status(**kwargs) Get cluster status .sp Additional parameters (kwargs) may be passed, they will be proxied to http.query .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.cluster_status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.collection_backup(collection_name, location, backup_name=None, **kwargs) Create a backup for a collection. .sp Additional parameters (kwargs) may be passed, they will be proxied to http.query .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.core_backup collection_name /mnt/nfs_backup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.collection_backup_all(location, backup_name=None, **kwargs) Create a backup for all collection present on the server. .sp Additional parameters (kwargs) may be passed, they will be proxied to http.query .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.core_backup /mnt/nfs_backup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.collection_check_options(options) Check collections options .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.collection_check_options \(aq{\(dqreplicationFactor\(dq:4}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.collection_create(collection_name, options=None, **kwargs) Create a collection, .sp Additional parameters (kwargs) may be passed, they will be proxied to http.query .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.collection_create collection_name .ft P .fi .UNINDENT .UNINDENT .sp Collection creation options may be passed using the \(dqoptions\(dq parameter. Do not include option \(dqname\(dq since it already specified by the mandatory parameter \(dqcollection_name\(dq .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.collection_create collection_name options={\(dqreplicationFactor\(dq:2, \(dqnumShards\(dq:3} .ft P .fi .UNINDENT .UNINDENT .sp Cores options may be passed using the \(dqproperties\(dq key in options. Do not include property \(dqname\(dq .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.collection_create collection_name options={\(dqreplicationFactor\(dq:2, \(dqnumShards\(dq:3, \(dqproperties\(dq:{\(dqdataDir\(dq:\(dq/srv/solr/hugePartitionSollection\(dq}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.collection_creation_options() Get collection option list that can only be defined at creation .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.collection_creation_options .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.collection_exists(collection_name, **kwargs) Check if a collection exists .sp Additional parameters (kwargs) may be passed, they will be proxied to http.query .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.collection_exists collection_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.collection_get_options(collection_name, **kwargs) Get collection options .sp Additional parameters (kwargs) may be passed, they will be proxied to http.query .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.collection_get_options collection_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.collection_list(**kwargs) List all collections .sp Additional parameters (kwargs) may be passed, they will be proxied to http.query .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.collection_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.collection_reload(collection, **kwargs) Check if a collection exists .sp Additional parameters (kwargs) may be passed, they will be proxied to http.query .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.collection_reload collection_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.collection_set_options(collection_name, options, **kwargs) Change collection options .sp Additional parameters (kwargs) may be passed, they will be proxied to http.query .sp Note that not every parameter can be changed after collection creation .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq solrcloud.collection_set_options collection_name options={\(dqreplicationFactor\(dq:4} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.solrcloud.log = <SaltLoggingClass salt.modules.solrcloud (GARBAGE)> Core properties type definition. Reference: \fI\%https://cwiki.apache.org/confluence/display/solr/Defining+core.properties\fP .UNINDENT .SS salt.modules.splunk .sp Module for interop with the Splunk API .sp New in version 2016.3.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 splunk\-sdk python module .UNINDENT .TP .B configuration Configure this module by specifying the name of a configuration profile in the minion config, minion pillar, or master config. The module will use the \(aqsplunk\(aq key by default, if defined. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C splunk: username: alice password: abc123 host: example.splunkcloud.com port: 8080 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.splunk.create_user(email, profile=\(aqsplunk\(aq, **kwargs) create a splunk user by name/email .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion splunk.create_user user@example.com roles=[\(aquser\(aq] realname=\(dqTest User\(dq name=testuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.splunk.delete_user(email, profile=\(aqsplunk\(aq) Delete a splunk user by email .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion splunk_user.delete \(aquser@example.com\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.splunk.get_user(email, profile=\(aqsplunk\(aq, **kwargs) Get a splunk user by name/email .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion splunk.get_user \(aquser@example.com\(aq user_details=false salt myminion splunk.get_user \(aquser@example.com\(aq user_details=true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.splunk.list_users(profile=\(aqsplunk\(aq) List all users in the splunk DB .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion splunk.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.splunk.update_user(email, profile=\(aqsplunk\(aq, **kwargs) Create a splunk user by email .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion splunk.update_user example@domain.com roles=[\(aquser\(aq] realname=\(dqTest User\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.splunk_search .sp Module for interop with the Splunk API .sp New in version 2015.5.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 splunk\-sdk python module .UNINDENT .TP .B configuration Configure this module by specifying the name of a configuration profile in the minion config, minion pillar, or master config. The module will use the \(aqsplunk\(aq key by default, if defined. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C splunk: username: alice password: abc123 host: example.splunkcloud.com port: 8080 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.splunk_search.create(name, profile=\(aqsplunk\(aq, **kwargs) Create a splunk search .sp CLI Example: .INDENT 7.0 .INDENT 3.5 splunk_search.create \(aqmy search name\(aq search=\(aqerror msg\(aq .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.splunk_search.delete(name, profile=\(aqsplunk\(aq) Delete a splunk search .sp CLI Example: .INDENT 7.0 .INDENT 3.5 splunk_search.delete \(aqmy search name\(aq .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.splunk_search.get(name, profile=\(aqsplunk\(aq) Get a splunk search .sp CLI Example: .INDENT 7.0 .INDENT 3.5 splunk_search.get \(aqmy search name\(aq .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.splunk_search.list_(profile=\(aqsplunk\(aq) List splunk searches (names only) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 splunk_search.list .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.splunk_search.list_all(prefix=None, app=None, owner=None, description_contains=None, name_not_contains=None, profile=\(aqsplunk\(aq) Get all splunk search details. Produces results that can be used to create an sls file. .sp if app or owner are specified, results will be limited to matching saved searches. .sp if description_contains is specified, results will be limited to those where \(dqdescription_contains in description\(dq is true if name_not_contains is specified, results will be limited to those where \(dqname_not_contains not in name\(dq is true. .sp If prefix parameter is given, alarm names in the output will be prepended with the prefix; alarms that have the prefix will be skipped. This can be used to convert existing alarms to be managed by salt, as follows: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 .INDENT 3.0 .TP .B Make a \(dqbackup\(dq of all existing searches $ salt\-call splunk_search.list_all \-\-out=txt | sed \(dqs/local: //\(dq > legacy_searches.sls .UNINDENT .IP 2. 3 .INDENT 3.0 .TP .B Get all searches with new prefixed names $ salt\-call splunk_search.list_all \(dqprefix=**MANAGED BY SALT** \(dq \-\-out=txt | sed \(dqs/local: //\(dq > managed_searches.sls .UNINDENT .IP 3. 3 .INDENT 3.0 .TP .B Insert the managed searches into splunk $ salt\-call state.sls managed_searches.sls .UNINDENT .IP 4. 3 Manually verify that the new searches look right .IP 5. 3 Delete the original searches $ sed s/present/absent/ legacy_searches.sls > remove_legacy_searches.sls $ salt\-call state.sls remove_legacy_searches.sls .IP 6. 3 Get all searches again, verify no changes $ salt\-call splunk_search.list_all \-\-out=txt | sed \(dqs/local: //\(dq > final_searches.sls $ diff final_searches.sls managed_searches.sls .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.splunk_search.update(name, profile=\(aqsplunk\(aq, **kwargs) Update a splunk search .sp CLI Example: .INDENT 7.0 .INDENT 3.5 splunk_search.update \(aqmy search name\(aq sharing=app .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.sqlite3 .sp Support for SQLite3 .INDENT 0.0 .TP .B salt.modules.sqlite3.fetch(db=None, sql=None) Retrieve data from an sqlite3 db (returns all rows, be careful!) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sqlite3.fetch /root/test.db \(aqSELECT * FROM test;\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sqlite3.indexes(db=None) Show all indices in the database, for people with poor spelling skills .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sqlite3.indexes /root/test.db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sqlite3.indices(db=None) Show all indices in the database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sqlite3.indices /root/test.db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sqlite3.modify(db=None, sql=None) Issue an SQL query to sqlite3 (with no return data), usually used to modify the database in some way (insert, delete, create, etc) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sqlite3.modify /root/test.db \(aqCREATE TABLE test(id INT, testdata TEXT);\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sqlite3.sqlite_version() Return version of sqlite .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sqlite3.sqlite_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sqlite3.tables(db=None) Show all tables in the database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sqlite3.tables /root/test.db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sqlite3.version() Return version of pysqlite .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sqlite3.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ssh .sp Manage client ssh components .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This module requires the use of MD5 hashing. Certain security audits may not permit the use of MD5. For those cases, this module should be disabled or removed. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.auth_keys(user=None, config=\(aq.ssh/authorized_keys\(aq, fingerprint_hash_type=None) Return the authorized keys for users .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.auth_keys salt \(aq*\(aq ssh.auth_keys root salt \(aq*\(aq ssh.auth_keys user=root salt \(aq*\(aq ssh.auth_keys user=\(dq[user1, user2]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.check_key(user, key, enc, comment, options, config=\(aq.ssh/authorized_keys\(aq, cache_keys=None, fingerprint_hash_type=None) Check to see if a key needs updating, returns \(dqupdate\(dq, \(dqadd\(dq or \(dqexists\(dq .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.check_key <user> <key> <enc> <comment> <options> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.check_key_file(user, source, config=\(aq.ssh/authorized_keys\(aq, saltenv=\(aqbase\(aq, fingerprint_hash_type=None) Check a keyfile from a source destination against the local keys and return the keys to change .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.check_key_file root salt://ssh/keyfile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.check_known_host(user=None, hostname=None, key=None, fingerprint=None, config=None, port=None, fingerprint_hash_type=None) Check the record in known_hosts file, either by its value or by fingerprint (it\(aqs enough to set up either key or fingerprint, you don\(aqt need to set up both). .sp If provided key or fingerprint doesn\(aqt match with stored value, return \(dqupdate\(dq, if no value is found for a given host, return \(dqadd\(dq, otherwise return \(dqexists\(dq. .sp If neither key, nor fingerprint is defined, then additional validation is not performed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.check_known_host <user> <hostname> key=\(aqAAAA...FAaQ==\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.get_known_host_entries(user, hostname, config=None, port=None, fingerprint_hash_type=None) New in version 2018.3.0. .sp Return information about known host entries from the configfile, if any. If there are no entries for a matching hostname, return None. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.get_known_host_entries <user> <hostname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.hash_known_hosts(user=None, config=None) Hash all the hostnames in the known hosts file. .sp New in version 2014.7.0. .INDENT 7.0 .TP .B user hash known hosts of this user .TP .B config path to known hosts file: can be absolute or relative to user\(aqs home directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.hash_known_hosts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.host_keys(keydir=None, private=True, certs=True) Return the minion\(aqs host keys .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.host_keys salt \(aq*\(aq ssh.host_keys keydir=/etc/ssh salt \(aq*\(aq ssh.host_keys keydir=/etc/ssh private=False salt \(aq*\(aq ssh.host_keys keydir=/etc/ssh certs=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.key_is_encrypted(key) New in version 2015.8.7. .sp Function to determine whether or not a private key is encrypted with a passphrase. .sp Checks key for a \fBProc\-Type\fP header with \fBENCRYPTED\fP in the value. If found, returns \fBTrue\fP, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.key_is_encrypted /root/id_rsa .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.recv_known_host_entries(hostname, enc=None, port=None, hash_known_hosts=True, timeout=5, fingerprint_hash_type=None) New in version 2018.3.0. .sp Retrieve information about host public keys from remote server .INDENT 7.0 .TP .B hostname The name of the remote host (e.g. \(dqgithub.com\(dq) .TP .B enc Defines what type of key is being used, can be ed25519, ecdsa, ssh\-rsa, ssh\-dss or any other type as of openssh server version 8.7. .TP .B port Optional parameter, denoting the port of the remote host on which an SSH daemon is running. By default the port 22 is used. .TP .B hash_known_hosts True Hash all hostnames and addresses in the known hosts file. .TP .B timeout int Set the timeout for connection attempts. If \fBtimeout\fP seconds have elapsed since a connection was initiated to a host or since the last time anything was read from that host, then the connection is closed and the host in question considered unavailable. Default is 5 seconds. .TP .B fingerprint_hash_type The fingerprint hash type that the public key fingerprints were originally hashed with. This defaults to \fBsha256\fP if not specified. .sp New in version 2016.11.4. .sp Changed in version 2017.7.0: default changed from \fBmd5\fP to \fBsha256\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.recv_known_host_entries <hostname> enc=<enc> port=<port> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.rm_auth_key(user, key, config=\(aq.ssh/authorized_keys\(aq, fingerprint_hash_type=None) Remove an authorized key from the specified user\(aqs authorized key file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.rm_auth_key <user> <key> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.rm_auth_key_from_file(user, source, config=\(aq.ssh/authorized_keys\(aq, saltenv=\(aqbase\(aq, fingerprint_hash_type=None) Remove an authorized key from the specified user\(aqs authorized key file, using a file as source .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.rm_auth_key_from_file <user> salt://ssh_keys/<user>.id_rsa.pub .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.rm_known_host(user=None, hostname=None, config=None, port=None) Remove all keys belonging to hostname from a known_hosts file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.rm_known_host <user> <hostname> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.set_auth_key(user, key, enc=\(aqssh\-rsa\(aq, comment=\(aq\(aq, options=None, config=\(aq.ssh/authorized_keys\(aq, cache_keys=None, fingerprint_hash_type=None) Add a key to the authorized_keys file. The \(dqkey\(dq parameter must only be the string of text that is the encoded key. If the key begins with \(dqssh\-rsa\(dq or ends with \fI\%user@host\fP, remove those from the key before passing it to this function. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.set_auth_key <user> \(aq<key>\(aq enc=\(aqdsa\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.set_auth_key_from_file(user, source, config=\(aq.ssh/authorized_keys\(aq, saltenv=\(aqbase\(aq, fingerprint_hash_type=None) Add a key to the authorized_keys file, using a file as the source. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.set_auth_key_from_file <user> salt://ssh_keys/<user>.id_rsa.pub .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.set_known_host(user=None, hostname=None, fingerprint=None, key=None, port=None, enc=None, config=None, hash_known_hosts=True, timeout=5, fingerprint_hash_type=None) Download SSH public key from remote host \(dqhostname\(dq, optionally validate its fingerprint against \(dqfingerprint\(dq variable and save the record in the known_hosts file. .sp If such a record does already exists in there, do nothing. .INDENT 7.0 .TP .B user The user who owns the ssh authorized keys file to modify .TP .B hostname The name of the remote host (e.g. \(dqgithub.com\(dq) .TP .B fingerprint The fingerprint of the key which must be present in the known_hosts file (optional if key specified) .TP .B key The public key which must be presented in the known_hosts file (optional if fingerprint specified) .TP .B port optional parameter, denoting the port of the remote host, which will be used in case, if the public key will be requested from it. By default the port 22 is used. .TP .B enc Defines what type of key is being used, can be ed25519, ecdsa, ssh\-rsa, ssh\-dss or any other type as of openssh server version 8.7. .TP .B config The location of the authorized keys file relative to the user\(aqs home directory, defaults to \(dq.ssh/known_hosts\(dq. If no user is specified, defaults to \(dq/etc/ssh/ssh_known_hosts\(dq. If present, must be an absolute path when a user is not specified. .TP .B hash_known_hosts True Hash all hostnames and addresses in the known hosts file. .TP .B timeout int Set the timeout for connection attempts. If \fBtimeout\fP seconds have elapsed since a connection was initiated to a host or since the last time anything was read from that host, then the connection is closed and the host in question considered unavailable. Default is 5 seconds. .sp New in version 2016.3.0. .TP .B fingerprint_hash_type The public key fingerprint hash type that the public key fingerprint was originally hashed with. This defaults to \fBsha256\fP if not specified. .sp New in version 2016.11.4. .sp Changed in version 2017.7.0: default changed from \fBmd5\fP to \fBsha256\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.set_known_host <user> fingerprint=\(aqxx:xx:..:xx\(aq enc=\(aqssh\-rsa\(aq config=\(aq.ssh/known_hosts\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.user_keys(user=None, pubfile=None, prvfile=None) Return the user\(aqs ssh keys on the minion .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ssh.user_keys salt \(aq*\(aq ssh.user_keys user=user1 salt \(aq*\(aq ssh.user_keys user=user1 pubfile=/home/user1/.ssh/id_rsa.pub prvfile=/home/user1/.ssh/id_rsa salt \(aq*\(aq ssh.user_keys user=user1 prvfile=False salt \(aq*\(aq ssh.user_keys user=\(dq[\(aquser1\(aq,\(aquser2\(aq] pubfile=id_rsa.pub prvfile=id_rsa .ft P .fi .UNINDENT .UNINDENT .sp As you can see you can tell Salt not to read from the user\(aqs private (or public) key file by setting the file path to \fBFalse\fP\&. This can be useful to prevent Salt from publishing private data via Salt Mine or others. .UNINDENT .SS salt.modules.ssh_pkg .sp Service support for the REST example .INDENT 0.0 .TP .B salt.modules.ssh_pkg.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh_pkg.list_pkgs(versions_as_list=False, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh_pkg.remove(name=None, pkgs=None, **kwargs) .UNINDENT .SS salt.modules.ssh_service .sp Provide the service module for the proxy\-minion SSH sample \&.. versionadded:: 2015.8.2 .INDENT 0.0 .TP .B salt.modules.ssh_service.enabled(name, sig=None) Only the \(aqredbull\(aq service is \(aqenabled\(aq in the test .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh_service.get_all() Return a list of all available services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh_service.list_() Return a list of all available services. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh_service.restart(name, sig=None) Restart the specified service with rest_sample .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh_service.running(name, sig=None) Return whether this service is running. .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh_service.start(name, sig=None) Start the specified service on the ssh_sample .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh_service.status(name, sig=None) Return the status for a service via ssh_sample. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Not implemented .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh_service.stop(name, sig=None) Stop the specified service on the rest_sample .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.state .sp Control the state system on the minion. .SS State Caching .sp When a highstate is called, the minion automatically caches a copy of the last high data. If you then run a highstate with cache=True it will use that cached highdata and won\(aqt hit the fileserver except for \fBsalt://\fP links in the states themselves. .INDENT 0.0 .TP .B salt.modules.state.apply_(mods=None, **kwargs) New in version 2015.5.0. .sp This function will call \fI\%state.highstate\fP or \fI\%state.sls\fP based on the arguments passed to this function. It exists as a more intuitive way of applying states. .sp APPLYING ALL STATES CONFIGURED IN TOP.SLS (A.K.A. \fI\%HIGHSTATE\fP) .sp To apply all configured states, simply run \fBstate.apply\fP with no SLS targets, like so: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply .ft P .fi .UNINDENT .UNINDENT .sp The following additional arguments are also accepted when applying all states configured in top.sls: .INDENT 7.0 .TP .B test Run states in test\-only (dry\-run) mode .TP .B mock The mock option allows for the state run to execute without actually calling any states. This then returns a mocked return which will show the requisite ordering as well as fully validate the state run. .sp New in version 2015.8.4. .TP .B pillar Custom Pillar values, passed as a dictionary of key\-value pairs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply stuff pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Values passed this way will override Pillar values set via \fBpillar_roots\fP or an external Pillar source. .UNINDENT .UNINDENT .TP .B exclude Exclude specific states from execution. Accepts a list of sls names, a comma\-separated string of sls names, or a list of dictionaries containing \fBsls\fP or \fBid\fP keys. Glob\-patterns may be used to match multiple states. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply exclude=bar,baz salt \(aq*\(aq state.apply exclude=foo* salt \(aq*\(aq state.apply exclude=\(dq[{\(aqid\(aq: \(aqid_to_exclude\(aq}, {\(aqsls\(aq: \(aqsls_to_exclude\(aq}]\(dq .ft P .fi .UNINDENT .UNINDENT .TP .B queue False Instead of failing immediately when another state run is in progress, a value of \fBTrue\fP will queue the new state run to begin running once the other has finished. .sp This option starts a new thread for each queued state run, so use this option sparingly. .sp Changed in version 3006.0: This parameter can also be set via the \fBstate_queue\fP configuration option. Additionally, it can now be set to an integer representing the maximum queue size which can be attained before the state runs will fail to be queued. This can prevent runaway conditions where new threads are started until system performance is hampered. .TP .B localconfig Optionally, instead of using the minion config, load minion opts from the file specified by this argument, and then merge them with the options from the minion config. This functionality allows for specific states to be run with their own custom minion configuration, including different pillars, file_roots, etc. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply localconfig=/path/to/minion.yml .ft P .fi .UNINDENT .UNINDENT .TP .B state_events The state_events option sends progress events as each function in a state run completes execution. .sp New in version 3006.0. .UNINDENT .sp APPLYING INDIVIDUAL SLS FILES (A.K.A. \fI\%STATE.SLS\fP) .sp To apply individual SLS files, pass them as a comma\-separated list: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Run the states configured in salt://stuff.sls (or salt://stuff/init.sls) salt \(aq*\(aq state.apply stuff # Run the states configured in salt://stuff.sls (or salt://stuff/init.sls) # and salt://pkgs.sls (or salt://pkgs/init.sls). salt \(aq*\(aq state.apply stuff,pkgs # Run the states configured in a more deeply nested directory such as salt://my/organized/stuff.sls (or salt://my/organized/stuff/init.sls) salt \(aq*\(aq state.apply my.organized.stuff .ft P .fi .UNINDENT .UNINDENT .sp The following additional arguments are also accepted when applying individual SLS files: .INDENT 7.0 .TP .B test Run states in test\-only (dry\-run) mode .TP .B mock The mock option allows for the state run to execute without actually calling any states. This then returns a mocked return which will show the requisite ordering as well as fully validate the state run. .sp New in version 2015.8.4. .TP .B pillar Custom Pillar values, passed as a dictionary of key\-value pairs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply stuff pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Values passed this way will override Pillar values set via \fBpillar_roots\fP or an external Pillar source. .UNINDENT .UNINDENT .TP .B queue False Instead of failing immediately when another state run is in progress, a value of \fBTrue\fP will queue the new state run to begin running once the other has finished. .sp This option starts a new thread for each queued state run, so use this option sparingly. .sp Changed in version 3006.0: This parameter can also be set via the \fBstate_queue\fP configuration option. Additionally, it can now be set to an integer representing the maximum queue size which can be attained before the state runs will fail to be queued. This can prevent runaway conditions where new threads are started until system performance is hampered. .TP .B concurrent False Execute state runs concurrently instead of serially .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This flag is potentially dangerous. It is designed for use when multiple state runs can safely be run at the same time. Do \fInot\fP use this flag for performance optimization. .UNINDENT .UNINDENT .TP .B saltenv Specify a salt fileserver environment to be used when applying states .sp Changed in version 0.17.0: Argument name changed from \fBenv\fP to \fBsaltenv\fP .sp Changed in version 2014.7.0: If no saltenv is specified, the minion config will be checked for an \fBenvironment\fP parameter and if found, it will be used. If none is found, \fBbase\fP will be used. In prior releases, the minion config was not checked and \fBbase\fP would always be assumed when the saltenv was not explicitly set. .TP .B pillarenv Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the \fI\%pillarenv\fP option. When neither the \fI\%pillarenv\fP minion config option nor this CLI argument is used, all Pillar environments will be merged together. .TP .B localconfig Optionally, instead of using the minion config, load minion opts from the file specified by this argument, and then merge them with the options from the minion config. This functionality allows for specific states to be run with their own custom minion configuration, including different pillars, file_roots, etc. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply stuff localconfig=/path/to/minion.yml .ft P .fi .UNINDENT .UNINDENT .TP .B sync_mods If specified, the desired custom module types will be synced prior to running the SLS files: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply stuff sync_mods=states,modules salt \(aq*\(aq state.apply stuff sync_mods=all .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is ignored when no SLS files are specified, as a \fI\%highstate\fP automatically syncs all custom module types. .UNINDENT .UNINDENT .sp New in version 2017.7.8,2018.3.3,2019.2.0. .TP .B state_events The state_events option sends progress events as each function in a state run completes execution. .sp New in version 3006.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.check_request(name=None) New in version 2015.5.0. .sp Return the state request information, if any .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.check_request .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.clear_cache() Clear out cached state files, forcing even cache runs to refresh the cache on the next state execution. .sp Remember that the state cache is completely disabled by default, this execution only applies if cache=True is used in states .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.clear_cache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.clear_request(name=None) New in version 2015.5.0. .sp Clear out the state execution request without executing it .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.clear_request .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.disable(states) Disable state runs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.disable highstate salt \(aq*\(aq state.disable highstate,test.succeed_without_changes .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To disable a state file from running provide the same name that would be passed in a state.sls call. .sp salt \(aq*\(aq state.disable bind.config .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.enable(states) Enable state function or sls run .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.enable highstate salt \(aq*\(aq state.enable test.succeed_without_changes .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To enable a state file from running provide the same name that would be passed in a state.sls call. .sp salt \(aq*\(aq state.disable bind.config .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.event(tagmatch=\(aq*\(aq, count=\-1, quiet=False, sock_dir=None, pretty=False, node=\(aqminion\(aq) Watch Salt\(aqs event bus and block until the given tag is matched .sp New in version 2016.3.0. .sp Changed in version 2019.2.0: \fBtagmatch\fP can now be either a glob or regular expression. .sp This is useful for utilizing Salt\(aqs event bus from shell scripts or for taking simple actions directly from the CLI. .sp Enable debug logging to see ignored events. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtagmatch\fP \-\- the event is written to stdout for each tag that matches this glob or regular expression. .IP \(bu 2 \fBcount\fP \-\- this number is decremented for each event that matches the \fBtagmatch\fP parameter; pass \fB\-1\fP to listen forever. .IP \(bu 2 \fBquiet\fP \-\- do not print to stdout; just block .IP \(bu 2 \fBsock_dir\fP \-\- path to the Salt master\(aqs event socket file. .IP \(bu 2 \fBpretty\fP \-\- Output the JSON all on a single line if \fBFalse\fP (useful for shell tools); pretty\-print the JSON output if \fBTrue\fP\&. .IP \(bu 2 \fBnode\fP \-\- Watch the minion\-side or master\-side event bus. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local state.event pretty=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.get_pauses(jid=None) Get a report on all of the currently paused state runs and pause run settings. Optionally send in a jid if you only desire to see a single pause data set. .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.high(data, test=None, queue=None, **kwargs) Execute the compound calls stored in a single set of high data .sp This function is mostly intended for testing the state system and is not likely to be needed in everyday usage. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.high \(aq{\(dqvim\(dq: {\(dqpkg\(dq: [\(dqinstalled\(dq]}}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.highstate(test=None, queue=None, state_events=None, **kwargs) Retrieve the state data from the salt master for this minion and execute it .INDENT 7.0 .TP .B test Run states in test\-only (dry\-run) mode .TP .B pillar Custom Pillar values, passed as a dictionary of key\-value pairs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.highstate stuff pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Values passed this way will override Pillar values set via \fBpillar_roots\fP or an external Pillar source. .UNINDENT .UNINDENT .sp Changed in version 2016.3.0: GPG\-encrypted CLI Pillar data is now supported via the GPG renderer. See \fI\%here\fP for details. .TP .B pillar_enc Specify which renderer to use to decrypt encrypted data located within the \fBpillar\fP value. Currently, only \fBgpg\fP is supported. .sp New in version 2016.3.0. .TP .B exclude Exclude specific states from execution. Accepts a list of sls names, a comma\-separated string of sls names, or a list of dictionaries containing \fBsls\fP or \fBid\fP keys. Glob\-patterns may be used to match multiple states. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.highstate exclude=bar,baz salt \(aq*\(aq state.highstate exclude=foo* salt \(aq*\(aq state.highstate exclude=\(dq[{\(aqid\(aq: \(aqid_to_exclude\(aq}, {\(aqsls\(aq: \(aqsls_to_exclude\(aq}]\(dq .ft P .fi .UNINDENT .UNINDENT .TP .B saltenv Specify a salt fileserver environment to be used when applying states .sp Changed in version 0.17.0: Argument name changed from \fBenv\fP to \fBsaltenv\fP\&. .sp Changed in version 2014.7.0: If no saltenv is specified, the minion config will be checked for a \fBsaltenv\fP parameter and if found, it will be used. If none is found, \fBbase\fP will be used. In prior releases, the minion config was not checked and \fBbase\fP would always be assumed when the saltenv was not explicitly set. .TP .B pillarenv Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the \fI\%pillarenv\fP option. When neither the \fI\%pillarenv\fP minion config option nor this CLI argument is used, all Pillar environments will be merged together. .TP .B queue False Instead of failing immediately when another state run is in progress, a value of \fBTrue\fP will queue the new state run to begin running once the other has finished. .sp This option starts a new thread for each queued state run, so use this option sparingly. .sp Changed in version 3006.0: This parameter can also be set via the \fBstate_queue\fP configuration option. Additionally, it can now be set to an integer representing the maximum queue size which can be attained before the state runs will fail to be queued. This can prevent runaway conditions where new threads are started until system performance is hampered. .TP .B concurrent False Execute state runs concurrently instead of serially .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This flag is potentially dangerous. It is designed for use when multiple state runs can safely be run at the same time. Do \fInot\fP use this flag for performance optimization. .UNINDENT .UNINDENT .TP .B localconfig Optionally, instead of using the minion config, load minion opts from the file specified by this argument, and then merge them with the options from the minion config. This functionality allows for specific states to be run with their own custom minion configuration, including different pillars, file_roots, etc. .TP .B mock The mock option allows for the state run to execute without actually calling any states. This then returns a mocked return which will show the requisite ordering as well as fully validate the state run. .sp New in version 2015.8.4. .TP .B state_events The state_events option sends progress events as each function in a state run completes execution. .sp New in version 3006.0. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.highstate salt \(aq*\(aq state.highstate whitelist=sls1_to_run,sls2_to_run salt \(aq*\(aq state.highstate exclude=sls_to_exclude salt \(aq*\(aq state.highstate exclude=\(dq[{\(aqid\(aq: \(aqid_to_exclude\(aq}, {\(aqsls\(aq: \(aqsls_to_exclude\(aq}]\(dq salt \(aq*\(aq state.highstate pillar=\(dq{foo: \(aqFoo!\(aq, bar: \(aqBar!\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.id_exists(ids, mods, test=None, queue=None, **kwargs) Tests for the existence of a specific ID or list of IDs within the specified SLS file(s). Similar to \fI\%state.sls_exists\fP, returns True or False. The default environment is base\(ga\(ga, use \fBsaltenv\fP to specify a different environment. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B saltenv Specify a salt fileserver environment from which to look for the SLS files specified in the \fBmods\fP argument .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.id_exists create_myfile,update_template filestate saltenv=dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.list_disabled() List the states which are currently disabled .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.list_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.low(data, queue=None, **kwargs) Execute a single low data call .sp This function is mostly intended for testing the state system and is not likely to be needed in everyday usage. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.low \(aq{\(dqstate\(dq: \(dqpkg\(dq, \(dqfun\(dq: \(dqinstalled\(dq, \(dqname\(dq: \(dqvi\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.orchestrate(mods, saltenv=\(aqbase\(aq, test=None, exclude=None, pillar=None, pillarenv=None) New in version 2016.11.0. .sp Execute the orchestrate runner from a masterless minion. .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 More Orchestrate documentation .INDENT 0.0 .IP \(bu 2 \fI\%Full Orchestrate Tutorial\fP .IP \(bu 2 Docs for the salt state module \fI\%salt.states.saltmod\fP .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local state.orchestrate webserver salt\-call \-\-local state.orchestrate webserver saltenv=dev test=True salt\-call \-\-local state.orchestrate webserver saltenv=dev pillarenv=aws .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.pause(jid, state_id=None, duration=None) Set up a state id pause, this instructs a running state to pause at a given state id. This needs to pass in the jid of the running state and can optionally pass in a duration in seconds. If a state_id is not passed then the jid referenced will be paused at the beginning of the next state run. .sp The given state id is the id got a given state execution, so given a state that looks like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed: [] .ft P .fi .UNINDENT .UNINDENT .sp The state_id to pass to \fIpause\fP is \fIvim\fP .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.pause 20171130110407769519 salt \(aq*\(aq state.pause 20171130110407769519 vim salt \(aq*\(aq state.pause 20171130110407769519 vim 20 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.pkg(pkg_path, pkg_sum, hash_type, test=None, **kwargs) Execute a packaged state run, the packaged state run will exist in a tarball available locally. This packaged state can be generated using salt\-ssh. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.pkg /tmp/salt_state.tgz 760a9353810e36f6d81416366fc426dc md5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.request(mods=None, **kwargs) New in version 2015.5.0. .sp Request that the local admin execute a state run via \fIsalt\-call state.run_request\fP\&. All arguments match those of state.apply. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.request salt \(aq*\(aq state.request stuff salt \(aq*\(aq state.request stuff,pkgs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.resume(jid, state_id=None) Remove a pause from a jid, allowing it to continue. If the state_id is not specified then the a general pause will be resumed. .sp The given state_id is the id got a given state execution, so given a state that looks like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed: [] .ft P .fi .UNINDENT .UNINDENT .sp The state_id to pass to \fIrm_pause\fP is \fIvim\fP .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.resume 20171130110407769519 salt \(aq*\(aq state.resume 20171130110407769519 vim .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.run_request(name=\(aqdefault\(aq, **kwargs) New in version 2015.5.0. .sp Execute the pending state request .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.run_request .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.running(concurrent=False) Return a list of strings that contain state return data if a state function is already running. This function is used to prevent multiple state calls from being run at the same time. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.running .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.show_highstate(queue=None, **kwargs) Retrieve the highstate data from the salt master and display it .sp Custom Pillar data can be passed with the \fBpillar\fP kwarg. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.show_highstate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.show_low_sls(mods, test=None, queue=None, **kwargs) Display the low data from a specific sls. The default environment is \fBbase\fP, use \fBsaltenv\fP to specify a different environment. .INDENT 7.0 .TP .B saltenv Specify a salt fileserver environment to be used when applying states .TP .B pillar Custom Pillar values, passed as a dictionary of key\-value pairs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.show_low_sls stuff pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Values passed this way will override Pillar values set via \fBpillar_roots\fP or an external Pillar source. .UNINDENT .UNINDENT .TP .B pillarenv Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the \fI\%pillarenv\fP option. When neither the \fI\%pillarenv\fP minion config option nor this CLI argument is used, all Pillar environments will be merged together. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.show_low_sls foo salt \(aq*\(aq state.show_low_sls foo saltenv=dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.show_lowstate(queue=None, **kwargs) List out the low data that will be applied to this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.show_lowstate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.show_sls(mods, test=None, queue=None, **kwargs) Display the state data from a specific sls or list of sls files on the master. The default environment is \fBbase\fP, use \fBsaltenv\fP to specify a different environment. .sp This function does not support topfiles. For \fBtop.sls\fP please use \fBshow_top\fP instead. .sp Custom Pillar data can be passed with the \fBpillar\fP kwarg. .INDENT 7.0 .TP .B saltenv Specify a salt fileserver environment to be used when applying states .TP .B pillarenv Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the \fI\%pillarenv\fP option. When neither the \fI\%pillarenv\fP minion config option nor this CLI argument is used, all Pillar environments will be merged together. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.show_sls core,edit.vim saltenv=dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.show_state_usage(queue=None, **kwargs) Retrieve the highstate data from the salt master to analyse used and unused states .sp Custom Pillar data can be passed with the \fBpillar\fP kwarg. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.show_state_usage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.show_states(queue=None, **kwargs) Returns the list of states that will be applied on highstate. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.show_states .ft P .fi .UNINDENT .UNINDENT .sp New in version 2019.2.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.show_top(queue=None, **kwargs) Return the top data that the minion will use for a highstate .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.show_top .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.single(fun, name, test=None, queue=None, **kwargs) Execute a single state function with the named kwargs, returns False if insufficient data is sent to the command .sp By default, the values of the kwargs will be parsed as YAML. So, you can specify lists values, or lists of single entry key\-value maps, as you would in a YAML salt file. Alternatively, JSON format of keyword values is also supported. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.single pkg.installed name=vim .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.sls(mods, test=None, exclude=None, queue=None, sync_mods=None, state_events=None, **kwargs) Execute the states in one or more SLS files .INDENT 7.0 .TP .B test Run states in test\-only (dry\-run) mode .TP .B pillar Custom Pillar values, passed as a dictionary of key\-value pairs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.sls stuff pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Values passed this way will override existing Pillar values set via \fBpillar_roots\fP or an external Pillar source. Pillar values that are not included in the kwarg will not be overwritten. .UNINDENT .UNINDENT .sp Changed in version 2016.3.0: GPG\-encrypted CLI Pillar data is now supported via the GPG renderer. See \fI\%here\fP for details. .TP .B pillar_enc Specify which renderer to use to decrypt encrypted data located within the \fBpillar\fP value. Currently, only \fBgpg\fP is supported. .sp New in version 2016.3.0. .TP .B exclude Exclude specific states from execution. Accepts a list of sls names, a comma\-separated string of sls names, or a list of dictionaries containing \fBsls\fP or \fBid\fP keys. Glob\-patterns may be used to match multiple states. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.sls foo,bar,baz exclude=bar,baz salt \(aq*\(aq state.sls foo,bar,baz exclude=ba* salt \(aq*\(aq state.sls foo,bar,baz exclude=\(dq[{\(aqid\(aq: \(aqid_to_exclude\(aq}, {\(aqsls\(aq: \(aqsls_to_exclude\(aq}]\(dq .ft P .fi .UNINDENT .UNINDENT .TP .B queue False Instead of failing immediately when another state run is in progress, a value of \fBTrue\fP will queue the new state run to begin running once the other has finished. .sp This option starts a new thread for each queued state run, so use this option sparingly. .sp Changed in version 3006.0: This parameter can also be set via the \fBstate_queue\fP configuration option. Additionally, it can now be set to an integer representing the maximum queue size which can be attained before the state runs will fail to be queued. This can prevent runaway conditions where new threads are started until system performance is hampered. .TP .B concurrent False Execute state runs concurrently instead of serially .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This flag is potentially dangerous. It is designed for use when multiple state runs can safely be run at the same time. Do \fInot\fP use this flag for performance optimization. .UNINDENT .UNINDENT .TP .B saltenv Specify a salt fileserver environment to be used when applying states .sp Changed in version 0.17.0: Argument name changed from \fBenv\fP to \fBsaltenv\fP\&. .sp Changed in version 2014.7.0: If no saltenv is specified, the minion config will be checked for an \fBenvironment\fP parameter and if found, it will be used. If none is found, \fBbase\fP will be used. In prior releases, the minion config was not checked and \fBbase\fP would always be assumed when the saltenv was not explicitly set. .TP .B pillarenv Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the \fI\%pillarenv\fP option. When neither the \fI\%pillarenv\fP minion config option nor this CLI argument is used, all Pillar environments will be merged together. .TP .B localconfig Optionally, instead of using the minion config, load minion opts from the file specified by this argument, and then merge them with the options from the minion config. This functionality allows for specific states to be run with their own custom minion configuration, including different pillars, file_roots, etc. .TP .B mock The mock option allows for the state run to execute without actually calling any states. This then returns a mocked return which will show the requisite ordering as well as fully validate the state run. .sp New in version 2015.8.4. .TP .B sync_mods If specified, the desired custom module types will be synced prior to running the SLS files: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.sls stuff sync_mods=states,modules salt \(aq*\(aq state.sls stuff sync_mods=all .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.8,2018.3.3,2019.2.0. .TP .B state_events The state_events option sends progress events as each function in a state run completes execution. .sp New in version 3006.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Run the states configured in salt://example.sls (or salt://example/init.sls) salt \(aq*\(aq state.apply example # Run the states configured in salt://core.sls (or salt://core/init.sls) # and salt://edit/vim.sls (or salt://edit/vim/init.sls) salt \(aq*\(aq state.sls core,edit.vim # Run the states configured in a more deeply nested directory such as salt://my/nested/state.sls (or salt://my/nested/state/init.sls) salt \(aq*\(aq state.sls my.nested.state salt \(aq*\(aq state.sls core exclude=\(dq[{\(aqid\(aq: \(aqid_to_exclude\(aq}, {\(aqsls\(aq: \(aqsls_to_exclude\(aq}]\(dq salt \(aq*\(aq state.sls myslsfile pillar=\(dq{foo: \(aqFoo!\(aq, bar: \(aqBar!\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.sls_exists(mods, test=None, queue=None, **kwargs) Tests for the existence the of a specific SLS or list of SLS files on the master. Similar to \fI\%state.show_sls\fP, rather than returning state details, returns True or False. The default environment is \fBbase\fP, use \fBsaltenv\fP to specify a different environment. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B saltenv Specify a salt fileserver environment from which to look for the SLS files specified in the \fBmods\fP argument .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.sls_exists core,edit.vim saltenv=dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.sls_id(id_, mods, test=None, queue=None, state_events=None, **kwargs) Call a single ID from the named module(s) and handle all requisites .sp The state ID comes \fIbefore\fP the module ID(s) on the command line. .INDENT 7.0 .TP .B id ID to call .TP .B mods Comma\-delimited list of modules to search for given id and its requisites .UNINDENT .sp New in version 2014.7.0. .INDENT 7.0 .TP .B saltenv base Specify a salt fileserver environment to be used when applying states .TP .B pillarenv Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the \fI\%pillarenv\fP option. When neither the \fI\%pillarenv\fP minion config option nor this CLI argument is used, all Pillar environments will be merged together. .TP .B pillar Custom Pillar values, passed as a dictionary of key\-value pairs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.sls_id my_state my_module pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Values passed this way will override existing Pillar values set via \fBpillar_roots\fP or an external Pillar source. Pillar values that are not included in the kwarg will not be overwritten. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.sls_id my_state my_module salt \(aq*\(aq state.sls_id my_state my_module,a_common_module .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.soft_kill(jid, state_id=None) Set up a state run to die before executing the given state id, this instructs a running state to safely exit at a given state id. This needs to pass in the jid of the running state. If a state_id is not passed then the jid referenced will be safely exited at the beginning of the next state run. .sp The given state id is the id got a given state execution, so given a state that looks like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed: [] .ft P .fi .UNINDENT .UNINDENT .sp The state_id to pass to \fIsoft_kill\fP is \fIvim\fP .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.soft_kill 20171130110407769519 salt \(aq*\(aq state.soft_kill 20171130110407769519 vim .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.template(tem, queue=None, **kwargs) Execute the information stored in a template file on the minion. .sp This function does not ask a master for a SLS file to render but instead directly processes the file at the provided path on the minion. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.template \(aq<Path to template on the minion>\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.template_str(tem, queue=None, **kwargs) Execute the information stored in a string from an sls template .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.template_str \(aq<Template String>\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.test(*args, **kwargs) New in version 3001. .sp Alias for \fIstate.apply\fP with the kwarg \fItest\fP forced to \fITrue\fP\&. .sp This is a nicety to avoid the need to type out \fItest=True\fP and the possibility of a typo causing changes you do not intend. .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.top(topfn, test=None, queue=None, **kwargs) Execute a specific top file instead of the default. This is useful to apply configurations from a different environment (for example, dev or prod), without modifying the default top file. .INDENT 7.0 .TP .B queue False Instead of failing immediately when another state run is in progress, a value of \fBTrue\fP will queue the new state run to begin running once the other has finished. .sp This option starts a new thread for each queued state run, so use this option sparingly. .sp Changed in version 3006.0: This parameter can also be set via the \fBstate_queue\fP configuration option. Additionally, it can now be set to an integer representing the maximum queue size which can be attained before the state runs will fail to be queued. This can prevent runaway conditions where new threads are started until system performance is hampered. .TP .B saltenv Specify a salt fileserver environment to be used when applying states .TP .B pillarenv Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the \fI\%pillarenv\fP option. When neither the \fI\%pillarenv\fP minion config option nor this CLI argument is used, all Pillar environments will be merged together. .sp New in version 2017.7.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.top reverse_top.sls salt \(aq*\(aq state.top prod_top.sls exclude=sls_to_exclude salt \(aq*\(aq state.top dev_top.sls exclude=\(dq[{\(aqid\(aq: \(aqid_to_exclude\(aq}, {\(aqsls\(aq: \(aqsls_to_exclude\(aq}]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.status .sp Module for returning various status data about a minion. These data can be useful for compiling into stats later. .INDENT 0.0 .TP .B salt.modules.status.all_status() Return a composite of all status data and info for this minion. Warning: There is a LOT here! .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.all_status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.cpuinfo() Changed in version 2016.3.2: Return the CPU info for this minion .sp Changed in version 2016.11.4: Added support for AIX .sp Changed in version 2018.3.0: Added support for NetBSD and OpenBSD .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.cpuinfo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.cpustats() Return the CPU stats for this minion .sp Changed in version 2016.11.4: Added support for AIX .sp Changed in version 2018.3.0: Added support for OpenBSD .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.cpustats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.custom() Return a custom composite of status data and info for this minion, based on the minion config file. An example config like might be: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C status.cpustats.custom: [ \(aqcpu\(aq, \(aqctxt\(aq, \(aqbtime\(aq, \(aqprocesses\(aq ] .ft P .fi .UNINDENT .UNINDENT .sp Where status refers to status.py, cpustats is the function where we get our data, and custom is this function It is followed by a list of keys that we want returned. .sp This function is meant to replace all_status(), which returns anything and everything, which we probably don\(aqt want. .sp By default, nothing is returned. Warning: Depending on what you include, there can be a LOT here! .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.custom .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.diskstats() Changed in version 2016.3.2: Return the disk stats for this minion .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.diskstats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.diskusage(*args) Return the disk usage for this minion .sp Usage: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.diskusage [paths and/or filesystem types] .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.diskusage # usage for all filesystems salt \(aq*\(aq status.diskusage / /tmp # usage for / and /tmp salt \(aq*\(aq status.diskusage ext? # usage for ext[234] filesystems salt \(aq*\(aq status.diskusage / ext? # usage for / and all ext filesystems .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.loadavg() Return the load averages for this minion .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.loadavg :raises CommandExecutionError: If the system cannot report loadaverages to Python .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.master(master=None, connected=True) New in version 2014.7.0. .sp Return the connection status with master. Fire an event if the connection to master is not as expected. This function is meant to be run via a scheduled job from the minion. If master_ip is an FQDN/Hostname, it must be resolvable to a valid IPv4 address. .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.meminfo() Return the memory info for this minion .sp Changed in version 2016.11.4: Added support for AIX .sp Changed in version 2018.3.0: Added support for OpenBSD .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.meminfo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.netdev() Changed in version 2016.3.2: Return the network device stats for this minion .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.netdev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.netstats() Return the network stats for this minion .sp Changed in version 2016.11.4: Added support for AIX .sp Changed in version 2018.3.0: Added support for OpenBSD .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.netstats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.nproc() Return the number of processing units available on this system .sp Changed in version 2016.11.4: Added support for AIX .sp Changed in version 2018.3.0: Added support for Darwin, FreeBSD and OpenBSD .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.nproc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.pid(sig) Return the PID or an empty string if the process is running or not. Pass a signature to use to find the process via ps. Note you can pass a Python\-compatible regular expression to return all pids of processes matching the regexp. .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.pid <sig> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.ping_master(master) New in version 2016.3.0. .sp Sends ping request to the given master. Fires \(aq__master_failback\(aq event on success. Returns bool result. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.ping_master localhost .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.procs() Return the process data .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.procs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.proxy_reconnect(proxy_name, opts=None) Forces proxy minion reconnection when not alive. .INDENT 7.0 .TP .B proxy_name The virtual name of the proxy module. .TP .B opts: None Opts dictionary. Not intended for CLI usage. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.proxy_reconnect rest_sample .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.time_(format=\(aq%A, %d. %B %Y %I:%M%p\(aq) New in version 2016.3.0. .sp Return the current time on the minion, formatted based on the format parameter. .sp Default date format: Monday, 27. July 2015 07:55AM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.time salt \(aq*\(aq status.time \(aq%s\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.uptime() Return the uptime for this system. .sp Changed in version 2015.8.9: The uptime function was changed to return a dictionary of easy\-to\-read key/value pairs containing uptime information, instead of the output from a \fBcmd.run\fP call. .sp Changed in version 2016.11.0: Support for OpenBSD, FreeBSD, NetBSD, MacOS, and Solaris .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.uptime .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.version() Return the system version for this minion .sp Changed in version 2016.11.4: Added support for AIX .sp Changed in version 2018.3.0: Added support for OpenBSD .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.vmstats() Changed in version 2016.3.2: Return the virtual memory stats for this minion .sp Changed in version 2016.11.4: Added support for AIX .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.vmstats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.w() Return a list of logged in users for this minion, using the w command .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.w .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.statuspage .SS StatusPage .sp Handle requests for the \fI\%StatusPage\fP \fI\%API\fP\&. .sp In the minion configuration file, the following block is required: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C statuspage: api_key: <API_KEY> page_id: <PAGE_ID> .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.modules.statuspage.create(endpoint=\(aqincidents\(aq, api_url=None, page_id=None, api_key=None, api_version=None, **kwargs) Insert a new entry under a specific endpoint. .INDENT 7.0 .TP .B endpoint: incidents Insert under this specific endpoint. .TP .B page_id Page ID. Can also be specified in the config file. .TP .B api_key API key. Can also be specified in the config file. .TP .B api_version: 1 API version. Can also be specified in the config file. .TP .B api_url Custom API URL in case the user has a StatusPage service running in a custom environment. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq statuspage.create endpoint=\(aqcomponents\(aq name=\(aqmy component\(aq group_id=\(aq993vgplshj12\(aq .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C minion: \-\-\-\-\-\-\-\-\-\- comment: out: \-\-\-\-\-\-\-\-\-\- created_at: 2017\-01\-05T19:35:27.135Z description: None group_id: 993vgplshj12 id: mjkmtt5lhdgc name: my component page_id: ksdhgfyiuhaa position: 7 status: operational updated_at: 2017\-01\-05T19:35:27.135Z result: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.statuspage.delete(endpoint=\(aqincidents\(aq, id=None, api_url=None, page_id=None, api_key=None, api_version=None) Remove an entry from an endpoint. .INDENT 7.0 .TP .B endpoint: incidents Request a specific endpoint. .TP .B page_id Page ID. Can also be specified in the config file. .TP .B api_key API key. Can also be specified in the config file. .TP .B api_version: 1 API version. Can also be specified in the config file. .TP .B api_url Custom API URL in case the user has a StatusPage service running in a custom environment. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq statuspage.delete endpoint=\(aqcomponents\(aq id=\(aqftgks51sfs2d\(aq .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C minion: \-\-\-\-\-\-\-\-\-\- comment: out: None result: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.statuspage.retrieve(endpoint=\(aqincidents\(aq, api_url=None, page_id=None, api_key=None, api_version=None) Retrieve a specific endpoint from the Statuspage API. .INDENT 7.0 .TP .B endpoint: incidents Request a specific endpoint. .TP .B page_id Page ID. Can also be specified in the config file. .TP .B api_key API key. Can also be specified in the config file. .TP .B api_version: 1 API version. Can also be specified in the config file. .TP .B api_url Custom API URL in case the user has a StatusPage service running in a custom environment. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq statuspage.retrieve components .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C minion: \-\-\-\-\-\-\-\-\-\- comment: out: |_ \-\-\-\-\-\-\-\-\-\- backfilled: False created_at: 2015\-01\-26T20:25:02.702Z id: kh2qwjbheqdc36 impact: major impact_override: None incident_updates: |_ \-\-\-\-\-\-\-\-\-\- affected_components: None body: We are currently investigating this issue. created_at: 2015\-01\-26T20:25:02.849Z display_at: 2015\-01\-26T20:25:02.849Z id: zvx7xz2z5skr incident_id: kh2qwjbheqdc36 status: investigating twitter_updated_at: None updated_at: 2015\-01\-26T20:25:02.849Z wants_twitter_update: False monitoring_at: None name: just testing some stuff page_id: ksdhgfyiuhaa postmortem_body: None postmortem_body_last_updated_at: None postmortem_ignored: False postmortem_notified_subscribers: False postmortem_notified_twitter: False postmortem_published_at: None resolved_at: None scheduled_auto_completed: False scheduled_auto_in_progress: False scheduled_for: None scheduled_remind_prior: False scheduled_reminded_at: None scheduled_until: None shortlink: http://stspg.io/voY status: investigating updated_at: 2015\-01\-26T20:25:13.379Z result: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.statuspage.update(endpoint=\(aqincidents\(aq, id=None, api_url=None, page_id=None, api_key=None, api_version=None, **kwargs) Update attribute(s) of a specific endpoint. .INDENT 7.0 .TP .B id The unique ID of the endpoint entry. .TP .B endpoint: incidents Endpoint name. .TP .B page_id Page ID. Can also be specified in the config file. .TP .B api_key API key. Can also be specified in the config file. .TP .B api_version: 1 API version. Can also be specified in the config file. .TP .B api_url Custom API URL in case the user has a StatusPage service running in a custom environment. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq statuspage.update id=dz959yz2nd4l status=resolved .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C minion: \-\-\-\-\-\-\-\-\-\- comment: out: \-\-\-\-\-\-\-\-\-\- created_at: 2017\-01\-03T15:25:30.718Z description: None group_id: 993vgplshj12 id: dz959yz2nd4l name: Management Portal page_id: xzwjjdw87vpf position: 11 status: resolved updated_at: 2017\-01\-05T15:34:27.676Z result: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.supervisord .sp Provide the service module for system supervisord or supervisord in a virtualenv .INDENT 0.0 .TP .B salt.modules.supervisord.add(name, user=None, conf_file=None, bin_env=None) Activates any updates in config for process/group. .INDENT 7.0 .TP .B user user to run supervisorctl as .TP .B conf_file path to supervisord config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq supervisord.add <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.supervisord.custom(command, user=None, conf_file=None, bin_env=None) Run any custom supervisord command .INDENT 7.0 .TP .B user user to run supervisorctl as .TP .B conf_file path to supervisord config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq supervisord.custom \(dqmstop \(aq*gunicorn*\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.supervisord.options(name, conf_file=None) New in version 2014.1.0. .sp Read the config file and return the config options for a given process .INDENT 7.0 .TP .B name Name of the configured process .TP .B conf_file path to supervisord config file .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq supervisord.options foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.supervisord.remove(name, user=None, conf_file=None, bin_env=None) Removes process/group from active config .INDENT 7.0 .TP .B user user to run supervisorctl as .TP .B conf_file path to supervisord config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq supervisord.remove <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.supervisord.reread(user=None, conf_file=None, bin_env=None) Reload the daemon\(aqs configuration files .INDENT 7.0 .TP .B user user to run supervisorctl as .TP .B conf_file path to supervisord config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq supervisord.reread .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.supervisord.restart(name=\(aqall\(aq, user=None, conf_file=None, bin_env=None) Restart the named service. Process group names should not include a trailing asterisk. .INDENT 7.0 .TP .B user user to run supervisorctl as .TP .B conf_file path to supervisord config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq supervisord.restart <service> salt \(aq*\(aq supervisord.restart <group>: .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.supervisord.start(name=\(aqall\(aq, user=None, conf_file=None, bin_env=None) Start the named service. Process group names should not include a trailing asterisk. .INDENT 7.0 .TP .B user user to run supervisorctl as .TP .B conf_file path to supervisord config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq supervisord.start <service> salt \(aq*\(aq supervisord.start <group>: .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.supervisord.status(name=None, user=None, conf_file=None, bin_env=None) List programs and its state .INDENT 7.0 .TP .B user user to run supervisorctl as .TP .B conf_file path to supervisord config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq supervisord.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.supervisord.status_bool(name, expected_state=None, user=None, conf_file=None, bin_env=None) Check for status of a specific supervisord process and return boolean result. .INDENT 7.0 .TP .B name name of the process to check .TP .B expected_state search for a specific process state. If set to \fBNone\fP \- any process state will match. .TP .B user user to run supervisorctl as .TP .B conf_file path to supervisord config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq supervisord.status_bool nginx expected_state=\(aqRUNNING\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.supervisord.status_raw(name=None, user=None, conf_file=None, bin_env=None) Display the raw output of status .INDENT 7.0 .TP .B user user to run supervisorctl as .TP .B conf_file path to supervisord config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq supervisord.status_raw .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.supervisord.stop(name=\(aqall\(aq, user=None, conf_file=None, bin_env=None) Stop the named service. Process group names should not include a trailing asterisk. .INDENT 7.0 .TP .B user user to run supervisorctl as .TP .B conf_file path to supervisord config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq supervisord.stop <service> salt \(aq*\(aq supervisord.stop <group>: .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.supervisord.update(user=None, conf_file=None, bin_env=None, name=None) Reload config and add/remove/update as necessary .INDENT 7.0 .TP .B user user to run supervisorctl as .TP .B conf_file path to supervisord config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .TP .B name name of the process group to update. if none then update any process group that has changes .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq supervisord.update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.suse_apache .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%apache Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Support for Apache .sp Please note: The functions in here are SUSE\-specific. Placing them in this separate file will allow them to load only on SUSE systems, while still loading under the \fBapache\fP namespace. .INDENT 0.0 .TP .B salt.modules.suse_apache.a2dismod(mod) Runs a2dismod for the given mod. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.a2dismod vhost_alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.suse_apache.a2enmod(mod) Runs a2enmod for the given mod. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.a2enmod vhost_alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.suse_apache.check_mod_enabled(mod) Checks to see if the specific apache mod is enabled. .sp This will only be functional on operating systems that support \fIa2enmod \-l\fP to list the enabled mods. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.check_mod_enabled status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.suse_ip .sp The networking module for SUSE based distros .sp New in version 3005. .INDENT 0.0 .TP .B salt.modules.suse_ip.apply_network_settings(**settings) Apply global network configuration. .INDENT 7.0 .TP .B :param param settings: The network settings to apply .UNINDENT .INDENT 7.0 .TP .B Returns The result of \fBservice.reload\fP for \fBnetwork\fP service .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.apply_network_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.suse_ip.build_interface(iface, iface_type, enabled, **settings) Build an interface script for a network interface. .INDENT 7.0 .TP .B :param param iface: The name of the interface to build the configuration for .TP .B :param param iface_type:.INDENT 7.0 .TP .B The type of the interface. The following types are possible: .INDENT 7.0 .IP \(bu 2 eth .IP \(bu 2 bond .IP \(bu 2 alias .IP \(bu 2 clone .IP \(bu 2 ipsec .IP \(bu 2 dialup .IP \(bu 2 bridge .IP \(bu 2 slave .IP \(bu 2 vlan .IP \(bu 2 ipip .IP \(bu 2 ib .UNINDENT .UNINDENT .TP .B :param param enabled: Build the interface enabled or disabled .TP .B :param param settings: The settings for the interface .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of file/content .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_interface eth0 eth <settings> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.suse_ip.build_network_settings(**settings) Build the global network script. .INDENT 7.0 .TP .B :param param settings: The network settings .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of file/content .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_network_settings <settings> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.suse_ip.build_routes(iface, **settings) Build a route script for a network interface. .INDENT 7.0 .TP .B :param param iface: The name of the interface to build the routes for .TP .B :param param settings: The settings for the routes .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of file/content .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_routes eth0 <settings> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.suse_ip.down(iface, iface_type=None) Shutdown a network interface .INDENT 7.0 .TP .B :param param iface: The name of the interface to shutdown .TP .B :param param iface_type: The type of the interface If \fBslave\fP is specified, no any action is performing Default is \fBNone\fP .UNINDENT .INDENT 7.0 .TP .B Returns The result of \fBifdown\fP command or \fBNone\fP if \fBslave\fP iface_type was specified .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.down eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.suse_ip.get_interface(iface) Return the contents of an interface script .INDENT 7.0 .TP .B :param param iface: The name of the interface to get settings for .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of file/content .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_interface eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.suse_ip.get_network_settings() Return the contents of the global network script. .INDENT 7.0 .TP .B :param param iface: The name of the interface to start up .TP .B :param param iface_type: The type of the interface If \fBslave\fP is specified, no any action is performing Default is \fBNone\fP .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of file/content .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_network_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.suse_ip.get_routes(iface) Return the contents of the interface routes script. .INDENT 7.0 .TP .B :param param iface: The name of the interface to get the routes for .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of file/content .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_routes eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.suse_ip.up(iface, iface_type=None) Start up a network interface .INDENT 7.0 .TP .B :param param iface: The name of the interface to start up .TP .B :param param iface_type: The type of the interface If \fBslave\fP is specified, no any action is performing Default is \fBNone\fP .UNINDENT .INDENT 7.0 .TP .B Returns The result of \fBifup\fP command or \fBNone\fP if \fBslave\fP iface_type was specified .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.up eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.svn .sp Subversion SCM .INDENT 0.0 .TP .B salt.modules.svn.add(cwd, targets, user=None, username=None, password=None, *opts) Add files to be tracked by the Subversion working\-copy checkout .INDENT 7.0 .TP .B cwd The path to the Subversion repository .TP .B targets None files and directories to pass to the command as arguments .TP .B user None Run svn as a user other than what the minion runs as .TP .B username None Connect to the Subversion server as another user .TP .B password None Connect to the Subversion server with this password .sp New in version 0.17.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq svn.add /path/to/repo /path/to/new/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.svn.checkout(cwd, remote, target=None, user=None, username=None, password=None, *opts) Download a working copy of the remote Subversion repository directory or file .INDENT 7.0 .TP .B cwd The path to the Subversion repository .TP .B remote None URL to checkout .TP .B target None The name to give the file or directory working copy Default: svn uses the remote basename .TP .B user None Run svn as a user other than what the minion runs as .TP .B username None Connect to the Subversion server as another user .TP .B password None Connect to the Subversion server with this password .sp New in version 0.17.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq svn.checkout /path/to/repo svn://remote/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.svn.commit(cwd, targets=None, msg=None, user=None, username=None, password=None, *opts) Commit the current directory, files, or directories to the remote Subversion repository .INDENT 7.0 .TP .B cwd The path to the Subversion repository .TP .B targets None files and directories to pass to the command as arguments Default: svn uses \(aq.\(aq .TP .B msg None Message to attach to the commit log .TP .B user None Run svn as a user other than what the minion runs as .TP .B username None Connect to the Subversion server as another user .TP .B password None Connect to the Subversion server with this password .sp New in version 0.17.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq svn.commit /path/to/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.svn.diff(cwd, targets=None, user=None, username=None, password=None, *opts) Return the diff of the current directory, files, or directories from the remote Subversion repository .INDENT 7.0 .TP .B cwd The path to the Subversion repository .TP .B targets None files and directories to pass to the command as arguments Default: svn uses \(aq.\(aq .TP .B user None Run svn as a user other than what the minion runs as .TP .B username None Connect to the Subversion server as another user .TP .B password None Connect to the Subversion server with this password .sp New in version 0.17.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq svn.diff /path/to/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.svn.export(cwd, remote, target=None, user=None, username=None, password=None, revision=\(aqHEAD\(aq, *opts) Create an unversioned copy of a tree. .INDENT 7.0 .TP .B cwd The path to the Subversion repository .TP .B remote None URL and path to file or directory checkout .TP .B target None The name to give the file or directory working copy Default: svn uses the remote basename .TP .B user None Run svn as a user other than what the minion runs as .TP .B username None Connect to the Subversion server as another user .TP .B password None Connect to the Subversion server with this password .sp New in version 0.17.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq svn.export /path/to/repo svn://remote/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.svn.info(cwd, targets=None, user=None, username=None, password=None, fmt=\(aqstr\(aq) Display the Subversion information from the checkout. .INDENT 7.0 .TP .B cwd The path to the Subversion repository .TP .B targets None files, directories, and URLs to pass to the command as arguments svn uses \(aq.\(aq by default .TP .B user None Run svn as a user other than what the minion runs as .TP .B username None Connect to the Subversion server as another user .TP .B password None Connect to the Subversion server with this password .sp New in version 0.17.0. .TP .B fmt str How to fmt the output from info. (str, xml, list, dict) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq svn.info /path/to/svn/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.svn.remove(cwd, targets, msg=None, user=None, username=None, password=None, *opts) Remove files and directories from the Subversion repository .INDENT 7.0 .TP .B cwd The path to the Subversion repository .TP .B targets None files, directories, and URLs to pass to the command as arguments .TP .B msg None Message to attach to the commit log .TP .B user None Run svn as a user other than what the minion runs as .TP .B username None Connect to the Subversion server as another user .TP .B password None Connect to the Subversion server with this password .sp New in version 0.17.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq svn.remove /path/to/repo /path/to/repo/remove .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.svn.status(cwd, targets=None, user=None, username=None, password=None, *opts) Display the status of the current directory, files, or directories in the Subversion repository .INDENT 7.0 .TP .B cwd The path to the Subversion repository .TP .B targets None files, directories, and URLs to pass to the command as arguments Default: svn uses \(aq.\(aq .TP .B user None Run svn as a user other than what the minion runs as .TP .B username None Connect to the Subversion server as another user .TP .B password None Connect to the Subversion server with this password .sp New in version 0.17.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq svn.status /path/to/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.svn.switch(cwd, remote, target=None, user=None, username=None, password=None, *opts) New in version 2014.1.0. .sp Switch a working copy of a remote Subversion repository directory .INDENT 7.0 .TP .B cwd The path to the Subversion repository .TP .B remote None URL to switch .TP .B target None The name to give the file or directory working copy Default: svn uses the remote basename .TP .B user None Run svn as a user other than what the minion runs as .TP .B username None Connect to the Subversion server as another user .TP .B password None Connect to the Subversion server with this password .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq svn.switch /path/to/repo svn://remote/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.svn.update(cwd, targets=None, user=None, username=None, password=None, *opts) Update the current directory, files, or directories from the remote Subversion repository .INDENT 7.0 .TP .B cwd The path to the Subversion repository .TP .B targets None files and directories to pass to the command as arguments Default: svn uses \(aq.\(aq .TP .B user None Run svn as a user other than what the minion runs as .TP .B password None Connect to the Subversion server with this password .sp New in version 0.17.0. .TP .B username None Connect to the Subversion server as another user .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq svn.update /path/to/repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.swarm .SS Docker Swarm Module using Docker\(aqs Python SDK .INDENT 0.0 .TP .B codeauthor Tyler Jones <\fI\%jonestyler806@gmail.com\fP> .UNINDENT .sp New in version 2018.3.0. .sp The Docker Swarm Module is used to manage and create Docker Swarms. .SS Dependencies .INDENT 0.0 .IP \(bu 2 Docker installed on the host .IP \(bu 2 Docker python sdk >= 2.5.1 .UNINDENT .SS Docker Python SDK .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install \-U docker .ft P .fi .UNINDENT .UNINDENT .sp More information: \fI\%https://docker\-py.readthedocs.io/en/stable/\fP .INDENT 0.0 .TP .B salt.modules.swarm.joinswarm(remote_addr=<class \(aqint\(aq>, listen_addr=<class \(aqint\(aq>, token=<class \(aqstr\(aq>) Join a Swarm Worker to the cluster .INDENT 7.0 .TP .B remote_addr The manager node you want to connect to for the swarm .TP .B listen_addr Listen address used for inter\-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP) .TP .B token Either the manager join token or the worker join token. You can get the worker or manager token via \fBsalt \(aq*\(aq swarm.swarm_tokens\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq swarm.joinswarm remote_addr=192.168.50.10 listen_addr=\(aq0.0.0.0\(aq token=\(aqSWMTKN\-1\-64tux2g0701r84ofq93zppcih0pe081akq45owe9ts61f30x4t\-06trjugdu7x2z47j938s54il\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.swarm.leave_swarm(force=<class \(aqbool\(aq>) Force the minion to leave the swarm .INDENT 7.0 .TP .B force Will force the minion/worker/manager to leave the swarm .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq swarm.leave_swarm force=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.swarm.node_ls(server=<class \(aqstr\(aq>) Displays Information about Swarm Nodes with passing in the server .INDENT 7.0 .TP .B server The minion/server name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq swarm.node_ls server=minion1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.swarm.remove_node(node_id=<class \(aqstr\(aq>, force=<class \(aqbool\(aq>) Remove a node from a swarm and the target needs to be a swarm manager .INDENT 7.0 .TP .B node_id The node id from the return of swarm.node_ls .TP .B force Forcefully remove the node/minion from the service .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq swarm.remove_node node_id=z4gjbe9rwmqahc2a91snvolm5 force=false .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.swarm.remove_service(service=<class \(aqstr\(aq>) Remove Swarm Service .INDENT 7.0 .TP .B service The name of the service .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq swarm.remove_service service=Test_Service .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.swarm.service_create(image=<class \(aqstr\(aq>, name=<class \(aqstr\(aq>, command=<class \(aqstr\(aq>, hostname=<class \(aqstr\(aq>, replicas=<class \(aqint\(aq>, target_port=<class \(aqint\(aq>, published_port=<class \(aqint\(aq>) Create Docker Swarm Service Create .INDENT 7.0 .TP .B image The docker image .TP .B name Is the service name .TP .B command The docker command to run in the container at launch .TP .B hostname The hostname of the containers .TP .B replicas How many replicas you want running in the swarm .TP .B target_port The target port on the container .TP .B published_port port that\(aqs published on the host/os .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq swarm.service_create image=httpd name=Test_Service command=None hostname=salthttpd replicas=6 target_port=80 published_port=80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.swarm.swarm_init(advertise_addr=<class \(aqstr\(aq>, listen_addr=<class \(aqint\(aq>, force_new_cluster=<class \(aqbool\(aq>) Initialize Docker on Minion as a Swarm Manager .INDENT 7.0 .TP .B advertise_addr The ip of the manager .TP .B listen_addr Listen address used for inter\-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form 192.168.1.1:4567, or an interface followed by a port number, like eth0:4567 .TP .B force_new_cluster Force a new cluster if True is passed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq swarm.swarm_init advertise_addr=\(aq192.168.50.10\(aq listen_addr=\(aq0.0.0.0\(aq force_new_cluster=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.swarm.swarm_service_info(service_name=<class \(aqstr\(aq>) Swarm Service Information .INDENT 7.0 .TP .B service_name The name of the service that you want information on about the service .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq swarm.swarm_service_info service_name=Test_Service .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.swarm.swarm_tokens() Get the Docker Swarm Manager or Worker join tokens .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq swarm.swarm_tokens .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.swarm.update_node(availability=<class \(aqstr\(aq>, node_name=<class \(aqstr\(aq>, role=<class \(aqstr\(aq>, node_id=<class \(aqstr\(aq>, version=<class \(aqint\(aq>) Updates docker swarm nodes/needs to target a manager node/minion .INDENT 7.0 .TP .B availability Drain or Active .TP .B node_name minion/node .TP .B role role of manager or worker .TP .B node_id The Id and that can be obtained via swarm.node_ls .TP .B version Is obtained by swarm.node_ls .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq swarm.update_node availability=drain node_name=minion2 role=worker node_id=3k9x7t8m4pel9c0nqr3iajnzp version=19 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.swift .sp Module for handling OpenStack Swift calls Author: Anthony Stanton <\fI\%anthony.stanton@gmail.com\fP> .sp Inspired by the S3 and Nova modules .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 swiftclient Python module .UNINDENT .TP .B configuration This module is not usable until the user, tenant, auth URL, and password or auth_key are specified either in a pillar or in the minion\(aqs config file. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C keystone.user: admin keystone.tenant: admin keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq keystone.password: verybadpass # or keystone.auth_key: 203802934809284k2j34lkj2l3kj43k .ft P .fi .UNINDENT .UNINDENT .sp If configuration for multiple OpenStack accounts is required, they can be set up as different configuration profiles: For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C openstack1: keystone.user: admin keystone.tenant: admin keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq keystone.password: verybadpass # or keystone.auth_key: 203802934809284k2j34lkj2l3kj43k openstack2: keystone.user: admin keystone.tenant: admin keystone.auth_url: \(aqhttp://127.0.0.2:5000/v2.0/\(aq keystone.password: verybadpass # or keystone.auth_key: 303802934809284k2j34lkj2l3kj43k .ft P .fi .UNINDENT .UNINDENT .sp With this configuration in place, any of the swift functions can make use of a configuration profile by declaring it explicitly. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq swift.get mycontainer myfile /tmp/file profile=openstack1 .ft P .fi .UNINDENT .UNINDENT .sp NOTE: For Rackspace cloud files setting keystone.auth_version = 1 is recommended. .UNINDENT .INDENT 0.0 .TP .B salt.modules.swift.delete(cont, path=None, profile=None) Delete a container, or delete an object from a container. .sp CLI Example to delete a container: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion swift.delete mycontainer .ft P .fi .UNINDENT .UNINDENT .sp CLI Example to delete an object from a container: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion swift.delete mycontainer remoteobject .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.swift.get(cont=None, path=None, local_file=None, return_bin=False, profile=None) List the contents of a container, or return an object from a container. Set return_bin to True in order to retrieve an object wholesale. Otherwise, Salt will attempt to parse an XML response. .sp CLI Example to list containers: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion swift.get .ft P .fi .UNINDENT .UNINDENT .sp CLI Example to list the contents of a container: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion swift.get mycontainer .ft P .fi .UNINDENT .UNINDENT .sp CLI Example to return the binary contents of an object: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion swift.get mycontainer myfile.png return_bin=True .ft P .fi .UNINDENT .UNINDENT .sp CLI Example to save the binary contents of an object to a local file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion swift.get mycontainer myfile.png local_file=/tmp/myfile.png .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.swift.head() .UNINDENT .INDENT 0.0 .TP .B salt.modules.swift.put(cont, path=None, local_file=None, profile=None) Create a new container, or upload an object to a container. .sp CLI Example to create a container: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion swift.put mycontainer .ft P .fi .UNINDENT .UNINDENT .sp CLI Example to upload an object to a container: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion swift.put mycontainer remotepath local_file=/path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.sysbench .sp 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. .INDENT 0.0 .TP .B salt.modules.sysbench.cpu() Tests for the CPU performance of minions. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysbench.cpu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysbench.fileio() This tests for the file read and write operations Various modes of operations are .INDENT 7.0 .IP \(bu 2 sequential write .IP \(bu 2 sequential rewrite .IP \(bu 2 sequential read .IP \(bu 2 random read .IP \(bu 2 random write .IP \(bu 2 random read and write .UNINDENT .sp The test works with 32 files with each file being 1Gb in size The test consumes a lot of time. Be patient! .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysbench.fileio .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysbench.memory() This tests the memory for read and write operations. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysbench.memory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysbench.mutex() Tests the implementation of mutex .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysbench.mutex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysbench.ping() .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysbench.threads() This tests the performance of the processor\(aqs scheduler .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysbench.threads .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.sysfs .sp Module for interfacing with SysFS .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt\fP .UNINDENT .UNINDENT .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.modules.sysfs.attr(key, value=None) Access/write a SysFS attribute. If the attribute is a symlink, its destination is returned .INDENT 7.0 .TP .B Returns value or bool .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysfs.attr block/sda/queue/logical_block_size .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysfs.interfaces(root) Generate a dictionary with all available interfaces relative to root. Symlinks are not followed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysfs.interfaces block/bcache0/bcache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Output example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(dqr\(dq: [ \(dqstate\(dq, \(dqpartial_stripes_expensive\(dq, \(dqwriteback_rate_debug\(dq, \(dqstripe_size\(dq, \(dqdirty_data\(dq, \(dqstats_total/cache_hits\(dq, \(dqstats_total/cache_bypass_misses\(dq, \(dqstats_total/bypassed\(dq, \(dqstats_total/cache_readaheads\(dq, \(dqstats_total/cache_hit_ratio\(dq, \(dqstats_total/cache_miss_collisions\(dq, \(dqstats_total/cache_misses\(dq, \(dqstats_total/cache_bypass_hits\(dq, ], \(dqrw\(dq: [ \(dqwriteback_rate\(dq, \(dqwriteback_rate_update_seconds\(dq, \(dqcache_mode\(dq, \(dqwriteback_delay\(dq, \(dqlabel\(dq, \(dqwriteback_running\(dq, \(dqwriteback_metadata\(dq, \(dqrunning\(dq, \(dqwriteback_rate_p_term_inverse\(dq, \(dqsequential_cutoff\(dq, \(dqwriteback_percent\(dq, \(dqwriteback_rate_d_term\(dq, \(dqreadahead\(dq ], \(dqw\(dq: [ \(dqstop\(dq, \(dqclear_stats\(dq, \(dqattach\(dq, \(dqdetach\(dq ] } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \(aqr\(aq interfaces are read\-only .IP \(bu 2 \(aqw\(aq interfaces are write\-only (e.g. actions) .IP \(bu 2 \(aqrw\(aq are interfaces that can both be read or written .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysfs.read(key, root=\(aq\(aq) Read from SysFS .INDENT 7.0 .TP .B Parameters \fBkey\fP \-\- file or path in SysFS; if key is a list then root will be prefixed on each key .TP .B Returns the full (tree of) SysFS attributes under key .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysfs.read class/net/em1/statistics .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysfs.target(key, full=True) Return the basename of a SysFS key path .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkey\fP \-\- the location to resolve within SysFS .IP \(bu 2 \fBfull\fP \-\- full path instead of basename .UNINDENT .TP .B Returns fullpath or basename of path .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysfs.read class/ttyS0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysfs.write(key, value) Write a SysFS attribute/action .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysfs.write devices/system/cpu/cpu0/cpufreq/scaling_governor \(aqperformance\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.syslog_ng .sp Module for getting information about syslog\-ng .INDENT 0.0 .TP .B maintainer Tibor Benke <\fI\%btibi@sch.bme.hu\fP> .TP .B maturity new .TP .B depends cmd .TP .B platform all .UNINDENT .sp This module is capable of managing syslog\-ng instances which were installed via a package manager or from source. Users can use a directory as a parameter in the case of most functions, which contains the syslog\-ng and syslog\-ng\-ctl binaries. .sp Syslog\-ng can be installed via a package manager or from source. In the latter case, the syslog\-ng and syslog\-ng\-ctl binaries are not available from the PATH, so users should set location of the sbin directory with \fI\%syslog_ng.set_binary_path\fP\&. .sp Similarly, users can specify the location of the configuration file with \fI\%syslog_ng.set_config_file\fP, then the module will use it. If it is not set, syslog\-ng uses the default configuration file. .INDENT 0.0 .TP .B class salt.modules.syslog_ng.Argument(value=\(aq\(aq) A TypedParameterValue has one or more Arguments. For example this can be the value of key_file. .sp Does not need examples. .INDENT 7.0 .TP .B build() .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.syslog_ng.Buildable(iterable, join_body_on=\(aq\(aq, append_extra_newline=True) Base class of most classes, which have a build method. .sp It contains a common build function. .sp Does not need examples. .INDENT 7.0 .TP .B build() Builds the textual representation of the whole configuration object with its children. .UNINDENT .INDENT 7.0 .TP .B build_body() Builds the body of a syslog\-ng configuration object. .UNINDENT .INDENT 7.0 .TP .B build_header() Builds the header of a syslog\-ng configuration object. .UNINDENT .INDENT 7.0 .TP .B build_tail() Builds the tail of a syslog\-ng configuration object. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.syslog_ng.GivenStatement(value, add_newline=True) .INDENT 7.0 .TP .B This statement returns a string without modification. It can be used to use existing configuration snippets. .UNINDENT .sp Does not need examples. .INDENT 7.0 .TP .B build() Builds the textual representation of the whole configuration object with its children. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.syslog_ng.NamedStatement(type, id=\(aq\(aq, options=None) It represents a configuration statement, which has a name, e.g. a source. .sp Does not need examples. .UNINDENT .INDENT 0.0 .TP .B class salt.modules.syslog_ng.Option(type=\(aq\(aq, params=None) A Statement class contains Option instances. .sp An instance of Option can represent a file(), tcp(), udp(), etc. option. .sp Does not need examples. .INDENT 7.0 .TP .B add_parameter(param) .UNINDENT .INDENT 7.0 .TP .B build() Builds the textual representation of the whole configuration object with its children. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.syslog_ng.Parameter(iterable=None, join_body_on=\(aq\(aq) An Option has one or more Parameter instances. .sp Does not need examples. .UNINDENT .INDENT 0.0 .TP .B class salt.modules.syslog_ng.ParameterValue(iterable=None, join_body_on=\(aq\(aq) A TypedParameter can have one or more values. .sp Does not need examples. .UNINDENT .INDENT 0.0 .TP .B class salt.modules.syslog_ng.SimpleParameter(value=\(aq\(aq) A Parameter is a SimpleParameter, if it\(aqs just a simple type, like a string. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C destination d_file { file( \(aq/var/log/messages\(aq ); }; .ft P .fi .UNINDENT .UNINDENT .sp \fB/var/log/messages\fP is a SimpleParameter. .sp Does not need examples. .INDENT 7.0 .TP .B build() Builds the textual representation of the whole configuration object with its children. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.syslog_ng.SimpleParameterValue(value=\(aq\(aq) A ParameterValuem which holds a simple type, like a string or a number. .sp For example in ip(127.0.0.1) 127.0.0.1 is a SimpleParameterValue. .sp Does not need examples. .INDENT 7.0 .TP .B build() Builds the textual representation of the whole configuration object with its children. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.syslog_ng.Statement(type, id=\(aq\(aq, options=None, has_name=True) It represents a syslog\-ng configuration statement, e.g. source, destination, filter. .sp Does not need examples. .INDENT 7.0 .TP .B add_child(option) .UNINDENT .INDENT 7.0 .TP .B build_header() Builds the header of a syslog\-ng configuration object. .UNINDENT .INDENT 7.0 .TP .B build_tail() Builds the tail of a syslog\-ng configuration object. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B exception salt.modules.syslog_ng.SyslogNgError .UNINDENT .INDENT 0.0 .TP .B class salt.modules.syslog_ng.TypedParameter(type=\(aq\(aq, values=None) A Parameter, which has a type: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C destination d_tcp { tcp( ip(127.0.0.1) ); }; .ft P .fi .UNINDENT .UNINDENT .sp \fBip(127.0.0.1)\fP is a TypedParameter. .sp Does not need examples. .INDENT 7.0 .TP .B add_value(value) .UNINDENT .INDENT 7.0 .TP .B build() Builds the textual representation of the whole configuration object with its children. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.syslog_ng.TypedParameterValue(type=\(aq\(aq, arguments=None) We have to go deeper... .sp A TypedParameter can have a \(aqparameter\(aq, which also have a type. For example key_file and cert_file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C source demo_tls_source { tcp( ip(0.0.0.0) port(1999) tls( key_file(\(aq/opt/syslog\-ng/etc/syslog\-ng/key.d/syslog\-ng.key\(aq) cert_file(\(aq/opt/syslog\-ng/etc/syslog\-ng/cert.d/syslog\-ng.cert\(aq) ) ); }; .ft P .fi .UNINDENT .UNINDENT .sp Does not need examples. .INDENT 7.0 .TP .B add_argument(arg) .UNINDENT .INDENT 7.0 .TP .B build() Builds the textual representation of the whole configuration object with its children. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.syslog_ng.UnnamedStatement(type, options=None) It represents a configuration statement, which doesn\(aqt have a name, e.g. a log path. .sp Does not need examples. .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.config(name, config, write=True) Builds syslog\-ng configuration. This function is intended to be used from the state module, users should not use it directly! .sp name : the id of the Salt document or it is the format of <statement name>.id config : the parsed YAML code write : if True, it writes the config into the configuration file, otherwise just returns it .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.config name=\(aqs_local\(aq config=\(dq[{\(aqtcp\(aq:[{\(aqip\(aq:\(aq127.0.0.1\(aq},{\(aqport\(aq:1233}]}]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.config_test(syslog_ng_sbin_dir=None, cfgfile=None) Runs syntax check against cfgfile. If syslog_ng_sbin_dir is specified, it is added to the PATH during the test. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.config_test salt \(aq*\(aq syslog_ng.config_test /home/user/install/syslog\-ng/sbin salt \(aq*\(aq syslog_ng.config_test /home/user/install/syslog\-ng/sbin /etc/syslog\-ng/syslog\-ng.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.get_config_file() Returns the configuration directory, which contains syslog\-ng.conf. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.get_config_file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.modules(syslog_ng_sbin_dir=None) Returns the available modules. If syslog_ng_sbin_dir is specified, it is added to the PATH during the execution of the command syslog\-ng. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.modules salt \(aq*\(aq syslog_ng.modules /home/user/install/syslog\-ng/sbin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.reload_(name) Reloads syslog\-ng. This function is intended to be used from states. .sp If \fI\%syslog_ng.set_config_file\fP, is called before, this function will use the set binary path. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.reload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.set_binary_path(name) Sets the path, where the syslog\-ng binary can be found. This function is intended to be used from states. .sp If syslog\-ng is installed via a package manager, users don\(aqt need to use this function. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.set_binary_path name=/usr/sbin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.set_config_file(name) Sets the configuration\(aqs name. This function is intended to be used from states. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.set_config_file name=/etc/syslog\-ng .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.set_parameters(version=None, binary_path=None, config_file=None, *args, **kwargs) Sets variables. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.set_parameters version=\(aq3.6\(aq salt \(aq*\(aq syslog_ng.set_parameters binary_path=/home/user/install/syslog\-ng/sbin config_file=/home/user/install/syslog\-ng/etc/syslog\-ng.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.start(name=None, user=None, group=None, chroot=None, caps=None, no_caps=False, pidfile=None, enable_core=False, fd_limit=None, verbose=False, debug=False, trace=False, yydebug=False, persist_file=None, control=None, worker_threads=None) Ensures, that syslog\-ng is started via the given parameters. This function is intended to be used from the state module. .sp Users shouldn\(aqt use this function, if the service module is available on their system. If \fI\%syslog_ng.set_config_file\fP, is called before, this function will use the set binary path. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.start .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.stats(syslog_ng_sbin_dir=None) Returns statistics from the running syslog\-ng instance. If syslog_ng_sbin_dir is specified, it is added to the PATH during the execution of the command syslog\-ng\-ctl. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.stats salt \(aq*\(aq syslog_ng.stats /home/user/install/syslog\-ng/sbin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.stop(name=None) Kills syslog\-ng. This function is intended to be used from the state module. .sp Users shouldn\(aqt use this function, if the service module is available on their system. If \fI\%syslog_ng.set_config_file\fP is called before, this function will use the set binary path. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.stop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.version(syslog_ng_sbin_dir=None) Returns the version of the installed syslog\-ng. If syslog_ng_sbin_dir is specified, it is added to the PATH during the execution of the command syslog\-ng. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.version salt \(aq*\(aq syslog_ng.version /home/user/install/syslog\-ng/sbin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.write_config(config, newlines=2) Writes the given parameter config into the config file. This function is intended to be used from states. .sp If \fI\%syslog_ng.set_config_file\fP, is called before, this function will use the set config file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.write_config config=\(aq# comment\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.syslog_ng.write_version(name) Removes the previous configuration file, then creates a new one and writes the name line. This function is intended to be used from states. .sp If \fI\%syslog_ng.set_config_file\fP, is called before, this function will use the set config file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq syslog_ng.write_version name=\(dq3.6\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.sysmod .sp The sys module provides information about the available functions on the minion .INDENT 0.0 .TP .B salt.modules.sysmod.argspec(module=\(aq\(aq) Return the argument specification of functions in Salt execution modules. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.argspec pkg.install salt \(aq*\(aq sys.argspec sys salt \(aq*\(aq sys.argspec .ft P .fi .UNINDENT .UNINDENT .sp Module names can be specified as globs. .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.argspec \(aqpkg.*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.doc(*args) Return the docstrings for all modules. Optionally, specify a module or a function to narrow the selection. .sp The strings are aggregated into a single document on the master for easy reading. .sp Multiple modules/functions can be specified. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.doc salt \(aq*\(aq sys.doc sys salt \(aq*\(aq sys.doc sys.doc salt \(aq*\(aq sys.doc network.traceroute user.info .ft P .fi .UNINDENT .UNINDENT .sp Modules can be specified as globs. .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.doc \(aqsys.*\(aq salt \(aq*\(aq sys.doc \(aqsys.list_*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.list_functions(*args, **kwargs) List the functions for all modules. Optionally, specify a module or modules from which to list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_functions salt \(aq*\(aq sys.list_functions sys salt \(aq*\(aq sys.list_functions sys user .ft P .fi .UNINDENT .UNINDENT .sp New in version 0.12.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_functions \(aqmodule.specific_function\(aq .ft P .fi .UNINDENT .UNINDENT .sp Function names can be specified as globs. .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_functions \(aqsys.list_*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.list_modules(*args) List the modules loaded on the minion .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_modules .ft P .fi .UNINDENT .UNINDENT .sp Module names can be specified as globs. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_modules \(aqs*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.list_renderers(*args) List the renderers loaded on the minion .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_renderers .ft P .fi .UNINDENT .UNINDENT .sp Render names can be specified as globs. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_renderers \(aqyaml*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.list_returner_functions(*args, **kwargs) List the functions for all returner modules. Optionally, specify a returner module or modules from which to list. .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_returner_functions salt \(aq*\(aq sys.list_returner_functions mysql salt \(aq*\(aq sys.list_returner_functions mysql etcd .ft P .fi .UNINDENT .UNINDENT .sp Returner names can be specified as globs. .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_returner_functions \(aqsqlite3.get_*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.list_returners(*args) List the returners loaded on the minion .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_returners .ft P .fi .UNINDENT .UNINDENT .sp Returner names can be specified as globs. .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_returners \(aqs*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.list_runner_functions(*args, **kwargs) List the functions for all runner modules. Optionally, specify a runner module or modules from which to list. .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_runner_functions salt \(aq*\(aq sys.list_runner_functions state salt \(aq*\(aq sys.list_runner_functions state virt .ft P .fi .UNINDENT .UNINDENT .sp Runner function names can be specified as globs. .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_runner_functions \(aqstate.*\(aq \(aqvirt.*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.list_runners(*args) List the runners loaded on the minion .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_runners .ft P .fi .UNINDENT .UNINDENT .sp Runner names can be specified as globs. .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_runners \(aqm*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.list_state_functions(*args, **kwargs) List the functions for all state modules. Optionally, specify a state module or modules from which to list. .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_state_functions salt \(aq*\(aq sys.list_state_functions file salt \(aq*\(aq sys.list_state_functions pkg user .ft P .fi .UNINDENT .UNINDENT .sp State function names can be specified as globs. .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_state_functions \(aqfile.*\(aq salt \(aq*\(aq sys.list_state_functions \(aqfile.s*\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.9.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_state_functions \(aqmodule.specific_function\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.list_state_modules(*args) List the modules loaded on the minion .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_state_modules .ft P .fi .UNINDENT .UNINDENT .sp State module names can be specified as globs. .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.list_state_modules \(aqmysql_*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.reload_modules() Tell the minion to reload the execution modules .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.reload_modules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.renderer_doc(*args) Return the docstrings for all renderers. Optionally, specify a renderer or a function to narrow the selection. .sp The strings are aggregated into a single document on the master for easy reading. .sp Multiple renderers can be specified. .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.renderer_doc salt \(aq*\(aq sys.renderer_doc cheetah salt \(aq*\(aq sys.renderer_doc jinja json .ft P .fi .UNINDENT .UNINDENT .sp Renderer names can be specified as globs. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.renderer_doc \(aqc*\(aq \(aqj*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.returner_argspec(module=\(aq\(aq) Return the argument specification of functions in Salt returner modules. .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.returner_argspec xmpp salt \(aq*\(aq sys.returner_argspec xmpp smtp salt \(aq*\(aq sys.returner_argspec .ft P .fi .UNINDENT .UNINDENT .sp Returner names can be specified as globs. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.returner_argspec \(aqsqlite3.*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.returner_doc(*args) Return the docstrings for all returners. Optionally, specify a returner or a function to narrow the selection. .sp The strings are aggregated into a single document on the master for easy reading. .sp Multiple returners/functions can be specified. .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.returner_doc salt \(aq*\(aq sys.returner_doc sqlite3 salt \(aq*\(aq sys.returner_doc sqlite3.get_fun salt \(aq*\(aq sys.returner_doc sqlite3.get_fun etcd.get_fun .ft P .fi .UNINDENT .UNINDENT .sp Returner names can be specified as globs. .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.returner_doc \(aqsqlite3.get_*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.runner_argspec(module=\(aq\(aq) Return the argument specification of functions in Salt runner modules. .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.runner_argspec state salt \(aq*\(aq sys.runner_argspec http salt \(aq*\(aq sys.runner_argspec .ft P .fi .UNINDENT .UNINDENT .sp Runner names can be specified as globs. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.runner_argspec \(aqwinrepo.*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.runner_doc(*args) Return the docstrings for all runners. Optionally, specify a runner or a function to narrow the selection. .sp The strings are aggregated into a single document on the master for easy reading. .sp Multiple runners/functions can be specified. .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.runner_doc salt \(aq*\(aq sys.runner_doc cache salt \(aq*\(aq sys.runner_doc cache.grains salt \(aq*\(aq sys.runner_doc cache.grains mine.get .ft P .fi .UNINDENT .UNINDENT .sp Runner names can be specified as globs. .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.runner_doc \(aqcache.clear_*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.state_argspec(module=\(aq\(aq) Return the argument specification of functions in Salt state modules. .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.state_argspec pkg.installed salt \(aq*\(aq sys.state_argspec file salt \(aq*\(aq sys.state_argspec .ft P .fi .UNINDENT .UNINDENT .sp State names can be specified as globs. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.state_argspec \(aqpkg.*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.state_doc(*args) Return the docstrings for all states. Optionally, specify a state or a function to narrow the selection. .sp The strings are aggregated into a single document on the master for easy reading. .sp Multiple states/functions can be specified. .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.state_doc salt \(aq*\(aq sys.state_doc service salt \(aq*\(aq sys.state_doc service.running salt \(aq*\(aq sys.state_doc service.running ipables.append .ft P .fi .UNINDENT .UNINDENT .sp State names can be specified as globs. .sp New in version 2015.5.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.state_doc \(aqservice.*\(aq \(aqiptables.*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.state_schema(module=\(aq\(aq) Return a JSON Schema for the given state function(s) .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.state_schema salt \(aq*\(aq sys.state_schema pkg.installed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.sysrc .sp sysrc module for FreeBSD .INDENT 0.0 .TP .B salt.modules.sysrc.get(**kwargs) Return system rc configuration variables .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysrc.get includeDefaults=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysrc.remove(name, **kwargs) Remove system rc configuration variables .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysrc.remove name=sshd_enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysrc.set_(name, value, **kwargs) Set system rc configuration variables .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysrc.set name=sshd_flags value=\(dq\-p 2222\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.system .sp Support for reboot, shutdown, etc on POSIX\-like systems. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If a wrapper such as \fBmolly\-guard\fP to intercept \fIinteractive\fP shutdown commands is configured, calling \fI\%system.halt\fP, \fI\%system.poweroff\fP, \fI\%system.reboot\fP, and \fI\%system.shutdown\fP with \fBsalt\-call\fP will hang indefinitely while the wrapper script waits for user input. Calling them with \fBsalt\fP will work as expected. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.get_computer_desc() Get \fBPRETTY_HOSTNAME\fP value stored in \fB/etc/machine\-info\fP If this file doesn\(aqt exist or the variable doesn\(aqt exist return \fBFalse\fP\&. .INDENT 7.0 .TP .B Returns Value of \fBPRETTY_HOSTNAME\fP in \fB/etc/machine\-info\fP\&. If file/variable does not exist \fBFalse\fP\&. .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_computer_desc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.get_computer_name() Get hostname. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.get_hostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.get_reboot_required_witnessed() .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This only applies to Minions running on NI Linux RT .UNINDENT .UNINDENT .sp Determine if at any time during the current boot session the salt minion witnessed an event indicating that a reboot is required. .INDENT 7.0 .TP .B Returns \fBTrue\fP if the a reboot request was witnessed, \fBFalse\fP otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_reboot_required_witnessed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.get_system_date(utc_offset=None) Get the system date .INDENT 7.0 .TP .B Parameters \fButc_offset\fP (\fI\%str\fP) \-\- The UTC offset in 4 digit (\fB+0600\fP) format with an optional sign (\fB+\fP/\fB\-\fP). Will default to \fBNone\fP which will use the local timezone. To set the time based off of UTC use \fB+0000\fP\&. Note: If being passed through the command line will need to be quoted twice to allow negative offsets (e.g. \fB\(dq\(aq+0000\(aq\(dq\fP). .TP .B Returns Returns the system date. .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_system_date .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.get_system_date_time(utc_offset=None) Get the system date/time. .INDENT 7.0 .TP .B Parameters \fButc_offset\fP (\fI\%str\fP) \-\- The UTC offset in 4 digit (\fB+0600\fP) format with an optional sign (\fB+\fP/\fB\-\fP). Will default to \fBNone\fP which will use the local timezone. To set the time based off of UTC use \fB+0000\fP\&. Note: If being passed through the command line will need to be quoted twice to allow negative offsets (e.g. \fB\(dq\(aq+0000\(aq\(dq\fP). .TP .B Returns Returns the system time in \fBYYYY\-MM\-DD hh:mm:ss\fP format. .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_system_date_time \(dq\(aq\-0500\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.get_system_time(utc_offset=None) Get the system time. .INDENT 7.0 .TP .B Parameters \fButc_offset\fP (\fI\%str\fP) \-\- The UTC offset in 4 digit (e.g. \fB+0600\fP) format with an optional sign (\fB+\fP/\fB\-\fP). Will default to \fBNone\fP which will use the local timezone. To set the time based off of UTC use \fB+0000\fP\&. Note: If being passed through the command line will need to be quoted twice to allow negative offsets (e.g. \fB\(dq\(aq+0000\(aq\(dq\fP). .TP .B Returns Returns the system time in \fBHH:MM:SS AM/PM\fP format. .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_system_time .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.halt() Halt a running system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.halt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.has_settable_hwclock() Returns \fBTrue\fP if the system has a hardware clock capable of being set from software. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.has_settable_hwclock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.init(runlevel) Change the system runlevel on sysV compatible systems .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.init 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.poweroff() Poweroff a running system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.poweroff .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.reboot(at_time=None) Reboot the system .INDENT 7.0 .TP .B at_time The wait time in minutes before the system will be rebooted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.reboot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.set_computer_desc(desc) Set \fBPRETTY_HOSTNAME\fP value stored in \fB/etc/machine\-info\fP This will create the file if it does not exist. If it is unable to create or modify this file, \fBFalse\fP is returned. .INDENT 7.0 .TP .B Parameters \fBdesc\fP (\fI\%str\fP) \-\- The computer description .TP .B Returns \fBFalse\fP on failure. \fBTrue\fP if successful. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_computer_desc \(dqMichael\(aqs laptop\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.set_computer_name(hostname) Modify hostname. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_computer_name master.saltstack.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.set_reboot_required_witnessed() .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This only applies to Minions running on NI Linux RT .UNINDENT .UNINDENT .sp This function is used to remember that an event indicating that a reboot is required was witnessed. This function writes to a temporary filesystem so the event gets cleared upon reboot. .INDENT 7.0 .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_reboot_required_witnessed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.set_system_date(newdate, utc_offset=None) Set the system date. Use \fB<mm\-dd\-yy>\fP format for the date. .INDENT 7.0 .TP .B Parameters \fBnewdate\fP (\fI\%str\fP) \-\- .sp The date to set. Can be any of the following formats: .INDENT 7.0 .IP \(bu 2 \fBYYYY\-MM\-DD\fP .IP \(bu 2 \fBMM\-DD\-YYYY\fP .IP \(bu 2 \fBMM\-DD\-YY\fP .IP \(bu 2 \fBMM/DD/YYYY\fP .IP \(bu 2 \fBMM/DD/YY\fP .IP \(bu 2 \fBYYYY/MM/DD\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_system_date \(aq03\-28\-13\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.set_system_date_time(years=None, months=None, days=None, hours=None, minutes=None, seconds=None, utc_offset=None) Set the system date and time. Each argument is an element of the date, but not required. If an element is not passed, the current system value for that element will be used. For example, if the year is not passed, the current system year will be used. (Used by \fI\%system.set_system_date\fP and \fI\%system.set_system_time\fP) .sp Updates hardware clock, if present, in addition to software (kernel) clock. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fByears\fP (\fI\%int\fP) \-\- Years digit, e.g.: \fB2015\fP .IP \(bu 2 \fBmonths\fP (\fI\%int\fP) \-\- Months digit: \fB1\fP\-\fB12\fP .IP \(bu 2 \fBdays\fP (\fI\%int\fP) \-\- Days digit: \fB1\fP\-\fB31\fP .IP \(bu 2 \fBhours\fP (\fI\%int\fP) \-\- Hours digit: \fB0\fP\-\fB23\fP .IP \(bu 2 \fBminutes\fP (\fI\%int\fP) \-\- Minutes digit: \fB0\fP\-\fB59\fP .IP \(bu 2 \fBseconds\fP (\fI\%int\fP) \-\- Seconds digit: \fB0\fP\-\fB59\fP .IP \(bu 2 \fButc_offset\fP (\fI\%str\fP) \-\- The UTC offset in 4 digit (\fB+0600\fP) format with an optional sign (\fB+\fP/\fB\-\fP). Will default to \fBNone\fP which will use the local timezone. To set the time based off of UTC use \fB+0000\fP\&. Note: If being passed through the command line will need to be quoted twice to allow negative offsets (e.g. \fB\(dq\(aq+0000\(aq\(dq\fP). .UNINDENT .TP .B Returns \fBTrue\fP if successful. Otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_system_date_time 2015 5 12 11 37 53 \(dq\(aq\-0500\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.set_system_time(newtime, utc_offset=None) Set the system time. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnewtime\fP (\fI\%str\fP) \-\- .sp The time to set. Can be any of the following formats. .INDENT 2.0 .IP \(bu 2 \fBHH:MM:SS AM/PM\fP .IP \(bu 2 \fBHH:MM AM/PM\fP .IP \(bu 2 \fBHH:MM:SS\fP (24 hour) .IP \(bu 2 \fBHH:MM\fP (24 hour) .UNINDENT .sp Note that the Salt command line parser parses the date/time before we obtain the argument (preventing us from doing UTC) Therefore the argument must be passed in as a string. Meaning the text might have to be quoted twice on the command line. .IP \(bu 2 \fButc_offset\fP (\fI\%str\fP) \-\- The UTC offset in 4 digit (\fB+0600\fP) format with an optional sign (\fB+\fP/\fB\-\fP). Will default to \fBNone\fP which will use the local timezone. To set the time based off of UTC use \fB+0000\fP\&. Note: If being passed through the command line will need to be quoted twice to allow negative offsets (e.g. \fB\(dq\(aq+0000\(aq\(dq\fP) .UNINDENT .TP .B Returns Returns \fBTrue\fP if successful. Otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_system_time \(dq\(aq11:20\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.shutdown(at_time=None) Shutdown a running system .INDENT 7.0 .TP .B at_time The wait time in minutes before the system will be shutdown. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.shutdown 5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.system_profiler .sp System Profiler Module .sp Interface with macOS\(aqs command\-line System Profiler utility to get information about package receipts and installed applications. .sp New in version 2015.5.0. .INDENT 0.0 .TP .B salt.modules.system_profiler.applications() Return the results of a call to \fBsystem_profiler \-xml \-detail full SPApplicationsDataType\fP as a dictionary. Top\-level keys of the dictionary are the names of each set of install receipts, since there can be multiple receipts with the same name. Contents of each key are a list of dictionaries. .sp Note that this can take a long time depending on how many applications are installed on the target Mac. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq systemprofiler.applications .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system_profiler.receipts() Return the results of a call to \fBsystem_profiler \-xml \-detail full SPInstallHistoryDataType\fP as a dictionary. Top\-level keys of the dictionary are the names of each set of install receipts, since there can be multiple receipts with the same name. Contents of each key are a list of dictionaries. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq systemprofiler.receipts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.systemd_service .sp Provides the service module for systemd .sp New in version 0.10.0. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage services on a minion, and it is using a different module (or gives an error similar to \fI\(aqservice.start\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 This is an implementation of virtual \(aqservice\(aq module. As such, you must call it under the name \(aqservice\(aq and NOT \(aqsystemd\(aq. You can see that also in the examples below. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.available(name) New in version 0.10.4. .sp Check that the given service is available taking into account template units. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.disable(name, no_block=False, root=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 run by this function from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to avoid a race condition in cases where the \fBsalt\-minion\fP service is restarted while a service is being modified. If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Disable the named service to not start when the system boots .INDENT 7.0 .TP .B no_block False Set to \fBTrue\fP to start the service using \fB\-\-no\-block\fP\&. .sp New in version 2017.7.0. .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.disabled(name, root=None) Return if the named service is disabled from starting on boot .INDENT 7.0 .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.enable(name, no_block=False, unmask=False, unmask_runtime=False, root=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 run by this function from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to avoid a race condition in cases where the \fBsalt\-minion\fP service is restarted while a service is being modified. If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Enable the named service to start when the system boots .INDENT 7.0 .TP .B no_block False Set to \fBTrue\fP to start the service using \fB\-\-no\-block\fP\&. .sp New in version 2017.7.0. .TP .B unmask False Set to \fBTrue\fP to remove an indefinite mask before attempting to enable the service. .sp New in version 2017.7.0: In previous releases, Salt would simply unmask a service before enabling. This behavior is no longer the default. .TP .B unmask_runtime False Set to \fBTrue\fP to remove a runtime mask before attempting to enable the service. .sp New in version 2017.7.0: In previous releases, Salt would simply unmask a service before enabling. This behavior is no longer the default. .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.enabled(name, root=None, **kwargs) Return if the named service is enabled to start on boot .INDENT 7.0 .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.execs(root=None) New in version 2014.7.0. .sp Return a list of all files specified as \fBExecStart\fP for all services. .INDENT 7.0 .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.execs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.firstboot(locale=None, locale_message=None, keymap=None, timezone=None, hostname=None, machine_id=None, root=None) New in version 3001. .sp Call systemd\-firstboot to configure basic settings of the system .INDENT 7.0 .TP .B locale Set primary locale (LANG=) .TP .B locale_message Set message locale (LC_MESSAGES=) .TP .B keymap Set keymap .TP .B timezone Set timezone .TP .B hostname Set host name .TP .B machine_id Set machine ID .TP .B root Operate on an alternative filesystem root .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.firstboot keymap=jp locale=en_US.UTF\-8 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.force_reload(name, no_block=True, unmask=False, unmask_runtime=False) 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 run by this function from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to avoid a race condition in cases where the \fBsalt\-minion\fP service is restarted while a service is being modified. If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp New in version 0.12.0. .sp Force\-reload the specified service with systemd .INDENT 7.0 .TP .B no_block False Set to \fBTrue\fP to start the service using \fB\-\-no\-block\fP\&. .sp New in version 2017.7.0. .TP .B unmask False Set to \fBTrue\fP to remove an indefinite mask before attempting to force\-reload the service. .sp New in version 2017.7.0: In previous releases, Salt would simply unmask a service before force\-reloading. This behavior is no longer the default. .TP .B unmask_runtime False Set to \fBTrue\fP to remove a runtime mask before attempting to force\-reload the service. .sp New in version 2017.7.0: In previous releases, Salt would simply unmask a service before force\-reloading. This behavior is no longer the default. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.force_reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.get_all(root=None) Return a list of all available services .INDENT 7.0 .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.get_disabled(root=None) Return a list of all disabled services .INDENT 7.0 .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.get_enabled(root=None) Return a list of all enabled services .INDENT 7.0 .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.get_running() Return a list of all running services, so far as systemd is concerned .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_running .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.get_static(root=None) New in version 2015.8.5. .sp Return a list of all static services .INDENT 7.0 .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_static .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.mask(name, runtime=False, root=None) New in version 2015.5.0. .sp 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 run by this function from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to avoid a race condition in cases where the \fBsalt\-minion\fP service is restarted while a service is being modified. If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Mask the specified service with systemd .INDENT 7.0 .TP .B runtime False Set to \fBTrue\fP to mask this service only until the next reboot .sp New in version 2015.8.5. .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.mask foo salt \(aq*\(aq service.mask foo runtime=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.masked(name, runtime=False, root=None) New in version 2015.8.0. .sp Changed in version 2015.8.5: The return data for this function has changed. If the service is masked, the return value will now be the output of the \fBsystemctl is\-enabled\fP command (so that a persistent mask can be distinguished from a runtime mask). If the service is not masked, then \fBFalse\fP will be returned. .sp Changed in version 2017.7.0: This function now returns a boolean telling the user whether a mask specified by the new \fBruntime\fP argument is set. If \fBruntime\fP is \fBFalse\fP, this function will return \fBTrue\fP if an indefinite mask is set for the named service (otherwise \fBFalse\fP will be returned). If \fBruntime\fP is \fBFalse\fP, this function will return \fBTrue\fP if a runtime mask is set, otherwise \fBFalse\fP\&. .sp Check whether or not a service is masked .INDENT 7.0 .TP .B runtime False Set to \fBTrue\fP to check for a runtime mask .sp New in version 2017.7.0: In previous versions, this function would simply return the output of \fBsystemctl is\-enabled\fP when the service was found to be masked. However, since it is possible to both have both indefinite and runtime masks on a service simultaneously, this function now only checks for runtime masks if this argument is set to \fBTrue\fP\&. Otherwise, it will check for an indefinite mask. .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.masked foo salt \(aq*\(aq service.masked foo runtime=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.missing(name) New in version 2014.1.0. .sp The inverse of \fBservice.available\fP\&. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.offline() New in version 3004. .sp Check if systemd is working in offline mode, where is not possible to talk with PID 1. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.offline .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.reload_(name, no_block=False, unmask=False, unmask_runtime=False) 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 run by this function from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to avoid a race condition in cases where the \fBsalt\-minion\fP service is restarted while a service is being modified. If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Reload the specified service with systemd .INDENT 7.0 .TP .B no_block False Set to \fBTrue\fP to reload the service using \fB\-\-no\-block\fP\&. .sp New in version 2017.7.0. .TP .B unmask False Set to \fBTrue\fP to remove an indefinite mask before attempting to reload the service. .sp New in version 2017.7.0: In previous releases, Salt would simply unmask a service before reloading. This behavior is no longer the default. .TP .B unmask_runtime False Set to \fBTrue\fP to remove a runtime mask before attempting to reload the service. .sp New in version 2017.7.0: In previous releases, Salt would simply unmask a service before reloading. This behavior is no longer the default. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.restart(name, no_block=False, unmask=False, unmask_runtime=False) 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 run by this function from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to avoid a race condition in cases where the \fBsalt\-minion\fP service is restarted while a service is being modified. If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Restart the specified service with systemd .INDENT 7.0 .TP .B no_block False Set to \fBTrue\fP to start the service using \fB\-\-no\-block\fP\&. .sp New in version 2017.7.0. .TP .B unmask False Set to \fBTrue\fP to remove an indefinite mask before attempting to restart the service. .sp New in version 2017.7.0: In previous releases, Salt would simply unmask a service before restarting. This behavior is no longer the default. .TP .B unmask_runtime False Set to \fBTrue\fP to remove a runtime mask before attempting to restart the service. .sp New in version 2017.7.0: In previous releases, Salt would simply unmask a service before restarting. This behavior is no longer the default. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.show(name, root=None) New in version 2014.7.0. .sp Show properties of one or more units/jobs or the manager .INDENT 7.0 .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.show <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.start(name, no_block=False, unmask=False, unmask_runtime=False) 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 run by this function from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to avoid a race condition in cases where the \fBsalt\-minion\fP service is restarted while a service is being modified. If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Start the specified service with systemd .INDENT 7.0 .TP .B no_block False Set to \fBTrue\fP to start the service using \fB\-\-no\-block\fP\&. .sp New in version 2017.7.0. .TP .B unmask False Set to \fBTrue\fP to remove an indefinite mask before attempting to start the service. .sp New in version 2017.7.0: In previous releases, Salt would simply unmask a service before starting. This behavior is no longer the default. .TP .B unmask_runtime False Set to \fBTrue\fP to remove a runtime mask before attempting to start the service. .sp New in version 2017.7.0: In previous releases, Salt would simply unmask a service before starting. This behavior is no longer the default. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.status(name, sig=None) Return the status for a service via systemd. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Not implemented .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> [service signature] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.stop(name, no_block=False) 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 run by this function from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to avoid a race condition in cases where the \fBsalt\-minion\fP service is restarted while a service is being modified. If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Stop the specified service with systemd .INDENT 7.0 .TP .B no_block False Set to \fBTrue\fP to start the service using \fB\-\-no\-block\fP\&. .sp New in version 2017.7.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.systemctl_reload() New in version 0.15.0. .sp Reloads systemctl, an action needed whenever unit files are updated. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.systemctl_reload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd_service.unmask_(name, runtime=False, root=None) New in version 2015.5.0. .sp 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 run by this function from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to avoid a race condition in cases where the \fBsalt\-minion\fP service is restarted while a service is being modified. If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Unmask the specified service with systemd .INDENT 7.0 .TP .B runtime False Set to \fBTrue\fP to unmask this service only until the next reboot .sp New in version 2017.7.0: In previous versions, this function would remove whichever mask was identified by running \fBsystemctl is\-enabled\fP on the service. However, since it is possible to both have both indefinite and runtime masks on a service simultaneously, this function now removes a runtime mask only when this argument is set to \fBTrue\fP, and otherwise removes an indefinite mask. .TP .B root Enable/disable/mask unit files in the specified root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.unmask foo salt \(aq*\(aq service.unmask foo runtime=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.telegram .sp Module for sending messages via Telegram. .INDENT 0.0 .TP .B configuration In order to send a message via the Telegram, certain configuration is required in /etc/salt/minion on the relevant minions or in the pillar. Some sample configs might look like: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C telegram.chat_id: \(aq123456789\(aq telegram.token: \(aq00000000:xxxxxxxxxxxxxxxxxxxxxxxx\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.telegram.post_message(message, chat_id=None, token=None) Send a message to a Telegram chat. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmessage\fP \-\- The message to send to the Telegram chat. .IP \(bu 2 \fBchat_id\fP \-\- (optional) The Telegram chat id. .IP \(bu 2 \fBtoken\fP \-\- (optional) The Telegram API token. .UNINDENT .TP .B Returns Boolean if message was sent successfully. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq telegram.post_message message=\(dqHello Telegram!\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.telemetry .sp Connection module for Telemetry .sp New in version 2016.3.0. .sp \fI\%https://github.com/mongolab/mongolab\-telemetry\-api\-docs/blob/master/alerts.md\fP .INDENT 0.0 .TP .B configuration This module accepts explicit telemetry credentials or can also read api key credentials from a pillar. More Information available \fI\%here\fP\&. .UNINDENT .sp In the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C telemetry.telemetry_api_keys: \- abc123 # Key 1 \- efg321 # Backup Key 1 telemetry_api_base_url: https://telemetry\-api.mongolab.com/v0 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends requests .UNINDENT .INDENT 0.0 .TP .B salt.modules.telemetry.create_alarm(deployment_id, metric_name, data, api_key=None, profile=\(aqtelemetry\(aq) create an telemetry alarms. .sp data is a dict of alert configuration data. .sp Returns (bool success, str message) tuple. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion telemetry.create_alarm rs\-ds033197 {} profile=telemetry .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.telemetry.delete_alarms(deployment_id, alert_id=None, metric_name=None, api_key=None, profile=\(aqtelemetry\(aq) .INDENT 7.0 .TP .B delete an alert specified by alert_id or if not specified blows away all the alerts in the current deployment. .UNINDENT .sp Returns (bool success, str message) tuple. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion telemetry.delete_alarms rs\-ds033197 profile=telemetry .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.telemetry.get_alarms(deployment_id, profile=\(aqtelemetry\(aq) get all the alarms set up against the current deployment .sp Returns dictionary of alarm information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion telemetry.get_alarms rs\-ds033197 profile=telemetry .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.telemetry.get_alert_config(deployment_id, metric_name=None, api_key=None, profile=\(aqtelemetry\(aq) Get all alert definitions associated with a given deployment or if metric_name is specified, obtain the specific alert config .sp Returns dictionary or list of dictionaries. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion telemetry.get_alert_config rs\-ds033197 currentConnections profile=telemetry salt myminion telemetry.get_alert_config rs\-ds033197 profile=telemetry .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.telemetry.get_notification_channel_id(notify_channel, profile=\(aqtelemetry\(aq) Given an email address, creates a notification\-channels if one is not found and also returns the corresponding notification channel id. .INDENT 7.0 .TP .B notify_channel Email escalation policy .TP .B profile A dict of telemetry config information. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion telemetry.get_notification_channel_id userx@company.com profile=telemetry .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.telemetry.update_alarm(deployment_id, metric_name, data, api_key=None, profile=\(aqtelemetry\(aq) update an telemetry alarms. data is a dict of alert configuration data. .sp Returns (bool success, str message) tuple. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion telemetry.update_alarm rs\-ds033197 {} profile=telemetry .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.temp .sp Simple module for creating temporary directories and files .sp This is a thin wrapper around Pythons tempfile module .sp New in version 2015.8.0. .INDENT 0.0 .TP .B salt.modules.temp.dir(suffix=\(aq\(aq, prefix=\(aqtmp\(aq, parent=None) Create a temporary directory .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq temp.dir salt \(aq*\(aq temp.dir prefix=\(aqmytemp\-\(aq parent=\(aq/var/run/\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.temp.file(suffix=\(aq\(aq, prefix=\(aqtmp\(aq, parent=None) Create a temporary file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq temp.file salt \(aq*\(aq temp.file prefix=\(aqmytemp\-\(aq parent=\(aq/var/run/\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.test .sp Module for running arbitrary tests .INDENT 0.0 .TP .B salt.modules.test.arg(*args, **kwargs) Print out the data passed into the function \fB*args\fP and \fBkwargs\fP, this is used to both test the publication data and CLI argument passing, but also to display the information available within the publication data. .INDENT 7.0 .TP .B Returns \fB{\(dqargs\(dq: args, \(dqkwargs\(dq: kwargs}\fP .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.arg 1 \(dqtwo\(dq 3.1 txt=\(dqhello\(dq wow=\(aq{a: 1, b: \(dqhello\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.arg_clean(*args, **kwargs) Like \fI\%test.arg\fP but cleans \fBkwargs\fP of the \fB__pub*\fP items .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.arg_clean 1 \(dqtwo\(dq 3.1 txt=\(dqhello\(dq wow=\(aq{a: 1, b: \(dqhello\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.arg_repr(*args, **kwargs) Print out the data passed into the function \fB*args\fP and \fBkwargs\fP, this is used to both test the publication data and CLI argument passing, but also to display the information available within the publication data. .INDENT 7.0 .TP .B Returns \fB{\(dqargs\(dq: repr(args), \(dqkwargs\(dq: repr(kwargs)}\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.arg_repr 1 \(dqtwo\(dq 3.1 txt=\(dqhello\(dq wow=\(aq{a: 1, b: \(dqhello\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.arg_type(*args, **kwargs) Print out the types of the \fBargs\fP and \fBkwargs\fP\&. This is used to test the types of the \fBargs\fP and \fBkwargs\fP passed down to the Minion .INDENT 7.0 .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.arg_type 1 \(aqint\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.assertion(assertion) Assert the given argument .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.assertion False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.attr_call() Call grains.items via the attribute .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.attr_call .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.collatz(start) Execute the collatz conjecture from the passed starting number, returns the sequence and the time it took to compute. Used for performance tests. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.collatz 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.conf_test() Return the value for test.foo in the minion configuration file, or return the default value .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.conf_test .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.cross_test(func, args=None) Execute a minion function via the \fB__salt__\fP object in the test module, used to verify that the Minion functions can be called via the \fB__salt__\fP module. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.cross_test file.gid_to_group 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.deprecation_warning() Return True, but also produce two DeprecationWarnings. One by date, the other by the codename \- release Oganesson, which should correspond to Salt 3108. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \e* test.deprecation_warning .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.echo(text) Return a string \- used for testing the connection .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.echo \(aqfoo bar baz quo qux\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.exception(message=\(aqTest Exception\(aq) Raise an exception .sp Optionally provide an error message or output the full stack. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.exception \(aqOh noes!\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.false_() Always return \fBFalse\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.false .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.fib(num) Return the \fBnum\fP\-th Fibonacci number, and the time it took to compute in seconds. Used for performance tests. .sp This function is designed to have terrible performance. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.fib 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.get_opts() Return the configuration options passed to this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.get_opts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.kwarg(**kwargs) Print out the data passed into the function \fB**kwargs\fP, this is used to both test the publication data and CLI \fBkwarg\fP passing, but also to display the information available within the publication data. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.kwarg num=1 txt=\(dqtwo\(dq env=\(aq{a: 1, b: \(dqhello\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.missing_func() .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.module_report() Return a dict containing all of the execution modules with a report on the overall availability via different references .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.module_report .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.not_loaded() List the modules that were not loaded by the salt loader system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.not_loaded .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.opts_pkg() Return an \fBopts\fP package with the \fBgrains\fP and \fBopts\fP for this Minion. This is primarily used to create the options used for Master side state compiling routines .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.opts_pkg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.outputter(data) Test the outputter, pass in data to return .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.outputter foobar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.ping() Used to make sure the minion is up and responding. Not an ICMP ping. .sp Returns \fBTrue\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.provider(module) Pass in a function name to discover what provider is being used .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.provider service .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.providers() Return a dict of the provider names and the files that provided them .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.providers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.raise_exception(name, *args, **kwargs) Raise an exception. Built\-in exceptions and those in \fBsalt.exceptions\fP can be raised by this test function. If no matching exception is found, then no exception will be raised and this function will return \fBFalse\fP\&. .sp This function is designed to test Salt\(aqs exception and return code handling. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.raise_exception TypeError \(dqAn integer is required\(dq salt \(aq*\(aq test.raise_exception salt.exceptions.CommandExecutionError \(dqSomething went wrong\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.rand_sleep(max=60) Sleep for a random number of seconds, used to test long\-running commands and minions returning at differing intervals .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.rand_sleep 60 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.rand_str(size=9999999999, hash_type=None) This function has been renamed to \fI\%test.random_hash\fP\&. This function will stay to ensure backwards compatibility, but please switch to using the preferred name \fI\%test.random_hash\fP\&. .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.random_hash(size=9999999999, hash_type=None) New in version 2015.5.2. .sp Changed in version 2018.3.0: Function has been renamed from \fBtest.rand_str\fP to \fBtest.random_hash\fP .sp Generates a random number between 1 and \fBsize\fP, then returns a hash of that number. If no \fBhash_type\fP is passed, the \fBhash_type\fP specified by the Minion\(aqs \fI\%hash_type\fP config option is used. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.random_hash salt \(aq*\(aq test.random_hash hash_type=sha512 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.retcode(code=42) Test that the returncode system is functioning correctly .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.retcode 42 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.sleep(length) Instruct the minion to initiate a process that will sleep for a given period of time. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.sleep 20 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.stack() Return the current stack trace .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.stack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.true_() Always return \fBTrue\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.try_(module, return_try_exception=False, **kwargs) Try to run a module command. On an exception return \fBNone\fP\&. If \fBreturn_try_exception\fP is set to \fBTrue\fP, return the exception. This can be helpful in templates where running a module might fail as expected. .sp Jinja Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% for i in range(0,230) %} {{ salt[\(aqtest.try\(aq](module=\(aqipmi.get_users\(aq, bmc_host=\(aq172.2.2.\(aq+i)|yaml(False) }} {% endfor %} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.tty(*args, **kwargs) Deprecated! Moved to \fI\%cmd.tty\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.tty tty0 \(aqThis is a test\(aq salt \(aq*\(aq test.tty pts3 \(aqThis is a test\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.version() Return the version of salt on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.versions() This function is an alias of \fBversions_report\fP\&. .INDENT 7.0 .INDENT 3.5 Returns versions of components used by salt .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.versions_report .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.versions_information() Report the versions of dependent and system software .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.versions_information .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.versions_report() Returns versions of components used by salt .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.versions_report .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.test_virtual .sp Module for testing that a __virtual__ function returning False will not be available via the Salt Loader. .INDENT 0.0 .TP .B salt.modules.test_virtual.ping() .UNINDENT .SS salt.modules.testinframod .sp This module exposes the functionality of the TestInfra library for use with SaltStack in order to verify the state of your minions. In order to allow for the addition of new resource types in TestInfra this module dynamically generates wrappers for the various resources by iterating over the values in the \fB__all__\fP variable exposed by the testinfra.modules namespace. .INDENT 0.0 .TP .B exception salt.modules.testinframod.InvalidArgumentError .UNINDENT .INDENT 0.0 .TP .B salt.modules.testinframod.camel_to_snake_case(camel_input) Converts camelCase (or CamelCase) to snake_case. From \fI\%https://codereview.stackexchange.com/questions/185966/functions\-to\-convert\-camelcase\-strings\-to\-snake\-case\fP .INDENT 7.0 .TP .B Parameters \fBcamel_input\fP (\fI\%str\fP) \-\- The camelcase or CamelCase string to convert to snake_case .UNINDENT .sp :return str .UNINDENT .INDENT 0.0 .TP .B salt.modules.testinframod.snake_to_camel_case(snake_input, uppercamel=False) Converts snake_case to camelCase (or CamelCase if uppercamel is \fBTrue\fP). Inspired by \fI\%https://codereview.stackexchange.com/questions/85311/transform\-snake\-case\-to\-camelcase\fP .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsnake_input\fP (\fI\%str\fP) \-\- The input snake_case string to convert to camelCase .IP \(bu 2 \fBuppercamel\fP (\fI\%bool\fP) \-\- Whether or not to convert to CamelCase instead .UNINDENT .UNINDENT .sp :return str .UNINDENT .SS salt.modules.textfsm_mod .SS TextFSM .sp New in version 2018.3.0. .sp Execution module that processes plain text and extracts data using TextFSM templates. The output is presented in JSON serializable data, and can be easily re\-used in other modules, or directly inside the renderer (Jinja, Mako, Genshi, etc.). .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 textfsm Python library .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Install \fBtextfsm\fP library: \fBpip install textfsm\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.textfsm_mod.extract(template_path, raw_text=None, raw_text_file=None, saltenv=\(aqbase\(aq) Extracts the data entities from the unstructured raw text sent as input and returns the data mapping, processing using the TextFSM template. .INDENT 7.0 .TP .B template_path The path to the TextFSM template. 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 template 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 raw_text: \fBNone\fP The unstructured text to be parsed. .TP .B raw_text_file: \fBNone\fP Text file to read, having the raw text to be parsed using the TextFSM template. Supports the same URL schemes as the \fBtemplate_path\fP argument. .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBtemplate_path\fP is not a \fBsalt://\fP URL. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq textfsm.extract salt://textfsm/juniper_version_template raw_text_file=s3://junos_ver.txt salt \(aq*\(aq textfsm.extract http://some\-server/textfsm/juniper_version_template raw_text=\(aqHostname: router.abc ... snip ...\(aq .ft P .fi .UNINDENT .UNINDENT .sp Jinja template example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set raw_text = \(aqHostname: router.abc ... snip ...\(aq \-%} {%\- set textfsm_extract = salt.textfsm.extract(\(aqhttps://some\-server/textfsm/juniper_version_template\(aq, raw_text) \-%} .ft P .fi .UNINDENT .UNINDENT .sp Raw text example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Hostname: router.abc Model: mx960 JUNOS Base OS boot [9.1S3.5] JUNOS Base OS Software Suite [9.1S3.5] JUNOS Kernel Software Suite [9.1S3.5] JUNOS Crypto Software Suite [9.1S3.5] JUNOS Packet Forwarding Engine Support (M/T Common) [9.1S3.5] JUNOS Packet Forwarding Engine Support (MX Common) [9.1S3.5] JUNOS Online Documentation [9.1S3.5] JUNOS Routing Software Suite [9.1S3.5] .ft P .fi .UNINDENT .UNINDENT .sp TextFSM Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Value Chassis (\eS+) Value Required Model (\eS+) Value Boot (.*) Value Base (.*) Value Kernel (.*) Value Crypto (.*) Value Documentation (.*) Value Routing (.*) Start # Support multiple chassis systems. ^\eS+:$$ \-> Continue.Record ^${Chassis}:$$ ^Model: ${Model} ^JUNOS Base OS boot \e[${Boot}\e] ^JUNOS Software Release \e[${Base}\e] ^JUNOS Base OS Software Suite \e[${Base}\e] ^JUNOS Kernel Software Suite \e[${Kernel}\e] ^JUNOS Crypto Software Suite \e[${Crypto}\e] ^JUNOS Online Documentation \e[${Documentation}\e] ^JUNOS Routing Software Suite \e[${Routing}\e] .ft P .fi .UNINDENT .UNINDENT .sp Output example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(dqcomment\(dq: \(dq\(dq, \(dqresult\(dq: true, \(dqout\(dq: [ { \(dqkernel\(dq: \(dq9.1S3.5\(dq, \(dqdocumentation\(dq: \(dq9.1S3.5\(dq, \(dqboot\(dq: \(dq9.1S3.5\(dq, \(dqcrypto\(dq: \(dq9.1S3.5\(dq, \(dqchassis\(dq: \(dq\(dq, \(dqrouting\(dq: \(dq9.1S3.5\(dq, \(dqbase\(dq: \(dq9.1S3.5\(dq, \(dqmodel\(dq: \(dqmx960\(dq } ] } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.textfsm_mod.index(command, platform=None, platform_grain_name=None, platform_column_name=None, output=None, output_file=None, textfsm_path=None, index_file=None, saltenv=\(aqbase\(aq, include_empty=False, include_pat=None, exclude_pat=None) Dynamically identify the template required to extract the information from the unstructured raw text. .sp The output has the same structure as the \fBextract\fP execution function, the difference being that \fBindex\fP is capable to identify what template to use, based on the platform details and the \fBcommand\fP\&. .INDENT 7.0 .TP .B command The command executed on the device, to get the output. .TP .B platform The platform name, as defined in the TextFSM index file. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For ease of use, it is recommended to define the TextFSM indexfile with values that can be matches using the grains. .UNINDENT .UNINDENT .TP .B platform_grain_name The name of the grain used to identify the platform name in the TextFSM index file. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option can be also specified in the minion configuration file or pillar as \fBtextfsm_platform_grain\fP\&. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is ignored when \fBplatform\fP is specified. .UNINDENT .UNINDENT .TP .B platform_column_name: \fBPlatform\fP The column name used to identify the platform, exactly as specified in the TextFSM index file. Default: \fBPlatform\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is field is case sensitive, make sure to assign the correct value to this option, exactly as defined in the index file. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option can be also specified in the minion configuration file or pillar as \fBtextfsm_platform_column_name\fP\&. .UNINDENT .UNINDENT .TP .B output The raw output from the device, to be parsed and extract the structured data. .TP .B output_file The path to a file that contains the raw output from the device, used to extract the structured data. This option supports the usual Salt\-specific schemes: \fBfile://\fP, \fBsalt://\fP, \fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP, \fBs3://\fP, \fBswift://\fP\&. .TP .B textfsm_path The path where the TextFSM templates can be found. This can be either absolute path on the server, either specified using the following URL schemes: \fBfile://\fP, \fBsalt://\fP, \fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP, \fBs3://\fP, \fBswift://\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This needs to be a directory with a flat structure, having an index file (whose name can be specified using the \fBindex_file\fP option) and a number of TextFSM templates. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option can be also specified in the minion configuration file or pillar as \fBtextfsm_path\fP\&. .UNINDENT .UNINDENT .TP .B index_file: \fBindex\fP The name of the TextFSM index file, under the \fBtextfsm_path\fP\&. Default: \fBindex\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option can be also specified in the minion configuration file or pillar as \fBtextfsm_index_file\fP\&. .UNINDENT .UNINDENT .TP .B saltenv: \fBbase\fP Salt fileserver environment from which to retrieve the file. Ignored if \fBtextfsm_path\fP is not a \fBsalt://\fP URL. .TP .B include_empty: \fBFalse\fP Include empty files under the \fBtextfsm_path\fP\&. .TP .B include_pat Glob or regex to narrow down the files cached from the given path. If matching with a regex, the regex must be prefixed with \fBE@\fP, otherwise the expression will be interpreted as a glob. .TP .B exclude_pat Glob or regex to exclude certain files from being cached from the given path. If matching with a regex, the regex must be prefixed with \fBE@\fP, otherwise the expression will be interpreted as a glob. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If used with \fBinclude_pat\fP, files matching this pattern will be excluded from the subset of files defined by \fBinclude_pat\fP\&. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq textfsm.index \(aqsh ver\(aq platform=Juniper output_file=salt://textfsm/juniper_version_example textfsm_path=salt://textfsm/ salt \(aq*\(aq textfsm.index \(aqsh ver\(aq output_file=salt://textfsm/juniper_version_example textfsm_path=ftp://textfsm/ platform_column_name=Vendor salt \(aq*\(aq textfsm.index \(aqsh ver\(aq output_file=salt://textfsm/juniper_version_example textfsm_path=https://some\-server/textfsm/ platform_column_name=Vendor platform_grain_name=vendor .ft P .fi .UNINDENT .UNINDENT .sp TextFSM index file example: .sp \fBsalt://textfsm/index\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Template, Hostname, Vendor, Command juniper_version_template, .*, Juniper, sh[[ow]] ve[[rsion]] .ft P .fi .UNINDENT .UNINDENT .sp The usage can be simplified, by defining (some of) the following options: \fBtextfsm_platform_grain\fP, \fBtextfsm_path\fP, \fBtextfsm_platform_column_name\fP, or \fBtextfsm_index_file\fP, in the (proxy) minion configuration file or pillar. .sp Configuration example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C textfsm_platform_grain: vendor textfsm_path: salt://textfsm/ textfsm_platform_column_name: Vendor .ft P .fi .UNINDENT .UNINDENT .sp And the CLI usage becomes as simple as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq textfsm.index \(aqsh ver\(aq output_file=salt://textfsm/juniper_version_example .ft P .fi .UNINDENT .UNINDENT .sp Usgae inside a Jinja template: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set command = \(aqsh ver\(aq \-%} {%\- set output = salt.net.cli(command) \-%} {%\- set textfsm_extract = salt.textfsm.index(command, output=output) \-%} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.timezone .sp Module for managing timezone on POSIX\-like systems. .INDENT 0.0 .TP .B salt.modules.timezone.get_hwclock() Get current hardware clock setting (UTC or localtime) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_hwclock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.timezone.get_offset() Get current numeric timezone offset from UTC (i.e. \-0700) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_offset .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.timezone.get_zone() Get current timezone (i.e. America/Denver) .sp Changed in version 2016.11.4. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On AIX operating systems, Posix values can also be returned \(aqCST6CDT,M3.2.0/2:00:00,M11.1.0/2:00:00\(aq .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.timezone.get_zonecode() Get current timezone (i.e. PST, MDT, etc) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_zonecode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.timezone.set_hwclock(clock) Sets the hardware clock to be either UTC or localtime .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.set_hwclock UTC .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.timezone.set_zone(timezone) Unlinks, then symlinks /etc/localtime to the set timezone. .sp The timezone is crucial to several system processes, each of which SHOULD be restarted (for instance, whatever you system uses as its cron and syslog daemons). This will not be automagically done and must be done manually! .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.set_zone \(aqAmerica/Denver\(aq .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2016.11.4. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On AIX operating systems, Posix values are also allowed, see below .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.set_zone \(aqCST6CDT,M3.2.0/2:00:00,M11.1.0/2:00:00\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.timezone.zone_compare(timezone) Compares the given timezone name with the system timezone name. Checks the hash sum between the given timezone, and the one set in /etc/localtime. Returns True if names and hash sums match, and False if not. Mostly useful for running state checks. .sp Changed in version 2016.3.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On Solaris\-like operating systems only a string comparison is done. .UNINDENT .UNINDENT .sp Changed in version 2016.11.4. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On AIX operating systems only a string comparison is done. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.zone_compare \(aqAmerica/Denver\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.tls .sp A salt module for SSL/TLS. Can create a Certificate Authority (CA) or use Self\-Signed certificates. .INDENT 0.0 .TP .B depends PyOpenSSL Python module (0.10 or later, 0.14 or later for X509 extension support) .TP .B configuration Add the following values in /etc/salt/minion for the CA module to function properly: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ca.cert_base_path: \(aq/etc/pki\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp CLI Example #1: Creating a CA, a server request and its signed certificate: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call tls.create_ca my_little \e days=5 \e CN=\(aqMy Little CA\(aq \e C=US \e ST=Utah \e L=Salt Lake City \e O=Saltstack \e emailAddress=pleasedontemail@example.com Created Private Key: \(dq/etc/pki/my_little/my_little_ca_cert.key\(dq Created CA \(dqmy_little_ca\(dq: \(dq/etc/pki/my_little_ca/my_little_ca_cert.crt\(dq # salt\-call tls.create_csr my_little CN=www.example.com Created Private Key: \(dq/etc/pki/my_little/certs/www.example.com.key Created CSR for \(dqwww.example.com\(dq: \(dq/etc/pki/my_little/certs/www.example.com.csr\(dq # salt\-call tls.create_ca_signed_cert my_little CN=www.example.com Created Certificate for \(dqwww.example.com\(dq: /etc/pki/my_little/certs/www.example.com.crt\(dq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example #2: Creating a client request and its signed certificate .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call tls.create_csr my_little CN=DBReplica_No.1 cert_type=client Created Private Key: \(dq/etc/pki/my_little/certs//DBReplica_No.1.key\(dq Created CSR for \(dqDBReplica_No.1\(dq: \(dq/etc/pki/my_little/certs/DBReplica_No.1.csr\(dq # salt\-call tls.create_ca_signed_cert my_little CN=DBReplica_No.1 Created Certificate for \(dqDBReplica_No.1\(dq: \(dq/etc/pki/my_little/certs/DBReplica_No.1.crt\(dq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example #3: Creating both a server and client req + cert for the same CN .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call tls.create_csr my_little CN=MasterDBReplica_No.2 \e cert_type=client Created Private Key: \(dq/etc/pki/my_little/certs/MasterDBReplica_No.2.key\(dq Created CSR for \(dqDBReplica_No.1\(dq: \(dq/etc/pki/my_little/certs/MasterDBReplica_No.2.csr\(dq # salt\-call tls.create_ca_signed_cert my_little CN=MasterDBReplica_No.2 Created Certificate for \(dqDBReplica_No.1\(dq: \(dq/etc/pki/my_little/certs/DBReplica_No.1.crt\(dq # salt\-call tls.create_csr my_little CN=MasterDBReplica_No.2 \e cert_type=server Certificate \(dqMasterDBReplica_No.2\(dq already exists (doh!) # salt\-call tls.create_csr my_little CN=MasterDBReplica_No.2 \e cert_type=server type_ext=True Created Private Key: \(dq/etc/pki/my_little/certs/DBReplica_No.1_client.key\(dq Created CSR for \(dqDBReplica_No.1\(dq: \(dq/etc/pki/my_little/certs/DBReplica_No.1_client.csr\(dq # salt\-call tls.create_ca_signed_cert my_little CN=MasterDBReplica_No.2 Certificate \(dqMasterDBReplica_No.2\(dq already exists (DOH!) # salt\-call tls.create_ca_signed_cert my_little CN=MasterDBReplica_No.2 \e cert_type=server type_ext=True Created Certificate for \(dqMasterDBReplica_No.2\(dq: \(dq/etc/pki/my_little/certs/MasterDBReplica_No.2_server.crt\(dq .ft P .fi .UNINDENT .UNINDENT .sp CLI Example #4: Create a server req + cert with non\-CN filename for the cert .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call tls.create_csr my_little CN=www.anothersometh.ing \e cert_type=server type_ext=True Created Private Key: \(dq/etc/pki/my_little/certs/www.anothersometh.ing_server.key\(dq Created CSR for \(dqDBReplica_No.1\(dq: \(dq/etc/pki/my_little/certs/www.anothersometh.ing_server.csr\(dq # salt\-call tls_create_ca_signed_cert my_little CN=www.anothersometh.ing \e cert_type=server cert_filename=\(dqsomething_completely_different\(dq Created Certificate for \(dqwww.anothersometh.ing\(dq: /etc/pki/my_little/certs/something_completely_different.crt .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.ca_exists(ca_name, cacert_path=None, ca_filename=None) Verify whether a Certificate Authority (CA) already exists .INDENT 7.0 .TP .B ca_name name of the CA .TP .B cacert_path absolute path to ca certificates root directory .TP .B ca_filename alternative filename for the CA .sp New in version 2015.5.3. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.ca_exists test_ca /etc/certs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.cert_base_path(cacert_path=None) Return the base path for certs from CLI or from options .INDENT 7.0 .TP .B cacert_path absolute path to ca certificates root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.cert_base_path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.cert_info(cert, digest=\(aqsha256\(aq) Return information for a particular certificate .INDENT 7.0 .TP .B cert path to the certifiate PEM file or string .sp Changed in version 2018.3.4. .TP .B digest what digest to use for fingerprinting .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.cert_info /dir/for/certs/cert.pem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.create_ca(ca_name, bits=2048, days=365, CN=\(aqlocalhost\(aq, C=\(aqUS\(aq, ST=\(aqUtah\(aq, L=\(aqSalt Lake City\(aq, O=\(aqSaltStack\(aq, OU=None, emailAddress=None, fixmode=False, cacert_path=None, ca_filename=None, digest=\(aqsha256\(aq, onlyif=None, unless=None, replace=False) Create a Certificate Authority (CA) .INDENT 7.0 .TP .B ca_name name of the CA .TP .B bits number of RSA key bits, default is 2048 .TP .B days number of days the CA will be valid, default is 365 .TP .B CN common name in the request, default is \(dqlocalhost\(dq .TP .B C country, default is \(dqUS\(dq .TP .B ST state, default is \(dqUtah\(dq .TP .B L locality, default is \(dqCenterville\(dq, the city where SaltStack originated .TP .B O organization, default is \(dqSaltStack\(dq .TP .B OU organizational unit, default is None .TP .B emailAddress email address for the CA owner, default is None .TP .B cacert_path absolute path to ca certificates root directory .TP .B ca_filename alternative filename for the CA .sp New in version 2015.5.3. .TP .B digest The message digest algorithm. Must be a string describing a digest algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically). For example, \(dqmd5\(dq or \(dqsha1\(dq. Default: \(aqsha256\(aq .TP .B replace Replace this certificate even if it exists .sp New in version 2015.5.1. .UNINDENT .sp Writes out a CA certificate based upon defined config values. If the file already exists, the function just returns assuming the CA certificate already exists. .sp If the following values were set: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ca.cert_base_path=\(aq/etc/pki\(aq ca_name=\(aqkoji\(aq .ft P .fi .UNINDENT .UNINDENT .sp the resulting CA, and corresponding key, would be written in the following location with appropriate permissions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/pki/koji/koji_ca_cert.crt /etc/pki/koji/koji_ca_cert.key .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.create_ca test_ca .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.create_ca_signed_cert(ca_name, CN, days=365, cacert_path=None, ca_filename=None, cert_path=None, cert_filename=None, digest=\(aqsha256\(aq, cert_type=None, type_ext=False, replace=False) Create a Certificate (CERT) signed by a named Certificate Authority (CA) .sp If the certificate file already exists, the function just returns assuming the CERT already exists. .sp The CN \fImust\fP match an existing CSR generated by create_csr. If it does not, this method does nothing. .INDENT 7.0 .TP .B ca_name name of the CA .TP .B CN common name matching the certificate signing request .TP .B days number of days certificate is valid, default is 365 (1 year) .TP .B cacert_path absolute path to ca certificates root directory .TP .B ca_filename alternative filename for the CA .sp New in version 2015.5.3. .TP .B cert_path full path to the certificates directory .TP .B cert_filename alternative filename for the certificate, useful when using special characters in the CN. If this option is set it will override the certificate filename output effects of \fBcert_type\fP\&. \fBtype_ext\fP will be completely overridden. .sp New in version 2015.5.3. .TP .B digest The message digest algorithm. Must be a string describing a digest algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically). For example, \(dqmd5\(dq or \(dqsha1\(dq. Default: \(aqsha256\(aq .TP .B replace Replace this certificate even if it exists .sp New in version 2015.5.1. .TP .B cert_type string. Either \(aqserver\(aq or \(aqclient\(aq (see create_csr() for details). .sp If create_csr(type_ext=True) this function \fBmust\fP be called with the same cert_type so it can find the CSR file. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 create_csr() defaults to cert_type=\(aqserver\(aq; therefore, if it was also called with type_ext, cert_type becomes a required argument for create_ca_signed_cert() .UNINDENT .UNINDENT .INDENT 7.0 .TP .B type_ext bool. If set True, use \fBcert_type\fP as an extension to the CN when formatting the filename. .sp e.g.: some_subject_CN_server.crt or some_subject_CN_client.crt .sp This facilitates the context where both types are required for the same subject .sp If \fBcert_filename\fP is \fInot None\fP, setting \fBtype_ext\fP has no effect .UNINDENT .sp If the following values were set: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ca.cert_base_path=\(aq/etc/pki\(aq ca_name=\(aqkoji\(aq CN=\(aqtest.egavas.org\(aq .ft P .fi .UNINDENT .UNINDENT .sp the resulting signed certificate would be written in the following location: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/pki/koji/certs/test.egavas.org.crt .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.create_ca_signed_cert test localhost .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.create_csr(ca_name, bits=2048, CN=\(aqlocalhost\(aq, C=\(aqUS\(aq, ST=\(aqUtah\(aq, L=\(aqSalt Lake City\(aq, O=\(aqSaltStack\(aq, OU=None, emailAddress=None, subjectAltName=None, cacert_path=None, ca_filename=None, csr_path=None, csr_filename=None, digest=\(aqsha256\(aq, type_ext=False, cert_type=\(aqserver\(aq, replace=False) Create a Certificate Signing Request (CSR) for a particular Certificate Authority (CA) .INDENT 7.0 .TP .B ca_name name of the CA .TP .B bits number of RSA key bits, default is 2048 .TP .B CN common name in the request, default is \(dqlocalhost\(dq .TP .B C country, default is \(dqUS\(dq .TP .B ST state, default is \(dqUtah\(dq .TP .B L locality, default is \(dqCenterville\(dq, the city where SaltStack originated .TP .B O organization, default is \(dqSaltStack\(dq NOTE: Must the same as CA certificate or an error will be raised .TP .B OU organizational unit, default is None .TP .B emailAddress email address for the request, default is None .TP .B subjectAltName valid subjectAltNames in full form, e.g. to add DNS entry you would call this function with this value: .INDENT 7.0 .TP .B examples: [\(aq\fI\%DNS:somednsname.com\fP\(aq, \(aq\fI\%DNS:1.2.3.4\fP\(aq, \(aqIP:1.2.3.4\(aq, \(aqIP:2001:4801:7821:77:be76:4eff:fe11:e51\(aq, \(aqemail:me@i.like.pie.com\(aq] .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 some libraries do not properly query IP: prefixes, instead looking for the given req. source with a DNS: prefix. To be thorough, you may want to include both DNS: and IP: entries if you are using subjectAltNames for destinations for your TLS connections. e.g.: requests to \fI\%https://1.2.3.4\fP will fail from python\(aqs requests library w/out the second entry in the above list .UNINDENT .UNINDENT .sp New in version 2015.8.0. .INDENT 7.0 .TP .B cert_type Specify the general certificate type. Can be either \fIserver\fP or \fIclient\fP\&. Indicates the set of common extensions added to the CSR. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C server: { \(aqbasicConstraints\(aq: \(aqCA:FALSE\(aq, \(aqextendedKeyUsage\(aq: \(aqserverAuth\(aq, \(aqkeyUsage\(aq: \(aqdigitalSignature, keyEncipherment\(aq } client: { \(aqbasicConstraints\(aq: \(aqCA:FALSE\(aq, \(aqextendedKeyUsage\(aq: \(aqclientAuth\(aq, \(aqkeyUsage\(aq: \(aqnonRepudiation, digitalSignature, keyEncipherment\(aq } .ft P .fi .UNINDENT .UNINDENT .TP .B type_ext boolean. Whether or not to extend the filename with CN_[cert_type] This can be useful if a server and client certificate are needed for the same CN. Defaults to False to avoid introducing an unexpected file naming pattern .sp The files normally named some_subject_CN.csr and some_subject_CN.key will then be saved .TP .B replace Replace this signing request even if it exists .sp New in version 2015.5.1. .UNINDENT .sp Writes out a Certificate Signing Request (CSR) If the file already exists, the function just returns assuming the CSR already exists. .sp If the following values were set: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ca.cert_base_path=\(aq/etc/pki\(aq ca_name=\(aqkoji\(aq CN=\(aqtest.egavas.org\(aq .ft P .fi .UNINDENT .UNINDENT .sp the resulting CSR, and corresponding key, would be written in the following location with appropriate permissions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/pki/koji/certs/test.egavas.org.csr /etc/pki/koji/certs/test.egavas.org.key .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.create_csr test .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.create_empty_crl(ca_name, cacert_path=None, ca_filename=None, crl_file=None, digest=\(aqsha256\(aq) Create an empty Certificate Revocation List. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B ca_name name of the CA .TP .B cacert_path absolute path to ca certificates root directory .TP .B ca_filename alternative filename for the CA .sp New in version 2015.5.3. .TP .B crl_file full path to the CRL file .TP .B digest The message digest algorithm. Must be a string describing a digest algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically). For example, \(dqmd5\(dq or \(dqsha1\(dq. Default: \(aqsha256\(aq .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.create_empty_crl ca_name=\(aqkoji\(aq ca_filename=\(aqca\(aq crl_file=\(aq/etc/openvpn/team1/crl.pem\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.create_pkcs12(ca_name, CN, passphrase=\(aq\(aq, cacert_path=None, replace=False) Create a PKCS#12 browser certificate for a particular Certificate (CN) .INDENT 7.0 .TP .B ca_name name of the CA .TP .B CN common name matching the certificate signing request .TP .B passphrase used to unlock the PKCS#12 certificate when loaded into the browser .TP .B cacert_path absolute path to ca certificates root directory .TP .B replace Replace this certificate even if it exists .sp New in version 2015.5.1. .UNINDENT .sp If the following values were set: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ca.cert_base_path=\(aq/etc/pki\(aq ca_name=\(aqkoji\(aq CN=\(aqtest.egavas.org\(aq .ft P .fi .UNINDENT .UNINDENT .sp the resulting signed certificate would be written in the following location: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/pki/koji/certs/test.egavas.org.p12 .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.create_pkcs12 test localhost .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.create_self_signed_cert(tls_dir=\(aqtls\(aq, bits=2048, days=365, CN=\(aqlocalhost\(aq, C=\(aqUS\(aq, ST=\(aqUtah\(aq, L=\(aqSalt Lake City\(aq, O=\(aqSaltStack\(aq, OU=None, emailAddress=None, cacert_path=None, cert_filename=None, digest=\(aqsha256\(aq, replace=False) Create a Self\-Signed Certificate (CERT) .INDENT 7.0 .TP .B tls_dir location appended to the ca.cert_base_path, default is \(aqtls\(aq .TP .B bits number of RSA key bits, default is 2048 .TP .B CN common name in the request, default is \(dqlocalhost\(dq .TP .B C country, default is \(dqUS\(dq .TP .B ST state, default is \(dqUtah\(dq .TP .B L locality, default is \(dqCenterville\(dq, the city where SaltStack originated .TP .B O organization, default is \(dqSaltStack\(dq NOTE: Must the same as CA certificate or an error will be raised .TP .B OU organizational unit, default is None .TP .B emailAddress email address for the request, default is None .TP .B cacert_path absolute path to ca certificates root directory .TP .B digest The message digest algorithm. Must be a string describing a digest algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically). For example, \(dqmd5\(dq or \(dqsha1\(dq. Default: \(aqsha256\(aq .TP .B replace Replace this certificate even if it exists .sp New in version 2015.5.1. .UNINDENT .sp Writes out a Self\-Signed Certificate (CERT). If the file already exists, the function just returns. .sp If the following values were set: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ca.cert_base_path=\(aq/etc/pki\(aq tls_dir=\(aqkoji\(aq CN=\(aqtest.egavas.org\(aq .ft P .fi .UNINDENT .UNINDENT .sp the resulting CERT, and corresponding key, would be written in the following location with appropriate permissions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/pki/koji/certs/test.egavas.org.crt /etc/pki/koji/certs/test.egavas.org.key .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.create_self_signed_cert .ft P .fi .UNINDENT .UNINDENT .sp Passing options from the command line: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\(aq tls.create_self_signed_cert CN=\(aqtest.mysite.org\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.get_ca(ca_name, as_text=False, cacert_path=None) Get the certificate path or content .INDENT 7.0 .TP .B ca_name name of the CA .TP .B as_text if true, return the certificate content instead of the path .TP .B cacert_path absolute path to ca certificates root directory .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.get_ca test_ca as_text=False cacert_path=/etc/certs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.get_ca_signed_cert(ca_name, CN=\(aqlocalhost\(aq, as_text=False, cacert_path=None, cert_filename=None) Get the certificate path or content .INDENT 7.0 .TP .B ca_name name of the CA .TP .B CN common name of the certificate .TP .B as_text if true, return the certificate content instead of the path .TP .B cacert_path absolute path to certificates root directory .TP .B cert_filename alternative filename for the certificate, useful when using special characters in the CN .sp New in version 2015.5.3. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.get_ca_signed_cert test_ca CN=localhost as_text=False cacert_path=/etc/certs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.get_ca_signed_key(ca_name, CN=\(aqlocalhost\(aq, as_text=False, cacert_path=None, key_filename=None) Get the certificate path or content .INDENT 7.0 .TP .B ca_name name of the CA .TP .B CN common name of the certificate .TP .B as_text if true, return the certificate content instead of the path .TP .B cacert_path absolute path to certificates root directory .TP .B key_filename alternative filename for the key, useful when using special characters .sp New in version 2015.5.3. .sp in the CN .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.get_ca_signed_key test_ca CN=localhost as_text=False cacert_path=/etc/certs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.get_expiration_date(cert, date_format=\(aq%Y\-%m\-%d\(aq) New in version 2019.2.0. .sp Get a certificate\(aqs expiration date .INDENT 7.0 .TP .B cert Full path to the certificate .TP .B date_format By default this will return the expiration date in YYYY\-MM\-DD format, use this to specify a different strftime format string. Note that the expiration time will be in UTC. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.get_expiration_date /path/to/foo.crt salt \(aq*\(aq tls.get_expiration_date /path/to/foo.crt date_format=\(aq%d/%m/%Y\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.get_extensions(cert_type) Fetch X509 and CSR extension definitions from tls:extensions: (common|server|client) or set them to standard defaults. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B cert_type: The type of certificate such as \fBserver\fP or \fBclient\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.get_extensions client .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.maybe_fix_ssl_version(ca_name, cacert_path=None, ca_filename=None) Check that the X509 version is correct (was incorrectly set in previous salt versions). This will fix the version if needed. .INDENT 7.0 .TP .B ca_name ca authority name .TP .B cacert_path absolute path to ca certificates root directory .TP .B ca_filename alternative filename for the CA .sp New in version 2015.5.3. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.maybe_fix_ssl_version test_ca /etc/certs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.revoke_cert(ca_name, CN, cacert_path=None, ca_filename=None, cert_path=None, cert_filename=None, crl_file=None, digest=\(aqsha256\(aq) Revoke a certificate. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B ca_name Name of the CA. .TP .B CN Common name matching the certificate signing request. .TP .B cacert_path Absolute path to ca certificates root directory. .TP .B ca_filename Alternative filename for the CA. .TP .B cert_path Path to the cert file. .TP .B cert_filename Alternative filename for the certificate, useful when using special characters in the CN. .TP .B crl_file Full path to the CRL file. .TP .B digest The message digest algorithm. Must be a string describing a digest algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically). For example, \(dqmd5\(dq or \(dqsha1\(dq. Default: \(aqsha256\(aq .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.revoke_cert ca_name=\(aqkoji\(aq ca_filename=\(aqca\(aq crl_file=\(aq/etc/openvpn/team1/crl.pem\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.set_ca_path(cacert_path) If wanted, store the aforementioned cacert_path in context to be used as the basepath for further operations .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.set_ca_path /etc/certs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tls.validate(cert, ca_name, crl_file) New in version 3000. .sp Validate a certificate against a given CA/CRL. .INDENT 7.0 .TP .B cert path to the certifiate PEM file or string .TP .B ca_name name of the CA .TP .B crl_file full path to the CRL file .UNINDENT .UNINDENT .SS salt.modules.tomcat .sp Support for Tomcat .sp This module uses the manager webapp to manage Apache tomcat webapps. If the manager webapp is not configured some of the functions won\(aqt work. .INDENT 0.0 .TP .B configuration .INDENT 7.0 .IP \(bu 2 Java bin path should be in default path .IP \(bu 2 If ipv6 is enabled make sure you permit manager access to ipv6 interface \(dq0:0:0:0:0:0:0:1\(dq .IP \(bu 2 If you are using tomcat.tar.gz it has to be installed or symlinked under \fB/opt\fP, preferably using name tomcat .IP \(bu 2 \(dqtomcat.signal start/stop\(dq works but it does not use the startup scripts .UNINDENT .UNINDENT .sp The following grains/pillar should be set: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tomcat\-manager: user: <username> passwd: <password> .ft P .fi .UNINDENT .UNINDENT .sp or the old format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tomcat\-manager.user: <username> tomcat\-manager.passwd: <password> .ft P .fi .UNINDENT .UNINDENT .sp Also configure a user in the conf/tomcat\-users.xml file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C <?xml version=\(aq1.0\(aq encoding=\(aqutf\-8\(aq?> <tomcat\-users> <role rolename=\(dqmanager\-script\(dq/> <user username=\(dqtomcat\(dq password=\(dqtomcat\(dq roles=\(dqmanager\-script\(dq/> </tomcat\-users> .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 More information about tomcat manager: \fI\%http://tomcat.apache.org/tomcat\-7.0\-doc/manager\-howto.html\fP .IP \(bu 2 if you use only this module for deployments you\(aqve might want to strict access to the manager only from localhost for more info: \fI\%http://tomcat.apache.org/tomcat\-7.0\-doc/manager\-howto.html#Configuring_Manager_Application_Access\fP .IP \(bu 2 Tested on: .INDENT 2.0 .TP .B JVM Vendor: Sun Microsystems Inc. .TP .B JVM Version: 1.6.0_43\-b01 .TP .B OS Architecture: amd64 .TP .B OS Name: Linux .TP .B OS Version: 2.6.32\-358.el6.x86_64 .TP .B Tomcat Version: Apache Tomcat/7.0.37 .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.deploy_war(war, context, force=\(aqno\(aq, url=\(aqhttp://localhost:8080/manager\(aq, saltenv=\(aqbase\(aq, timeout=180, temp_war_location=None, version=True) Deploy a WAR file .INDENT 7.0 .TP .B war absolute path to WAR file (should be accessible by the user running tomcat) or a path supported by the salt.modules.cp.get_file function .TP .B context the context path to deploy .TP .B force False set True to deploy the webapp even one is deployed in the context .TP .B url \fI\%http://localhost:8080/manager\fP the URL of the server manager webapp .TP .B saltenv base the environment for WAR file in used by salt.modules.cp.get_url function .TP .B timeout 180 timeout for HTTP request .TP .B temp_war_location None use another location to temporarily copy to war file by default the system\(aqs temp directory is used .TP .B version \(aq\(aq Specify the war version. If this argument is provided, it overrides the version encoded in the war file name, if one is present. .sp Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.deploy_war salt://salt\-2015.8.6.war version=2015.08.r6 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.6. .UNINDENT .sp CLI Examples: .sp cp module .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.deploy_war salt://application.war /api salt \(aq*\(aq tomcat.deploy_war salt://application.war /api no salt \(aq*\(aq tomcat.deploy_war salt://application.war /api yes http://localhost:8080/manager .ft P .fi .UNINDENT .UNINDENT .sp minion local file system .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.deploy_war /tmp/application.war /api salt \(aq*\(aq tomcat.deploy_war /tmp/application.war /api no salt \(aq*\(aq tomcat.deploy_war /tmp/application.war /api yes http://localhost:8080/manager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.extract_war_version(war) Extract the version from the war file name. There does not seem to be a standard for encoding the version into the \fI\%war file name\fP .sp Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /path/salt\-2015.8.6.war \-> 2015.8.6 /path/V6R2013xD5.war \-> None .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.fullversion() Return all server information from catalina.sh version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.fullversion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.leaks(url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) Find memory leaks in tomcat .INDENT 7.0 .TP .B url \fI\%http://localhost:8080/manager\fP the URL of the server manager webapp .TP .B timeout 180 timeout for HTTP request .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.leaks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.ls(url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) list all the deployed webapps .INDENT 7.0 .TP .B url \fI\%http://localhost:8080/manager\fP the URL of the server manager webapp .TP .B timeout 180 timeout for HTTP request .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.ls salt \(aq*\(aq tomcat.ls http://localhost:8080/manager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.passwd(passwd, user=\(aq\(aq, alg=\(aqsha1\(aq, realm=None) This function replaces the $CATALINA_HOME/bin/digest.sh script convert a clear\-text password to the $CATALINA_BASE/conf/tomcat\-users.xml format .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.passwd secret salt \(aq*\(aq tomcat.passwd secret tomcat sha1 salt \(aq*\(aq tomcat.passwd secret tomcat sha1 \(aqProtected Realm\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.reload_(app, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) Reload the webapp .INDENT 7.0 .TP .B app the webapp context path .TP .B url \fI\%http://localhost:8080/manager\fP the URL of the server manager webapp .TP .B timeout 180 timeout for HTTP request .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.reload /jenkins salt \(aq*\(aq tomcat.reload /jenkins http://localhost:8080/manager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.serverinfo(url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) return details about the server .INDENT 7.0 .TP .B url \fI\%http://localhost:8080/manager\fP the URL of the server manager webapp .TP .B timeout 180 timeout for HTTP request .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.serverinfo salt \(aq*\(aq tomcat.serverinfo http://localhost:8080/manager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.sessions(app, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) return the status of the webapp sessions .INDENT 7.0 .TP .B app the webapp context path .TP .B url \fI\%http://localhost:8080/manager\fP the URL of the server manager webapp .TP .B timeout 180 timeout for HTTP request .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.sessions /jenkins salt \(aq*\(aq tomcat.sessions /jenkins http://localhost:8080/manager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.signal(signal=None) Signals catalina to start, stop, securestart, forcestop. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.signal start .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.start(app, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) Start the webapp .INDENT 7.0 .TP .B app the webapp context path .TP .B url \fI\%http://localhost:8080/manager\fP the URL of the server manager webapp .TP .B timeout timeout for HTTP request .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.start /jenkins salt \(aq*\(aq tomcat.start /jenkins http://localhost:8080/manager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.status(url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) Used to test if the tomcat manager is up .INDENT 7.0 .TP .B url \fI\%http://localhost:8080/manager\fP the URL of the server manager webapp .TP .B timeout 180 timeout for HTTP request .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.status salt \(aq*\(aq tomcat.status http://localhost:8080/manager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.status_webapp(app, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) return the status of the webapp (stopped | running | missing) .INDENT 7.0 .TP .B app the webapp context path .TP .B url \fI\%http://localhost:8080/manager\fP the URL of the server manager webapp .TP .B timeout 180 timeout for HTTP request .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.status_webapp /jenkins salt \(aq*\(aq tomcat.status_webapp /jenkins http://localhost:8080/manager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.stop(app, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) Stop the webapp .INDENT 7.0 .TP .B app the webapp context path .TP .B url \fI\%http://localhost:8080/manager\fP the URL of the server manager webapp .TP .B timeout 180 timeout for HTTP request .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.stop /jenkins salt \(aq*\(aq tomcat.stop /jenkins http://localhost:8080/manager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.undeploy(app, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) Undeploy a webapp .INDENT 7.0 .TP .B app the webapp context path .TP .B url \fI\%http://localhost:8080/manager\fP the URL of the server manager webapp .TP .B timeout 180 timeout for HTTP request .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.undeploy /jenkins salt \(aq*\(aq tomcat.undeploy /jenkins http://localhost:8080/manager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.version() Return server version from catalina.sh version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tomcat.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.trafficserver .sp Apache Traffic Server execution module. .sp New in version 2015.8.0. .sp \fBtraffic_ctl\fP is used to execute individual Traffic Server commands and to script multiple commands in a shell. .INDENT 0.0 .TP .B salt.modules.trafficserver.alarms() List all alarm events that have not been acknowledged (cleared). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.alarms .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.bounce_cluster() Bounce all Traffic Server nodes in the cluster. Bouncing Traffic Server shuts down and immediately restarts Traffic Server, node\-by\-node. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.bounce_cluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.bounce_local(drain=False) Bounce Traffic Server on the local node. Bouncing Traffic Server shuts down and immediately restarts the Traffic Server node. .INDENT 7.0 .TP .B drain This option modifies the restart behavior such that traffic_server is not shut down until the number of active client connections drops to the number given by the proxy.config.restart.active_client_threshold configuration variable. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.bounce_local salt \(aq*\(aq trafficserver.bounce_local drain=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.clear_alarms(alarm) Clear (acknowledge) an alarm event. The arguments are “all” for all current alarms, a specific alarm number (e.g. ‘‘1’‘), or an alarm string identifier (e.g. ‘’MGMT_ALARM_PROXY_CONFIG_ERROR’‘). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.clear_alarms [all | #event | name] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.clear_cluster() Clears accumulated statistics on all nodes in the cluster. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.clear_cluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.clear_node() Clears accumulated statistics on the local node. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.clear_node .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.match_config(regex) Display the current values of all configuration variables whose names match the given regular expression. .sp New in version 2016.11.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.match_config regex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.match_metric(regex) Display the current values of all metrics whose names match the given regular expression. .sp New in version 2016.11.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.match_metric regex .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.offline(path) Mark a cache storage device as offline. The storage is identified by a path which must match exactly a path specified in storage.config. This removes the storage from the cache and redirects requests that would have used this storage to other storage. This has exactly the same effect as a disk failure for that storage. This does not persist across restarts of the traffic_server process. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.offline /path/to/cache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.read_config(*args) Read Traffic Server configuration variable definitions. .sp New in version 2016.11.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.read_config proxy.config.http.keep_alive_post_out .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.read_metric(*args) Read Traffic Server one or more metrics. .sp New in version 2016.11.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.read_metric proxy.process.http.tcp_hit_count_stat .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.refresh() Initiate a Traffic Server configuration file reread. Use this command to update the running configuration after any configuration file modification. .sp The timestamp of the last reconfiguration event (in seconds since epoch) is published in the proxy.node.config.reconfigure_time metric. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.refresh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.restart_cluster() Restart the traffic_manager process and the traffic_server process on all the nodes in a cluster. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.restart_cluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.restart_local(drain=False) Restart the traffic_manager and traffic_server processes on the local node. .INDENT 7.0 .TP .B drain This option modifies the restart behavior such that \fBtraffic_server\fP is not shut down until the number of active client connections drops to the number given by the \fBproxy.config.restart.active_client_threshold\fP configuration variable. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.restart_local salt \(aq*\(aq trafficserver.restart_local drain=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.set_config(variable, value) Set the value of a Traffic Server configuration variable. .INDENT 7.0 .TP .B variable Name of a Traffic Server configuration variable. .TP .B value The new value to set. .UNINDENT .sp New in version 2016.11.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.set_config proxy.config.http.keep_alive_post_out 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.shutdown() Shut down Traffic Server on the local node. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.shutdown .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.startup() Start Traffic Server on the local node. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.start .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.status() Show the current proxy server status, indicating if we’re running or not. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.zero_cluster() Reset performance statistics to zero across the cluster. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.zero_cluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.trafficserver.zero_node() Reset performance statistics to zero on the local node. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq trafficserver.zero_cluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.transactional_update module .SS Transactional update .sp New in version 3004. .sp A transactional system, like \fI\%MicroOS\fP, can present some challenges when the user decided to manage it via Salt. .sp MicroOS provides a read\-only rootfs and a tool, \fBtransactional\-update\fP, that takes care of the management of the system (updating, upgrading, installation or reboot, among others) in an atomic way. .sp Atomicity is the main feature of MicroOS, and to guarantee this property, this model leverages \fBsnapper\fP, \fBzypper\fP, \fBbtrfs\fP and \fBoverlayfs\fP to create snapshots that will be updated independently of the currently running system, and that are activated after the reboot. This implies, for example, that some changes made on the system are not visible until the next reboot, as those changes are living in a different snapshot of the file system. .sp This model presents a lot of problems with the traditional Salt model, where the inspections (like \(aqis this package installed?\(aq) are executed in order to determine if a subsequent action is required (like \(aqinstall this package\(aq). .sp Lets consider this use case, to see how it works on a traditional system, and in a transactional system: .INDENT 0.0 .IP 1. 3 Check if \fBapache\fP is installed .IP 2. 3 If it is not installed, install it .IP 3. 3 Check that a \fBvhost\fP is configured for \fBapache\fP .IP 4. 3 Make sure that \fBapache2.service\fP is enabled .IP 5. 3 If the configuration changes, restart \fBapache2.service\fP .UNINDENT .sp In the traditional system everything will work as expected. The system can see if the package is present or not, install it if it isn\(aqt, and a re\-check will shows that is already present. The same will happen to the configuration file in \fB/etc/apache2\fP, that will be available as soon the package gets installed. Salt can inspect the current form of this file, and add the missing bits if required. Salt can annotate that a change is present, and restart the service. .sp In a transactional system we will have multiple issues. The first one is that Salt can only see the content of the snapshot where the system booted from. Later snapshots may contain different content, including the presence of \fBapache\fP\&. If Salt decides to install \fBapache\fP calling \fBzypper\fP, it will fail, as this will try to write into the read\-only rootfs. Even if Salt would call \fBtransactional\-update pkg install\fP, the package would only be present in the new transaction (snapshot), and will not be found in the currently running system when later Salt tries to validate the presence of the package in the current one. .sp Any change in \fB/etc\fP alone will have also problems, as the changes will be alive in a different overlay, only visible after the reboot. And, finally, the service can only be enabled and restarted if the service file is already present in the current \fB/etc\fP\&. .SS General strategy .sp \fBtransactional\-update\fP is the reference tool used for the administration of transactional systems. Newer versions of this tool support the execution of random commands in the new transaction, the continuation of a transaction, the automatic detection of changes in new transactions and the merge of \fB/etc\fP overlays. .SS Continue a transaction .sp One prerequisite already present is the support for branching from a different snapshot than the current one in snapper. .sp With this feature we can represent in \fBtransactional\-update\fP the action of creating a transaction snapshot based on one that is planned to be the active one after the reboot. This feature removes a lot of user complains (like, for example, losing changes that are stored in a transaction not yet activated), but also provide a more simple model to work with. .sp So, for example, if the user have this scenario: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C +\-\-\-\-\-+ *=====* +\-\-V\-\-+ \-\-| T.1 |\-\-| T.2 |\-\-| T.3 | +\-\-\-\-\-+ *=====* +\-\-A\-\-+ .ft P .fi .UNINDENT .UNINDENT .sp where T.2 is the current active one, and T.3 is an snapshot generated from T.2 with a new package (\fBapache2\fP), and is marked to be the active after the reboot. .sp Previously, if the user (that is still on T.2) created a new transaction, maybe for adding a new package (\fBtomcat\fP, for example), the new T.4 will be based on the content of T.2 again, and not T.3, so the new T.4 will have lost the changes of T.3 (i.e. \fIapache2\fP will not be present in T.4). .sp With the \fB\-\-continue\fP parameter, \fBtransactional\-update\fP will create T.4 based on T.3, and nothing will be lost. .SS Command execution inside a new transaction .sp With \fBtransactional\-update run\fP we will create a new transaction based on the current one (T.2), where we can send interactive commands that can modify the new transaction, and as commented, with \fBtransactional\-update \-\-continue run\fP, we will create a new transaction based on the last created (T.3) .sp The \fBrun\fP command can execute any application inside the new transaction namespace. This module uses this feature to execute the different Salt execution modules, via \fBcall()\fP\&. Or even the full \fBsalt\-thin\fP or \fBsalt\-call\fP via \fBsls()\fP, \fBapply()\fP, \fBsingle()\fP or \fBhighstate\fP\&. .SS \fBtransactional\-update\fP will drop empty snapshots .sp The option \fB\-\-drop\-if\-no\-change\fP is used to detect whether there is any change in the file system on the read\-only subvolume of the new transaction will be added. If a change is present, the new transaction will remain, if not it will be discarded. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C transactional\-update \-\-continue \-\-drop\-if\-no\-change run zypper in apache2 .ft P .fi .UNINDENT .UNINDENT .sp If we are in the scenario described before, \fBapache2\fP is already present in T.3. In this case a new transaction, T.4, will be created based on T.3, \fBzypper\fP will detect that the package is already present and no change will be produced on T.4. At the end of the execution, \fBtransactional\-update\fP will validate that T.3 and T.4 are equivalent and T.4 will be discarded. .sp If the command is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C transactional\-update \-\-continue \-\-drop\-if\-no\-change run zypper in tomcat .ft P .fi .UNINDENT .UNINDENT .sp the new T.4 will be indeed different from T.3, and will remain after the transaction is closed. .sp With this feature, every time that we call any function of this execution module, we will minimize the amount of transaction, while maintaining the idempotence so some operations. .SS Report for pending transaction .sp A change in the system will create a new transaction, that needs to be activated via a reboot. With \fBpending_transaction()\fP we can check if a reboot is needed. We can execute the reboot using the \fBreboot()\fP function, that will follow the plan established by the functions of the \fBrebootmgr\fP execution module. .SS \fB/etc\fP overlay merge when no new transaction is created .sp In a transactional model, \fB/etc\fP is an overlay file system. Changes done during the update are only present in the new transaction, and so will only be available after the reboot. Or worse, if the transaction gets dropped, because there is no change in the \fBrootfs\fP, the changes in \fB/etc\fP will be dropped too!. This is designed like that in order to make the configuration files for the new package available only when new package is also available to the user. So, after the reboot. .sp This makes sense for the case when, for example, \fBapache2\fP is not present in the current transaction, but we installed it. The new snapshot contains the \fBapache2\fP service, and the configuration files in \fB/etc\fP will be accessible only after the reboot. .sp But this model presents an issue. If we use \fBtransactional\-update \-\-continue \-\-drop\-if\-no\-change run <command>\fP, where \fB<command>\fP does not make any change in the read\-only subvolume, but only in \fB/etc\fP (which is also read\-write in the running system), the new overlay with the changes in \fB/etc\fP will be dropped together with the transaction. .sp To fix this, \fBtransactional\-update\fP will detect that when no change has been made on the read\-only subvolume, but done in the overlay, the transaction will be dropped and the changes in the overlay will be merged back into \fB/etc\fP overlay of the current transaction. .SS Using the execution module .sp With this module we can create states that leverage Salt into this kind of systems: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Install apache (low\-level API) salt\-call transactional_update.pkg_install apache2 # We can call any execution module salt\-call transactional_update.call pkg.install apache2 # Or via a state salt\-call transactional_update.single pkg.installed name=apache2 # We can also execute a zypper directly salt\-call transactional_update run \(dqzypper in apache2\(dq snapshot=\(dqcontinue\(dq # We can reuse SLS states salt\-call transactional_update.apply install_and_configure_apache # Or apply the full highstate salt\-call transactional_update.highstate # Is there any change done in the system? salt\-call transactional_update pending_transaction # If so, reboot via rebootmgr salt\-call transactional_update reboot # We can enable the service salt\-call service.enable apache2 # If apache2 is available, this will work too salt\-call service.restart apache2 .ft P .fi .UNINDENT .UNINDENT .SS Fixing some expectations .sp This module alone is an improvement over the current state, but is easy to see some limitations and problems: .SS Is not a fully transparent approach .sp The user needs to know if the system is transactional or not, as not everything can be expressed inside a transaction (for example, restarting a service inside transaction is not allowed). .SS Two step for service restart .sp In the \fBapache2\fP example from the beginning we can observe the biggest drawback. If the package \fBapache2\fP is missing, the new module will create a new transaction, will execute \fBpkg.install\fP inside the transaction (creating the salt\-thin, moving it inside and delegating the execution to \fBtransactional\-update\fP CLI as part of the full state). Inside the transaction we can do too the required changes in \fB/etc\fP for adding the new \fBvhost\fP, and we can enable the service via systemctl inside the same transaction. .sp At this point we will not merge the \fB/etc\fP overlay into the current one, and we expect from the user call the \fBreboot\fP function inside this module, in order to activate the new transaction and start the \fBapache2\fP service. .sp In the case that the package is already there, but the configuration for the \fBvhost\fP is required, the new transaction will be dropped and the \fB/etc\fP overlay will be visible in the live system. Then from outside the transaction, via a different call to Salt, we can command a restart of the \fBapache2\fP service. .sp We can see that in both cases we break the user expectation, where a change on the configuration will trigger automatically the restart of the associated service. In a transactional scenario we need two different steps: or a reboot, or a restart from outside of the transaction. .INDENT 0.0 .TP .B maintainer Alberto Planas <\fI\%aplanas@suse.com\fP> .TP .B maturity new .TP .B depends None .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.apply_(mods=None, **kwargs) Apply an state inside a transaction. .sp This function will call \fItransactional_update.highstate\fP or \fItransactional_update.sls\fP based on the arguments passed to this function. It exists as a more intuitive way of applying states. .sp For a formal description of the possible parameters accepted in this function, check \fIstate.apply_\fP documentation. .INDENT 7.0 .TP .B activate_transaction If at the end of the transaction there is a pending activation (i.e there is a new snapshot in the system), a new reboot will be scheduled (default False) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update.apply salt microos transactional_update.apply stuff salt microos transactional_update.apply stuff pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq salt microos transactional_update.apply stuff activate_transaction=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.bootloader(self_update=False, snapshot=None) Reinstall the bootloader .sp Same as grub.cfg, but will also rewrite the bootloader itself. .INDENT 7.0 .TP .B self_update Check for newer transactional\-update versions. .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqcontinue\(dq to indicate the last snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update bootloader snapshot=\(dqcontinue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.call(function, *args, **kwargs) Executes a Salt function inside a transaction. .sp The chroot does not need to have Salt installed, but Python is required. .INDENT 7.0 .TP .B function Salt execution module function .TP .B activate_transaction If at the end of the transaction there is a pending activation (i.e there is a new snapshot in the system), a new reboot will be scheduled (default False) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update.call test.ping salt microos transactional_update.call ssh.set_auth_key user key=mykey salt microos transactional_update.call pkg.install emacs activate_transaction=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.cleanup(self_update=False) Run both cleanup\-snapshots and cleanup\-overlays. .sp Identical to calling both cleanup\-snapshots and cleanup\-overlays. .INDENT 7.0 .TP .B self_update Check for newer transactional\-update versions. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update cleanup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.cleanup_overlays(self_update=False) Remove unused overlay layers. .sp Removes all unreferenced (and thus unused) /etc overlay directories in /var/lib/overlay. .INDENT 7.0 .TP .B self_update Check for newer transactional\-update versions. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update cleanup_overlays .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.cleanup_snapshots(self_update=False) Mark unused snapshots for snapper removal. .sp If the current root filesystem is identical to the active root filesystem (means after a reboot, before transactional\-update creates a new snapshot with updates), all old snapshots without a cleanup algorithm get a cleanup algorithm set. This is to make sure, that old snapshots will be deleted by snapper. See the section about cleanup algorithms in snapper(8). .INDENT 7.0 .TP .B self_update Check for newer transactional\-update versions. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update cleanup_snapshots .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.dup(self_update=False, snapshot=None) Call \(aqzypper dup\(aq .sp If new updates are available, a new snapshot is created and zypper dup \-\-no\-allow\-vendor\-change is used to update the snapshot. Afterwards, the snapshot is activated and will be used as the new root filesystem during next boot. .INDENT 7.0 .TP .B self_update Check for newer transactional\-update versions. .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqcontinue\(dq to indicate the last snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update dup snapshot=\(dqcontinue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.grub_cfg(self_update=False, snapshot=None) Regenerate grub.cfg .sp grub2\-mkconfig(8) is called to create a new /boot/grub2/grub.cfg configuration file for the bootloader. .INDENT 7.0 .TP .B self_update Check for newer transactional\-update versions. .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqcontinue\(dq to indicate the last snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update grub_cfg snapshot=\(dqcontinue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.highstate(activate_transaction=False, queue=False, **kwargs) Retrieve the state data from the salt master for this minion and execute it inside a transaction. .sp For a formal description of the possible parameters accepted in this function, check \fIstate.highstate\fP documentation. .INDENT 7.0 .TP .B activate_transaction If at the end of the transaction there is a pending activation (i.e there is a new snapshot in the system), a new reboot will be scheduled (Default: False). .TP .B queue Instead of failing immediately when another state run is in progress, queue the new state run to begin running once the other has finished. .sp This option starts a new thread for each queued state run, so use this option sparingly (Default: False). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update.highstate salt microos transactional_update.highstate pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq salt microos transactional_update.highstate activate_transaction=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.in_transaction() Check if Salt is executing while in a transaction .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update in_transaction .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.initrd(self_update=False, snapshot=None) Regenerate initrd .sp A new initrd is created in a snapshot. .INDENT 7.0 .TP .B self_update Check for newer transactional\-update versions. .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqcontinue\(dq to indicate the last snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update initrd snapshot=\(dqcontinue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.kdump(self_update=False, snapshot=None) Regenerate kdump initrd .sp A new initrd for kdump is created in a snapshot. .INDENT 7.0 .TP .B self_update Check for newer transactional\-update versions. .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqcontinue\(dq to indicate the last snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update kdump snapshot=\(dqcontinue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.migration(self_update=False, snapshot=None) Updates systems registered via SCC / SMT .sp On systems which are registered against the SUSE Customer Center (SCC) or SMT, a migration to a new version of the installed products can be made with this option. .INDENT 7.0 .TP .B self_update Check for newer transactional\-update versions. .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqcontinue\(dq to indicate the last snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update migration snapshot=\(dqcontinue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.patch(self_update=False, snapshot=None) Call \(aqzypper patch\(aq .sp If new updates are available, a new snapshot is created and zypper patch is used to update the snapshot. Afterwards, the snapshot is activated and will be used as the new root filesystem during next boot. .INDENT 7.0 .TP .B self_update Check for newer transactional\-update versions. .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqcontinue\(dq to indicate the last snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update patch snapshot=\(dqcontinue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.pending_transaction() Check if there is a pending transaction .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update pending_transaction .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.pkg_install(pkg=None, pkgs=None, args=None, self_update=False, snapshot=None) Install individual packages .sp Installs additional software. See the install description in the \(dqPackage Management Commands\(dq section of zypper\(aqs man page for all available arguments. .INDENT 7.0 .TP .B pkg Package name to install .TP .B pkgs List of packages names to install .TP .B args String or list of extra parameters for zypper .TP .B self_update Check for newer transactional\-update versions. .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqcontinue\(dq to indicate the last snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update pkg_install pkg=emacs snapshot=\(dqcontinue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.pkg_remove(pkg=None, pkgs=None, args=None, self_update=False, snapshot=None) Remove individual packages .sp Removes installed software. See the remove description in the \(dqPackage Management Commands\(dq section of zypper\(aqs man page for all available arguments. .INDENT 7.0 .TP .B pkg Package name to install .TP .B pkgs List of packages names to install .TP .B args String or list of extra parameters for zypper .TP .B self_update Check for newer transactional\-update versions. .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqcontinue\(dq to indicate the last snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update pkg_remove pkg=vim snapshot=\(dqcontinue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.pkg_update(pkg=None, pkgs=None, args=None, self_update=False, snapshot=None) Updates individual packages .sp Update selected software. See the update description in the \(dqUpdate Management Commands\(dq section of zypper\(aqs man page for all available arguments. .INDENT 7.0 .TP .B pkg Package name to install .TP .B pkgs List of packages names to install .TP .B args String or list of extra parameters for zypper .TP .B self_update Check for newer transactional\-update versions. .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqcontinue\(dq to indicate the last snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update pkg_update pkg=emacs snapshot=\(dqcontinue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.reboot(self_update=False) Reboot after update .sp Trigger a reboot after updating the system. .sp Several different reboot methods are supported, configurable via the REBOOT_METHOD configuration option in transactional\-update.conf(5). By default rebootmgrd(8) will be used to reboot the system according to the configured policies if the service is running, otherwise systemctl reboot will be called. .INDENT 7.0 .TP .B self_update Check for newer transactional\-update versions. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update reboot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.rollback(snapshot=None) Set the current, given or last working snapshot as default snapshot .sp Sets the default root file system. On a read\-only system the root file system is set directly using btrfs. On read\-write systems snapper(8) rollback is called. .sp If no snapshot number is given, the current root file system is set as the new default root file system. Otherwise number can either be a snapshot number (as displayed by snapper list) or the word last. last will try to reset to the latest working snapshot. .INDENT 7.0 .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqlast\(dq to indicate the last working snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update rollback .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.run(command, self_update=False, snapshot=None) Run a command in a new snapshot .sp Execute the command inside a new snapshot. By default this snapshot will remain, but if \-\-drop\-if\-no\-change is set, the new snapshot will be dropped if there is no change in the file system. .INDENT 7.0 .TP .B command Command with parameters that will be executed (as string or array) .TP .B self_update Check for newer transactional\-update versions. .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqcontinue\(dq to indicate the last snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update run \(dqmkdir /tmp/dir\(dq snapshot=\(dqcontinue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.single(fun, name, activate_transaction=False, queue=False, **kwargs) Execute a single state function with the named kwargs, returns False if insufficient data is sent to the command .sp By default, the values of the kwargs will be parsed as YAML. So, you can specify lists values, or lists of single entry key\-value maps, as you would in a YAML salt file. Alternatively, JSON format of keyword values is also supported. .INDENT 7.0 .TP .B activate_transaction If at the end of the transaction there is a pending activation (i.e there is a new snapshot in the system), a new reboot will be scheduled (Default: False). .TP .B queue Instead of failing immediately when another state run is in progress, queue the new state run to begin running once the other has finished. .sp This option starts a new thread for each queued state run, so use this option sparingly (Default: False). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update.single pkg.installed name=emacs salt microos transactional_update.single pkg.installed name=emacs activate_transaction=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.sls(mods, activate_transaction=False, queue=False, **kwargs) Execute the states in one or more SLS files inside a transaction. .INDENT 7.0 .TP .B saltenv Specify a salt fileserver environment to be used when applying states .TP .B mods List of states to execute .TP .B test Run states in test\-only (dry\-run) mode .TP .B exclude Exclude specific states from execution. Accepts a list of sls names, a comma\-separated string of sls names, or a list of dictionaries containing \fBsls\fP or \fBid\fP keys. Glob\-patterns may be used to match multiple states. .TP .B activate_transaction If at the end of the transaction there is a pending activation (i.e there is a new snapshot in the system), a new reboot will be scheduled (Default: False). .TP .B queue Instead of failing immediately when another state run is in progress, queue the new state run to begin running once the other has finished. .sp This option starts a new thread for each queued state run, so use this option sparingly (Default: False). .UNINDENT .sp For a formal description of the possible parameters accepted in this function, check \fIstate.sls\fP documentation. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update.sls stuff pillar=\(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq salt microos transactional_update.sls stuff activate_transaction=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.transactional() Check if the system is a transactional system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update transactional .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.transactional_update.up(self_update=False, snapshot=None) Call \(aqzypper up\(aq .sp If new updates are available, a new snapshot is created and zypper up is used to update the snapshot. Afterwards, the snapshot is activated and will be used as the new root filesystem during next boot. .INDENT 7.0 .TP .B self_update Check for newer transactional\-update versions. .TP .B snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use \(dqcontinue\(dq to indicate the last snapshot done. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt microos transactional_update up snapshot=\(dqcontinue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.travisci .sp Commands for working with travisci. .INDENT 0.0 .TP .B depends pyOpenSSL >= 16.0.0 .UNINDENT .INDENT 0.0 .TP .B salt.modules.travisci.verify_webhook(signature, body) Verify the webhook signature from travisci .INDENT 7.0 .TP .B signature The signature header from the webhook header .TP .B body The full payload body from the webhook post .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The body needs to be the urlencoded version of the body. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq travisci.verify_webhook \(aqM6NucCX5722bxisQs7e...\(aq \(aqpayload=%7B%22id%22%3A183791261%2C%22repository...\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.tuned .sp Interface to Red Hat tuned\-adm module .INDENT 0.0 .TP .B maintainer Syed Ali <\fI\%alicsyed@gmail.com\fP> .TP .B maturity new .TP .B depends tuned\-adm .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.modules.tuned.active() Return current active profile in stdout key if retcode is 0, otherwise raw result .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tuned.active .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tuned.list_() List the profiles available .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tuned.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tuned.off() Turn off all profiles .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tuned.off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.tuned.profile(profile_name) Activate specified profile .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tuned.profile virtual\-guest .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.twilio_notify .sp Module for notifications via Twilio .sp New in version 2014.7.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 twilio python module .UNINDENT .TP .B configuration Configure this module by specifying the name of a configuration profile in the minion config, minion pillar, or master config (with \fI\%pillar_opts\fP set to True). .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my\-twilio\-account: twilio.account_sid: AC32a3c83990934481addd5ce1659f04d2 twilio.auth_token: mytoken .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.twilio_notify.send_sms(profile, body, to, from_) Send an sms .sp CLI Example: .INDENT 7.0 .INDENT 3.5 twilio.send_sms my\-twilio\-account \(aqTest sms\(aq \(aq+18019999999\(aq \(aq+18011111111\(aq .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.udev .sp Manage and query udev info .sp New in version 2015.8.0. .INDENT 0.0 .TP .B salt.modules.udev.env(dev) Return all environment variables udev has for dev .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq udev.env /dev/sda salt \(aq*\(aq udev.env /sys/class/net/eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.udev.exportdb() Return all the udev database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq udev.exportdb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.udev.info(dev) Extract all info delivered by udevadm .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq udev.info /dev/sda salt \(aq*\(aq udev.info /sys/class/net/eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.udev.links(dev) Return all udev\-created device symlinks .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq udev.links /dev/sda salt \(aq*\(aq udev.links /sys/class/net/eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.udev.name(dev) Return the actual dev name(s?) according to udev for dev .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq udev.dev /dev/sda salt \(aq*\(aq udev.dev /sys/class/net/eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.udev.path(dev) Return the physical device path(s?) according to udev for dev .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq udev.path /dev/sda salt \(aq*\(aq udev.path /sys/class/net/eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.upstart_service .sp Module for the management of upstart systems. The Upstart system only supports service starting, stopping and restarting. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage services on a minion, and it is using a different module (or gives an error similar to \fI\(aqservice.start\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .sp Currently (as of Ubuntu 12.04) there is no tool available to disable Upstart services (like update\-rc.d). This[1] is the recommended way to disable an Upstart service. So we assume that all Upstart services that have not been disabled in this manner are enabled. .sp But this is broken because we do not check to see that the dependent services are enabled. Otherwise we would have to do something like parse the output of \(dqinitctl show\-config\(dq to determine if all service dependencies are enabled to start on boot. For example, see the \(dqstart on\(dq condition for the lightdm service below[2]. And this would be too hard. So we wait until the upstart developers have solved this problem. :) This is to say that an Upstart service that is enabled may not really be enabled. .sp Also, when an Upstart service is enabled, should the dependent services be enabled too? Probably not. But there should be a notice about this, at least. .sp [1] \fI\%http://upstart.ubuntu.com/cookbook/#disabling\-a\-job\-from\-automatically\-starting\fP .sp [2] example upstart configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lightdm emits login\-session\-start emits desktop\-session\-start emits desktop\-shutdown start on ((((filesystem and runlevel [!06]) and started dbus) and (drm\-device\-added card0 PRIMARY_DEVICE_FOR_DISPLAY=1 or stopped udev\-fallback\-graphics)) or runlevel PREVLEVEL=S) stop on runlevel [016] .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module should not be used on Red Hat systems. For these, the \fI\%rh_service\fP module should be used, as it supports the hybrid upstart/sysvinit system used in RHEL/CentOS 6. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.disable(name, **kwargs) Disable the named service from starting on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.disabled(name) Check to see if the named service is disabled to start on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.enable(name, **kwargs) Enable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.enabled(name, **kwargs) Check to see if the named service is enabled to start on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.force_reload(name) Force\-reload the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.force_reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.full_restart(name) Do a full restart (stop/start) of the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.full_restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.get_all() Return all installed services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.get_disabled() Return the disabled services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.get_enabled() Return the enabled services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.missing(name) The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.reload_(name) Reload the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.restart(name) Restart the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.start(name) Start the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.status(name, sig=None) Return the status for a service. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .IP \(bu 2 \fBsig\fP (\fI\%str\fP) \-\- Signature to use to find the service via ps .UNINDENT .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> [service signature] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart_service.stop(name) Stop the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.uptime .SS Wrapper around uptime API .INDENT 0.0 .TP .B salt.modules.uptime.check_exists(name) Check if a given URL is in being monitored by uptime .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq uptime.check_exists http://example.org .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.uptime.checks_list() List URL checked by uptime .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq uptime.checks_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.uptime.create(name, **params) Create a check on a given URL. .sp Additional parameters can be used and are passed to API (for example interval, maxTime, etc). See the documentation \fI\%https://github.com/fzaninotto/uptime\fP for a full list of the parameters. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq uptime.create http://example.org .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.uptime.delete(name) Delete a check on a given URL .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq uptime.delete http://example.org .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.useradd .sp Manage users with the useradd command .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage users on a minion, and it is using a different module (or gives an error similar to \fI\(aquser.info\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.add(name, uid=None, gid=None, groups=None, home=None, shell=None, unique=True, system=False, fullname=\(aq\(aq, roomnumber=\(aq\(aq, workphone=\(aq\(aq, homephone=\(aq\(aq, other=\(aq\(aq, createhome=True, loginclass=None, nologinit=False, root=None, usergroup=None, local=False) Add a user to the minion .INDENT 7.0 .TP .B name Username LOGIN to add .TP .B uid User ID of the new account .TP .B gid Name or ID of the primary group of the new account .TP .B groups List of supplementary groups of the new account .TP .B home Home directory of the new account .TP .B shell Login shell of the new account .TP .B unique If not True, the user account can have a non\-unique UID .TP .B system Create a system account .TP .B fullname GECOS field for the full name .TP .B roomnumber GECOS field for the room number .TP .B workphone GECOS field for the work phone .TP .B homephone GECOS field for the home phone .TP .B other GECOS field for other information .TP .B createhome Create the user\(aqs home directory .TP .B loginclass Login class for the new account (OpenBSD) .TP .B nologinit Do not add the user to the lastlog and faillog databases .TP .B root Directory to chroot into .TP .B usergroup Create and add the user to a new primary group of the same name .TP .B local (Only on systems with luseradd available) Specifically add the user locally rather than possibly through remote providers (e.g. LDAP) .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.add name <uid> <gid> <groups> <home> <shell> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chfullname(name, fullname, root=None) Change the user\(aqs Full Name .INDENT 7.0 .TP .B name User to modify .TP .B fullname GECOS field for the full name .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chfullname foo \(dqFoo Bar\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chgid(name, gid, root=None) Change the default group of the user .INDENT 7.0 .TP .B name User to modify .TP .B gid Force use GID as new primary group .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chgid foo 4376 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chgroups(name, groups, append=False, root=None) Change the groups to which this user belongs .INDENT 7.0 .TP .B name User to modify .TP .B groups Groups to set for the user .TP .B append False If \fBTrue\fP, append the specified group(s). Otherwise, this function will replace the user\(aqs groups with the specified group(s). .TP .B root Directory to chroot into .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chgroups foo wheel,root salt \(aq*\(aq user.chgroups foo wheel,root append=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chhome(name, home, persist=False, root=None) Change the home directory of the user, pass True for persist to move files to the new home directory if the old home directory exist. .INDENT 7.0 .TP .B name User to modify .TP .B home New home directory for the user account .TP .B persist Move contents of the home directory to the new location .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chhome foo /home/users/foo True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chhomephone(name, homephone, root=None) Change the user\(aqs Home Phone .INDENT 7.0 .TP .B name User to modify .TP .B homephone GECOS field for the home phone .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chhomephone foo 7735551234 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chloginclass(name, loginclass, root=None) Change the default login class of the user .INDENT 7.0 .TP .B name User to modify .TP .B loginclass Login class for the new account .TP .B root Directory to chroot into .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function only applies to OpenBSD systems. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chloginclass foo staff .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chother(name, other, root=None) Change the user\(aqs other GECOS attribute .INDENT 7.0 .TP .B name User to modify .TP .B other GECOS field for other information .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chother foobar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chroomnumber(name, roomnumber, root=None) Change the user\(aqs Room Number .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chroomnumber foo 123 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chshell(name, shell, root=None) Change the default shell of the user .INDENT 7.0 .TP .B name User to modify .TP .B shell New login shell for the user account .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chshell foo /bin/zsh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chuid(name, uid, root=None) Change the uid for a named user .INDENT 7.0 .TP .B name User to modify .TP .B uid New UID for the user account .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chuid foo 4376 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chworkphone(name, workphone, root=None) Change the user\(aqs Work Phone .INDENT 7.0 .TP .B name User to modify .TP .B workphone GECOS field for the work phone .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chworkphone foo 7735550123 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.delete(name, remove=False, force=False, root=None, local=False) Remove a user from the minion .INDENT 7.0 .TP .B name Username to delete .TP .B remove Remove home directory and mail spool .TP .B force Force some actions that would fail otherwise .TP .B root Directory to chroot into .TP .B local (Only on systems with luserdel available): Ensure the user account is removed locally ignoring global account management (default is False). .sp New in version 3007.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.delete name remove=True force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.get_loginclass(name) Get the login class of the user .INDENT 7.0 .TP .B name User to get the information .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function only applies to OpenBSD systems. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.get_loginclass foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.getent(refresh=False, root=None) Return the list of all info for all users .INDENT 7.0 .TP .B refresh Force a refresh of user information .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.getent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.info(name, root=None) Return user information .INDENT 7.0 .TP .B name User to get the information .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.info root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.list_groups(name) Return a list of groups the named user belongs to .INDENT 7.0 .TP .B name User to get the information .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.list_groups foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.list_users(root=None) Return a list of all users .INDENT 7.0 .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.primary_group(name) Return the primary group of the named user .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name User to get the information .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.primary_group saltadmin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.rename(name, new_name, root=None) Change the username for a named user .INDENT 7.0 .TP .B name User to modify .TP .B new_name New value of the login name .TP .B root Directory to chroot into .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.rename name new_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.uwsgi .sp uWSGI stats server \fI\%https://uwsgi\-docs.readthedocs.io/en/latest/StatsServer.html\fP .INDENT 0.0 .TP .B maintainer Peter Baumgartner <\fI\%pete@lincolnloop.com\fP> .TP .B maturity new .TP .B platform all .UNINDENT .INDENT 0.0 .TP .B salt.modules.uwsgi.stats(socket) Return the data from \fIuwsgi \-\-connect\-and\-read\fP as a dictionary. .INDENT 7.0 .TP .B socket The socket the uWSGI stats server is listening on .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq uwsgi.stats /var/run/mystatsserver.sock salt \(aq*\(aq uwsgi.stats 127.0.0.1:5050 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.vagrant .sp Work with virtual machines managed by Vagrant. .sp New in version 2018.3.0. .sp Mapping between a Salt node id and the Vagrant machine name (and the path to the Vagrantfile where it is defined) is stored in a Salt sdb database on the Vagrant host (minion) machine. In order to use this module, sdb must be configured. An SQLite database is the recommended storage method. The URI used for the sdb lookup is \(dqsdb://vagrant_sdb_data\(dq. .INDENT 0.0 .TP .B requirements: .INDENT 7.0 .IP \(bu 2 the VM host machine must have salt\-minion, Vagrant and a vm provider installed. .IP \(bu 2 the VM host must have a valid definition for \fIsdb://vagrant_sdb_data\fP .UNINDENT .INDENT 7.0 .INDENT 3.5 Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # file /etc/salt/minion.d/vagrant_sdb.conf vagrant_sdb_data: driver: sqlite3 database: /var/cache/salt/vagrant.sqlite table: sdb create_table: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.destroy(name) Destroy and delete a virtual machine. (vagrant destroy \-f) .sp This also removes the salt_id name defined by vagrant.init. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <host> vagrant.destroy <salt_id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.get_machine_id(machine, cwd) returns the salt_id name of the Vagrant VM .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmachine\fP \-\- the Vagrant machine name .IP \(bu 2 \fBcwd\fP \-\- the path to Vagrantfile .UNINDENT .TP .B Returns salt_id name .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.get_ssh_config(name, network_mask=\(aq\(aq, get_private_key=False) Retrieve hints of how you might connect to a Vagrant VM. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- the salt_id of the machine .IP \(bu 2 \fBnetwork_mask\fP \-\- a CIDR mask to search for the VM\(aqs address .IP \(bu 2 \fBget_private_key\fP \-\- (default: False) return the key used for ssh login .UNINDENT .TP .B Returns a dict of ssh login information for the VM .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <host> vagrant.get_ssh_config <salt_id> salt my_laptop vagrant.get_ssh_config quail1 network_mask=10.0.0.0/8 get_private_key=True .ft P .fi .UNINDENT .UNINDENT .sp The returned dictionary contains: .INDENT 7.0 .IP \(bu 2 key_filename: the name of the private key file on the VM host computer .IP \(bu 2 ssh_username: the username to be used to log in to the VM .IP \(bu 2 ssh_host: the IP address used to log in to the VM. (This will usually be \fI127.0.0.1\fP) .IP \(bu 2 ssh_port: the TCP port used to log in to the VM. (This will often be \fI2222\fP) .IP \(bu 2 [ip_address:] (if \fInetwork_mask\fP is defined. see below) .IP \(bu 2 [private_key:] (if \fIget_private_key\fP is True) the private key for ssh_username .UNINDENT .sp About \fInetwork_mask\fP: .sp Vagrant usually uses a redirected TCP port on its host computer to log in to a VM using ssh. This redirected port and its IP address are \(dqssh_port\(dq and \(dqssh_host\(dq. The ssh_host is usually the localhost (127.0.0.1). This makes it impossible for a third machine (such as a salt\-cloud master) to contact the VM unless the VM has another network interface defined. You will usually want a bridged network defined by having a \fIconfig.vm.network \(dqpublic_network\(dq\fP statement in your \fIVagrantfile\fP\&. .sp The IP address of the bridged adapter will typically be assigned by DHCP and unknown to you, but you should be able to determine what IP network the address will be chosen from. If you enter a CIDR network mask, Salt will attempt to find the VM\(aqs address for you. The host machine will send an \(dqip link show\(dq or \(dqifconfig\(dq command to the VM (using ssh to \fIssh_host\fP:\fIssh_port\fP) and return the IP address of the first interface it can find which matches your mask. .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.get_vm_info(name) get the information for a VM. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- salt_id name .TP .B Returns dictionary of {\(aqmachine\(aq: x, \(aqcwd\(aq: y, ...}. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.init(name, cwd=None, machine=\(aq\(aq, runas=None, start=False, vagrant_provider=\(aq\(aq, vm=None) Initialize a new Vagrant VM. .sp This inputs all the information needed to start a Vagrant VM. These settings are stored in a Salt sdb database on the Vagrant host minion and used to start, control, and query the guest VMs. The salt_id assigned here is the key field for that database and must be unique. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The salt_id name you will use to control this VM .IP \(bu 2 \fBcwd\fP \-\- The path to the directory where the Vagrantfile is located .IP \(bu 2 \fBmachine\fP \-\- The machine name in the Vagrantfile. If blank, the primary machine will be used. .IP \(bu 2 \fBrunas\fP \-\- The username on the host who owns the Vagrant work files. .IP \(bu 2 \fBstart\fP \-\- (default: False) Start the virtual machine now. .IP \(bu 2 \fBvagrant_provider\fP \-\- The name of a Vagrant VM provider (if not the default). .IP \(bu 2 \fBvm\fP \-\- Optionally, all the above information may be supplied in this dictionary. .UNINDENT .TP .B Returns A string indicating success, or False. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <host> vagrant.init <salt_id> /path/to/Vagrantfile salt my_laptop vagrant.init x1 /projects/bevy_master machine=quail1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.list_active_vms(cwd=None) Return a list of machine names for active virtual machine on the host, which are defined in the Vagrantfile at the indicated path. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vagrant.list_active_vms cwd=/projects/project_1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.list_domains() Return a list of the salt_id names of all available Vagrant VMs on this host without regard to the path where they are defined. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vagrant.list_domains \-\-log\-level=info .ft P .fi .UNINDENT .UNINDENT .sp The log shows information about all known Vagrant environments on this machine. This data is cached and may not be completely up\-to\-date. .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.list_inactive_vms(cwd=None) Return a list of machine names for inactive virtual machine on the host, which are defined in the Vagrantfile at the indicated path. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.list_inactive_vms cwd=/projects/project_1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.pause(name) Pause (vagrant suspend) the named VM. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <host> vagrant.pause <salt_id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.reboot(name, provision=False) Reboot a VM. (vagrant reload) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <host> vagrant.reboot <salt_id> provision=True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The salt_id name you will use to control this VM .IP \(bu 2 \fBprovision\fP \-\- (False) also re\-run the Vagrant provisioning scripts. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.shutdown(name) Send a soft shutdown (vagrant halt) signal to the named vm. .sp This does the same thing as vagrant.stop. Other\-VM control modules use \(dqstop\(dq and \(dqshutdown\(dq to differentiate between hard and soft shutdowns. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <host> vagrant.shutdown <salt_id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.start(name) Start (vagrant up) a virtual machine defined by salt_id name. The machine must have been previously defined using \(dqvagrant.init\(dq. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <host> vagrant.start <salt_id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.stop(name) Hard shutdown the virtual machine. (vagrant halt) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt <host> vagrant.stop <salt_id> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.version() Return the version of Vagrant on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vagrant.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vagrant.vm_state(name=\(aq\(aq, cwd=None) Return list of information for all the vms indicating their state. .sp If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs defined by the Vagrantfile in the \fIcwd\fP directory. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vagrant.vm_state <name> cwd=/projects/project_1 .ft P .fi .UNINDENT .UNINDENT .sp returns a list of dictionaries with machine name, state, provider, and salt_id name. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C datum = {\(aqmachine\(aq: _, # Vagrant machine name, \(aqstate\(aq: _, # string indicating machine state, like \(aqrunning\(aq \(aqprovider\(aq: _, # the Vagrant VM provider \(aqname\(aq: _} # salt_id name .ft P .fi .UNINDENT .UNINDENT .sp Known bug: if there are multiple machines in your Vagrantfile, and you request the status of the \fBprimary\fP machine, which you defined by leaving the \fBmachine\fP parameter blank, then you may receive the status of all of them. Please specify the actual machine name for each VM if there are more than one. .UNINDENT .SS salt.modules.varnish .sp Support for Varnish .sp New in version 2014.7.0. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 These functions are designed to work with all implementations of Varnish from 3.x onwards .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.varnish.ban(ban_expression) Add ban to the varnish cache .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq varnish.ban ban_expression .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.varnish.ban_list() List varnish cache current bans .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq varnish.ban_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.varnish.param_set(param, value) Set a param in varnish cache .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq varnish.param_set param value .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.varnish.param_show(param=None) Show params of varnish cache .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq varnish.param_show param .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.varnish.purge() Purge the varnish cache .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq varnish.purge .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.varnish.version() Return server version from varnishd \-V .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq varnish.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.vault .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%vault Salt Extension\fP\&. .UNINDENT .UNINDENT .SS Functions to interact with Hashicorp Vault. .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity new .TP .B platform all .TP .B note If you see the following error, you\(aqll need to upgrade \fBrequests\fP to at least 2.4.2 .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C <timestamp> [salt.pillar][CRITICAL][14337] Pillar render error: Failed to load ext_pillar vault: {\(aqerror\(aq: \(dqrequest() got an unexpected keyword argument \(aqjson\(aq\(dq} .ft P .fi .UNINDENT .UNINDENT .SS Configuration .sp In addition to the module configuration, it is required for the Salt master to be configured to allow peer runs in order to use the Vault integration. .sp Changed in version 3007.0: The \fBvault\fP configuration structure has changed significantly to account for many new features. If found, the old structure will be automatically translated to the new one. .sp \fBPlease update your peer_run configuration\fP to take full advantage of the updated modules. The old endpoint (\fBvault.generate_token\fP) will continue to work, but result in unnecessary roundtrips once your minions have been updated. .sp To allow minions to pull configuration and credentials from the Salt master, add this segment to the master configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer_run: .*: \- vault.get_config # always \- vault.generate_new_token # relevant when \(gatoken\(ga == \(gaissue:type\(ga \- vault.generate_secret_id # relevant when \(gaapprole\(ga == \(gaissue:type\(ga .ft P .fi .UNINDENT .UNINDENT .sp Minimally required configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vault: auth: token: abcdefg\-hijklmnop\-qrstuvw server: url: https://vault.example.com:8200 .ft P .fi .UNINDENT .UNINDENT .sp A sensible example configuration, e.g. in \fB/etc/salt/master.d/vault.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vault: auth: method: approle role_id: e5a7b66e\-5d08\-da9c\-7075\-71984634b882 secret_id: 841771dc\-11c9\-bbc7\-bcac\-6a3945a69cd9 cache: backend: file issue: token: role_name: salt_minion params: explicit_max_ttl: 30 num_uses: 10 policies: assign: \- salt_minion \- salt_role_{pillar[roles]} server: url: https://vault.example.com:8200 .ft P .fi .UNINDENT .UNINDENT .sp The above configuration requires the following policies for the master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Issue tokens path \(dqauth/token/create\(dq { capabilities = [\(dqcreate\(dq, \(dqread\(dq, \(dqupdate\(dq] } # Issue tokens with token roles path \(dqauth/token/create/*\(dq { capabilities = [\(dqcreate\(dq, \(dqread\(dq, \(dqupdate\(dq] } .ft P .fi .UNINDENT .UNINDENT .sp A sensible example configuration that issues AppRoles to minions from a separate authentication endpoint (notice differing mounts): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vault: auth: method: approle mount: approle # <\-\- mount the salt master authenticates at role_id: e5a7b66e\-5d08\-da9c\-7075\-71984634b882 secret_id: 841771dc\-11c9\-bbc7\-bcac\-6a3945a69cd9 cache: backend: file issue: type: approle approle: mount: salt\-minions # <\-\- mount the salt master manages metadata: entity: minion\-id: \(aq{minion}\(aq role: \(aq{pillar[role]}\(aq server: url: https://vault.example.com:8200 ext_pillar: \- vault: path=salt/minions/{minion} \- vault: path=salt/roles/{pillar[role]} .ft P .fi .UNINDENT .UNINDENT .sp The above configuration requires the following policies for the master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # List existing AppRoles path \(dqauth/salt\-minions/role\(dq { capabilities = [\(dqlist\(dq] } # Manage AppRoles path \(dqauth/salt\-minions/role/*\(dq { capabilities = [\(dqread\(dq, \(dqcreate\(dq, \(dqupdate\(dq, \(dqdelete\(dq] } # Lookup mount accessor path \(dqsys/auth/salt\-minions\(dq { capabilities = [\(dqread\(dq, \(dqsudo\(dq] } # Lookup entities by alias name (role\-id) and alias mount accessor path \(dqidentity/lookup/entity\(dq { capabilities = [\(dqcreate\(dq, \(dqupdate\(dq] allowed_parameters = { \(dqalias_name\(dq = [] \(dqalias_mount_accessor\(dq = [\(dqauth_approle_0a1b2c3d\(dq] } } # Manage entities with name prefix salt_minion_ path \(dqidentity/entity/name/salt_minion_*\(dq { capabilities = [\(dqread\(dq, \(dqcreate\(dq, \(dqupdate\(dq, \(dqdelete\(dq] } # Create entity aliases – you can restrict the mount_accessor # This might allow privilege escalation in case the salt master # is compromised and the attacker knows the entity ID of an # entity with relevant policies attached \- although you might # have other problems at that point. path \(dqidentity/entity\-alias\(dq { capabilities = [\(dqcreate\(dq, \(dqupdate\(dq] allowed_parameters = { \(dqid\(dq = [] \(dqcanonical_id\(dq = [] \(dqmount_accessor\(dq = [\(dqauth_approle_0a1b2c3d\(dq] \(dqname\(dq = [] } } .ft P .fi .UNINDENT .UNINDENT .sp This enables you to write templated ACL policies like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C path \(dqsalt/data/minions/{{identity.entity.metadata.minion\-id}}\(dq { capabilities = [\(dqread\(dq] } path \(dqsalt/data/roles/{{identity.entity.metadata.role}}\(dq { capabilities = [\(dqread\(dq] } .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 AppRole policies and entity metadata are generally not updated automatically. After a change, you will need to synchronize them by running \fI\%vault.sync_approles\fP or \fI\%vault.sync_entities\fP respectively. .UNINDENT .UNINDENT .sp All possible master configuration options with defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vault: auth: approle_mount: approle approle_name: salt\-master method: token role_id: <required if auth:method == approle> secret_id: null token: <required if auth:method == token> token_lifecycle: minimum_ttl: 10 renew_increment: null cache: backend: session config: 3600 kv_metadata: connection secret: ttl issue: allow_minion_override_params: false type: token approle: mount: salt\-minions params: bind_secret_id: true secret_id_num_uses: 1 secret_id_ttl: 60 token_explicit_max_ttl: 60 token_num_uses: 10 secret_id_bound_cidrs: null token_ttl: null token_max_ttl: null token_no_default_policy: false token_period: null token_bound_cidrs: null token: role_name: null params: explicit_max_ttl: null num_uses: 1 ttl: null period: null no_default_policy: false renewable: true wrap: 30s keys: [] metadata: entity: minion\-id: \(aq{minion}\(aq secret: saltstack\-jid: \(aq{jid}\(aq saltstack\-minion: \(aq{minion}\(aq saltstack\-user: \(aq{user}\(aq policies: assign: \- saltstack/minions \- saltstack/{minion} cache_time: 60 refresh_pillar: null server: url: <required, e. g. https://vault.example.com:8200> namespace: null verify: null .ft P .fi .UNINDENT .UNINDENT .SS \fBauth\fP .sp Contains authentication information for the local machine. .INDENT 0.0 .TP .B approle_mount New in version 3007.0. .sp The name of the AppRole authentication mount point. Defaults to \fBapprole\fP\&. .TP .B approle_name New in version 3007.0. .sp The name of the AppRole. Defaults to \fBsalt\-master\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Only relevant when a locally configured role_id/secret_id uses response wrapping. .UNINDENT .UNINDENT .TP .B method Currently only \fBtoken\fP and \fBapprole\fP auth types are supported. Defaults to \fBtoken\fP\&. .sp AppRole is the preferred way to authenticate with Vault as it provides some advanced options to control the authentication process. Please see the \fI\%Vault documentation\fP for more information. .TP .B role_id The role ID of the AppRole. Required if \fBauth:method\fP == \fBapprole\fP\&. .sp Changed in version 3007.0: In addition to a plain string, this can also be specified as a dictionary that includes \fBwrap_info\fP, i.e. the return payload of a wrapping request. .TP .B secret_id The secret ID of the AppRole. Only required if the configured AppRole requires it. .sp Changed in version 3007.0: In addition to a plain string, this can also be specified as a dictionary that includes \fBwrap_info\fP, i.e. the return payload of a wrapping request. .TP .B token Token to authenticate to Vault with. Required if \fBauth:method\fP == \fBtoken\fP\&. .sp The token must be able to create tokens with the policies that should be assigned to minions. You can still use the token auth via a OS environment variable via this config example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C vault: auth: method: token token: sdb://osenv/VAULT_TOKEN server: url: https://vault.service.domain:8200 osenv: driver: env .ft P .fi .UNINDENT .UNINDENT .sp And then export the VAULT_TOKEN variable in your OS: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C export VAULT_TOKEN=11111111\-1111\-1111\-1111\-1111111111111 .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3007.0: In addition to a plain string, this can also be specified as a dictionary that includes \fBwrap_info\fP, i.e. the return payload of a wrapping request. .TP .B token_lifecycle Token renewal settings. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This setting can be specified inside a minion\(aqs configuration as well and will override the master\(aqs default for the minion. .sp Token lifecycle settings have significancy for any authentication method, not just \fBtoken\fP\&. .UNINDENT .UNINDENT .sp \fBminimum_ttl\fP specifies the time (in seconds or as a time string like \fB24h\fP) an in\-use token should be valid for. If the current validity period is less than this and the token is renewable, a renewal will be attempted. If it is not renewable or a renewal does not extend the ttl beyond the specified minimum, a new token will be generated. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Since leases like database credentials are tied to a token, setting this to a much higher value than the default can be necessary, depending on your specific use case and configuration. .UNINDENT .UNINDENT .sp \fBrenew_increment\fP specifies the amount of time the token\(aqs validity should be requested to be renewed for when renewing a token. When unset, will extend the token\(aqs validity by its default ttl. Set this to \fBfalse\fP to disable token renewals. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The Vault server is allowed to disregard this request. .UNINDENT .UNINDENT .UNINDENT .SS \fBcache\fP .sp Configures token/lease and metadata cache (for KV secrets) on all hosts as well as configuration cache on minions that receive issued credentials. .INDENT 0.0 .TP .B backend Changed in version 3007.0: This used to be found in \fBauth:token_backend\fP\&. .sp The cache backend in use. Defaults to \fBsession\fP, which will store the Vault configuration in memory only for that specific Salt run. \fBdisk\fP/\fBfile\fP/\fBlocalfs\fP will force using the localfs driver, regardless of configured minion data cache. Setting this to anything else will use the default configured cache for minion data (\fI\%cache\fP), by default the local filesystem as well. .TP .B clear_attempt_revocation New in version 3007.0. .sp When flushing still valid cached tokens and leases, attempt to have them revoked after a (short) delay. Defaults to \fB60\fP\&. Set this to false to disable revocation (not recommended). .TP .B clear_on_unauthorized New in version 3007.0. .sp When encountering an \fBUnauthorized\fP response with an otherwise valid token, flush the cache and request new credentials. Defaults to true. If your policies are relatively stable, disabling this will prevent a lot of unnecessary overhead, with the tradeoff that once they change, you might have to clear the cache manually or wait for the token to expire. .TP .B config New in version 3007.0. .sp The time in seconds to cache queried configuration from the master. Defaults to \fB3600\fP (one hour). Set this to \fBnull\fP to disable cache expiration. Changed \fBserver\fP configuration on the master will still be recognized, but changes in \fBauth\fP and \fBcache\fP will need a manual update using \fBvault.update_config\fP or cache clearance using \fBvault.clear_cache\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Expiring the configuration will also clear cached authentication credentials and leases. .UNINDENT .UNINDENT .TP .B expire_events New in version 3007.0. .sp Fire an event when the session cache containing leases is cleared (\fBvault/cache/<scope>/clear\fP) or cached leases have expired (\fBvault/lease/<cache_key>/expire\fP). A reactor can be employed to ensure fresh leases are issued. Defaults to false. .TP .B kv_metadata New in version 3007.0. .sp The time in seconds to cache KV metadata used to determine if a path is using version 1/2 for. Defaults to \fBconnection\fP, which will clear the metadata cache once a new configuration is requested from the master. Setting this to \fBnull\fP will keep the information indefinitely until the cache is cleared manually using \fBvault.clear_cache\fP with \fBconnection=false\fP\&. .TP .B secret New in version 3007.0. .sp The time in seconds to cache tokens/secret IDs for. Defaults to \fBttl\fP, which caches the secret for as long as it is valid, unless a new configuration is requested from the master. .UNINDENT .SS \fBissue\fP .sp Configures authentication data issued by the master to minions. .INDENT 0.0 .TP .B type New in version 3007.0. .sp The type of authentication to issue to minions. Can be \fBtoken\fP or \fBapprole\fP\&. Defaults to \fBtoken\fP\&. .sp To be able to issue AppRoles to minions, the master needs to be able to create new AppRoles on the configured auth mount (see policy example above). It is strongly encouraged to create a separate mount dedicated to minions. .TP .B approle New in version 3007.0. .sp Configuration regarding issued AppRoles. .sp \fBmount\fP specifies the name of the auth mount the master manages. Defaults to \fBsalt\-minions\fP\&. This mount should be exclusively dedicated to the Salt master. .sp \fBparams\fP configures the AppRole the master creates for minions. See the \fI\%Vault AppRole API docs\fP for details. If you update these params, you can update the minion AppRoles manually using the vault runner: \fBsalt\-run vault.sync_approles\fP, but they will be updated automatically during a request by a minion as well. .TP .B token New in version 3007.0. .sp Configuration regarding issued tokens. .sp \fBrole_name\fP specifies the role name for minion tokens created. Optional. .sp Changed in version 3007.0: This used to be found in \fBrole_name\fP\&. .sp If omitted, minion tokens will be created without any role, thus being able to inherit any master token policy (including token creation capabilities). .sp Example configuration: \fI\%https://www.nomadproject.io/docs/vault\-integration/index.html#vault\-token\-role\-configuration\fP .sp \fBparams\fP configures the tokens the master issues to minions. .sp Changed in version 3007.0: This used to be found in \fBauth:ttl\fP and \fBauth:uses\fP\&. The possible parameters were synchronized with the Vault nomenclature: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBttl\fP previously was mapped to \fBexplicit_max_ttl\fP on Vault, not \fBttl\fP\&. For the same behavior as before, you will need to set \fBexplicit_max_ttl\fP now. .IP \(bu 2 \fBuses\fP is now called \fBnum_uses\fP\&. .UNINDENT .UNINDENT .UNINDENT .sp See the \fI\%Vault token API docs\fP for details. To make full use of multi\-use tokens, you should configure a cache that survives a single session (e.g. \fBdisk\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If unset, the master issues single\-use tokens to minions, which can be quite expensive. .UNINDENT .UNINDENT .TP .B allow_minion_override_params Changed in version 3007.0: This used to be found in \fBauth:allow_minion_override\fP\&. .sp Whether to allow minions to request to override parameters for issuing credentials. See \fBissue_params\fP below. .TP .B wrap New in version 3007.0. .sp The time a minion has to unwrap a wrapped secret issued by the master. Set this to false to disable wrapping, otherwise a time string like \fB30s\fP can be used. Defaults to \fB30s\fP\&. .UNINDENT .SS \fBkeys\fP .INDENT 0.0 .INDENT 3.5 List of keys to use to unseal vault server with the \fBvault.unseal\fP runner. .UNINDENT .UNINDENT .SS \fBmetadata\fP .sp New in version 3007.0. .sp Configures metadata for the issued entities/secrets. Values have to be strings and can be templated with the following variables: .INDENT 0.0 .IP \(bu 2 \fB{jid}\fP Salt job ID that issued the secret. .IP \(bu 2 \fB{minion}\fP The minion ID the secret was issued for. .IP \(bu 2 \fB{user}\fP The user the Salt daemon issuing the secret was running as. .IP \(bu 2 \fB{pillar[<var>]}\fP A minion pillar value that does not depend on Vault. .IP \(bu 2 \fB{grains[<var>]}\fP A minion grain value. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Values have to be strings, hence templated variables that resolve to lists will be concatenated to a lexicographically sorted comma\-separated list (Python \fBlist.sort()\fP). .UNINDENT .UNINDENT .INDENT 0.0 .TP .B entity Configures the metadata associated with the minion entity inside Vault. Entities are only created when issuing AppRoles to minions. .TP .B secret Configures the metadata associated with issued tokens/secret IDs. They are logged in plaintext to the Vault audit log. .UNINDENT .SS \fBpolicies\fP .sp Changed in version 3007.0: This used to specify the list of policies associated with a minion token only. The equivalent is found in \fBassign\fP\&. .INDENT 0.0 .TP .B assign List of policies that are assigned to issued minion authentication data, either token or AppRole. .sp They can be static strings or string templates with .INDENT 7.0 .IP \(bu 2 \fB{minion}\fP The minion ID. .IP \(bu 2 \fB{pillar[<var>]}\fP A minion pillar value. .IP \(bu 2 \fB{grains[<var>]}\fP A minion grain value. .UNINDENT .sp For pillar and grain values, lists are expanded, so \fBsalt_role_{pillar[roles]}\fP with \fB[a, b]\fP results in \fBsalt_role_a\fP and \fBsalt_role_b\fP to be issued. .sp Defaults to \fB[saltstack/minions, saltstack/{minion}]\fP\&. .sp New in version 3006.0: Policies can be templated with pillar values as well: \fBsalt_role_{pillar[roles]}\fP\&. Make sure to only reference pillars that are not sourced from Vault since the latter ones might be unavailable during policy rendering. If you use the Vault integration in one of your pillar \fBsls\fP files, all values from that file will be absent during policy rendering, even the ones that do not depend on Vault. .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 See \fI\%Is Targeting using Grain Data Secure?\fP for important security information. In short, everything except \fBgrains[id]\fP is minion\-controlled. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 List members which do not have simple string representations, such as dictionaries or objects, do not work and will throw an exception. Strings and numbers are examples of types which work well. .UNINDENT .UNINDENT .TP .B cache_time New in version 3007.0. .sp Number of seconds compiled templated policies are cached on the master. This is important when using pillar values in templates, since compiling the pillar is an expensive operation. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Only effective when issuing tokens to minions. Token policies need to be compiled every time a token is requested, while AppRole\-associated policies are written to Vault configuration the first time authentication data is requested (they can be refreshed on demand by running \fBsalt\-run vault.sync_approles\fP). .sp They will also be refreshed in case other issuance parameters are changed (such as uses/ttl), either on the master or the minion (if allow_minion_override_params is True). .UNINDENT .UNINDENT .TP .B refresh_pillar New in version 3007.0. .sp Whether to refresh the minion pillar when compiling templated policies that contain pillar variables. Only effective when issuing tokens to minions (see note on cache_time above). .INDENT 7.0 .IP \(bu 2 \fBnull\fP (default) only compiles the pillar when no cached pillar is found. .IP \(bu 2 \fBfalse\fP never compiles the pillar. This means templated policies that contain pillar values are skipped if no cached pillar is found. .IP \(bu 2 \fBtrue\fP always compiles the pillar. This can cause additional strain on the master since the compilation is costly. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Hardcoded to True when issuing AppRoles. .sp Using cached pillar data only (refresh_pillar=False) might cause the policies to be out of sync. If there is no cached pillar data available for the minion, pillar templates will fail to render at all. .sp If you use pillar values for templating policies and do not disable refreshing pillar data, make sure the relevant values are not sourced from Vault (ext_pillar, sdb) or from a pillar sls file that uses the vault execution/sdb module. Although this will often work when cached pillar data is available, if the master needs to compile the pillar data during policy rendering, all Vault modules will be broken to prevent an infinite loop. .UNINDENT .UNINDENT .UNINDENT .SS \fBserver\fP .sp Changed in version 3007.0: The values found in here were found in the \fBvault\fP root namespace previously. .sp Configures Vault server details. .INDENT 0.0 .TP .B url URL of your Vault installation. Required. .TP .B verify Configures certificate verification behavior when issuing requests to the Vault server. If unset, requests will use the CA certificates bundled with \fBcertifi\fP\&. .sp For details, please see \fI\%the requests documentation\fP\&. .sp New in version 2018.3.0. .sp Changed in version 3007.0: Minions again respect the master configuration value, which was changed implicitly in v3001. If this value is set in the minion configuration as well, it will take precedence. .sp In addition, this value can now be set to a PEM\-encoded CA certificate to use as the sole trust anchor for certificate chain verification. .TP .B namespace Optional Vault namespace. Used with Vault Enterprise. .sp For details please see: \fI\%https://www.vaultproject.io/docs/enterprise/namespaces\fP .sp New in version 3004. .UNINDENT .sp Minion configuration (optional): .SS \fBconfig_location\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 Where to get the connection details for calling vault. By default, vault will try to determine if it needs to request the connection details from the master or from the local config. This optional option will force vault to use the connection details from the master or the local config. Can only be either \fBmaster\fP or \fBlocal\fP\&. .UNINDENT .UNINDENT .sp New in version 3006.0. .UNINDENT .UNINDENT .SS \fBissue_params\fP .INDENT 0.0 .INDENT 3.5 Request overrides for token/AppRole issuance. This needs to be allowed on the master by setting \fBissue:allow_minion_override_params\fP to true. See the master configuration \fBissue:token:params\fP or \fBissue:approle:params\fP for reference. .sp Changed in version 3007.0: For token issuance, this used to be found in \fBauth:ttl\fP and \fBauth:uses\fP\&. Mind that the parameter names have been synchronized with Vault, see notes above (TLDR: \fBttl\fP => \fBexplicit_max_ttl\fP, \fBuses\fP => \fBnum_uses\fP\&. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBauth:token_lifecycle\fP and \fBserver:verify\fP can be set on the minion as well. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.clear_cache(connection=True, session=False) New in version 3007.0. .sp Delete Vault caches. Will ensure the current token and associated leases are revoked by default. .sp The cache is organized in a hierarchy: \fB/vault/connection/session/leases\fP\&. (\fIitalics\fP mark data that is only cached when receiving configuration from a master) .sp \fBconnection\fP contains KV metadata (by default), \fIconfiguration\fP and \fI(AppRole) auth credentials\fP\&. \fBsession\fP contains the currently active token. \fBleases\fP contains leases issued to the currently active token like database credentials. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.clear_cache salt \(aq*\(aq vault.clear_cache session=True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B connection Only clear the cached data scoped to a connection. This includes configuration, auth credentials, the currently active auth token as well as leases and KV metadata (by default). Defaults to true. Set this to false to clear all Vault caches. .TP .B session Only clear the cached data scoped to a session. This only includes leases and the currently active auth token, but not configuration or (AppRole) auth credentials. Defaults to false. Setting this to true will keep the connection cache, regardless of \fBconnection\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.clear_token_cache() Changed in version 3001. .sp Changed in version 3007.0: This is now an alias for \fBvault.clear_cache\fP with \fBconnection=True\fP\&. .sp Delete minion Vault token cache. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.clear_token_cache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.delete_secret(path, *args) Delete secret at <path>. The vault policy used must allow this. If <path> is on KV v2, the secret will be soft\-deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.delete_secret \(dqsecret/my/secret\(dq salt \(aq*\(aq vault.delete_secret \(dqsecret/my/secret\(dq 1 2 3 .ft P .fi .UNINDENT .UNINDENT .sp Required policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C path \(dq<mount>/<secret>\(dq { capabilities = [\(dqdelete\(dq] } # or KV v2 path \(dq<mount>/data/<secret>\(dq { capabilities = [\(dqdelete\(dq] } # KV v2 versions path \(dq<mount>/delete/<secret>\(dq { capabilities = [\(dqupdate\(dq] } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path The path to the secret, including mount. .UNINDENT .sp New in version 3007.0: For KV v2, you can specify versions to soft\-delete as supplemental positional arguments. .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.destroy_secret(path, *args) New in version 3001. .sp Destroy specified secret versions <path>. The vault policy used must allow this. Only supported on Vault KV version 2. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.destroy_secret \(dqsecret/my/secret\(dq 1 2 .ft P .fi .UNINDENT .UNINDENT .sp Required policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C path \(dq<mount>/destroy/<secret>\(dq { capabilities = [\(dqupdate\(dq] } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path The path to the secret, including mount. .UNINDENT .sp You can specify versions to destroy as supplemental positional arguments. At least one is required. .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.get_server_config() New in version 3007.0. .sp Return the server connection configuration that\(aqs currently in use by Salt. Contains \fBurl\fP, \fBverify\fP and \fBnamespace\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.get_server_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.list_secrets(path, default=<Constant.NOT_SET>, keys_only=False) List secret keys at <path>. The vault policy used must allow this. The path should end with a trailing slash. .sp Changed in version 3001: The \fBdefault\fP argument has been added. When the path or path/key combination is not found, an exception will be raised, unless a default is provided. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.list_secrets \(dqsecret/my/\(dq .ft P .fi .UNINDENT .UNINDENT .sp Required policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C path \(dq<mount>/<path>\(dq { capabilities = [\(dqlist\(dq] } # or KV v2 path \(dq<mount>/metadata/<path>\(dq { capabilities = [\(dqlist\(dq] } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path The path to the secret, including mount. .TP .B default New in version 3001. .sp When the path is not found, an exception will be raised, unless a default is provided here. .TP .B keys_only New in version 3007.0. .sp This function used to return a dictionary like \fB{\(dqkeys\(dq: [\(dqsome/\(dq, \(dqsome/key\(dq]}\fP\&. Setting this to True will only return the list of keys. For backwards\-compatibility reasons, this defaults to False. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.patch_secret(path, **kwargs) Patch secret dataset at <path>. Fields are specified as arbitrary keyword arguments. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This works even for older Vault versions, KV v1 and with missing \fBpatch\fP capability, but will use more than one request to simulate the functionality by issuing a read and update request. .sp For proper, single\-request patching, requires versions of KV v2 that support the \fBpatch\fP capability and the \fBpatch\fP capability to be available for the path. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This uses JSON Merge Patch format internally. Keys set to \fBnull\fP (JSON/YAML)/\fBNone\fP (Python) will be deleted. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.patch_secret \(dqsecret/my/secret\(dq password=\(dqbaz\(dq .ft P .fi .UNINDENT .UNINDENT .sp Required policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Proper patching path \(dq<mount>/data/<secret>\(dq { capabilities = [\(dqpatch\(dq] } # OR (!), for older KV v2 setups: path \(dq<mount>/data/<secret>\(dq { capabilities = [\(dqread\(dq, \(dqupdate\(dq] } # OR (!), for KV v1 setups: path \(dq<mount>/<secret>\(dq { capabilities = [\(dqread\(dq, \(dqupdate\(dq] } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path The path to the secret, including mount. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.policies_list() New in version 3007.0. .sp List all ACL policies. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.policies_list .ft P .fi .UNINDENT .UNINDENT .sp Required policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C path \(dqsys/policy\(dq { capabilities = [\(dqread\(dq] } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.policy_delete(policy) New in version 3007.0. .sp Delete an ACL policy. Returns False if the policy did not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.policy_delete salt_minion .ft P .fi .UNINDENT .UNINDENT .sp Required policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C path \(dqsys/policy/<policy>\(dq { capabilities = [\(dqdelete\(dq] } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B policy The name of the policy to delete. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.policy_fetch(policy) New in version 3007.0. .sp Fetch the rules associated with an ACL policy. Returns None if the policy does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.policy_fetch salt_minion .ft P .fi .UNINDENT .UNINDENT .sp Required policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C path \(dqsys/policy/<policy>\(dq { capabilities = [\(dqread\(dq] } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B policy The name of the policy to fetch. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.policy_write(policy, rules) New in version 3007.0. .sp Create or update an ACL policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.policy_write salt_minion \(aqpath \(dqsecret/foo\(dq {...}\(aq .ft P .fi .UNINDENT .UNINDENT .sp Required policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C path \(dqsys/policy/<policy>\(dq { capabilities = [\(dqcreate\(dq, \(dqupdate\(dq] } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B policy The name of the policy to create/update. .TP .B rules Rules to write, formatted as in\-line HCL. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.query(method, endpoint, payload=None) New in version 3007.0. .sp Issue arbitrary queries against the Vault API. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.query GET auth/token/lookup\-self .ft P .fi .UNINDENT .UNINDENT .sp Required policy: Depends on the query. .sp You can ask the vault CLI to output the necessary policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C vault read \-output\-policy auth/token/lookup\-self .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B method HTTP method to use. .TP .B endpoint Vault API endpoint to issue the request against. Do not include \fB/v1/\fP\&. .TP .B payload Optional dictionary to use as JSON payload. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.read_secret(path, key=None, metadata=False, default=<Constant.NOT_SET>) Return the value of <key> at <path> in vault, or entire secret. .sp Changed in version 3001: The \fBdefault\fP argument has been added. When the path or path/key combination is not found, an exception will be raised, unless a default is provided. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.read_secret salt/kv/secret .ft P .fi .UNINDENT .UNINDENT .sp Required policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C path \(dq<mount>/<secret>\(dq { capabilities = [\(dqread\(dq] } # or KV v2 path \(dq<mount>/data/<secret>\(dq { capabilities = [\(dqread\(dq] } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path The path to the secret, including mount. .TP .B key The data field at <path> to read. If unspecified, returns the whole dataset. .TP .B metadata New in version 3001. .sp If using KV v2 backend, display full results, including metadata. Defaults to False. .TP .B default New in version 3001. .sp When the path or path/key combination is not found, an exception will be raised, unless a default is provided here. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.update_config(keep_session=False) New in version 3007.0. .sp Attempt to update the cached configuration without clearing the currently active Vault session. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.update_config .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B keep_session Only update configuration that can be updated without creating a new login session. If this is false, still tries to keep the active session, but might clear it if the server configuration has changed significantly. Defaults to False. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.write_raw(path, raw) Set raw data at <path>. The vault policy used must allow this. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.write_raw \(dqsecret/my/secret\(dq \(aq{\(dquser\(dq:\(dqfoo\(dq,\(dqpassword\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp Required policy: see write_secret .INDENT 7.0 .TP .B path The path to the secret, including mount. .TP .B raw Secret data to write to <path>. Has to be a mapping. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.write_secret(path, **kwargs) Set secret dataset at <path>. The vault policy used must allow this. Fields are specified as arbitrary keyword arguments. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vault.write_secret \(dqsecret/my/secret\(dq user=\(dqfoo\(dq password=\(dqbar\(dq .ft P .fi .UNINDENT .UNINDENT .sp Required policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C path \(dq<mount>/<secret>\(dq { capabilities = [\(dqcreate\(dq, \(dqupdate\(dq] } # or KV v2 path \(dq<mount>/data/<secret>\(dq { capabilities = [\(dqcreate\(dq, \(dqupdate\(dq] } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path The path to the secret, including mount. .UNINDENT .UNINDENT .SS salt.modules.vbox_guest .sp VirtualBox Guest Additions installer .INDENT 0.0 .TP .B salt.modules.vbox_guest.additions_install(**kwargs) Install VirtualBox Guest Additions. Uses the CD, connected by VirtualBox. .sp To connect VirtualBox Guest Additions via VirtualBox graphical interface press \(aqHost+D\(aq (\(aqHost\(aq is usually \(aqRight Ctrl\(aq). .sp See \fI\%https://www.virtualbox.org/manual/ch04.html#idp52733088\fP for more details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vbox_guest.additions_install salt \(aq*\(aq vbox_guest.additions_install reboot=True salt \(aq*\(aq vbox_guest.additions_install upgrade_os=True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBreboot\fP (\fI\%bool\fP) \-\- reboot computer to complete installation .IP \(bu 2 \fBupgrade_os\fP (\fI\%bool\fP) \-\- upgrade OS (to ensure the latests version of kernel and developer tools are installed) .UNINDENT .TP .B Returns version of VirtualBox Guest Additions or string with error .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vbox_guest.additions_mount() Mount VirtualBox Guest Additions CD to the temp directory. .sp To connect VirtualBox Guest Additions via VirtualBox graphical interface press \(aqHost+D\(aq (\(aqHost\(aq is usually \(aqRight Ctrl\(aq). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vbox_guest.additions_mount .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns True or OSError exception .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vbox_guest.additions_remove(**kwargs) Remove VirtualBox Guest Additions. .sp Firstly it tries to uninstall itself by executing \(aq/opt/VBoxGuestAdditions\-VERSION/uninstall.run uninstall\(aq. It uses the CD, connected by VirtualBox if it failes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vbox_guest.additions_remove salt \(aq*\(aq vbox_guest.additions_remove force=True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBforce\fP (\fI\%bool\fP) \-\- force VirtualBox Guest Additions removing .TP .B Returns True if VirtualBox Guest Additions were removed successfully else False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vbox_guest.additions_umount(mount_point) Unmount VirtualBox Guest Additions CD from the temp directory. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vbox_guest.additions_umount .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBmount_point\fP \-\- directory VirtualBox Guest Additions is mounted to .TP .B Returns True or an string with error .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vbox_guest.additions_version() Check VirtualBox Guest Additions version. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vbox_guest.additions_version .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns version of VirtualBox Guest Additions or False if they are not installed .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vbox_guest.grant_access_to_shared_folders_to(name, users=None) Grant access to auto\-mounted shared folders to the users. .sp User is specified by its name. To grant access for several users use argument \fIusers\fP\&. Access will be denied to the users not listed in \fIusers\fP argument. .sp See \fI\%https://www.virtualbox.org/manual/ch04.html#sf_mount_auto\fP for more details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vbox_guest.grant_access_to_shared_folders_to fred salt \(aq*\(aq vbox_guest.grant_access_to_shared_folders_to users [\(aqfred\(aq, \(aqroman\(aq] .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- name of the user to grant access to auto\-mounted shared folders to .IP \(bu 2 \fBusers\fP (\fI\%list\fP\fI of \fP\fI\%str\fP) \-\- list of names of users to grant access to auto\-mounted shared folders to (if specified, \fIname\fP will not be taken into account) .UNINDENT .TP .B Returns list of users who have access to auto\-mounted shared folders .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vbox_guest.list_shared_folders_users() List users who have access to auto\-mounted shared folders. .sp See \fI\%https://www.virtualbox.org/manual/ch04.html#sf_mount_auto\fP for more details. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vbox_guest.list_shared_folders_users .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns list of users who have access to auto\-mounted shared folders .UNINDENT .UNINDENT .SS salt.modules.vboxmanage .sp Support for VirtualBox using the VBoxManage command .sp New in version 2016.3.0. .sp If the \fBvboxdrv\fP kernel module is not loaded, this module can automatically load it by configuring \fBautoload_vboxdrv\fP in \fB/etc/salt/minion\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C autoload_vboxdrv: True .ft P .fi .UNINDENT .UNINDENT .sp The default for this setting is \fBFalse\fP\&. .INDENT 0.0 .TP .B depends virtualbox .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.clonemedium(medium, uuid_in=None, file_in=None, uuid_out=None, file_out=None, mformat=None, variant=None, existing=False, **kwargs) Clone a new VM from an existing VM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqhypervisor\(aq vboxmanage.clonemedium <name> <new_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.clonevm(name=None, uuid=None, new_name=None, snapshot_uuid=None, snapshot_name=None, mode=\(aqmachine\(aq, options=None, basefolder=None, new_uuid=None, register=False, groups=None, **kwargs) Clone a new VM from an existing VM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqhypervisor\(aq vboxmanage.clonevm <name> <new_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.create(name, groups=None, ostype=None, register=True, basefolder=None, new_uuid=None, **kwargs) Create a new VM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqhypervisor\(aq vboxmanage.create <name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.destroy(name) Unregister and destroy a VM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vboxmanage.destroy my_vm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.list_items(item, details=False, group_by=\(aqUUID\(aq) Return a list of a specific type of item. The following items are available: .INDENT 7.0 .INDENT 3.5 vms runningvms ostypes hostdvds hostfloppies intnets bridgedifs hostonlyifs natnets dhcpservers hostinfo hostcpuids hddbackends hdds dvds floppies usbhost usbfilters systemproperties extpacks groups webcams screenshotformats .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqhypervisor\(aq vboxmanage.items <item> salt \(aqhypervisor\(aq vboxmanage.items <item> details=True salt \(aqhypervisor\(aq vboxmanage.items <item> details=True group_by=Name .ft P .fi .UNINDENT .UNINDENT .sp Some items do not display well, or at all, unless \fBdetails\fP is set to \fBTrue\fP\&. By default, items are grouped by the \fBUUID\fP field, but not all items contain that field. In those cases, another field must be specified. .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.list_nodes() Return a list of registered VMs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vboxmanage.list_nodes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.list_nodes_full() Return a list of registered VMs, with detailed information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vboxmanage.list_nodes_full .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.list_nodes_min() Return a list of registered VMs, with minimal information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vboxmanage.list_nodes_min .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.list_ostypes() List the available OS Types .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vboxmanage.list_ostypes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.register(filename) Register a VM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vboxmanage.register my_vm_filename .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.start(name) Start a VM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vboxmanage.start my_vm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.stop(name) Stop a VM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vboxmanage.stop my_vm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.unregister(name, delete=False) Unregister a VM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vboxmanage.unregister my_vm_filename .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vboxmanage.vboxcmd() Return the location of the VBoxManage command .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vboxmanage.vboxcmd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.vcenter .sp Module used to access the vcenter proxy connection methods .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be deprecated in a future release of Salt. VMware strongly recommends using the \fI\%VMware Salt extensions\fP instead of the vCenter module. Because the Salt extensions are newer and actively supported by VMware, they are more compatible with current versions of ESXi and they work well with the latest features in the VMware product line. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vcenter.get_details() .UNINDENT .SS salt.modules.victorops .sp Support for VictorOps .sp New in version 2015.8.0. .sp Requires an \fBapi_key\fP in \fB/etc/salt/minion\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C victorops: api_key: \(aq280d4699\-a817\-4719\-ba6f\-ca56e573e44f\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.victorops.create_event(message_type=None, routing_key=\(aqeverybody\(aq, **kwargs) Create an event in VictorOps. Designed for use in states. .sp The following parameters are required: .INDENT 7.0 .TP .B Parameters \fBmessage_type\fP \-\- One of the following values: INFO, WARNING, ACKNOWLEDGEMENT, CRITICAL, RECOVERY. .UNINDENT .sp The following parameters are optional: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrouting_key\fP \-\- The key for where messages should be routed. By default, sent to \(aqeveryone\(aq route. .IP \(bu 2 \fBentity_id\fP \-\- The name of alerting entity. If not provided, a random name will be assigned. .IP \(bu 2 \fBtimestamp\fP \-\- Timestamp of the alert in seconds since epoch. Defaults to the time the alert is received at VictorOps. .UNINDENT .UNINDENT .sp :param timestamp_fmt The date format for the timestamp parameter. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstate_start_time\fP \-\- The time this entity entered its current state (seconds since epoch). Defaults to the time alert is received. .IP \(bu 2 \fBstate_start_time_fmt\fP \-\- The date format for the timestamp parameter. .IP \(bu 2 \fBstate_message\fP \-\- Any additional status information from the alert item. .IP \(bu 2 \fBentity_is_host\fP \-\- Used within VictorOps to select the appropriate display format for the incident. .IP \(bu 2 \fBentity_display_name\fP \-\- Used within VictorOps to display a human\-readable name for the entity. .IP \(bu 2 \fBack_message\fP \-\- A user entered comment for the acknowledgment. .IP \(bu 2 \fBack_author\fP \-\- The user that acknowledged the incident. .UNINDENT .TP .B Returns A dictionary with result, entity_id, and message if result was failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion victorops.create_event message_type=\(aqCRITICAL\(aq routing_key=\(aqeveryone\(aq entity_id=\(aqhostname/diskspace\(aq salt myminion victorops.create_event message_type=\(aqACKNOWLEDGEMENT\(aq routing_key=\(aqeveryone\(aq entity_id=\(aqhostname/diskspace\(aq ack_message=\(aqAcknowledged\(aq ack_author=\(aqusername\(aq salt myminion victorops.create_event message_type=\(aqRECOVERY\(aq routing_key=\(aqeveryone\(aq entity_id=\(aqhostname/diskspace\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B The following parameters are required: message_type .UNINDENT .UNINDENT .SS salt.modules.virt .sp Work with virtual machines managed by libvirt .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 libvirt Python module .IP \(bu 2 libvirt client .IP \(bu 2 qemu\-img .IP \(bu 2 grep .UNINDENT .UNINDENT .SS Connection .sp The connection to the virtualization host can be either setup in the minion configuration, pillar data or overridden for each individual call. .sp By default, the libvirt connection URL will be guessed: the first available libvirt hypervisor driver will be used. This can be overridden like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virt: connection: uri: lxc:/// .ft P .fi .UNINDENT .UNINDENT .sp If the connection requires an authentication like for ESXi, this can be defined in the minion pillar data like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virt: connection: uri: esx://10.1.1.101/?no_verify=1&auto_answer=1 auth: username: user password: secret .ft P .fi .UNINDENT .UNINDENT .SS Connecting with SSH protocol .sp Libvirt can connect to remote hosts using SSH using one of the \fBssh\fP, \fBlibssh\fP and \fBlibssh2\fP transports. Note that \fBlibssh2\fP is likely to fail as it doesn\(aqt read the \fBknown_hosts\fP file. Libvirt may also have been built without \fBlibssh\fP or \fBlibssh2\fP support. .sp To use the SSH transport, on the minion setup an SSH agent with a key authorized on the remote libvirt machine. .SS Per call connection setup .sp New in version 2019.2.0. .sp All the calls requiring the libvirt connection configuration as mentioned above can override this configuration using \fBconnection\fP, \fBusername\fP and \fBpassword\fP parameters. .sp This means that the following will list the domains on the local LXC libvirt driver, whatever the \fBvirt:connection\fP is. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqhypervisor\(aq virt.list_domains connection=lxc:/// .ft P .fi .UNINDENT .UNINDENT .sp The calls not using the libvirt connection setup are: .INDENT 0.0 .IP \(bu 2 \fBseed_non_shared_migrate\fP .IP \(bu 2 \fBvirt_type\fP .IP \(bu 2 \fBis_*hyper\fP .IP \(bu 2 all migration functions .IP \(bu 2 \fI\%libvirt ESX URI format\fP .IP \(bu 2 \fI\%libvirt URI format\fP .IP \(bu 2 \fI\%libvirt authentication configuration\fP .UNINDENT .SS Units .sp Units specification .sp New in version 3002. .sp The string should contain a number optionally followed by a unit. The number may have a decimal fraction. If the unit is not given then MiB are set by default. Units can optionally be given in IEC style (such as MiB), although the standard single letter style (such as M) is more convenient. .sp Valid units include: .TS center; |l|l|l|l|l|. _ T{ Standard T} T{ IEC T} T{ Standard T} T{ IEC T} T{ T} _ T{ Unit T} T{ Unit T} T{ Name T} T{ Name T} T{ Factor T} _ T{ B T} T{ T} T{ Bytes T} T{ T} T{ 1 T} _ T{ K T} T{ KiB T} T{ Kilobytes T} T{ Kibibytes T} T{ 2**10 T} _ T{ M T} T{ MiB T} T{ Megabytes T} T{ Mebibytes T} T{ 2**20 T} _ T{ G T} T{ GiB T} T{ Gigabytes T} T{ Gibibytes T} T{ 2**30 T} _ T{ T T} T{ TiB T} T{ Terabytes T} T{ Tebibytes T} T{ 2**40 T} _ T{ P T} T{ PiB T} T{ Petabytes T} T{ Pebibytes T} T{ 2**50 T} _ T{ E T} T{ EiB T} T{ Exabytes T} T{ Exbibytes T} T{ 2**60 T} _ T{ Z T} T{ ZiB T} T{ Zettabytes T} T{ Zebibytes T} T{ 2**70 T} _ T{ Y T} T{ YiB T} T{ Yottabytes T} T{ Yobibytes T} T{ 2**80 T} _ .TE .sp Additional decimal based units: .TS center; |l|l|. _ T{ Unit T} T{ Factor T} _ T{ KB T} T{ 10**3 T} _ T{ MB T} T{ 10**6 T} _ T{ GB T} T{ 10**9 T} _ T{ TB T} T{ 10**12 T} _ T{ PB T} T{ 10**15 T} _ T{ EB T} T{ 10**18 T} _ T{ ZB T} T{ 10**21 T} _ T{ YB T} T{ 10**24 T} _ .TE .INDENT 0.0 .TP .B salt.modules.virt.all_capabilities(**kwargs) Return the host and domain capabilities in a single call. .sp New in version 3001. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.all_capabilities .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.capabilities(**kwargs) Return the hypervisor connection capabilities. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.capabilities .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.cpu_baseline(full=False, migratable=False, out=\(aqlibvirt\(aq, **kwargs) Return the optimal \(aqcustom\(aq CPU baseline config for VM\(aqs on this minion .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfull\fP \-\- Return all CPU features rather than the ones on top of the closest CPU model .IP \(bu 2 \fBmigratable\fP \-\- Exclude CPU features that are unmigratable (libvirt 2.13+) .IP \(bu 2 \fBout\fP \-\- \(aqlibvirt\(aq (default) for usable libvirt XML definition, \(aqsalt\(aq for nice dict .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.cpu_baseline .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.create_xml_path(path, **kwargs) Start a transient domain based on the XML\-file path passed to the function .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- path to a file containing the libvirt XML definition of the domain .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.create_xml_path <path to XML file on the node> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.create_xml_str(xml, **kwargs) Start a transient domain based on the XML passed to the function .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBxml\fP \-\- libvirt XML definition of the domain .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.create_xml_str <XML in string format> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.ctrl_alt_del(vm_, **kwargs) Sends CTRL+ALT+DEL to a VM .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.ctrl_alt_del <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.define_vol_xml_path(path, pool=None, **kwargs) Define a volume based on the XML\-file path passed to the function .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- path to a file containing the libvirt XML definition of the volume .IP \(bu 2 \fBpool\fP \-\- .sp storage pool name to define the volume in. If defined, this parameter will override the configuration setting. .sp New in version 3001. .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.define_vol_xml_path <path to XML file on the node> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.define_vol_xml_str(xml, pool=None, **kwargs) Define a volume based on the XML passed to the function .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBxml\fP \-\- libvirt XML definition of the storage volume .IP \(bu 2 \fBpool\fP \-\- .sp storage pool name to define the volume in. If defined, this parameter will override the configuration setting. .sp New in version 3001. .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.define_vol_xml_str <XML in string format> .ft P .fi .UNINDENT .UNINDENT .sp The storage pool where the disk image will be defined is \fBdefault\fP unless changed with the pool parameter or a configuration like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C virt: storagepool: mine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.define_xml_path(path, **kwargs) Define a persistent domain based on the XML\-file path passed to the function .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- path to a file containing the libvirt XML definition of the domain .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.define_xml_path <path to XML file on the node> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.define_xml_str(xml, **kwargs) Define a persistent domain based on the XML passed to the function .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBxml\fP \-\- libvirt XML definition of the domain .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.define_xml_str <XML in string format> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.delete_snapshots(name, *names, **kwargs) Delete one or more snapshots of the given VM. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- domain name .IP \(bu 2 \fBnames\fP \-\- names of the snapshots to remove .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.delete_snapshots <domain> all=True salt \(aq*\(aq virt.delete_snapshots <domain> <snapshot> salt \(aq*\(aq virt.delete_snapshots <domain> <snapshot1> <snapshot2> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.domain_capabilities(emulator=None, arch=None, machine=None, domain=None, **kwargs) Return the domain capabilities given an emulator, architecture, machine or virtualization type. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemulator\fP \-\- return the capabilities for the given emulator binary .IP \(bu 2 \fBarch\fP \-\- return the capabilities for the given CPU architecture .IP \(bu 2 \fBmachine\fP \-\- return the capabilities for the given emulated machine type .IP \(bu 2 \fBdomain\fP \-\- return the capabilities for the given virtualization type. .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp The list of the possible emulator, arch, machine and domain can be found in the host capabilities output. .sp If none of the parameters is provided, the libvirt default one is returned. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.domain_capabilities arch=\(aqx86_64\(aq domain=\(aqkvm\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.freecpu(**kwargs) Return an int representing the number of unallocated cpus on this hypervisor .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.freecpu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.freemem(**kwargs) Return an int representing the amount of memory (in MB) that has not been given to virtual machines on this node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.freemem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.full_info(**kwargs) Return the node_info, vm_info and freemem .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.full_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_disks(vm_, **kwargs) Return the disks of a named vm .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- name of the domain .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.get_disks <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_graphics(vm_, **kwargs) Returns the information on vnc for a given vm .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- name of the domain .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.get_graphics <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_hypervisor() Returns the name of the hypervisor running on this node or \fBNone\fP\&. .sp Detected hypervisors: .INDENT 7.0 .IP \(bu 2 kvm .IP \(bu 2 xen .IP \(bu 2 bhyve .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.get_hypervisor .ft P .fi .UNINDENT .UNINDENT .sp New in version 2019.2.0: the function and the \fBkvm\fP, \fBxen\fP and \fBbhyve\fP hypervisors support .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_loader(vm_, **kwargs) Returns the information on the loader for a given vm .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- name of the domain .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.get_loader <domain> .ft P .fi .UNINDENT .UNINDENT .sp New in version 2019.2.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_macs(vm_, **kwargs) Return a list off MAC addresses from the named vm .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- name of the domain .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.get_macs <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_nics(vm_, **kwargs) Return info about the network interfaces of a named vm .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- name of the domain .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.get_nics <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_profiles(hypervisor=None, **kwargs) Return the virt profiles for hypervisor. .sp Currently there are profiles for: .INDENT 7.0 .IP \(bu 2 nic .IP \(bu 2 disk .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhypervisor\fP \-\- override the default machine type. .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.get_profiles salt \(aq*\(aq virt.get_profiles hypervisor=vmware .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_xml(vm_, **kwargs) Returns the XML for a given vm .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.get_xml <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.init(name, cpu, mem, nic=\(aqdefault\(aq, interfaces=None, hypervisor=None, start=True, disk=\(aqdefault\(aq, disks=None, saltenv=\(aqbase\(aq, seed=True, install=True, pub_key=None, priv_key=None, seed_cmd=\(aqseed.apply\(aq, graphics=None, os_type=None, arch=None, boot=None, boot_dev=None, numatune=None, hypervisor_features=None, clock=None, serials=None, consoles=None, stop_on_reboot=False, host_devices=None, **kwargs) Initialize a new vm .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- name of the virtual machine to create .IP \(bu 2 \fBcpu\fP \-\- .sp Number of virtual CPUs to assign to the virtual machine or a dictionary with detailed information to configure cpu model and topology, numa node tuning, cpu tuning and iothreads allocation. The structure of the dictionary is documented in \fI\%cpu parameters definition\fP\&. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C cpu: placement: static cpuset: 0\-11 current: 5 maximum: 12 vcpus: 0: enabled: True hotpluggable: False order: 1 1: enabled: False hotpluggable: True match: minimum mode: custom check: full vendor: Intel model: name: core2duo fallback: allow vendor_id: GenuineIntel topology: sockets: 1 cores: 12 threads: 1 cache: level: 3 mode: emulate features: lahf: optional pcid: require numa: 0: cpus: 0\-3 memory: 1g discard: True distances: 0: 10 # sibling id : value 1: 21 2: 31 3: 41 1: cpus: 4\-6 memory: 1g memAccess: shared distances: 0: 21 1: 10 2: 21 3: 31 tuning: vcpupin: 0: 1\-4,^2 # vcpuid : cpuset 1: 0,1 2: 2,3 3: 0,4 emulatorpin: 1\-3 iothreadpin: 1: 5,6 # iothread id: cpuset 2: 7,8 shares: 2048 period: 1000000 quota: \-1 global_period: 1000000 global_quota: \-1 emulator_period: 1000000 emulator_quota: \-1 iothread_period: 1000000 iothread_quota: \-1 vcpusched: \- scheduler: fifo priority: 1 vcpus: 0,3\-5 \- scheduler: rr priority: 3 iothreadsched: \- scheduler: idle \- scheduler: batch iothreads: 2,3 emulatorsched: \- scheduler: batch cachetune: 0\-3: # vcpus set 0: # cache id level: 3 type: both size: 4 1: level: 3 type: both size: 6 monitor: 1: 3 0\-3: 3 4\-5: monitor: 4: 3 # vcpus: level 5: 3 memorytune: 0\-3: # vcpus set 0: 60 # node id: bandwidth 4\-5: 0: 60 iothreads: 4 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBmem\fP \-\- .sp Amount of memory to allocate to the virtual machine in MiB. Since 3002, a dictionary can be used to contain detailed configuration which support memory allocation or tuning. Supported parameters are \fBboot\fP, \fBcurrent\fP, \fBmax\fP, \fBslots\fP, \fBhard_limit\fP, \fBsoft_limit\fP, \fBswap_hard_limit\fP, \fBmin_guarantee\fP, \fBhugepages\fP , \fBnosharepages\fP, \fBlocked\fP, \fBsource\fP, \fBaccess\fP, \fBallocation\fP and \fBdiscard\fP\&. The structure of the dictionary is documented in \fI\%Memory parameter definition\fP\&. Both decimal and binary base are supported. Detail unit specification is documented in \fI\%Units specification\fP\&. Please note that the value for \fBslots\fP must be an integer. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C { \(aqboot\(aq: 1g, \(aqcurrent\(aq: 1g, \(aqmax\(aq: 1g, \(aqslots\(aq: 10, \(aqhard_limit\(aq: \(aq1024\(aq, \(aqsoft_limit\(aq: \(aq512m\(aq, \(aqswap_hard_limit\(aq: \(aq1g\(aq, \(aqmin_guarantee\(aq: \(aq512mib\(aq, \(aqhugepages\(aq: [{\(aqnodeset\(aq: \(aq0\-3,^2\(aq, \(aqsize\(aq: \(aq1g\(aq}, {\(aqnodeset\(aq: \(aq2\(aq, \(aqsize\(aq: \(aq2m\(aq}], \(aqnosharepages\(aq: True, \(aqlocked\(aq: True, \(aqsource\(aq: \(aqfile\(aq, \(aqaccess\(aq: \(aqshared\(aq, \(aqallocation\(aq: \(aqimmediate\(aq, \(aqdiscard\(aq: True } .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3002. .IP \(bu 2 \fBnic\fP \-\- NIC profile to use (Default: \fB\(aqdefault\(aq\fP). The profile interfaces can be customized / extended with the interfaces parameter. If set to \fBNone\fP, no profile will be used. .IP \(bu 2 \fBinterfaces\fP \-\- .sp List of dictionaries providing details on the network interfaces to create. These data are merged with the ones from the nic profile. The structure of each dictionary is documented in \fI\%Network Interfaces Definitions\fP\&. .sp New in version 2019.2.0. .IP \(bu 2 \fBhypervisor\fP \-\- the virtual machine type. By default the value will be computed according to the virtual host capabilities. .IP \(bu 2 \fBstart\fP \-\- \fBTrue\fP to start the virtual machine after having defined it (Default: \fBTrue\fP) .IP \(bu 2 \fBdisk\fP \-\- Disk profile to use (Default: \fB\(aqdefault\(aq\fP). If set to \fBNone\fP, no profile will be used. .IP \(bu 2 \fBdisks\fP \-\- .sp List of dictionaries providing details on the disk devices to create. These data are merged with the ones from the disk profile. The structure of each dictionary is documented in \fI\%Disks Definitions\fP\&. .sp New in version 2019.2.0. .IP \(bu 2 \fBsaltenv\fP \-\- Fileserver environment (Default: \fB\(aqbase\(aq\fP). See \fI\%cp module for more details\fP .IP \(bu 2 \fBseed\fP \-\- \fBTrue\fP to seed the disk image. Only used when the \fBimage\fP parameter is provided. (Default: \fBTrue\fP) .IP \(bu 2 \fBinstall\fP \-\- install salt minion if absent (Default: \fBTrue\fP) .IP \(bu 2 \fBpub_key\fP \-\- public key to seed with (Default: \fBNone\fP) .IP \(bu 2 \fBpriv_key\fP \-\- public key to seed with (Default: \fBNone\fP) .IP \(bu 2 \fBseed_cmd\fP \-\- Salt command to execute to seed the image. (Default: \fB\(aqseed.apply\(aq\fP) .IP \(bu 2 \fBgraphics\fP \-\- .sp Dictionary providing details on the graphics device to create. (Default: \fBNone\fP) See \fI\%Graphics Definition\fP for more details on the possible values. .sp New in version 2019.2.0. .IP \(bu 2 \fBos_type\fP \-\- .sp type of virtualization as found in the \fB//os/type\fP element of the libvirt definition. The default value is taken from the host capabilities, with a preference for \fBhvm\fP\&. .sp New in version 2019.2.0. .IP \(bu 2 \fBarch\fP \-\- .sp architecture of the virtual machine. The default value is taken from the host capabilities, but \fBx86_64\fP is prefed over \fBi686\fP\&. .sp New in version 2019.2.0. .IP \(bu 2 \fBconfig\fP \-\- minion configuration to use when seeding. See \fI\%seed module for more details\fP .IP \(bu 2 \fBboot_dev\fP \-\- String of space\-separated devices to boot from (Default: \fB\(aqhd\(aq\fP) .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBstop_on_reboot\fP \-\- .sp If set to \fBTrue\fP the guest will stop instead of rebooting. This is specially useful when creating a virtual machine with an installation cdrom or an autoinstallation needing a special first boot configuration. Defaults to \fBFalse\fP .sp New in version 3003. .IP \(bu 2 \fBboot\fP \-\- .sp Specifies kernel, initial ramdisk and kernel command line parameters for the virtual machine. This is an optional parameter, all of the keys are optional within the dictionary. The structure of the dictionary is documented in \fI\%Boot parameters definition\fP\&. If a remote path is provided to kernel or initrd, salt will handle the downloading of the specified remote file and modify the XML accordingly. To boot VM with UEFI, specify loader and nvram path or specify \(aqefi\(aq: \fBTrue\fP if your libvirtd version is >= 5.2.0 and QEMU >= 3.0.0. .sp New in version 3000. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C { \(aqkernel\(aq: \(aq/root/f8\-i386\-vmlinuz\(aq, \(aqinitrd\(aq: \(aq/root/f8\-i386\-initrd\(aq, \(aqcmdline\(aq: \(aqconsole=ttyS0 ks=http://example.com/f8\-i386/os/\(aq, \(aqloader\(aq: \(aq/usr/share/OVMF/OVMF_CODE.fd\(aq, \(aqnvram\(aq: \(aq/usr/share/OVMF/OVMF_VARS.ms.fd\(aq } .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBboot_dev\fP \-\- .sp Space separated list of devices to boot from sorted by decreasing priority. Values can be \fBhd\fP, \fBfd\fP, \fBcdrom\fP or \fBnetwork\fP\&. .sp By default, the value will \fB\(dqhd\(dq\fP\&. .IP \(bu 2 \fBnumatune\fP \-\- .sp The optional numatune element provides details of how to tune the performance of a NUMA host via controlling NUMA policy for domain process. The optional \fBmemory\fP element specifies how to allocate memory for the domain process on a NUMA host. \fBmemnode\fP elements can specify memory allocation policies per each guest NUMA node. The definition used in the dictionary can be found at \fI\%cpu parameters definition\fP\&. .sp New in version 3003. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C { \(aqmemory\(aq: {\(aqmode\(aq: \(aqstrict\(aq, \(aqnodeset\(aq: \(aq0\-11\(aq}, \(aqmemnodes\(aq: {0: {\(aqmode\(aq: \(aqstrict\(aq, \(aqnodeset\(aq: 1}, 1: {\(aqmode\(aq: \(aqpreferred\(aq, \(aqnodeset\(aq: 2}} } .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBhypervisor_features\fP \-\- .sp Enable or disable hypervisor\-specific features on the virtual machine. .sp New in version 3003. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C hypervisor_features: kvm\-hint\-dedicated: True .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBclock\fP \-\- .sp Configure the guest clock. The value is a dictionary with the following keys: .INDENT 2.0 .TP .B adjustment time adjustment in seconds or \fBreset\fP .TP .B utc set to \fBFalse\fP to use the host local time as the guest clock. Defaults to \fBTrue\fP\&. .TP .B timezone synchronize the guest to the correspding timezone .TP .B timers a dictionary associating the timer name with its configuration. This configuration is a dictionary with the properties \fBtrack\fP, \fBtickpolicy\fP, \fBcatchup\fP, \fBfrequency\fP, \fBmode\fP, \fBpresent\fP, \fBslew\fP, \fBthreshold\fP and \fBlimit\fP\&. See \fI\%libvirt time keeping documentation\fP for the possible values. .UNINDENT .sp New in version 3003. .sp Set the clock to local time using an offset in seconds \&.. code\-block:: yaml .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .TP .B clock: adjustment: 3600 utc: False .UNINDENT .UNINDENT .UNINDENT .sp Set the clock to a specific time zone: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C clock: timezone: CEST .ft P .fi .UNINDENT .UNINDENT .sp Tweak guest timers: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C clock: timers: tsc: frequency: 3504000000 mode: native rtc: track: wall tickpolicy: catchup slew: 4636 threshold: 123 limit: 2342 hpet: present: False .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBserials\fP \-\- .sp Dictionary providing details on the serials connection to create. (Default: \fBNone\fP) See \fI\%Serials and Consoles Definitions\fP for more details on the possible values. .sp New in version 3003. .IP \(bu 2 \fBconsoles\fP \-\- .sp Dictionary providing details on the consoles device to create. (Default: \fBNone\fP) See \fI\%Serials and Consoles Definitions\fP for more details on the possible values. .sp New in version 3003. .IP \(bu 2 \fBhost_devices\fP \-\- .sp List of host devices to passthrough to the guest. The value is a list of device names as provided by the \fI\%node_devices()\fP function. (Default: \fBNone\fP) .sp New in version 3003. .UNINDENT .UNINDENT .sp cpu parameters definition .sp The cpu parameters dictionary can contain the following properties: .INDENT 7.0 .TP .B cpuset a comma\-separated list of physical CPU numbers that domain process and virtual CPUs can be pinned to by default. eg. \fB1\-4,^3\fP cpuset 3 is excluded. .TP .B current the number of virtual cpus available at startup .TP .B placement indicate the CPU placement mode for domain process. the value can be either \fBstatic\fP or \fBauto\fP .TP .B vcpus specify the state of individual vcpu. Possible attribute for each individual vcpu include: \fBid\fP, \fBenabled\fP, \fBhotpluggable\fP and \fBorder\fP\&. Valid \fBids\fP are from 0 to the maximum vCPU count minus 1. \fBenabled\fP takes boolean values which controls the state of the vcpu. \fBhotpluggable\fP take boolean value which controls whether given vCPU can be hotplugged and hotunplugged. \fBorder\fP takes an integer value which specifies the order to add the online vCPUs. .TP .B match The cpu attribute \fBmatch\fP attribute specifies how strictly the virtual CPU provided to the guest matches the CPU requirements, possible values are \fBminimum\fP, \fBexact\fP or \fBstrict\fP\&. .TP .B check Optional cpu attribute \fBcheck\fP attribute can be used to request a specific way of checking whether the virtual CPU matches the specification, possible values are \fBnone\fP, \fBpartial\fP and \fBfull\fP\&. .TP .B mode Optional cpu attribute \fBmode\fP attribute may be used to make it easier to configure a guest CPU to be as close to host CPU as possible, possible values are \fBcustom\fP, \fBhost\-model\fP and \fBhost\-passthrough\fP\&. .TP .B model specifies CPU model requested by the guest. An optional \fBfallback\fP attribute can be used to forbid libvirt falls back to the closest model supported by the hypervisor, possible values are \fBallow\fP or \fBforbid\fP\&. \fBvendor_id\fP attribute can be used to set the vendor id seen by the guest, the length must be exactly 12 characters long. .TP .B vendor specifies CPU vendor requested by the guest. .TP .B topology specifies requested topology of virtual CPU provided to the guest. Four possible attributes , \fBsockets\fP, \fBdies\fP, \fBcores\fP, and \fBthreads\fP, accept non\-zero positive integer values. They refer to the number of CPU sockets per NUMA node, number of dies per socket, number of cores per die, and number of threads per core, respectively. .TP .B features A dictionary contains a set of cpu features to fine\-tune features provided by the selected CPU model. Use cpu feature \fBname\fP as the key and the \fBpolicy\fP as the value. \fBpolicy\fP Attribute takes \fBforce\fP, \fBrequire\fP, \fBoptional\fP, \fBdisable\fP or \fBforbid\fP\&. .TP .B cache describes the virtual CPU cache. Optional attribute \fBlevel\fP takes an integer value which describes cache level \fBmode\fP attribute supported three possible values: \fBemulate\fP, \fBpassthrough\fP, \fBdisable\fP .TP .B numa specify the guest numa topology. \fBcell\fP element specifies a NUMA cell or a NUMA node, \fBcpus\fP specifies the CPU or range of CPUs that are part of the node, \fBmemory\fP specifies the size of the node memory. All cells should have \fBid\fP attribute in case referring to some cell is necessary in the code. optional attribute \fBmemAccess\fP control whether the memory is to be mapped as \fBshared\fP or \fBprivate\fP, \fBdiscard\fP attribute which fine tunes the discard feature for given numa node, possible values are \fBTrue\fP or \fBFalse\fP\&. \fBdistances\fP element define the distance between NUMA cells and \fBsibling\fP sub\-element is used to specify the distance value between sibling NUMA cells. .TP .B vcpupin The optional vcpupin element specifies which of host\(aqs physical CPUs the domain vCPU will be pinned to. .TP .B emulatorpin The optional emulatorpin element specifies which of host physical CPUs the \(dqemulator\(dq, a subset of a domain not including vCPU or iothreads will be pinned to. .TP .B iothreadpin The optional iothreadpin element specifies which of host physical CPUs the IOThreads will be pinned to. .TP .B shares The optional shares element specifies the proportional weighted share for the domain. .TP .B period The optional period element specifies the enforcement interval (unit: microseconds). .TP .B quota The optional quota element specifies the maximum allowed bandwidth (unit: microseconds). .TP .B global_period The optional global_period element specifies the enforcement CFS scheduler interval (unit: microseconds) for the whole domain in contrast with period which enforces the interval per vCPU. .TP .B global_quota The optional global_quota element specifies the maximum allowed bandwidth (unit: microseconds) within a period for the whole domain. .TP .B emulator_period The optional emulator_period element specifies the enforcement interval (unit: microseconds). .TP .B emulator_quota The optional emulator_quota element specifies the maximum allowed bandwidth (unit: microseconds) for domain\(aqs emulator threads (those excluding vCPUs). .TP .B iothread_period The optional iothread_period element specifies the enforcement interval (unit: microseconds) for IOThreads. .TP .B iothread_quota The optional iothread_quota element specifies the maximum allowed bandwidth (unit: microseconds) for IOThreads. .TP .B vcpusched specify the scheduler type for vCPUs. The value is a list of dictionaries with the \fBscheduler\fP key (values \fBbatch\fP, \fBidle\fP, \fBfifo\fP, \fBrr\fP) and the optional \fBpriority\fP and \fBvcpus\fP keys. The \fBpriority\fP value usually is a positive integer and the \fBvcpus\fP value is a cpu set like \fB1\-4,^3,6\fP or simply the vcpu id. .TP .B iothreadsched specify the scheduler type for IO threads. The value is a list of dictionaries with the \fBscheduler\fP key (values \fBbatch\fP, \fBidle\fP, \fBfifo\fP, \fBrr\fP) and the optional \fBpriority\fP and \fBvcpus\fP keys. The \fBpriority\fP value usually is a positive integer and the \fBvcpus\fP value is a cpu set like \fB1\-4,^3,6\fP or simply the vcpu id. .TP .B emulatorsched specify the scheduler type (values batch, idle, fifo, rr) for particular the emulator. The value is a dictionary with the \fBscheduler\fP key (values \fBbatch\fP, \fBidle\fP, \fBfifo\fP, \fBrr\fP) and the optional \fBpriority\fP and \fBvcpus\fP keys. The \fBpriority\fP value usually is a positive integer. .TP .B cachetune Optional cachetune element can control allocations for CPU caches using the resctrl on the host. .TP .B monitor The optional element monitor creates the cache monitor(s) for current cache allocation. .TP .B memorytune Optional memorytune element can control allocations for memory bandwidth using the resctrl on the host. .TP .B iothreads Number of threads for supported disk devices to perform I/O requests. iothread id will be numbered from 1 to the provided number (Default: None). .UNINDENT .sp Boot parameters definition .sp The boot parameters dictionary can contains the following properties: .INDENT 7.0 .TP .B kernel The URL or path to the kernel to run the virtual machine with. .TP .B initrd The URL or path to the initrd file to run the virtual machine with. .TP .B cmdline The parameters to pass to the kernel provided in the \fIkernel\fP property. .TP .B loader The path to the UEFI binary loader to use. .sp New in version 3001. .TP .B nvram The path to the UEFI data template. The file will be copied when creating the virtual machine. .sp New in version 3001. .TP .B efi A boolean value. .sp New in version 3001. .UNINDENT .sp Memory parameter definition .sp Memory parameter can contain the following properties: .INDENT 7.0 .TP .B boot The maximum allocation of memory for the guest at boot time .TP .B current The actual allocation of memory for the guest .TP .B max The run time maximum memory allocation of the guest .TP .B slots specifies the number of slots available for adding memory to the guest .TP .B hard_limit the maximum memory the guest can use .TP .B soft_limit memory limit to enforce during memory contention .TP .B swap_hard_limit the maximum memory plus swap the guest can use .TP .B min_guarantee the guaranteed minimum memory allocation for the guest .TP .B hugepages memory allocated using \fBhugepages\fP instead of the normal native page size. It takes a list of dictionaries with \fBnodeset\fP and \fBsize\fP keys. For example \fB\(dqhugepages\(dq: [{\(dqnodeset\(dq: \(dq1\-4,^3\(dq, \(dqsize\(dq: \(dq2m\(dq}, {\(dqnodeset\(dq: \(dq3\(dq, \(dqsize\(dq: \(dq1g\(dq}]\fP\&. .TP .B nosharepages boolean value to instruct hypervisor to disable shared pages (memory merge, KSM) for this domain .TP .B locked boolean value that allows memory pages belonging to the domain will be locked in host\(aqs memory and the host will not be allowed to swap them out, which might be required for some workloads such as real\-time. .TP .B source possible values are \fBfile\fP which utilizes file memorybacking, \fBanonymous\fP by default and \fBmemfd\fP backing. (QEMU/KVM only) .TP .B access specify if the memory is to be \fBshared\fP or \fBprivate\fP\&. This can be overridden per numa node by memAccess. .TP .B allocation specify when to allocate the memory by supplying either \fBimmediate\fP or \fBondemand\fP\&. .TP .B discard boolean value to ensure the memory content is discarded just before guest shuts down (or when DIMM module is unplugged). Please note that this is just an optimization and is not guaranteed to work in all cases (e.g. when hypervisor crashes). (QEMU/KVM only) .UNINDENT .sp Network Interfaces Definitions .sp Network interfaces dictionaries can contain the following properties: .INDENT 7.0 .TP .B name Name of the network interface. This is only used as a key to merge with the profile data .TP .B type Network type. One of \fB\(aqbridge\(aq\fP, \fB\(aqnetwork\(aq\fP .TP .B source The network source, typically the bridge or network name .TP .B mac The desired mac address, computed if \fBNone\fP (Default: \fBNone\fP). .TP .B model The network card model (Default: depends on the hypervisor) .UNINDENT .sp Disks Definitions .sp Disk dictionaries can contain the following properties: .INDENT 7.0 .TP .B name Name of the disk. This is mostly used in the name of the disk image and as a key to merge with the profile data. .TP .B format Format of the disk image, like \fB\(aqqcow2\(aq\fP, \fB\(aqraw\(aq\fP, \fB\(aqvmdk\(aq\fP\&. (Default: depends on the hypervisor) .TP .B size Disk size in MiB .TP .B pool Path to the folder or name of the pool where disks should be created. (Default: depends on hypervisor and the virt:storagepool configuration) .sp Changed in version 3001. .sp If the value contains no \(aq/\(aq, it is considered a pool name where to create a volume. Using volumes will be mandatory for some pools types like rdb, iscsi, etc. .TP .B model One of the disk busses allowed by libvirt (Default: depends on hypervisor) .sp See the libvirt \fI\%disk element\fP documentation for the allowed bus types. .TP .B image Path to the image to use for the disk. If no image is provided, an empty disk will be created (Default: \fBNone\fP) .sp Note that some pool types do not support uploading an image. This list can evolve with libvirt versions. .TP .B overlay_image \fBTrue\fP to create a QCOW2 disk image with \fBimage\fP as backing file. If \fBFalse\fP the file pointed to by the \fBimage\fP property will simply be copied. (Default: \fBFalse\fP) .sp Changed in version 3001. .sp This property is only valid on path\-based disks, not on volumes. To create a volume with a backing store, set the \fBbacking_store_path\fP and \fBbacking_store_format\fP properties. .TP .B backing_store_path Path to the backing store image to use. This can also be the name of a volume to use as backing store within the same pool. .sp New in version 3001. .TP .B backing_store_format Image format of the disk or volume to use as backing store. This property is mandatory when using \fBbacking_store_path\fP to avoid \fI\%problems\fP .sp New in version 3001. .TP .B source_file Absolute path to the disk image to use. Not to be confused with \fBimage\fP parameter. This parameter is useful to use disk images that are created outside of this module. Can also be \fBNone\fP for devices that have no associated image like cdroms. .sp Changed in version 3001. .sp For volume disks, this can be the name of a volume already existing in the storage pool. .TP .B device Type of device of the disk. Can be one of \(aqdisk\(aq, \(aqcdrom\(aq, \(aqfloppy\(aq or \(aqlun\(aq. (Default: \fB\(aqdisk\(aq\fP) .TP .B hostname_property When using ZFS volumes, setting this value to a ZFS property ID will make Salt store the name of the virtual machine inside this property. (Default: \fBNone\fP) .TP .B sparse_volume Boolean to specify whether to use a thin provisioned ZFS volume. .sp Example profile for a bhyve VM with two ZFS disks. The first is cloned from the specified image. The second disk is a thin provisioned volume. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C virt: disk: two_zvols: \- system: image: zroot/bhyve/CentOS\-7\-x86_64\-v1@v1.0.5 hostname_property: virt:hostname pool: zroot/bhyve/guests \- data: pool: tank/disks size: 20G hostname_property: virt:hostname sparse_volume: True .ft P .fi .UNINDENT .UNINDENT .TP .B io I/O control policy. String value amongst \fBnative\fP, \fBthreads\fP and \fBio_uring\fP\&. (Default: \fBnative\fP) .sp New in version 3003. .TP .B iothread_id I/O thread id to assign the disk to. (Default: none assigned) .sp New in version 3003. .UNINDENT .sp Graphics Definition .sp The graphics dictionary can have the following properties: .INDENT 7.0 .TP .B type Graphics type. The possible values are \fBnone\fP, \fB\(aqspice\(aq\fP, \fB\(aqvnc\(aq\fP and other values allowed as a libvirt graphics type (Default: \fBNone\fP) .sp See the libvirt \fI\%graphics element\fP documentation for more details on the possible types. .TP .B port Port to export the graphics on for \fBvnc\fP, \fBspice\fP and \fBrdp\fP types. .TP .B tls_port Port to export the graphics over a secured connection for \fBspice\fP type. .TP .B listen Dictionary defining on what address to listen on for \fBvnc\fP, \fBspice\fP and \fBrdp\fP\&. It has a \fBtype\fP property with \fBaddress\fP and \fBNone\fP as possible values, and an \fBaddress\fP property holding the IP or hostname to listen on. .sp By default, not setting the \fBlisten\fP part of the dictionary will default to listen on all addresses. .UNINDENT .sp Serials and Consoles Definitions .sp Serial dictionaries can contain the following properties: .INDENT 7.0 .TP .B type Type of the serial connection, like \fB\(aqtcp\(aq\fP, \fB\(aqpty\(aq\fP, \fB\(aqfile\(aq\fP, \fB\(aqudp\(aq\fP, \fB\(aqdev\(aq\fP, \fB\(aqpipe\(aq\fP, \fB\(aqunix\(aq\fP\&. .TP .B path Path to the source device. Can be a log file, a host character device to pass through, a unix socket, a named pipe path. .TP .B host The serial UDP or TCP host name. (Default: 23023) .TP .B port The serial UDP or TCP port number. (Default: 23023) .TP .B protocol Name of the TCP connection protocol. (Default: telnet) .TP .B tls Boolean value indicating whether to use hypervisor TLS certificates environment for TCP devices. .TP .B target_port The guest device port number starting from 0 .TP .B target_type The guest device type. Common values are \fBserial\fP, \fBvirtio\fP or \fBusb\-serial\fP, but more are documented in \fI\%the libvirt documentation\fP\&. .UNINDENT .sp CLI Example .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqhypervisor\(aq virt.init vm_name 4 512 salt://path/to/image.raw salt \(aqhypervisor\(aq virt.init vm_name 4 512 /var/lib/libvirt/images/img.raw salt \(aqhypervisor\(aq virt.init vm_name 4 512 nic=profile disk=profile .ft P .fi .UNINDENT .UNINDENT .sp The disk images will be created in an image folder within the directory defined by the \fBvirt:images\fP option. Its default value is \fB/srv/salt\-images/\fP but this can changed with such a configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C virt: images: /data/my/vm/images/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.is_hyper() Returns a bool whether or not this node is a hypervisor of any kind .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.is_hyper .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.list_active_vms(**kwargs) Return a list of names for active virtual machine on the minion .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.list_active_vms .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.list_domains(**kwargs) Return a list of available domains. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.list_domains .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.list_inactive_vms(**kwargs) Return a list of names for inactive virtual machine on the minion .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.list_inactive_vms .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.list_networks(**kwargs) List all virtual networks. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.list_networks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.list_pools(**kwargs) List all storage pools. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.list_pools .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.list_snapshots(domain=None, **kwargs) List available snapshots for certain vm or for all. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.list_snapshots salt \(aq*\(aq virt.list_snapshots <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.migrate(vm_, target, **kwargs) Shared storage migration .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBtarget\fP \-\- target libvirt URI or host name .IP \(bu 2 \fBkwargs\fP \-\- .INDENT 2.0 .IP \(bu 2 live: Use live migration. Default value is True. .IP \(bu 2 .INDENT 2.0 .TP .B persistent: Leave the domain persistent on destination host. Default value is True. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B undefinesource: Undefine the domain on the source host. Default value is True. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B offline: If set to True it will migrate the domain definition without starting the domain on destination and without stopping it on source host. Default value is False. .UNINDENT .IP \(bu 2 max_bandwidth: The maximum bandwidth (in MiB/s) that will be used. .IP \(bu 2 .INDENT 2.0 .TP .B max_downtime: Set maximum tolerable downtime for live\-migration. The value represents a number of milliseconds the guest is allowed to be down at the end of live migration. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B parallel_connections: Specify a number of parallel network connections to be used to send memory pages to the destination host. .UNINDENT .IP \(bu 2 compressed: Activate compression. .IP \(bu 2 .INDENT 2.0 .TP .B comp_methods: A comma\-separated list of compression methods. Supported methods are \(dqmt\(dq and \(dqxbzrle\(dq and can be used in any combination. QEMU defaults to \(dqxbzrle\(dq. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B comp_mt_level: Set compression level. Values are in range from 0 to 9, where 1 is maximum speed and 9 is maximum compression. .UNINDENT .IP \(bu 2 comp_mt_threads: Set number of compress threads on source host. .IP \(bu 2 comp_mt_dthreads: Set number of decompress threads on target host. .IP \(bu 2 comp_xbzrle_cache: Set the size of page cache for xbzrle compression in bytes. .IP \(bu 2 .INDENT 2.0 .TP .B copy_storage: Migrate non\-shared storage. It must be one of the following values: all (full disk copy) or incremental (Incremental copy) .UNINDENT .IP \(bu 2 postcopy: Enable the use of post\-copy migration. .IP \(bu 2 postcopy_bandwidth: The maximum bandwidth allowed in post\-copy phase. (MiB/s) .IP \(bu 2 username: Username to connect with target host .IP \(bu 2 password: Password to connect with target host .UNINDENT .sp New in version 3002. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.migrate <domain> <target hypervisor URI> salt src virt.migrate guest qemu+ssh://dst/system salt src virt.migrate guest qemu+tls://dst/system salt src virt.migrate guest qemu+tcp://dst/system .ft P .fi .UNINDENT .UNINDENT .sp A tunnel data migration can be performed by setting this in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C virt: tunnel: True .ft P .fi .UNINDENT .UNINDENT .sp For more details on tunnelled data migrations, report to \fI\%https://libvirt.org/migration.html#transporttunnel\fP .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.migrate_start_postcopy(vm_) Starts post\-copy migration. This function has to be called while live migration is in progress and it has been initiated with the \fIpostcopy=True\fP option. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.migrate_start_postcopy <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.nesthash(value=None) create default dict that allows arbitrary level of nesting .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.network_define(name, bridge, forward, ipv4_config=None, ipv6_config=None, vport=None, tag=None, autostart=True, start=True, mtu=None, domain=None, nat=None, interfaces=None, addresses=None, physical_function=None, dns=None, **kwargs) Create libvirt network. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Network name. .IP \(bu 2 \fBbridge\fP \-\- Bridge name. .IP \(bu 2 \fBforward\fP \-\- .sp Forward mode (bridge, router, nat). .sp Changed in version 3003: a \fBNone\fP value creates an isolated network with no forwarding at all .IP \(bu 2 \fBvport\fP \-\- .sp Virtualport type. The value can also be a dictionary with \fBtype\fP and \fBparameters\fP keys. The \fBparameters\fP value is a dictionary of virtual port parameters. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- vport: type: openvswitch parameters: interfaceid: 09b11c53\-8b5c\-4eeb\-8f00\-d84eaa0aaa4f .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3003: possible dictionary value .IP \(bu 2 \fBtag\fP \-\- .sp Vlan tag. The value can also be a dictionary with the \fBtags\fP and optional \fBtrunk\fP keys. \fBtrunk\fP is a boolean value indicating whether to use VLAN trunking. \fBtags\fP is a list of dictionaries with keys \fBid\fP and \fBnativeMode\fP\&. The \fBnativeMode\fP value can be one of \fBtagged\fP or \fBuntagged\fP\&. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- tag: trunk: True tags: \- id: 42 nativeMode: untagged \- id: 47 .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3003: possible dictionary value .IP \(bu 2 \fBautostart\fP \-\- Network autostart (default True). .IP \(bu 2 \fBstart\fP \-\- Network start (default True). .IP \(bu 2 \fBipv4_config\fP (\fI\%dict\fP\fI or \fP\fINone\fP) \-\- .sp IP v4 configuration. Dictionary describing the IP v4 setup like IP range and a possible DHCP configuration. The structure is documented in \fI\%net\-define\-ip\fP\&. .sp New in version 3000. .IP \(bu 2 \fBipv6_config\fP (\fI\%dict\fP\fI or \fP\fINone\fP) \-\- .sp IP v6 configuration. Dictionary describing the IP v6 setup like IP range and a possible DHCP configuration. The structure is documented in \fI\%net\-define\-ip\fP\&. .sp New in version 3000. .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults. .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults. .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults. .IP \(bu 2 \fBmtu\fP \-\- .sp size of the Maximum Transmission Unit (MTU) of the network. (default \fBNone\fP) .sp New in version 3003. .IP \(bu 2 \fBdomain\fP \-\- .sp DNS domain name of the DHCP server. The value is a dictionary with a mandatory \fBname\fP property and an optional \fBlocalOnly\fP boolean one. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- domain: name: lab.acme.org localOnly: True .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBnat\fP \-\- .sp addresses and ports to route in NAT forward mode. The value is a dictionary with optional keys \fBaddress\fP and \fBport\fP\&. Both values are a dictionary with \fBstart\fP and \fBend\fP values. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: nat \- nat: address: start: 1.2.3.4 end: 1.2.3.10 port: start: 500 end: 1000 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBinterfaces\fP \-\- .sp whitespace separated list of network interfaces devices that can be used for this network. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: passthrough \- interfaces: \(dqeth10 eth11 eth12\(dq .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBaddresses\fP \-\- .sp whitespace separated list of addresses of PCI devices that can be used for this network in \fIhostdev\fP forward mode. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: hostdev \- interfaces: \(dq0000:04:00.1 0000:e3:01.2\(dq .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBphysical_function\fP \-\- .sp device name of the physical interface to use in \fBhostdev\fP forward mode. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: hostdev \- physical_function: \(dqeth0\(dq .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBdns\fP \-\- .sp virtual network DNS configuration. The value is a dictionary described in \fI\%net\-define\-dns\fP\&. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- dns: forwarders: \- domain: example.com addr: 192.168.1.1 \- addr: 8.8.8.8 \- domain: www.example.com txt: example.com: \(dqv=spf1 a \-all\(dq _http.tcp.example.com: \(dqname=value,paper=A4\(dq hosts: 192.168.1.2: \- mirror.acme.lab \- test.acme.lab srvs: \- name: ldap protocol: tcp domain: ldapserver.example.com target: . port: 389 priority: 1 weight: 10 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .UNINDENT .UNINDENT .sp IP configuration definition .sp Both the IPv4 and IPv6 configuration dictionaries can contain the following properties: .INDENT 7.0 .TP .B cidr CIDR notation for the network. For example \(aq192.168.124.0/24\(aq .TP .B dhcp_ranges A list of dictionaries with \fB\(aqstart\(aq\fP and \fB\(aqend\(aq\fP properties. .TP .B hosts A list of dictionaries with \fBip\fP property and optional \fBname\fP, \fBmac\fP and \fBid\fP properties. .sp New in version 3003. .TP .B bootp A dictionary with a \fBfile\fP property and an optional \fBserver\fP one. .sp New in version 3003. .TP .B tftp The path to the TFTP root directory to serve. .sp New in version 3003. .UNINDENT .sp DNS configuration definition .sp The DNS configuration dictionary contains the following optional properties: .INDENT 7.0 .TP .B forwarders List of alternate DNS forwarders to use. Each item is a dictionary with the optional \fBdomain\fP and \fBaddr\fP keys. If both are provided, the requests to the domain are forwarded to the server at the \fBaddr\fP\&. If only \fBdomain\fP is provided the requests matching this domain will be resolved locally. If only \fBaddr\fP is provided all requests will be forwarded to this DNS server. .TP .B txt: Dictionary of TXT fields to set. .TP .B hosts: Dictionary of host DNS entries. The key is the IP of the host, and the value is a list of hostnames for it. .TP .B srvs: List of SRV DNS entries. Each entry is a dictionary with the mandatory \fBname\fP and \fBprotocol\fP keys. Entries can also have \fBtarget\fP, \fBport\fP, \fBpriority\fP, \fBdomain\fP and \fBweight\fP optional properties. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.network_define network main bridge openvswitch .ft P .fi .UNINDENT .UNINDENT .sp New in version 2019.2.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.network_get_xml(name, **kwargs) Return the XML definition of a virtual network .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- libvirt network name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 3000. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.network_get_xml default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.network_info(name=None, **kwargs) Return information on a virtual network provided its name. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- virtual network name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp If no name is provided, return the infos for all defined virtual networks. .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.network_info default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.network_set_autostart(name, state=\(aqon\(aq, **kwargs) Set the autostart flag on a virtual network so that the network will start with the host system on reboot. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- virtual network name .IP \(bu 2 \fBstate\fP \-\- \(aqon\(aq to auto start the network, anything else to mark the virtual network not to be started when the host boots .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq virt.network_set_autostart <pool> <on | off> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.network_start(name, **kwargs) Start a defined virtual network. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- virtual network name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.network_start default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.network_stop(name, **kwargs) Stop a defined virtual network. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- virtual network name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.network_stop default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.network_undefine(name, **kwargs) Remove a defined virtual network. This does not stop the virtual network. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- virtual network name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.network_undefine default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.network_update(name, bridge, forward, ipv4_config=None, ipv6_config=None, vport=None, tag=None, mtu=None, domain=None, nat=None, interfaces=None, addresses=None, physical_function=None, dns=None, test=False, **kwargs) Update a virtual network if needed. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Network name. .IP \(bu 2 \fBbridge\fP \-\- Bridge name. .IP \(bu 2 \fBforward\fP \-\- Forward mode (bridge, router, nat). A \fBNone\fP value creates an isolated network with no forwarding at all. .IP \(bu 2 \fBvport\fP \-\- .sp Virtualport type. The value can also be a dictionary with \fBtype\fP and \fBparameters\fP keys. The \fBparameters\fP value is a dictionary of virtual port parameters. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- vport: type: openvswitch parameters: interfaceid: 09b11c53\-8b5c\-4eeb\-8f00\-d84eaa0aaa4f .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBtag\fP \-\- .sp Vlan tag. The value can also be a dictionary with the \fBtags\fP and optional \fBtrunk\fP keys. \fBtrunk\fP is a boolean value indicating whether to use VLAN trunking. \fBtags\fP is a list of dictionaries with keys \fBid\fP and \fBnativeMode\fP\&. The \fBnativeMode\fP value can be one of \fBtagged\fP or \fBuntagged\fP\&. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- tag: trunk: True tags: \- id: 42 nativeMode: untagged \- id: 47 .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBipv4_config\fP (\fI\%dict\fP\fI or \fP\fINone\fP) \-\- IP v4 configuration. Dictionary describing the IP v4 setup like IP range and a possible DHCP configuration. The structure is documented in \fI\%net\-define\-ip\fP\&. .IP \(bu 2 \fBipv6_config\fP (\fI\%dict\fP\fI or \fP\fINone\fP) \-\- IP v6 configuration. Dictionary describing the IP v6 setup like IP range and a possible DHCP configuration. The structure is documented in \fI\%net\-define\-ip\fP\&. .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults. .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults. .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults. .IP \(bu 2 \fBmtu\fP \-\- size of the Maximum Transmission Unit (MTU) of the network. (default \fBNone\fP) .IP \(bu 2 \fBdomain\fP \-\- .sp DNS domain name of the DHCP server. The value is a dictionary with a mandatory \fBname\fP property and an optional \fBlocalOnly\fP boolean one. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- domain: name: lab.acme.org localOnly: True .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBnat\fP \-\- .sp addresses and ports to route in NAT forward mode. The value is a dictionary with optional keys \fBaddress\fP and \fBport\fP\&. Both values are a dictionary with \fBstart\fP and \fBend\fP values. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: nat \- nat: address: start: 1.2.3.4 end: 1.2.3.10 port: start: 500 end: 1000 .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBinterfaces\fP \-\- .sp whitespace separated list of network interfaces devices that can be used for this network. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: passthrough \- interfaces: \(dqeth10 eth11 eth12\(dq .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBaddresses\fP \-\- .sp whitespace separated list of addresses of PCI devices that can be used for this network in \fIhostdev\fP forward mode. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: hostdev \- interfaces: \(dq0000:04:00.1 0000:e3:01.2\(dq .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBphysical_function\fP \-\- .sp device name of the physical interface to use in \fBhostdev\fP forward mode. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: hostdev \- physical_function: \(dqeth0\(dq .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBdns\fP \-\- .sp virtual network DNS configuration. The value is a dictionary described in \fI\%net\-define\-dns\fP\&. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- dns: forwarders: \- domain: example.com addr: 192.168.1.1 \- addr: 8.8.8.8 \- domain: www.example.com txt: example.com: \(dqv=spf1 a \-all\(dq _http.tcp.example.com: \(dqname=value,paper=A4\(dq hosts: 192.168.1.2: \- mirror.acme.lab \- test.acme.lab srvs: \- name: ldap protocol: tcp domain: ldapserver.example.com target: . port: 389 priority: 1 weight: 10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp New in version 3003. .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.node_devices(**kwargs) List the host available devices. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 3003. .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.node_info(**kwargs) Return a dict with information about this node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.node_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pause(vm_, **kwargs) Pause the named vm .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pause <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_build(name, **kwargs) Build a defined libvirt storage pool. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- libvirt storage pool name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_build default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_capabilities(**kwargs) Return the hypervisor connection storage pool capabilities. .sp The returned data are either directly extracted from libvirt or computed. In the latter case some pool types could be listed as supported while they are not. To distinguish between the two cases, check the value of the \fBcomputed\fP property. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 3000. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_capabilities .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_define(name, ptype, target=None, permissions=None, source_devices=None, source_dir=None, source_initiator=None, source_adapter=None, source_hosts=None, source_auth=None, source_name=None, source_format=None, transient=False, start=True, **kwargs) Create libvirt pool. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Pool name .IP \(bu 2 \fBptype\fP \-\- Pool type. See \fI\%libvirt documentation\fP for the possible values. .IP \(bu 2 \fBtarget\fP \-\- Pool full path target .IP \(bu 2 \fBpermissions\fP \-\- Permissions to set on the target folder. This is mostly used for filesystem\-based pool types. See \fI\%Permissions definition\fP for more details on this structure. .IP \(bu 2 \fBsource_devices\fP \-\- .sp List of source devices for pools backed by physical devices. (Default: \fBNone\fP) .sp Each item in the list is a dictionary with \fBpath\fP and optionally \fBpart_separator\fP keys. The path is the qualified name for iSCSI devices. .sp Report to \fI\%this libvirt page\fP for more information on the use of \fBpart_separator\fP .IP \(bu 2 \fBsource_dir\fP \-\- Path to the source directory for pools of type \fBdir\fP, \fBnetfs\fP or \fBgluster\fP\&. (Default: \fBNone\fP) .IP \(bu 2 \fBsource_initiator\fP \-\- .sp Initiator IQN for libiscsi\-direct pool types. (Default: \fBNone\fP) .sp New in version 3000. .IP \(bu 2 \fBsource_adapter\fP \-\- .sp SCSI source definition. The value is a dictionary with \fBtype\fP, \fBname\fP, \fBparent\fP, \fBmanaged\fP, \fBparent_wwnn\fP, \fBparent_wwpn\fP, \fBparent_fabric_wwn\fP, \fBwwnn\fP, \fBwwpn\fP and \fBparent_address\fP keys. .sp The \fBparent_address\fP value is a dictionary with \fBunique_id\fP and \fBaddress\fP keys. The address represents a PCI address and is itself a dictionary with \fBdomain\fP, \fBbus\fP, \fBslot\fP and \fBfunction\fP properties. Report to \fI\%this libvirt page\fP for the meaning and possible values of these properties. .IP \(bu 2 \fBsource_hosts\fP \-\- List of source for pools backed by storage from remote servers. Each item is the hostname optionally followed by the port separated by a colon. (Default: \fBNone\fP) .IP \(bu 2 \fBsource_auth\fP \-\- .sp Source authentication details. (Default: \fBNone\fP) .sp The value is a dictionary with \fBtype\fP, \fBusername\fP and \fBsecret\fP keys. The type can be one of \fBceph\fP for Ceph RBD or \fBchap\fP for iSCSI sources. .sp The \fBsecret\fP value links to a libvirt secret object. It is a dictionary with \fBtype\fP and \fBvalue\fP keys. The type value can be either \fBuuid\fP or \fBusage\fP\&. .sp Examples: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C source_auth={ \(aqtype\(aq: \(aqceph\(aq, \(aqusername\(aq: \(aqadmin\(aq, \(aqsecret\(aq: { \(aqtype\(aq: \(aquuid\(aq, \(aqvalue\(aq: \(aq2ec115d7\-3a88\-3ceb\-bc12\-0ac909a6fd87\(aq } } .ft P .fi .UNINDENT .UNINDENT .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C source_auth={ \(aqtype\(aq: \(aqchap\(aq, \(aqusername\(aq: \(aqmyname\(aq, \(aqsecret\(aq: { \(aqtype\(aq: \(aqusage\(aq, \(aqvalue\(aq: \(aqmycluster_myname\(aq } } .ft P .fi .UNINDENT .UNINDENT .sp Since 3000, instead the source authentication can only contain \fBusername\fP and \fBpassword\fP properties. In this case the libvirt secret will be defined and used. For Ceph authentications a base64 encoded key is expected. .IP \(bu 2 \fBsource_name\fP \-\- Identifier of name\-based sources. .IP \(bu 2 \fBsource_format\fP \-\- .sp String representing the source format. The possible values are depending on the source type. See \fI\%libvirt documentation\fP for the possible values. .IP \(bu 2 \fBstart\fP \-\- Pool start (default True) .IP \(bu 2 \fBtransient\fP \-\- When \fBTrue\fP, the pool will be automatically undefined after being stopped. Note that a transient pool will force \fBstart\fP to \fBTrue\fP\&. (Default: \fBFalse\fP) .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp Permissions definition .sp The permissions are described by a dictionary containing the following keys: .INDENT 7.0 .TP .B mode The octal representation of the permissions. (Default: \fI0711\fP) .TP .B owner the numeric user ID of the owner. (Default: from the parent folder) .TP .B group the numeric ID of the group. (Default: from the parent folder) .TP .B label the SELinux label. (Default: \fINone\fP) .UNINDENT .sp CLI Example: .sp Local folder pool: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_define somepool dir target=/srv/mypool permissions=\(dq{\(aqmode\(aq: \(aq0744\(aq \(aqower\(aq: 107, \(aqgroup\(aq: 107 }\(dq .ft P .fi .UNINDENT .UNINDENT .sp CIFS backed pool: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_define myshare netfs source_format=cifs source_dir=samba_share source_hosts=\(dq[\(aqexample.com\(aq]\(dq target=/mnt/cifs .ft P .fi .UNINDENT .UNINDENT .sp New in version 2019.2.0. .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_delete(name, **kwargs) Delete the resources of a defined libvirt storage pool. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- libvirt storage pool name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_delete default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_get_xml(name, **kwargs) Return the XML definition of a virtual storage pool .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- libvirt storage pool name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 3000. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_get_xml default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_info(name=None, **kwargs) Return information on a storage pool provided its name. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- libvirt storage pool name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp If no name is provided, return the infos for all defined storage pools. .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_info default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_list_volumes(name, **kwargs) List the volumes contained in a defined libvirt storage pool. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- libvirt storage pool name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq virt.pool_list_volumes <pool> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_refresh(name, **kwargs) Refresh a defined libvirt storage pool. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- libvirt storage pool name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_refresh default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_set_autostart(name, state=\(aqon\(aq, **kwargs) Set the autostart flag on a libvirt storage pool so that the storage pool will start with the host system on reboot. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- libvirt storage pool name .IP \(bu 2 \fBstate\fP \-\- \(aqon\(aq to auto start the pool, anything else to mark the pool not to be started when the host boots .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq virt.pool_set_autostart <pool> <on | off> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_start(name, **kwargs) Start a defined libvirt storage pool. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- libvirt storage pool name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_start default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_stop(name, **kwargs) Stop a defined libvirt storage pool. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- libvirt storage pool name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_stop default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_undefine(name, **kwargs) Remove a defined libvirt storage pool. The pool needs to be stopped before calling. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- libvirt storage pool name .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_undefine default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pool_update(name, ptype, target=None, permissions=None, source_devices=None, source_dir=None, source_initiator=None, source_adapter=None, source_hosts=None, source_auth=None, source_name=None, source_format=None, test=False, **kwargs) Update a libvirt storage pool if needed. If called with test=True, this is also reporting whether an update would be performed. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Pool name .IP \(bu 2 \fBptype\fP \-\- .sp Pool type. See \fI\%libvirt documentation\fP for the possible values. .IP \(bu 2 \fBtarget\fP \-\- Pool full path target .IP \(bu 2 \fBpermissions\fP \-\- Permissions to set on the target folder. This is mostly used for filesystem\-based pool types. See \fI\%Permissions definition\fP for more details on this structure. .IP \(bu 2 \fBsource_devices\fP \-\- .sp List of source devices for pools backed by physical devices. (Default: \fBNone\fP) .sp Each item in the list is a dictionary with \fBpath\fP and optionally \fBpart_separator\fP keys. The path is the qualified name for iSCSI devices. .sp Report to \fI\%this libvirt page\fP for more information on the use of \fBpart_separator\fP .IP \(bu 2 \fBsource_dir\fP \-\- Path to the source directory for pools of type \fBdir\fP, \fBnetfs\fP or \fBgluster\fP\&. (Default: \fBNone\fP) .IP \(bu 2 \fBsource_initiator\fP \-\- .sp Initiator IQN for libiscsi\-direct pool types. (Default: \fBNone\fP) .sp New in version 3000. .IP \(bu 2 \fBsource_adapter\fP \-\- .sp SCSI source definition. The value is a dictionary with \fBtype\fP, \fBname\fP, \fBparent\fP, \fBmanaged\fP, \fBparent_wwnn\fP, \fBparent_wwpn\fP, \fBparent_fabric_wwn\fP, \fBwwnn\fP, \fBwwpn\fP and \fBparent_address\fP keys. .sp The \fBparent_address\fP value is a dictionary with \fBunique_id\fP and \fBaddress\fP keys. The address represents a PCI address and is itself a dictionary with \fBdomain\fP, \fBbus\fP, \fBslot\fP and \fBfunction\fP properties. Report to \fI\%this libvirt page\fP for the meaning and possible values of these properties. .IP \(bu 2 \fBsource_hosts\fP \-\- List of source for pools backed by storage from remote servers. Each item is the hostname optionally followed by the port separated by a colon. (Default: \fBNone\fP) .IP \(bu 2 \fBsource_auth\fP \-\- .sp Source authentication details. (Default: \fBNone\fP) .sp The value is a dictionary with \fBtype\fP, \fBusername\fP and \fBsecret\fP keys. The type can be one of \fBceph\fP for Ceph RBD or \fBchap\fP for iSCSI sources. .sp The \fBsecret\fP value links to a libvirt secret object. It is a dictionary with \fBtype\fP and \fBvalue\fP keys. The type value can be either \fBuuid\fP or \fBusage\fP\&. .sp Examples: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C source_auth={ \(aqtype\(aq: \(aqceph\(aq, \(aqusername\(aq: \(aqadmin\(aq, \(aqsecret\(aq: { \(aqtype\(aq: \(aquuid\(aq, \(aquuid\(aq: \(aq2ec115d7\-3a88\-3ceb\-bc12\-0ac909a6fd87\(aq } } .ft P .fi .UNINDENT .UNINDENT .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C source_auth={ \(aqtype\(aq: \(aqchap\(aq, \(aqusername\(aq: \(aqmyname\(aq, \(aqsecret\(aq: { \(aqtype\(aq: \(aqusage\(aq, \(aquuid\(aq: \(aqmycluster_myname\(aq } } .ft P .fi .UNINDENT .UNINDENT .sp Since 3000, instead the source authentication can only contain \fBusername\fP and \fBpassword\fP properties. In this case the libvirt secret will be defined and used. For Ceph authentications a base64 encoded key is expected. .IP \(bu 2 \fBsource_name\fP \-\- Identifier of name\-based sources. .IP \(bu 2 \fBsource_format\fP \-\- .sp String representing the source format. The possible values are depending on the source type. See \fI\%libvirt documentation\fP for the possible values. .IP \(bu 2 \fBtest\fP \-\- run in dry\-run mode if set to True .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp Example: .sp Local folder pool: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_update somepool dir target=/srv/mypool permissions=\(dq{\(aqmode\(aq: \(aq0744\(aq \(aqower\(aq: 107, \(aqgroup\(aq: 107 }\(dq .ft P .fi .UNINDENT .UNINDENT .sp CIFS backed pool: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pool_update myshare netfs source_format=cifs source_dir=samba_share source_hosts=\(dq[\(aqexample.com\(aq]\(dq target=/mnt/cifs .ft P .fi .UNINDENT .UNINDENT .sp New in version 3000. .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.purge(vm_, dirs=False, removables=False, **kwargs) Recursively destroy and delete a persistent virtual machine, pass True for dir\(aqs to also delete the directories containing the virtual machine disk images \- USE WITH EXTREME CAUTION! .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBdirs\fP \-\- pass True to remove containing directories .IP \(bu 2 \fBremovables\fP \-\- .sp pass True to remove removable devices .sp New in version 2019.2.0. .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.purge <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.reboot(name, **kwargs) Reboot a domain via ACPI request .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.reboot <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.reset(vm_, **kwargs) Reset a VM by emulating the reset button on a physical machine .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.reset <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.resume(vm_, **kwargs) Resume the named vm .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.resume <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.revert_snapshot(name, vm_snapshot=None, cleanup=False, **kwargs) Revert snapshot to the previous from current (if available) or to the specific. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- domain name .IP \(bu 2 \fBvm_snapshot\fP \-\- name of the snapshot to revert .IP \(bu 2 \fBcleanup\fP \-\- Remove all newer than reverted snapshots. Values: True or False (default False). .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.revert <domain> salt \(aq*\(aq virt.revert <domain> <snapshot> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.seed_non_shared_migrate(disks, force=False) Non shared migration requires that the disks be present on the migration destination, pass the disks information via this function, to the migration destination before executing the migration. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdisks\fP \-\- the list of disk data as provided by virt.get_disks .IP \(bu 2 \fBforce\fP \-\- skip checking the compatibility of source and target disk images if True. (default: False) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.seed_non_shared_migrate <disks> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.set_autostart(vm_, state=\(aqon\(aq, **kwargs) Set the autostart flag on a VM so that the VM will start with the host system on reboot. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBstate\fP \-\- \(aqon\(aq to auto start the VM, \(aqoff\(aq to mark the VM not to be started when the host boots .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq virt.set_autostart <domain> <on | off> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.setmem(vm_, memory, config=False, **kwargs) Changes the amount of memory allocated to VM. The VM must be shutdown for this to work. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- name of the domain .IP \(bu 2 \fBmemory\fP \-\- memory amount to set in MB .IP \(bu 2 \fBconfig\fP \-\- if True then libvirt will be asked to modify the config as well .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.setmem <domain> <size> salt \(aq*\(aq virt.setmem my_domain 768 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.setvcpus(vm_, vcpus, config=False, **kwargs) Changes the amount of vcpus allocated to VM. The VM must be shutdown for this to work. .sp If config is True then we ask libvirt to modify the config as well .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- name of the domain .IP \(bu 2 \fBvcpus\fP \-\- integer representing the number of CPUs to be assigned .IP \(bu 2 \fBconfig\fP \-\- if True then libvirt will be asked to modify the config as well .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.setvcpus <domain> <amount> salt \(aq*\(aq virt.setvcpus my_domain 4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.shutdown(vm_, **kwargs) Send a soft shutdown signal to the named vm .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.shutdown <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.snapshot(domain, name=None, suffix=None, **kwargs) Create a snapshot of a VM. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain\fP \-\- domain name .IP \(bu 2 \fBname\fP \-\- Name of the snapshot. If the name is omitted, then will be used original domain name with ISO 8601 time as a suffix. .IP \(bu 2 \fBsuffix\fP \-\- Add suffix for the new name. Useful in states, where such snapshots can be distinguished from manually created. .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.snapshot <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.start(name, **kwargs) Start a defined domain .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.start <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.stop(name, **kwargs) Hard power down the virtual machine, this is equivalent to pulling the power. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.stop <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.undefine(vm_, **kwargs) Remove a defined vm, this does not purge the virtual machine image, and this only works if the vm is powered down .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.undefine <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.update(name, cpu=0, mem=0, disk_profile=None, disks=None, nic_profile=None, interfaces=None, graphics=None, live=True, boot=None, numatune=None, test=False, boot_dev=None, hypervisor_features=None, clock=None, serials=None, consoles=None, stop_on_reboot=False, host_devices=None, autostart=False, **kwargs) Update the definition of an existing domain. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Name of the domain to update .IP \(bu 2 \fBcpu\fP \-\- .sp Number of virtual CPUs to assign to the virtual machine or a dictionary with detailed information to configure cpu model and topology, numa node tuning, cpu tuning and iothreads allocation. The structure of the dictionary is documented in \fI\%cpu parameters definition\fP\&. .sp To update any cpu parameters specify the new values to the corresponding tag. To remove any element or attribute, specify \fBNone\fP object. Please note that \fBNone\fP object is mapped to \fBnull\fP in yaml, use \fBnull\fP in sls file instead. .IP \(bu 2 \fBmem\fP \-\- .sp Amount of memory to allocate to the virtual machine in MiB. Since 3002, a dictionary can be used to contain detailed configuration which support memory allocation or tuning. Supported parameters are \fBboot\fP, \fBcurrent\fP, \fBmax\fP, \fBslots\fP, \fBhard_limit\fP, \fBsoft_limit\fP, \fBswap_hard_limit\fP, \fBmin_guarantee\fP, \fBhugepages\fP , \fBnosharepages\fP, \fBlocked\fP, \fBsource\fP, \fBaccess\fP, \fBallocation\fP and \fBdiscard\fP\&. The structure of the dictionary is documented in \fI\%Memory parameter definition\fP\&. Both decimal and binary base are supported. Detail unit specification is documented in \fI\%Units specification\fP\&. Please note that the value for \fBslots\fP must be an integer. .sp To remove any parameters, pass a None object, for instance: \(aqsoft_limit\(aq: \fBNone\fP\&. Please note that \fBNone\fP is mapped to \fBnull\fP in sls file, pass \fBnull\fP in sls file instead. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- mem: hard_limit: null soft_limit: null .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3002. .IP \(bu 2 \fBdisk_profile\fP \-\- disk profile to use .IP \(bu 2 \fBdisks\fP \-\- Disk definitions as documented in the \fI\%init()\fP function. If neither the profile nor this parameter are defined, the disk devices will not be changed. However to clear disks set this parameter to empty list. .IP \(bu 2 \fBnic_profile\fP \-\- network interfaces profile to use .IP \(bu 2 \fBinterfaces\fP \-\- Network interface definitions as documented in the \fI\%init()\fP function. If neither the profile nor this parameter are defined, the interface devices will not be changed. However to clear network interfaces set this parameter to empty list. .IP \(bu 2 \fBgraphics\fP \-\- The new graphics definition as defined in \fI\%Graphics Definition\fP\&. If not set, the graphics will not be changed. To remove a graphics device, set this parameter to \fB{\(aqtype\(aq: \(aqnone\(aq}\fP\&. .IP \(bu 2 \fBlive\fP \-\- \fBFalse\fP to avoid trying to live update the definition. In such a case, the new definition is applied at the next start of the virtual machine. If \fBTrue\fP, not all aspects of the definition can be live updated, but as much as possible will be attempted. (Default: \fBTrue\fP) .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .IP \(bu 2 \fBboot\fP \-\- .sp Specifies kernel, initial ramdisk and kernel command line parameters for the virtual machine. This is an optional parameter, all of the keys are optional within the dictionary. .sp Refer to \fI\%Boot parameters definition\fP for the complete boot parameter description. .sp To update any boot parameters, specify the new path for each. To remove any boot parameters, pass \fBNone\fP object, for instance: \(aqkernel\(aq: \fBNone\fP\&. To switch back to BIOS boot, specify (\(aqloader\(aq: \fBNone\fP and \(aqnvram\(aq: \fBNone\fP) or \(aqefi\(aq: \fBFalse\fP\&. Please note that \fBNone\fP is mapped to \fBnull\fP in sls file, pass \fBnull\fP in sls file instead. .sp SLS file Example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- boot: loader: null nvram: null .ft P .fi .UNINDENT .UNINDENT .sp New in version 3000. .IP \(bu 2 \fBboot_dev\fP \-\- .sp Space separated list of devices to boot from sorted by decreasing priority. Values can be \fBhd\fP, \fBfd\fP, \fBcdrom\fP or \fBnetwork\fP\&. .sp By default, the value will \fB\(dqhd\(dq\fP\&. .sp New in version 3002. .IP \(bu 2 \fBnumatune\fP \-\- .sp The optional numatune element provides details of how to tune the performance of a NUMA host via controlling NUMA policy for domain process. The optional \fBmemory\fP element specifies how to allocate memory for the domain process on a NUMA host. \fBmemnode\fP elements can specify memory allocation policies per each guest NUMA node. The definition used in the dictionary can be found at \fI\%cpu parameters definition\fP\&. .sp To update any numatune parameters, specify the new value. To remove any \fBnumatune\fP parameters, pass a None object, for instance: \(aqnumatune\(aq: \fBNone\fP\&. Please note that \fBNone\fP is mapped to \fBnull\fP in sls file, pass \fBnull\fP in sls file instead. .sp New in version 3003. .IP \(bu 2 \fBserials\fP \-\- .sp Dictionary providing details on the serials connection to create. (Default: \fBNone\fP) See \fI\%Serials and Consoles Definitions\fP for more details on the possible values. .sp New in version 3003. .IP \(bu 2 \fBconsoles\fP \-\- .sp Dictionary providing details on the consoles device to create. (Default: \fBNone\fP) See \fI\%Serials and Consoles Definitions\fP for more details on the possible values. .sp New in version 3003. .IP \(bu 2 \fBstop_on_reboot\fP \-\- .sp If set to \fBTrue\fP the guest will stop instead of rebooting. This is specially useful when creating a virtual machine with an installation cdrom or an autoinstallation needing a special first boot configuration. Defaults to \fBFalse\fP .sp New in version 3003. .IP \(bu 2 \fBtest\fP \-\- .sp run in dry\-run mode if set to True .sp New in version 3001. .IP \(bu 2 \fBhypervisor_features\fP \-\- .sp Enable or disable hypervisor\-specific features on the virtual machine. .sp New in version 3003. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C hypervisor_features: kvm\-hint\-dedicated: True .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBclock\fP \-\- .sp Configure the guest clock. The value is a dictionary with the following keys: .INDENT 2.0 .TP .B adjustment time adjustment in seconds or \fBreset\fP .TP .B utc set to \fBFalse\fP to use the host local time as the guest clock. Defaults to \fBTrue\fP\&. .TP .B timezone synchronize the guest to the correspding timezone .TP .B timers a dictionary associating the timer name with its configuration. This configuration is a dictionary with the properties \fBtrack\fP, \fBtickpolicy\fP, \fBcatchup\fP, \fBfrequency\fP, \fBmode\fP, \fBpresent\fP, \fBslew\fP, \fBthreshold\fP and \fBlimit\fP\&. See \fI\%libvirt time keeping documentation\fP for the possible values. .UNINDENT .sp New in version 3003. .sp Set the clock to local time using an offset in seconds \&.. code\-block:: yaml .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .TP .B clock: adjustment: 3600 utc: False .UNINDENT .UNINDENT .UNINDENT .sp Set the clock to a specific time zone: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C clock: timezone: CEST .ft P .fi .UNINDENT .UNINDENT .sp Tweak guest timers: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C clock: timers: tsc: frequency: 3504000000 mode: native rtc: track: wall tickpolicy: catchup slew: 4636 threshold: 123 limit: 2342 hpet: present: False .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBhost_devices\fP \-\- .sp List of host devices to passthrough to the guest. The value is a list of device names as provided by the \fI\%node_devices()\fP function. (Default: \fBNone\fP) .sp New in version 3003. .IP \(bu 2 \fBautostart\fP \-\- If set to \fBTrue\fP the host will start the guest after boot. (Default: \fBFalse\fP) .UNINDENT .TP .B Returns Returns a dictionary indicating the status of what has been done. It is structured in the following way: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqdefinition\(aq: True, \(aqcpu\(aq: True, \(aqmem\(aq: True, \(aqdisks\(aq: {\(aqattached\(aq: [list of actually attached disks], \(aqdetached\(aq: [list of actually detached disks]}, \(aqnics\(aq: {\(aqattached\(aq: [list of actually attached nics], \(aqdetached\(aq: [list of actually detached nics]}, \(aqerrors\(aq: [\(aqerror messages for failures\(aq] } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.update domain cpu=2 mem=1024 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.virt_type() Returns the virtual machine type as a string .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.virt_type .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.vm_cputime(vm_=None, **kwargs) Return cputime used by the vms on this hyper in a list of dicts: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ \(aqyour\-vm\(aq: { \(aqcputime\(aq <int> \(aqcputime_percent\(aq <int> }, ... ] .ft P .fi .UNINDENT .UNINDENT .sp If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.vm_cputime .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.vm_diskstats(vm_=None, **kwargs) Return disk usage counters used by the vms on this hyper in a list of dicts: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ \(aqyour\-vm\(aq: { \(aqrd_req\(aq : 0, \(aqrd_bytes\(aq : 0, \(aqwr_req\(aq : 0, \(aqwr_bytes\(aq : 0, \(aqerrs\(aq : 0 }, ... ] .ft P .fi .UNINDENT .UNINDENT .sp If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.vm_blockstats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.vm_info(vm_=None, **kwargs) Return detailed information about the vms on this hyper in a list of dicts: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- name of the domain .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ \(aqyour\-vm\(aq: { \(aqcpu\(aq: <int>, \(aqmaxMem\(aq: <int>, \(aqmem\(aq: <int>, \(aqstate\(aq: \(aq<state>\(aq, \(aqcputime\(aq <int> }, ... ] .ft P .fi .UNINDENT .UNINDENT .sp If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.vm_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.vm_netstats(vm_=None, **kwargs) Return combined network counters used by the vms on this hyper in a list of dicts: .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- domain name .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ \(aqyour\-vm\(aq: { \(aqrx_bytes\(aq : 0, \(aqrx_packets\(aq : 0, \(aqrx_errs\(aq : 0, \(aqrx_drop\(aq : 0, \(aqtx_bytes\(aq : 0, \(aqtx_packets\(aq : 0, \(aqtx_errs\(aq : 0, \(aqtx_drop\(aq : 0 }, ... ] .ft P .fi .UNINDENT .UNINDENT .sp If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.vm_netstats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.vm_state(vm_=None, **kwargs) Return list of all the vms and their state. .sp If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvm\fP \-\- name of the domain .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.vm_state <domain> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.volume_define(pool, name, size, allocation=0, format=None, type=None, permissions=None, backing_store=None, nocow=False, **kwargs) Create libvirt volume. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpool\fP \-\- name of the pool to create the volume in .IP \(bu 2 \fBname\fP \-\- name of the volume to define .IP \(bu 2 \fBsize\fP \-\- capacity of the volume to define in MiB .IP \(bu 2 \fBallocation\fP \-\- allocated size of the volume in MiB. Defaults to 0. .IP \(bu 2 \fBformat\fP \-\- volume format. The allowed values are depending on the pool type. Check the virt.pool_capabilities output for the possible values and the default. .IP \(bu 2 \fBtype\fP \-\- type of the volume. One of file, block, dir, network, netdiri, ploop or None. By default, the type is guessed by libvirt from the pool type. .IP \(bu 2 \fBpermissions\fP \-\- Permissions to set on the target folder. This is mostly used for filesystem\-based pool types. See \fI\%Permissions definition\fP for more details on this structure. .IP \(bu 2 \fBbacking_store\fP \-\- .sp dictionary describing a backing file for the volume. It must contain a \fBpath\fP property pointing to the base volume and a \fBformat\fP property defining the format of the base volume. .sp The base volume format will not be guessed for security reasons and is thus mandatory. .IP \(bu 2 \fBnocow\fP \-\- disable COW for the volume. .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp CLI Example: .sp Volume on ESX: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.volume_define \(dq[local\-storage]\(dq myvm/myvm.vmdk vmdk 8192 .ft P .fi .UNINDENT .UNINDENT .sp QCow2 volume with backing file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.volume_define default myvm.qcow2 qcow2 8192 permissions=\(dq{\(aqmode\(aq: \(aq0775\(aq, \(aqowner\(aq: \(aq123\(aq, \(aqgroup\(aq: \(aq345\(aq\(dq}\(dq backing_store=\(dq{\(aqpath\(aq: \(aq/path/to/base.img\(aq, \(aqformat\(aq: \(aqraw\(aq}\(dq nocow=True .ft P .fi .UNINDENT .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.volume_delete(pool, volume, **kwargs) Delete a libvirt managed volume. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpool\fP \-\- libvirt storage pool name .IP \(bu 2 \fBvolume\fP \-\- name of the volume to delete .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 3000. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq virt.volume_delete <pool> <volume> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.volume_infos(pool=None, volume=None, **kwargs) Provide details on a storage volume. If no volume name is provided, the infos all the volumes contained in the pool are provided. If no pool is provided, the infos of the volumes of all pools are output. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpool\fP \-\- libvirt storage pool name (default: \fBNone\fP) .IP \(bu 2 \fBvolume\fP \-\- name of the volume to get infos from (default: \fBNone\fP) .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp New in version 3000. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq virt.volume_infos <pool> <volume> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.volume_upload(pool, volume, file, offset=0, length=0, sparse=False, **kwargs) Create libvirt volume. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpool\fP \-\- name of the pool to create the volume in .IP \(bu 2 \fBname\fP \-\- name of the volume to define .IP \(bu 2 \fBfile\fP \-\- the file to upload to the volume .IP \(bu 2 \fBoffset\fP \-\- where to start writing the data in the volume .IP \(bu 2 \fBlength\fP \-\- amount of bytes to transfer to the volume .IP \(bu 2 \fBsparse\fP \-\- set to True to preserve data sparsiness. .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.volume_upload default myvm.qcow2 /path/to/disk.qcow2 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3001. .UNINDENT .SS salt.modules.virtualenv .sp Create virtualenv environments. .sp New in version 0.17.0. .INDENT 0.0 .TP .B salt.modules.virtualenv_mod.create(path, venv_bin=None, system_site_packages=False, distribute=False, clear=False, python=None, extra_search_dir=None, never_download=None, prompt=None, pip=False, symlinks=None, upgrade=None, user=None, use_vt=False, saltenv=\(aqbase\(aq, **kwargs) Create a virtualenv .INDENT 7.0 .TP .B path The path to the virtualenv to be created .TP .B venv_bin The name (and optionally path) of the virtualenv command. This can also be set globally in the minion config file as \fBvirtualenv.venv_bin\fP\&. Defaults to \fBvirtualenv\fP\&. .TP .B system_site_packages False Passthrough argument given to virtualenv or pyvenv .TP .B distribute False Passthrough argument given to virtualenv .TP .B pip False Install pip after creating a virtual environment. Implies \fBdistribute=True\fP .TP .B clear False Passthrough argument given to virtualenv or pyvenv .TP .B python None (default) Passthrough argument given to virtualenv .TP .B extra_search_dir None (default) Passthrough argument given to virtualenv .TP .B never_download None (default) Passthrough argument given to virtualenv if True .TP .B prompt None (default) Passthrough argument given to virtualenv if not None .TP .B symlinks None Passthrough argument given to pyvenv if True .TP .B upgrade None Passthrough argument given to pyvenv if True .TP .B user None Set ownership for the virtualenv .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On Windows you must also pass a \fBpassword\fP parameter. Additionally, the user must have permissions to the location where the virtual environment is being created .UNINDENT .UNINDENT .TP .B runas None Set ownership for the virtualenv .sp Deprecated since version 2014.1.0: \fBuser\fP should be used instead .TP .B use_vt False Use VT terminal emulation (see output while installing) .sp New in version 2015.5.0. .TP .B saltenv \(aqbase\(aq Specify a different environment. The default environment is \fBbase\fP\&. .sp New in version 2014.1.0. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fBrunas\fP argument is deprecated as of 2014.1.0. \fBuser\fP should be used instead. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virtualenv.create /path/to/new/virtualenv Example of using \-\-always\-copy environment variable (in case your fs doesn\(aqt support symlinks). This will copy files into the virtualenv instead of symlinking them. \&.. code\-block:: yaml \- env: \- VIRTUALENV_ALWAYS_COPY: 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virtualenv_mod.get_distribution_path(venv, distribution) Return the path to a distribution installed inside a virtualenv .sp New in version 2016.3.0. .INDENT 7.0 .TP .B venv Path to the virtualenv. .TP .B distribution Name of the distribution. Note, all non\-alphanumeric characters will be converted to dashes. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virtualenv.get_distribution_path /path/to/my/venv my_distribution .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virtualenv_mod.get_resource_content(venv, package=None, resource=None) Return the content of a package resource installed inside a virtualenv .sp New in version 2015.5.0. .INDENT 7.0 .TP .B venv Path to the virtualenv .TP .B package Name of the package in which the resource resides .sp New in version 2016.3.0. .TP .B resource Name of the resource of which the content is to be returned .sp New in version 2016.3.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virtualenv.get_resource_content /path/to/my/venv my_package my/resource.xml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virtualenv_mod.get_resource_path(venv, package=None, resource=None) Return the path to a package resource installed inside a virtualenv .sp New in version 2015.5.0. .INDENT 7.0 .TP .B venv Path to the virtualenv .TP .B package Name of the package in which the resource resides .sp New in version 2016.3.0. .TP .B resource Name of the resource of which the path is to be returned .sp New in version 2016.3.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virtualenv.get_resource_path /path/to/my/venv my_package my/resource.xml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virtualenv_mod.get_site_packages(venv) Return the path to the site\-packages directory of a virtualenv .INDENT 7.0 .TP .B venv Path to the virtualenv. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virtualenv.get_site_packages /path/to/my/venv .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virtualenv_mod.virtualenv_ver(venv_bin, user=None, **kwargs) return virtualenv version if exists .UNINDENT .SS salt.modules.vmctl .sp Manage vms running on the OpenBSD VMM hypervisor using vmctl(8). .sp New in version 2019.2.0. .INDENT 0.0 .TP .B codeauthor \fBJasper Lievisse Adriaanse <jasper@openbsd.org>\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This module requires the \fIvmd\fP service to be running on the OpenBSD target machine. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vmctl.create_disk(name, size) Create a VMM disk with the specified \fIname\fP and \fIsize\fP\&. .INDENT 7.0 .TP .B size: Size in megabytes, or use a specifier such as M, G, T. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmctl.create_disk /path/to/disk.img size=10G .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vmctl.load(path) Load additional configuration from the specified file. .INDENT 7.0 .TP .B path Path to the configuration file. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmctl.load path=/etc/vm.switches.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vmctl.reload() Remove all stopped VMs and reload configuration from the default configuration file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmctl.reload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vmctl.reset(all=False, vms=False, switches=False) Reset the running state of VMM or a subsystem. .INDENT 7.0 .TP .B all: Reset the running state. .TP .B switches: Reset the configured switches. .TP .B vms: Reset and terminate all VMs. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmctl.reset all=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vmctl.start(name=None, id=None, bootpath=None, disk=None, disks=None, local_iface=False, memory=None, nics=0, switch=None) Starts a VM defined by the specified parameters. When both a name and id are provided, the id is ignored. .INDENT 7.0 .TP .B name: Name of the defined VM. .TP .B id: VM id. .TP .B bootpath: Path to a kernel or BIOS image to load. .TP .B disk: Path to a single disk to use. .TP .B disks: List of multiple disks to use. .TP .B local_iface: Whether to add a local network interface. See \(dqLOCAL INTERFACES\(dq in the vmctl(8) manual page for more information. .TP .B memory: Memory size of the VM specified in megabytes. .TP .B switch: Add a network interface that is attached to the specified virtual switch on the host. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmctl.start 2 # start VM with id 2 salt \(aq*\(aq vmctl.start name=web1 bootpath=\(aq/bsd.rd\(aq nics=2 memory=512M disk=\(aq/disk.img\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vmctl.status(name=None, id=None) List VMs running on the host, or only the VM specified by \fBid\fP\&. When both a name and id are provided, the id is ignored. .INDENT 7.0 .TP .B name: Name of the defined VM. .TP .B id: VM id. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmctl.status # to list all VMs salt \(aq*\(aq vmctl.status name=web1 # to get a single VM .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vmctl.stop(name=None, id=None) Stop (terminate) the VM identified by the given id or name. When both a name and id are provided, the id is ignored. .INDENT 7.0 .TP .B name: Name of the defined VM. .TP .B id: VM id. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vmctl.stop name=alpine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.vsphere .sp Manage VMware vCenter servers and ESXi hosts. .sp New in version 2015.8.4. .INDENT 0.0 .TP .B codeauthor Alexandru Bleotu <\fI\%alexandru.bleotu@morganstaley.com\fP> .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 pyVmomi Python Module .IP \(bu 2 ESXCLI .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.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 vSphere Execution Module was developed against. .SS vSphere Automation SDK .sp vSphere Automation SDK can be installed via pip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install \-\-upgrade pip setuptools pip install \-\-upgrade git+https://github.com/vmware/vsphere\-automation\-sdk\-python.git .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The SDK also requires OpenSSL 1.0.1+ if you want to connect to vSphere 6.5+ in order to support TLS1.1 & 1.2. .sp In order to use the tagging functions in this module, vSphere Automation SDK is necessary to install. .UNINDENT .UNINDENT .sp The module is currently in version 1.0.3 (as of 8/26/2019) .SS ESXCLI .sp Currently, about a third of the functions used in the vSphere Execution Module 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 or vCenter server by running the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C esxcli \-s <host\-location> \-u <username> \-p <password> 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Be aware that some functionality in this execution module may depend on the type of license attached to a vCenter Server or 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 About .sp This execution module was designed to be able to handle connections both to a vCenter Server, as well as to an ESXi host. It utilizes the pyVmomi Python library and the ESXCLI package to run remote execution functions against either the defined vCenter server or the ESXi host. .sp Whether or not the function runs against a vCenter Server or an ESXi host depends entirely upon the arguments passed into the function. Each function requires a \fBhost\fP location, \fBusername\fP, and \fBpassword\fP\&. If the credentials provided apply to a vCenter Server, then the function will be run against the vCenter Server. For example, when listing hosts using vCenter credentials, you\(aqll get a list of hosts associated with that vCenter Server: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt my\-minion vsphere.list_hosts <vcenter\-ip> <vcenter\-user> <vcenter\-password> my\-minion: \- esxi\-1.example.com \- esxi\-2.example.com .ft P .fi .UNINDENT .UNINDENT .sp However, some functions should be used against ESXi hosts, not vCenter Servers. Functionality such as getting a host\(aqs coredump network configuration should be performed against a host and not a vCenter server. If the authentication information you\(aqre using is against a vCenter server and not an ESXi host, you can provide the host name that is associated with the vCenter server in the command, as a list, using the \fBhost_names\fP or \fBesxi_host\fP kwarg. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt my\-minion vsphere.get_coredump_network_config <vcenter\-ip> <vcenter\-user> <vcenter\-password> esxi_hosts=\(aq[esxi\-1.example.com, esxi\-2.example.com]\(aq my\-minion: \-\-\-\-\-\-\-\-\-\- esxi\-1.example.com: \-\-\-\-\-\-\-\-\-\- Coredump Config: \-\-\-\-\-\-\-\-\-\- enabled: False esxi\-2.example.com: \-\-\-\-\-\-\-\-\-\- Coredump Config: \-\-\-\-\-\-\-\-\-\- enabled: True host_vnic: vmk0 ip: coredump\-location.example.com port: 6500 .ft P .fi .UNINDENT .UNINDENT .sp You can also use these functions against an ESXi host directly by establishing a connection to an ESXi host using the host\(aqs location, username, and password. If ESXi connection credentials are used instead of vCenter credentials, the \fBhost_names\fP and \fBesxi_hosts\fP arguments are not needed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt my\-minion vsphere.get_coredump_network_config esxi\-1.example.com root <host\-password> local: \-\-\-\-\-\-\-\-\-\- 10.4.28.150: \-\-\-\-\-\-\-\-\-\- Coredump Config: \-\-\-\-\-\-\-\-\-\- enabled: True host_vnic: vmk0 ip: coredump\-location.example.com port: 6500 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.add_capacity_to_diskgroup(cache_disk_id, capacity_disk_ids, safety_checks=True, service_instance=None) Adds capacity disks to the disk group with the specified cache disk. .INDENT 7.0 .TP .B cache_disk_id The canonical name of the cache disk. .TP .B capacity_disk_ids A list containing canonical names of the capacity disks to add. .TP .B safety_checks Specify whether to perform safety check or to skip the checks and try performing the required task. Default value is True. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.add_capacity_to_diskgroup cache_disk_id=\(aqnaa.000000000000001\(aq capacity_disk_ids=\(aq[naa.000000000000002, naa.000000000000003]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.add_host_to_dvs(host, username, password, vmknic_name, vmnic_name, dvs_name, target_portgroup_name, uplink_portgroup_name, protocol=None, port=None, host_names=None, verify_ssl=True) Adds an ESXi host to a vSphere Distributed Virtual Switch and migrates the desired adapters to the DVS from the standard switch. .INDENT 7.0 .TP .B host The location of the vCenter server. .TP .B username The username used to login to the vCenter server. .TP .B password The password used to login to the vCenter server. .TP .B vmknic_name The name of the virtual NIC to migrate. .TP .B vmnic_name The name of the physical NIC to migrate. .TP .B dvs_name The name of the Distributed Virtual Switch. .TP .B target_portgroup_name The name of the distributed portgroup in which to migrate the virtual NIC. .TP .B uplink_portgroup_name The name of the uplink portgroup in which to migrate the physical NIC. .TP .B protocol Optionally set to alternate protocol if the vCenter server or ESX/ESXi host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the vCenter server or ESX/ESXi host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names: An array of VMware host names to migrate .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt some_host vsphere.add_host_to_dvs host=\(aqvsphere.corp.com\(aq username=\(aqadministrator@vsphere.corp.com\(aq password=\(aqvsphere_password\(aq vmknic_name=\(aqvmk0\(aq vmnic_name=\(aqvnmic0\(aq dvs_name=\(aqDSwitch\(aq target_portgroup_name=\(aqDPortGroup\(aq uplink_portgroup_name=\(aqDSwitch1\-DVUplinks\-181\(aq protocol=\(aqhttps\(aq port=\(aq443\(aq, host_names=\(dq[\(aqesxi1.corp.com\(aq,\(aqesxi2.corp.com\(aq,\(aqesxi3.corp.com\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .sp Return Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C somehost: \-\-\-\-\-\-\-\-\-\- esxi1.corp.com: \-\-\-\-\-\-\-\-\-\- dvs: DSwitch portgroup: DPortGroup status: True uplink: DSwitch\-DVUplinks\-181 vmknic: vmk0 vmnic: vmnic0 esxi2.corp.com: \-\-\-\-\-\-\-\-\-\- dvs: DSwitch portgroup: DPortGroup status: True uplink: DSwitch\-DVUplinks\-181 vmknic: vmk0 vmnic: vmnic0 esxi3.corp.com: \-\-\-\-\-\-\-\-\-\- dvs: DSwitch portgroup: DPortGroup status: True uplink: DSwitch\-DVUplinks\-181 vmknic: vmk0 vmnic: vmnic0 message: success: True .ft P .fi .UNINDENT .UNINDENT .sp This was very difficult to figure out. VMware\(aqs PyVmomi documentation at .sp \fI\%https://github.com/vmware/pyvmomi/blob/master/docs/vim/DistributedVirtualSwitch.rst\fP (which is a copy of the official documentation here: \fI\%https://www.vmware.com/support/developer/converter\-sdk/conv60_apireference/vim.DistributedVirtualSwitch.html\fP) .sp says to create the DVS, create distributed portgroups, and then add the host to the DVS specifying which physical NIC to use as the port backing. However, if the physical NIC is in use as the only link from the host to vSphere, this will fail with an unhelpful \(dqbusy\(dq error. .sp There is, however, a Powershell PowerCLI cmdlet called Add\-VDSwitchPhysicalNetworkAdapter that does what we want. I used Onyx (\fI\%https://labs.vmware.com/flings/onyx\fP) to sniff the SOAP stream from Powershell to our vSphere server and got this snippet out: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C <UpdateNetworkConfig xmlns=\(dqurn:vim25\(dq> <_this type=\(dqHostNetworkSystem\(dq>networkSystem\-187</_this> <config> <vswitch> <changeOperation>edit</changeOperation> <name>vSwitch0</name> <spec> <numPorts>7812</numPorts> </spec> </vswitch> <proxySwitch> <changeOperation>edit</changeOperation> <uuid>73 a4 05 50 b0 d2 7e b9\-38 80 5d 24 65 8f da 70</uuid> <spec> <backing xsi:type=\(dqDistributedVirtualSwitchHostMemberPnicBacking\(dq> <pnicSpec><pnicDevice>vmnic0</pnicDevice></pnicSpec> </backing> </spec> </proxySwitch> <portgroup> <changeOperation>remove</changeOperation> <spec> <name>Management Network</name><vlanId>\-1</vlanId><vswitchName /><policy /> </spec> </portgroup> <vnic> <changeOperation>edit</changeOperation> <device>vmk0</device> <portgroup /> <spec> <distributedVirtualPort> <switchUuid>73 a4 05 50 b0 d2 7e b9\-38 80 5d 24 65 8f da 70</switchUuid> <portgroupKey>dvportgroup\-191</portgroupKey> </distributedVirtualPort> </spec> </vnic> </config> <changeMode>modify</changeMode> </UpdateNetworkConfig> .ft P .fi .UNINDENT .UNINDENT .sp The SOAP API maps closely to PyVmomi, so from there it was (relatively) easy to figure out what Python to write. .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.add_license(key, description, safety_checks=True, service_instance=None) Adds a license to the vCenter or ESXi host .INDENT 7.0 .TP .B key License key. .TP .B description License description added in as a label. .TP .B safety_checks Specify whether to perform safety check or to skip the checks and try performing the required task .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.add_license key=<license_key> desc=\(aqLicense desc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.assign_default_storage_policy_to_datastore(policy, datastore, service_instance=None) Assigns a storage policy as the default policy to a datastore. .INDENT 7.0 .TP .B policy Name of the policy to assign. .TP .B datastore Name of the datastore to assign. The datastore needs to be visible to the VMware entity the proxy points to. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.assign_storage_policy_to_datastore policy=\(aqpolicy name\(aq datastore=ds1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.assign_license(license_key, license_name, entity, entity_display_name, safety_checks=True, service_instance=None) Assigns a license to an entity .INDENT 7.0 .TP .B license_key Key of the license to assign See \fB_get_entity\fP docstrings for format. .TP .B license_name Display name of license .TP .B entity Dictionary representation of an entity .TP .B entity_display_name Entity name used in logging .TP .B safety_checks Specify whether to perform safety check or to skip the checks and try performing the required task. Default is False. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.assign_license license_key=AAAAA\-11111\-AAAAA\-11111\-AAAAA license_name=test entity={type:cluster,datacenter:dc,cluster:cl} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.attach_tag(object_id, tag_id, managed_obj=\(aqClusterComputeResource\(aq, server=None, username=None, password=None, service_instance=None, verify_ssl=None, ca_bundle=None) Attach an existing tag to an input object. .sp The tag needs to meet the cardinality (\fICategoryModel.cardinality\fP) and associability (\fICategoryModel.associable_types\fP) criteria in order to be eligible for attachment. If the tag is already attached to the object, then this method is a no\-op and an error will not be thrown. To invoke this method, you need the attach tag privilege on the tag and the read privilege on the object. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt vm_minion vsphere.attach_tag domain\-c2283 urn:vmomi:InventoryServiceTag:b55ecc77\-f4a5\-49f8\-ab52\-38865467cfbe:GLOBAL .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobject_id\fP (\fI\%str\fP) \-\- The identifier of the input object. .IP \(bu 2 \fBtag_id\fP (\fI\%str\fP) \-\- The identifier of the tag object. .IP \(bu 2 \fBmanaged_obj\fP (\fI\%str\fP) \-\- Classes that contain methods for creating and deleting resources typically contain a class attribute specifying the resource type for the resources being created and deleted. .IP \(bu 2 \fBserver\fP (\fIbasestring\fP) \-\- Target DNS or IP of vCenter center. .IP \(bu 2 \fBusername\fP (\fIbasestring\fP) \-\- Username associated with the vCenter center. .IP \(bu 2 \fBpassword\fP (\fIbasestring\fP) \-\- Password associated with the vCenter center. .IP \(bu 2 \fBverify_ssl\fP (\fIboolean\fP) \-\- Verify the SSL certificate. Default: True .IP \(bu 2 \fBca_bundle\fP (\fIbasestring\fP) \-\- Path to the ca bundle to use when verifying SSL certificates. .UNINDENT .TP .B Returns The list of all tag identifiers that correspond to the tags attached to the given object. .TP .B Return type \fI\%list\fP of tags .TP .B Raise Unauthorized if you do not have the privilege to read the object. .TP .B Raise Unauthenticated if the user can not be authenticated. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.compare_vm_configs(new_config, current_config) Compares virtual machine current and new configuration, the current is the one which is deployed now, and the new is the target config. Returns the differences between the objects in a dictionary, the keys are the configuration parameter keys and the values are differences objects: either list or recursive difference .INDENT 7.0 .TP .B new_config: New config dictionary with every available parameter .TP .B current_config Currently deployed configuration .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.configure_host_cache(enabled, datastore=None, swap_size_MiB=None, service_instance=None) Configures the host cache on the selected host. .INDENT 7.0 .TP .B enabled Boolean flag specifying whether the host cache is enabled. .TP .B datastore Name of the datastore that contains the host cache. Must be set if enabled is \fBtrue\fP\&. .TP .B swap_size_MiB Swap size in Mibibytes. Needs to be set if enabled is \fBtrue\fP\&. Must be smaller than the datastore size. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.configure_host_cache enabled=False salt \(aq*\(aq vsphere.configure_host_cache enabled=True datastore=ds1 swap_size_MiB=1024 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.coredump_network_enable(host, username, password, enabled, protocol=None, port=None, esxi_hosts=None, credstore=None) Enable or disable ESXi core dump collection. Returns \fBTrue\fP if coredump is enabled and returns \fBFalse\fP if core dump is not enabled. If there was an error, the error will be the value printed in the \fBError\fP key dictionary for the given host. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B enabled Python True or False to enable or disable coredumps. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B esxi_hosts If \fBhost\fP is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines. .TP .B credstore Optionally set to path to the credential store file. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for ESXi host connection information salt \(aq*\(aq vsphere.coredump_network_enable my.esxi.host root bad\-password True # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.coredump_network_enable my.vcenter.location root bad\-password True esxi_hosts=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.create_cluster(cluster_dict, datacenter=None, cluster=None, service_instance=None) Creates a cluster. .sp Note: cluster_dict[\(aqname\(aq] will be overridden by the cluster param value .INDENT 7.0 .TP .B config_dict Dictionary with the config values of the new cluster. .TP .B datacenter Name of datacenter containing the cluster. Ignored if already contained by proxy details. Default value is None. .TP .B cluster Name of cluster. Ignored if already contained by proxy details. Default value is None. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # esxdatacenter proxy salt \(aq*\(aq vsphere.create_cluster cluster_dict=$cluster_dict cluster=cl1 # esxcluster proxy salt \(aq*\(aq vsphere.create_cluster cluster_dict=$cluster_dict .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.create_datacenter(datacenter_name, service_instance=None) Creates a datacenter. .sp Supported proxies: esxdatacenter .INDENT 7.0 .TP .B datacenter_name The datacenter name .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.create_datacenter dc1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.create_diskgroup(cache_disk_id, capacity_disk_ids, safety_checks=True, service_instance=None) Creates disk group on an ESXi host with the specified cache and capacity disks. .INDENT 7.0 .TP .B cache_disk_id The canonical name of the disk to be used as a cache. The disk must be ssd. .TP .B capacity_disk_ids A list containing canonical names of the capacity disks. Must contain at least one id. Default is True. .TP .B safety_checks Specify whether to perform safety check or to skip the checks and try performing the required task. Default value is True. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.create_diskgroup cache_disk_id=\(aqnaa.000000000000001\(aq capacity_disk_ids=\(aq[naa.000000000000002, naa.000000000000003]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.create_dvportgroup(portgroup_dict, portgroup_name, dvs, service_instance=None) Creates a distributed virtual portgroup. .sp Note: The \fBportgroup_name\fP param will override any name already set in \fBportgroup_dict\fP\&. .INDENT 7.0 .TP .B portgroup_dict Dictionary with the config values the portgroup should be created with (example in salt.states.dvs). .TP .B portgroup_name Name of the portgroup to be created. .TP .B dvs Name of the DVS that will contain the portgroup. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.create_dvportgroup portgroup_dict=<dict> portgroup_name=pg1 dvs=dvs1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.create_dvs(dvs_dict, dvs_name, service_instance=None) Creates a distributed virtual switch (DVS). .sp Note: The \fBdvs_name\fP param will override any name set in \fBdvs_dict\fP\&. .INDENT 7.0 .TP .B dvs_dict Dict representation of the new DVS (example in salt.states.dvs) .TP .B dvs_name Name of the DVS to be created. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.create_dvs dvs dict=$dvs_dict dvs_name=dvs_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.create_storage_policy(policy_name, policy_dict, service_instance=None) Creates a storage policy. .sp Supported capability types: scalar, set, range. .INDENT 7.0 .TP .B policy_name Name of the policy to create. The value of the argument will override any existing name in \fBpolicy_dict\fP\&. .TP .B policy_dict Dictionary containing the changes to apply to the policy. (example in salt.states.pbm) .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.create_storage_policy policy_name=\(aqpolicy name\(aq policy_dict=\(dq$policy_dict\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.create_tag(name, description, category_id, server=None, username=None, password=None, service_instance=None, verify_ssl=None, ca_bundle=None) Create a tag under a category with given description. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt vm_minion vsphere.create_tag .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBserver\fP (\fIbasestring\fP) \-\- Target DNS or IP of vCenter client. .IP \(bu 2 \fBusername\fP (\fIbasestring\fP) \-\- Username associated with the vCenter client. .IP \(bu 2 \fBpassword\fP (\fIbasestring\fP) \-\- Password associated with the vCenter client. .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name of tag category to create (ex. Machine, OS, Availability, etc.) .IP \(bu 2 \fBdescription\fP (\fI\%str\fP) \-\- Given description of tag category. .IP \(bu 2 \fBcategory_id\fP (\fI\%str\fP) \-\- Value of category_id representative of the category created previously. .IP \(bu 2 \fBverify_ssl\fP (\fIboolean\fP) \-\- Verify the SSL certificate. Default: True .IP \(bu 2 \fBca_bundle\fP (\fIbasestring\fP) \-\- Path to the ca bundle to use when verifying SSL certificates. .UNINDENT .TP .B Returns The identifier of the created tag. .TP .B Return type \fI\%str\fP .TP .B Raise AlreadyExists if the name provided in the create_spec is the name of an already existing tag in the input category. .TP .B Raise InvalidArgument if any of the input information in the create_spec is invalid. .TP .B Raise NotFound if the category for in the given create_spec does not exist in the system. .TP .B Raise Unauthorized if you do not have the privilege to create tag. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.create_tag_category(name, description, cardinality, server=None, username=None, password=None, service_instance=None, verify_ssl=None, ca_bundle=None) Create a category with given cardinality. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt vm_minion vsphere.create_tag_category .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name of tag category to create (ex. Machine, OS, Availability, etc.) .IP \(bu 2 \fBdescription\fP (\fI\%str\fP) \-\- Given description of tag category. .IP \(bu 2 \fBcardinality\fP (\fI\%str\fP) \-\- The associated cardinality (SINGLE, MULTIPLE) of the category. .IP \(bu 2 \fBserver\fP (\fIbasestring\fP) \-\- Target DNS or IP of vCenter center. .IP \(bu 2 \fBusername\fP (\fIbasestring\fP) \-\- Username associated with the vCenter center. .IP \(bu 2 \fBpassword\fP (\fIbasestring\fP) \-\- Password associated with the vCenter center. .IP \(bu 2 \fBverify_ssl\fP (\fIboolean\fP) \-\- Verify the SSL certificate. Default: True .IP \(bu 2 \fBca_bundle\fP (\fIbasestring\fP) \-\- Path to the ca bundle to use when verifying SSL certificates. .UNINDENT .TP .B Returns Identifier of the created category. .TP .B Return type \fI\%str\fP .TP .B Raise AlreadyExists if the name\(ga provided in the create_spec is the name of an already existing category. .TP .B Raise InvalidArgument if any of the information in the create_spec is invalid. .TP .B Raise Unauthorized if you do not have the privilege to create a category. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.create_vm(vm_name, cpu, memory, image, version, datacenter, datastore, placement, interfaces, disks, scsi_devices, serial_ports=None, ide_controllers=None, sata_controllers=None, cd_drives=None, advanced_configs=None, service_instance=None) Creates a virtual machine container. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt vm_minion vsphere.create_vm vm_name=vmname cpu=\(aq{count: 2, nested: True}\(aq ... .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B vm_name Name of the virtual machine .TP .B cpu Properties of CPUs for freshly created machines .TP .B memory Memory size for freshly created machines .TP .B image Virtual machine guest OS version identifier VirtualMachineGuestOsIdentifier .TP .B version Virtual machine container hardware version .TP .B datacenter Datacenter where the virtual machine will be deployed (mandatory) .TP .B datastore Datastore where the virtual machine files will be placed .TP .B placement Resource pool or cluster or host or folder where the virtual machine will be deployed .TP .B devices interfaces .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C interfaces: adapter: \(aqNetwork adapter 1\(aq name: vlan100 switch_type: distributed or standard adapter_type: vmxnet3 or vmxnet, vmxnet2, vmxnet3, e1000, e1000e mac: \(aq00:11:22:33:44:55\(aq connectable: allow_guest_control: True connected: True start_connected: True .ft P .fi .UNINDENT .UNINDENT .sp disks .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C disks: adapter: \(aqHard disk 1\(aq size: 16 unit: GB address: \(aq0:0\(aq controller: \(aqSCSI controller 0\(aq thin_provision: False eagerly_scrub: False datastore: \(aqmyshare\(aq filename: \(aqvm/mydisk.vmdk\(aq .ft P .fi .UNINDENT .UNINDENT .sp scsi_devices .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C scsi_devices: controller: \(aqSCSI controller 0\(aq type: paravirtual bus_sharing: no_sharing .ft P .fi .UNINDENT .UNINDENT .sp serial_ports .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C serial_ports: adapter: \(aqSerial port 1\(aq type: network backing: uri: \(aqtelnet://something:port\(aq direction: <client|server> filename: \(aqservice_uri\(aq connectable: allow_guest_control: True connected: True start_connected: True yield: False .ft P .fi .UNINDENT .UNINDENT .sp cd_drives .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cd_drives: adapter: \(aqCD/DVD drive 0\(aq controller: \(aqIDE 0\(aq device_type: datastore_iso_file datastore_iso_file: path: path_to_iso connectable: allow_guest_control: True connected: True start_connected: True .ft P .fi .UNINDENT .UNINDENT .TP .B advanced_config Advanced config parameters to be set for the virtual machine .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.create_vmfs_datastore(datastore_name, disk_id, vmfs_major_version, safety_checks=True, service_instance=None) Creates a ESXi host disk group with the specified cache and capacity disks. .INDENT 7.0 .TP .B datastore_name The name of the datastore to be created. .TP .B disk_id The disk id (canonical name) on which the datastore is created. .TP .B vmfs_major_version The VMFS major version. .TP .B safety_checks Specify whether to perform safety check or to skip the checks and try performing the required task. Default is True. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.create_vmfs_datastore datastore_name=ds1 disk_id= vmfs_major_version=5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.delete_advanced_configs(vm_name, datacenter, advanced_configs, service_instance=None) Removes extra config parameters from a virtual machine .INDENT 7.0 .TP .B vm_name Virtual machine name .TP .B datacenter Datacenter name where the virtual machine is available .TP .B advanced_configs List of advanced config values to be removed .TP .B service_instance vCenter service instance for connection and configuration .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.delete_tag(tag_id, server=None, username=None, password=None, service_instance=None, verify_ssl=None, ca_bundle=None) Delete a tag. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt vm_minion vsphere.delete_tag .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtag_id\fP (\fI\%str\fP) \-\- The identifier of tag to be deleted. The parameter must be an identifier for the resource type: \fBcom.vmware.cis.tagging.Tag\fP\&. .IP \(bu 2 \fBserver\fP (\fIbasestring\fP) \-\- Target DNS or IP of vCenter center. .IP \(bu 2 \fBusername\fP (\fIbasestring\fP) \-\- Username associated with the vCenter center. .IP \(bu 2 \fBpassword\fP (\fIbasestring\fP) \-\- Password associated with the vCenter center. .IP \(bu 2 \fBverify_ssl\fP (\fIboolean\fP) \-\- Verify the SSL certificate. Default: True .IP \(bu 2 \fBca_bundle\fP (\fIbasestring\fP) \-\- Path to the ca bundle to use when verifying SSL certificates. .UNINDENT .TP .B Raise AlreadyExists if the name provided in the create_spec is the name of an already existing category. .TP .B Raise InvalidArgument if any of the information in the create_spec is invalid. .TP .B Raise Unauthorized if you do not have the privilege to create a category. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.delete_tag_category(category_id, server=None, username=None, password=None, service_instance=None, verify_ssl=None, ca_bundle=None) Delete a category. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt vm_minion vsphere.delete_tag_category .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcategory_id\fP (\fI\%str\fP) \-\- The identifier of category to be deleted. The parameter must be an identifier for the resource type: \fBcom.vmware.cis.tagging.Category\fP\&. .IP \(bu 2 \fBserver\fP (\fIbasestring\fP) \-\- Target DNS or IP of vCenter center. .IP \(bu 2 \fBusername\fP (\fIbasestring\fP) \-\- Username associated with the vCenter center. .IP \(bu 2 \fBpassword\fP (\fIbasestring\fP) \-\- Password associated with the vCenter center. .IP \(bu 2 \fBverify_ssl\fP (\fIboolean\fP) \-\- Verify the SSL certificate. Default: True .IP \(bu 2 \fBca_bundle\fP (\fIbasestring\fP) \-\- Path to the ca bundle to use when verifying SSL certificates. .UNINDENT .TP .B Raise NotFound if the tag for the given tag_id does not exist in the system. .TP .B Raise Unauthorized if you do not have the privilege to delete the tag. .TP .B Raise Unauthenticated if the user can not be authenticated. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.delete_vm(name, datacenter, placement=None, power_off=False, service_instance=None) Deletes a virtual machine defined by name and placement .INDENT 7.0 .TP .B name Name of the virtual machine .TP .B datacenter Datacenter of the virtual machine .TP .B placement Placement information of the virtual machine .TP .B service_instance vCenter service instance for connection and configuration .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.delete_vm name=my_vm datacenter=my_datacenter .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.disconnect(service_instance) Disconnects from a vCenter or ESXi host .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Should be used by state functions, not invoked directly. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B service_instance Service instance (vim.ServiceInstance) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 See note above. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.enable_firewall_ruleset(host, username, password, ruleset_enable, ruleset_name, protocol=None, port=None, esxi_hosts=None, credstore=None) Enable or disable an ESXi firewall rule set. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B ruleset_enable True to enable the ruleset, false to disable. .TP .B ruleset_name Name of ruleset to target. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B esxi_hosts If \fBhost\fP is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines. .TP .B credstore Optionally set to path to the credential store file. .UNINDENT .INDENT 7.0 .TP .B Returns A standard cmd.run_all dictionary, per host. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for ESXi host connection information salt \(aq*\(aq vsphere.enable_firewall_ruleset my.esxi.host root bad\-password True \(aqsyslog\(aq # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.enable_firewall_ruleset my.vcenter.location root bad\-password True \(aqsyslog\(aq esxi_hosts=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.erase_disk_partitions(disk_id=None, scsi_address=None, service_instance=None) Erases the partitions on a disk. The disk can be specified either by the canonical name, or by the scsi_address. .INDENT 7.0 .TP .B disk_id Canonical name of the disk. Either \fBdisk_id\fP or \fBscsi_address\fP needs to be specified (\fBdisk_id\fP supersedes \fBscsi_address\fP\&. .TP .B scsi_address Scsi address of the disk. \fBdisk_id\fP or \fBscsi_address\fP needs to be specified (\fBdisk_id\fP supersedes \fBscsi_address\fP\&. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.erase_disk_partitions scsi_address=\(aqvmhaba0:C0:T0:L0\(aq salt \(aq*\(aq vsphere.erase_disk_partitions disk_id=\(aqnaa.000000000000001\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.esxcli_cmd(cmd_str, host=None, username=None, password=None, protocol=None, port=None, esxi_hosts=None, credstore=None) Run an ESXCLI command directly on the host or list of hosts. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B cmd_str The ESXCLI command to run. Note: This should not include the \fB\-s\fP, \fB\-u\fP, \fB\-p\fP, \fB\-h\fP, \fB\-\-protocol\fP, or \fB\-\-portnumber\fP arguments that are frequently passed when using a bare ESXCLI command from the command line. Those arguments are handled by this function via the other args and kwargs. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B esxi_hosts If \fBhost\fP is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines. .TP .B credstore Optionally set to path to the credential store file. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for ESXi host connection information salt \(aq*\(aq vsphere.esxcli_cmd my.esxi.host root bad\-password \(aqsystem coredump network get\(aq # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.esxcli_cmd my.vcenter.location root bad\-password \(aqsystem coredump network get\(aq esxi_hosts=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_advanced_configs(vm_name, datacenter, service_instance=None) Returns extra config parameters from a virtual machine advanced config list .INDENT 7.0 .TP .B vm_name Virtual machine name .TP .B datacenter Datacenter name where the virtual machine is available .TP .B service_instance vCenter service instance for connection and configuration .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_coredump_network_config(host, username, password, protocol=None, port=None, esxi_hosts=None, credstore=None) Retrieve information on ESXi or vCenter network dump collection and format it into a dictionary. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B esxi_hosts If \fBhost\fP is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines. .TP .B credstore Optionally set to path to the credential store file. .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary with the network configuration, or, if getting the network config failed, a an error message retrieved from the standard cmd.run_all dictionary, per host. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for ESXi host connection information salt \(aq*\(aq vsphere.get_coredump_network_config my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.get_coredump_network_config my.vcenter.location root bad\-password esxi_hosts=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_firewall_status(host, username, password, protocol=None, port=None, esxi_hosts=None, credstore=None) Show status of all firewall rule sets. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B esxi_hosts If \fBhost\fP is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines. .TP .B credstore Optionally set to path to the credential store file. .UNINDENT .INDENT 7.0 .TP .B Returns Nested dictionary with two toplevel keys \fBrulesets\fP and \fBsuccess\fP \fBsuccess\fP will be True or False depending on query success \fBrulesets\fP will list the rulesets and their statuses if \fBsuccess\fP was true, per host. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for ESXi host connection information salt \(aq*\(aq vsphere.get_firewall_status my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.get_firewall_status my.vcenter.location root bad\-password esxi_hosts=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_host_cache(service_instance=None) Returns the host cache configuration on the proxy host. .INDENT 7.0 .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.get_host_cache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_host_datetime(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Get the date/time information for a given host or list of host_names. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to get date/time information. .sp If host_names is not provided, the date/time information will be retrieved for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.get_host_datetime my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.get_host_datetime my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_ntp_config(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Get the NTP configuration information for a given host or list of host_names. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to get ntp configuration information. .sp If host_names is not provided, the NTP configuration will be retrieved for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.get_ntp_config my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.get_ntp_config my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_proxy_type() Returns the proxy type retrieved either from the pillar of from the proxy minion\(aqs config. Returns \fB<undefined>\fP otherwise. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.get_proxy_type .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_service_instance_via_proxy(service_instance=None) Returns a service instance to the proxied endpoint (vCenter/ESXi host). .INDENT 7.0 .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Should be used by state functions not invoked directly. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 See note above .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_service_policy(host, username, password, service_name, protocol=None, port=None, host_names=None, verify_ssl=True) Get the service name\(aqs policy for a given host or list of hosts. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B service_name .INDENT 7.0 .TP .B The name of the service for which to retrieve the policy. Supported service names are: .INDENT 7.0 .IP \(bu 2 DCUI .IP \(bu 2 TSM .IP \(bu 2 SSH .IP \(bu 2 lbtd .IP \(bu 2 lsassd .IP \(bu 2 lwiod .IP \(bu 2 netlogond .IP \(bu 2 ntpd .IP \(bu 2 sfcbd\-watchdog .IP \(bu 2 snmpd .IP \(bu 2 vprobed .IP \(bu 2 vpxa .IP \(bu 2 xorg .UNINDENT .UNINDENT .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to get service policy information. .sp If host_names is not provided, the service policy information will be retrieved for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.get_service_policy my.esxi.host root bad\-password \(aqssh\(aq # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.get_service_policy my.vcenter.location root bad\-password \(aqntpd\(aq host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_service_running(host, username, password, service_name, protocol=None, port=None, host_names=None, verify_ssl=True) Get the service name\(aqs running state for a given host or list of hosts. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B service_name .INDENT 7.0 .TP .B The name of the service for which to retrieve the policy. Supported service names are: .INDENT 7.0 .IP \(bu 2 DCUI .IP \(bu 2 TSM .IP \(bu 2 SSH .IP \(bu 2 lbtd .IP \(bu 2 lsassd .IP \(bu 2 lwiod .IP \(bu 2 netlogond .IP \(bu 2 ntpd .IP \(bu 2 sfcbd\-watchdog .IP \(bu 2 snmpd .IP \(bu 2 vprobed .IP \(bu 2 vpxa .IP \(bu 2 xorg .UNINDENT .UNINDENT .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to get the service\(aqs running state. .sp If host_names is not provided, the service\(aqs running state will be retrieved for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.get_service_running my.esxi.host root bad\-password \(aqssh\(aq # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.get_service_running my.vcenter.location root bad\-password \(aqntpd\(aq host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_ssh_key(host, username, password, protocol=None, port=None, certificate_verify=None) Retrieve the authorized_keys entry for root. This function only works for ESXi, not vCenter. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhost\fP \-\- The location of the ESXi Host .IP \(bu 2 \fBusername\fP \-\- Username to connect as .IP \(bu 2 \fBpassword\fP \-\- Password for the ESXi web endpoint .IP \(bu 2 \fBprotocol\fP \-\- defaults to https, can be http if ssl is disabled on ESXi .IP \(bu 2 \fBport\fP \-\- defaults to 443 for https .IP \(bu 2 \fBcertificate_verify\fP \-\- If true require that the SSL connection present a valid certificate. Default: True .UNINDENT .TP .B Returns True if upload is successful .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.get_ssh_key my.esxi.host root bad\-password certificate_verify=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_syslog_config(host, username, password, protocol=None, port=None, esxi_hosts=None, credstore=None) Retrieve the syslog configuration. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B esxi_hosts If \fBhost\fP is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines. .TP .B credstore Optionally set to path to the credential store file. .UNINDENT .INDENT 7.0 .TP .B Returns Dictionary with keys and values corresponding to the syslog configuration, per host. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for ESXi host connection information salt \(aq*\(aq vsphere.get_syslog_config my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.get_syslog_config my.vcenter.location root bad\-password esxi_hosts=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_vm(name, datacenter=None, vm_properties=None, traversal_spec=None, parent_ref=None, service_instance=None) Returns vm object properties. .INDENT 7.0 .TP .B name Name of the virtual machine. .TP .B datacenter Datacenter name .TP .B vm_properties List of vm properties. .TP .B traversal_spec Traversal Spec object(s) for searching. .TP .B parent_ref Container Reference object for searching under a given object. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_vm_config(name, datacenter=None, objects=True, service_instance=None) Queries and converts the virtual machine properties to the available format from the schema. If the objects attribute is True the config objects will have extra properties, like \(aqobject\(aq which will include the vim.vm.device.VirtualDevice, this is necessary for deletion and update actions. .INDENT 7.0 .TP .B name Name of the virtual machine .TP .B datacenter Datacenter\(aqs name where the virtual machine is available .TP .B objects Indicates whether to return the vmware object properties (eg. object, key) or just the properties which can be set .TP .B service_instance vCenter service instance for connection and configuration .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_vm_config_file(name, datacenter, placement, datastore, service_instance=None) Queries the virtual machine config file and returns vim.host.DatastoreBrowser.SearchResults object on success None on failure .INDENT 7.0 .TP .B name Name of the virtual machine .TP .B datacenter Datacenter name .TP .B datastore Datastore where the virtual machine files are stored .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_vmotion_enabled(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Get the VMotion enabled status for a given host or a list of host_names. Returns \fBTrue\fP if VMotion is enabled, \fBFalse\fP if it is not enabled. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts to check if VMotion is enabled. .sp If host_names is not provided, the VMotion status will be retrieved for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.get_vmotion_enabled my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.get_vmotion_enabled my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_vsan_eligible_disks(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Returns a list of VSAN\-eligible disks for a given host or list of host_names. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts to check if any VSAN\-eligible disks are available. .sp If host_names is not provided, the VSAN\-eligible disks will be retrieved for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.get_vsan_eligible_disks my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.get_vsan_eligible_disks my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.get_vsan_enabled(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Get the VSAN enabled status for a given host or a list of host_names. Returns \fBTrue\fP if VSAN is enabled, \fBFalse\fP if it is not enabled, and \fBNone\fP if a VSAN Host Config is unset, per host. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts to check if VSAN enabled. .sp If host_names is not provided, the VSAN status will be retrieved for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.get_vsan_enabled my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.get_vsan_enabled my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_assigned_licenses(entity, entity_display_name, license_keys=None, service_instance=None) Lists the licenses assigned to an entity .INDENT 7.0 .TP .B entity Dictionary representation of an entity. See \fB_get_entity\fP docstrings for format. .TP .B entity_display_name Entity name used in logging .TP .B license_keys: List of license keys to be retrieved. Default is None. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_assigned_licenses entity={type:cluster,datacenter:dc,cluster:cl} entiy_display_name=cl .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_attached_tags(object_id, managed_obj=\(aqClusterComputeResource\(aq, server=None, username=None, password=None, service_instance=None, verify_ssl=None, ca_bundle=None) List existing tags a user has access to. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt vm_minion vsphere.list_attached_tags domain\-c2283 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobject_id\fP (\fI\%str\fP) \-\- The identifier of the input object. .IP \(bu 2 \fBmanaged_obj\fP (\fI\%str\fP) \-\- Classes that contain methods for creating and deleting resources typically contain a class attribute specifying the resource type for the resources being created and deleted. .IP \(bu 2 \fBserver\fP (\fIbasestring\fP) \-\- Target DNS or IP of vCenter center. .IP \(bu 2 \fBusername\fP (\fIbasestring\fP) \-\- Username associated with the vCenter center. .IP \(bu 2 \fBpassword\fP (\fIbasestring\fP) \-\- Password associated with the vCenter center. .IP \(bu 2 \fBverify_ssl\fP (\fIboolean\fP) \-\- Verify the SSL certificate. Default: True .IP \(bu 2 \fBca_bundle\fP (\fIbasestring\fP) \-\- Path to the ca bundle to use when verifying SSL certificates. .UNINDENT .TP .B Returns The list of all tag identifiers that correspond to the tags attached to the given object. .TP .B Return type \fI\%list\fP of tags .TP .B Raise Unauthorized if you do not have the privilege to read the object. .TP .B Raise Unauthenticated if the user can not be authenticated. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_capability_definitions(service_instance=None) Returns a list of the metadata of all capabilities in the vCenter. .INDENT 7.0 .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_capabilities .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_cluster(datacenter=None, cluster=None, service_instance=None) Returns a dict representation of an ESX cluster. .INDENT 7.0 .TP .B datacenter Name of datacenter containing the cluster. Ignored if already contained by proxy details. Default value is None. .TP .B cluster Name of cluster. Ignored if already contained by proxy details. Default value is None. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # vcenter proxy salt \(aq*\(aq vsphere.list_cluster datacenter=dc1 cluster=cl1 # esxdatacenter proxy salt \(aq*\(aq vsphere.list_cluster cluster=cl1 # esxcluster proxy salt \(aq*\(aq vsphere.list_cluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_clusters(host, username, password, protocol=None, port=None, verify_ssl=True) Returns a list of clusters for the specified host. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_clusters 1.2.3.4 root bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_datacenters(host, username, password, protocol=None, port=None, verify_ssl=True) Returns a list of datacenters for the specified host. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_datacenters 1.2.3.4 root bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_datacenters_via_proxy(datacenter_names=None, service_instance=None) Returns a list of dict representations of VMware datacenters. Connection is done via the proxy details. .sp Supported proxies: esxdatacenter .INDENT 7.0 .TP .B datacenter_names List of datacenter names. Default is None. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_datacenters_via_proxy salt \(aq*\(aq vsphere.list_datacenters_via_proxy dc1 salt \(aq*\(aq vsphere.list_datacenters_via_proxy dc1,dc2 salt \(aq*\(aq vsphere.list_datacenters_via_proxy datacenter_names=[dc1, dc2] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_datastore_clusters(host, username, password, protocol=None, port=None, verify_ssl=True) Returns a list of datastore clusters for the specified host. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_datastore_clusters 1.2.3.4 root bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_datastores(host, username, password, protocol=None, port=None, verify_ssl=True) Returns a list of datastores for the specified host. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_datastores 1.2.3.4 root bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_datastores_via_proxy(datastore_names=None, backing_disk_ids=None, backing_disk_scsi_addresses=None, service_instance=None) Returns a list of dict representations of the datastores visible to the proxy object. The list of datastores can be filtered by datastore names, backing disk ids (canonical names) or backing disk scsi addresses. .sp Supported proxy types: esxi, esxcluster, esxdatacenter .INDENT 7.0 .TP .B datastore_names List of the names of datastores to filter on .TP .B backing_disk_ids List of canonical names of the backing disks of the datastores to filer. Default is None. .TP .B backing_disk_scsi_addresses List of scsi addresses of the backing disks of the datastores to filter. Default is None. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_datastores_via_proxy salt \(aq*\(aq vsphere.list_datastores_via_proxy datastore_names=[ds1, ds2] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_default_storage_policy_of_datastore(datastore, service_instance=None) Returns a list of datastores assign the storage policies. .INDENT 7.0 .TP .B datastore Name of the datastore to assign. The datastore needs to be visible to the VMware entity the proxy points to. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_default_storage_policy_of_datastore datastore=ds1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_default_vsan_policy(service_instance=None) Returns the default vsan storage policy. .INDENT 7.0 .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_default_vsan_policy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_disk_partitions(disk_id=None, scsi_address=None, service_instance=None) Lists the partitions on a disk. The disk can be specified either by the canonical name, or by the scsi_address. .INDENT 7.0 .TP .B disk_id Canonical name of the disk. Either \fBdisk_id\fP or \fBscsi_address\fP needs to be specified (\fBdisk_id\fP supersedes \fBscsi_address\fP\&. .TP .B scsi_address\(ga Scsi address of the disk. \fBdisk_id\fP or \fBscsi_address\fP needs to be specified (\fBdisk_id\fP supersedes \fBscsi_address\fP\&. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_disk_partitions scsi_address=\(aqvmhaba0:C0:T0:L0\(aq salt \(aq*\(aq vsphere.list_disk_partitions disk_id=\(aqnaa.000000000000001\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_diskgroups(cache_disk_ids=None, service_instance=None) Returns a list of disk group dict representation on an ESXi host. The list of disk groups can be filtered by the cache disks canonical names. If no filtering is applied, all disk groups are returned. .INDENT 7.0 .TP .B cache_disk_ids: List of cache disk canonical names of the disk groups to be retrieved. Default is None. .TP .B use_proxy_details Specify whether to use the proxy minion\(aqs details instead of the arguments .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_diskgroups salt \(aq*\(aq vsphere.list_diskgroups cache_disk_ids=\(aq[naa.000000000000001]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_disks(disk_ids=None, scsi_addresses=None, service_instance=None) Returns a list of dict representations of the disks in an ESXi host. The list of disks can be filtered by disk canonical names or scsi addresses. .INDENT 7.0 .TP .B disk_ids: List of disk canonical names to be retrieved. Default is None. .TP .B scsi_addresses List of scsi addresses of disks to be retrieved. Default is None .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_disks salt \(aq*\(aq vsphere.list_disks disk_ids=\(aq[naa.00, naa.001]\(aq salt \(aq*\(aq vsphere.list_disks scsi_addresses=\(aq[vmhba0:C0:T0:L0, vmhba1:C0:T0:L0]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_dvportgroups(dvs=None, portgroup_names=None, service_instance=None) Returns a list of distributed virtual switch portgroups. The list can be filtered by the portgroup names or by the DVS. .INDENT 7.0 .TP .B dvs Name of the DVS containing the portgroups. Default value is None. .TP .B portgroup_names List of portgroup names to look for. If None, all portgroups are returned. Default value is None .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_dvportgroups salt \(aq*\(aq vsphere.list_dvportgroups dvs=dvs1 salt \(aq*\(aq vsphere.list_dvportgroups portgroup_names=[pg1] salt \(aq*\(aq vsphere.list_dvportgroups dvs=dvs1 portgroup_names=[pg1] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_dvs(host, username, password, protocol=None, port=None, verify_ssl=True) Returns a list of distributed virtual switches for the specified host. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_dvs 1.2.3.4 root bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_dvss(datacenter=None, dvs_names=None, service_instance=None) Returns a list of distributed virtual switches (DVSs). The list can be filtered by the datacenter or DVS names. .INDENT 7.0 .TP .B datacenter The datacenter to look for DVSs in. Default value is None. .TP .B dvs_names List of DVS names to look for. If None, all DVSs are returned. Default value is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_dvss salt \(aq*\(aq vsphere.list_dvss dvs_names=[dvs1,dvs2] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_folders(host, username, password, protocol=None, port=None, verify_ssl=True) Returns a list of folders for the specified host. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_folders 1.2.3.4 root bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_hosts(host, username, password, protocol=None, port=None, verify_ssl=True) Returns a list of hosts for the specified VMware environment. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_hosts 1.2.3.4 root bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_hosts_via_proxy(hostnames=None, datacenter=None, cluster=None, service_instance=None) Returns a list of hosts for the specified VMware environment. The list of hosts can be filtered by datacenter name and/or cluster name .INDENT 7.0 .TP .B hostnames Hostnames to filter on. .TP .B datacenter_name Name of datacenter. Only hosts in this datacenter will be retrieved. Default is None. .TP .B cluster_name Name of cluster. Only hosts in this cluster will be retrieved. If a datacenter is not specified the first cluster with this name will be considerred. Default is None. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_hosts_via_proxy salt \(aq*\(aq vsphere.list_hosts_via_proxy hostnames=[esxi1.example.com] salt \(aq*\(aq vsphere.list_hosts_via_proxy datacenter=dc1 cluster=cluster1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_licenses(service_instance=None) Lists all licenses on a vCenter. .INDENT 7.0 .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_licenses .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_networks(host, username, password, protocol=None, port=None, verify_ssl=True) Returns a list of networks for the specified host. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_networks 1.2.3.4 root bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_non_ssds(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Returns a list of Non\-SSD disks for the given host or list of host_names. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 In the pyVmomi StorageSystem, ScsiDisks may, or may not have an \fBssd\fP attribute. This attribute indicates if the ScsiDisk is SSD backed. As this option is optional, if a relevant disk in the StorageSystem does not have \fBssd = true\fP, it will end up in the \fBnon_ssds\fP list here. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to retrieve Non\-SSD disks. .sp If host_names is not provided, Non\-SSD disks will be retrieved for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.list_non_ssds my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.list_non_ssds my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_resourcepools(host, username, password, protocol=None, port=None, verify_ssl=True) Returns a list of resource pools for the specified host. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_resourcepools 1.2.3.4 root bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_ssds(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Returns a list of SSDs for the given host or list of host_names. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to retrieve SSDs. .sp If host_names is not provided, SSDs will be retrieved for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.list_ssds my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.list_ssds my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_storage_policies(policy_names=None, service_instance=None) Returns a list of storage policies. .INDENT 7.0 .TP .B policy_names Names of policies to list. If None, all policies are listed. Default is None. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_storage_policies salt \(aq*\(aq vsphere.list_storage_policies policy_names=[policy_name] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_tag_categories(server=None, username=None, password=None, service_instance=None, verify_ssl=None, ca_bundle=None) List existing categories a user has access to. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt vm_minion vsphere.list_tag_categories .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBserver\fP (\fIbasestring\fP) \-\- Target DNS or IP of vCenter center. .IP \(bu 2 \fBusername\fP (\fIbasestring\fP) \-\- Username associated with the vCenter center. .IP \(bu 2 \fBpassword\fP (\fIbasestring\fP) \-\- Password associated with the vCenter center. .IP \(bu 2 \fBverify_ssl\fP (\fIboolean\fP) \-\- Verify the SSL certificate. Default: True .IP \(bu 2 \fBca_bundle\fP (\fIbasestring\fP) \-\- Path to the ca bundle to use when verifying SSL certificates. .UNINDENT .TP .B Returns Value(s) of category_id. .TP .B Return type \fI\%list\fP of \fI\%str\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_tags(server=None, username=None, password=None, service_instance=None, verify_ssl=None, ca_bundle=None) List existing tags a user has access to. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt vm_minion vsphere.list_tags .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBserver\fP (\fIbasestring\fP) \-\- Target DNS or IP of vCenter center. .IP \(bu 2 \fBusername\fP (\fIbasestring\fP) \-\- Username associated with the vCenter center. .IP \(bu 2 \fBpassword\fP (\fIbasestring\fP) \-\- Password associated with the vCenter center. .IP \(bu 2 \fBverify_ssl\fP (\fIboolean\fP) \-\- Verify the SSL certificate. Default: True .IP \(bu 2 \fBca_bundle\fP (\fIbasestring\fP) \-\- Path to the ca bundle to use when verifying SSL certificates. .UNINDENT .TP .B Returns Value(s) of tag_id. .TP .B Return type \fI\%list\fP of \fI\%str\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_uplink_dvportgroup(dvs, service_instance=None) Returns the uplink portgroup of a distributed virtual switch. .INDENT 7.0 .TP .B dvs Name of the DVS containing the portgroup. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_uplink_dvportgroup dvs=dvs_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_vapps(host, username, password, protocol=None, port=None, verify_ssl=True) Returns a list of vApps for the specified host. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # List vapps from all minions salt \(aq*\(aq vsphere.list_vapps 1.2.3.4 root bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.list_vms(host, username, password, protocol=None, port=None, verify_ssl=True) Returns a list of VMs for the specified host. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.list_vms 1.2.3.4 root bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.power_off_vm(name, datacenter=None, service_instance=None) Powers off a virtual machine specified by its name. .INDENT 7.0 .TP .B name Name of the virtual machine .TP .B datacenter Datacenter of the virtual machine .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.power_off_vm name=my_vm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.power_on_vm(name, datacenter=None, service_instance=None) Powers on a virtual machine specified by its name. .INDENT 7.0 .TP .B name Name of the virtual machine .TP .B datacenter Datacenter of the virtual machine .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.power_on_vm name=my_vm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.register_vm(name, datacenter, placement, vmx_path, service_instance=None) Registers a virtual machine to the inventory with the given vmx file. Returns comments and change list .INDENT 7.0 .TP .B name Name of the virtual machine .TP .B datacenter Datacenter of the virtual machine .TP .B placement Placement dictionary of the virtual machine, host or cluster .TP .B vmx_path: Full path to the vmx file, datastore name should be included .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.remove_capacity_from_diskgroup(cache_disk_id, capacity_disk_ids, data_evacuation=True, safety_checks=True, service_instance=None) Remove capacity disks from the disk group with the specified cache disk. .INDENT 7.0 .TP .B cache_disk_id The canonical name of the cache disk. .TP .B capacity_disk_ids A list containing canonical names of the capacity disks to add. .TP .B data_evacuation Specifies whether to gracefully evacuate the data on the capacity disks before removing them from the disk group. Default value is True. .TP .B safety_checks Specify whether to perform safety check or to skip the checks and try performing the required task. Default value is True. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.remove_capacity_from_diskgroup cache_disk_id=\(aqnaa.000000000000001\(aq capacity_disk_ids=\(aq[naa.000000000000002, naa.000000000000003]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.remove_datastore(datastore, service_instance=None) Removes a datastore. If multiple datastores an error is raised. .INDENT 7.0 .TP .B datastore Datastore name .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.remove_datastore ds_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.remove_diskgroup(cache_disk_id, data_accessibility=True, service_instance=None) Remove the diskgroup with the specified cache disk. .INDENT 7.0 .TP .B cache_disk_id The canonical name of the cache disk. .TP .B data_accessibility Specifies whether to ensure data accessibility. Default value is True. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.remove_diskgroup cache_disk_id=\(aqnaa.000000000000001\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.remove_dvportgroup(portgroup, dvs, service_instance=None) Removes a distributed virtual portgroup. .INDENT 7.0 .TP .B portgroup Name of the portgroup to be removed. .TP .B dvs Name of the DVS containing the portgroups. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.remove_dvportgroup portgroup=pg1 dvs=dvs1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.rename_datastore(datastore_name, new_datastore_name, service_instance=None) Renames a datastore. The datastore needs to be visible to the proxy. .INDENT 7.0 .TP .B datastore_name Current datastore name. .TP .B new_datastore_name New datastore name. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.rename_datastore old_name new_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.reset_syslog_config(host, username, password, protocol=None, port=None, syslog_config=None, esxi_hosts=None, credstore=None) Reset the syslog service to its default settings. .sp Valid syslog_config values are \fBlogdir\fP, \fBloghost\fP, \fBlogdir\-unique\fP, \fBdefault\-rotate\fP, \fBdefault\-size\fP, \fBdefault\-timeout\fP, or \fBall\fP for all of these. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B syslog_config List of parameters to reset, provided as a comma\-delimited string, or \(aqall\(aq to reset all syslog configuration parameters. Required. .TP .B esxi_hosts If \fBhost\fP is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines. .TP .B credstore Optionally set to path to the credential store file. .UNINDENT .INDENT 7.0 .TP .B Returns Dictionary with a top\-level key of \(aqsuccess\(aq which indicates if all the parameters were reset, and individual keys for each parameter indicating which succeeded or failed, per host. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBsyslog_config\fP can be passed as a quoted, comma\-separated string. See CLI Example for details. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for ESXi host connection information salt \(aq*\(aq vsphere.reset_syslog_config my.esxi.host root bad\-password syslog_config=\(aqlogdir,loghost\(aq # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.reset_syslog_config my.vcenter.location root bad\-password syslog_config=\(aqlogdir,loghost\(aq esxi_hosts=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.service_restart(host, username, password, service_name, protocol=None, port=None, host_names=None, verify_ssl=True) Restart the named service for the given host or list of hosts. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B service_name .INDENT 7.0 .TP .B The name of the service for which to set the policy. Supported service names are: .INDENT 7.0 .IP \(bu 2 DCUI .IP \(bu 2 TSM .IP \(bu 2 SSH .IP \(bu 2 lbtd .IP \(bu 2 lsassd .IP \(bu 2 lwiod .IP \(bu 2 netlogond .IP \(bu 2 ntpd .IP \(bu 2 sfcbd\-watchdog .IP \(bu 2 snmpd .IP \(bu 2 vprobed .IP \(bu 2 vpxa .IP \(bu 2 xorg .UNINDENT .UNINDENT .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to restart the service. .sp If host_names is not provided, the service will be restarted for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.service_restart my.esxi.host root bad\-password \(aqntpd\(aq # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.service_restart my.vcenter.location root bad\-password \(aqntpd\(aq host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.service_start(host, username, password, service_name, protocol=None, port=None, host_names=None, verify_ssl=True) Start the named service for the given host or list of hosts. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B service_name .INDENT 7.0 .TP .B The name of the service for which to set the policy. Supported service names are: .INDENT 7.0 .IP \(bu 2 DCUI .IP \(bu 2 TSM .IP \(bu 2 SSH .IP \(bu 2 lbtd .IP \(bu 2 lsassd .IP \(bu 2 lwiod .IP \(bu 2 netlogond .IP \(bu 2 ntpd .IP \(bu 2 sfcbd\-watchdog .IP \(bu 2 snmpd .IP \(bu 2 vprobed .IP \(bu 2 vpxa .IP \(bu 2 xorg .UNINDENT .UNINDENT .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to start the service. .sp If host_names is not provided, the service will be started for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.service_start my.esxi.host root bad\-password \(aqntpd\(aq # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.service_start my.vcenter.location root bad\-password \(aqntpd\(aq host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.service_stop(host, username, password, service_name, protocol=None, port=None, host_names=None, verify_ssl=True) Stop the named service for the given host or list of hosts. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B service_name .INDENT 7.0 .TP .B The name of the service for which to set the policy. Supported service names are: .INDENT 7.0 .IP \(bu 2 DCUI .IP \(bu 2 TSM .IP \(bu 2 SSH .IP \(bu 2 lbtd .IP \(bu 2 lsassd .IP \(bu 2 lwiod .IP \(bu 2 netlogond .IP \(bu 2 ntpd .IP \(bu 2 sfcbd\-watchdog .IP \(bu 2 snmpd .IP \(bu 2 vprobed .IP \(bu 2 vpxa .IP \(bu 2 xorg .UNINDENT .UNINDENT .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to stop the service. .sp If host_names is not provided, the service will be stopped for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.service_stop my.esxi.host root bad\-password \(aqssh\(aq # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.service_stop my.vcenter.location root bad\-password \(aqssh\(aq host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.set_advanced_configs(vm_name, datacenter, advanced_configs, service_instance=None) Appends extra config parameters to a virtual machine advanced config list .INDENT 7.0 .TP .B vm_name Virtual machine name .TP .B datacenter Datacenter name where the virtual machine is available .TP .B advanced_configs Dictionary with advanced parameter key value pairs .TP .B service_instance vCenter service instance for connection and configuration .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.set_coredump_network_config(host, username, password, dump_ip, protocol=None, port=None, host_vnic=\(aqvmk0\(aq, dump_port=6500, esxi_hosts=None, credstore=None) Set the network parameters for a network coredump collection. Note that ESXi requires that the dumps first be enabled (see \fIcoredump_network_enable\fP) before these parameters may be set. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B dump_ip IP address of host that will accept the dump. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B esxi_hosts If \fBhost\fP is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines. .TP .B host_vnic Host VNic port through which to communicate. Defaults to \fBvmk0\fP\&. .TP .B dump_port TCP port to use for the dump, defaults to \fB6500\fP\&. .TP .B credstore Optionally set to path to the credential store file. .UNINDENT .INDENT 7.0 .TP .B Returns A standard cmd.run_all dictionary with a \fIsuccess\fP key added, per host. \fIsuccess\fP will be True if the set succeeded, False otherwise. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for ESXi host connection information salt \(aq*\(aq vsphere.set_coredump_network_config my.esxi.host root bad\-password \(aqdump_ip.host.com\(aq # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.set_coredump_network_config my.vcenter.location root bad\-password \(aqdump_ip.host.com\(aq esxi_hosts=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.set_ntp_config(host, username, password, ntp_servers, protocol=None, port=None, host_names=None, verify_ssl=True) Set NTP configuration for a given host of list of host_names. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B ntp_servers A list of servers that should be added to and configured for the specified host\(aqs NTP configuration. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts to configure ntp servers. .sp If host_names is not provided, the NTP servers will be configured for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.ntp_configure my.esxi.host root bad\-password \(aq[192.174.1.100, 192.174.1.200]\(aq # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.ntp_configure my.vcenter.location root bad\-password \(aq[192.174.1.100, 192.174.1.200]\(aq host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.set_service_policy(host, username, password, service_name, service_policy, protocol=None, port=None, host_names=None, verify_ssl=True) Set the service name\(aqs policy for a given host or list of hosts. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B service_name .INDENT 7.0 .TP .B The name of the service for which to set the policy. Supported service names are: .INDENT 7.0 .IP \(bu 2 DCUI .IP \(bu 2 TSM .IP \(bu 2 SSH .IP \(bu 2 lbtd .IP \(bu 2 lsassd .IP \(bu 2 lwiod .IP \(bu 2 netlogond .IP \(bu 2 ntpd .IP \(bu 2 sfcbd\-watchdog .IP \(bu 2 snmpd .IP \(bu 2 vprobed .IP \(bu 2 vpxa .IP \(bu 2 xorg .UNINDENT .UNINDENT .TP .B service_policy The policy to set for the service. For example, \(aqautomatic\(aq. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to set the service policy. .sp If host_names is not provided, the service policy information will be retrieved for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.set_service_policy my.esxi.host root bad\-password \(aqntpd\(aq \(aqautomatic\(aq # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.set_service_policy my.vcenter.location root bad\-password \(aqntpd\(aq \(aqautomatic\(aq host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.set_syslog_config(host, username, password, syslog_config, config_value, protocol=None, port=None, firewall=True, reset_service=True, esxi_hosts=None, credstore=None) Set the specified syslog configuration parameter. By default, this function will reset the syslog service after the configuration is set. .INDENT 7.0 .TP .B host ESXi or vCenter host to connect to. .TP .B username User to connect as, usually root. .TP .B password Password to connect with. .TP .B syslog_config Name of parameter to set (corresponds to the command line switch for esxcli without the double dashes (\-\-)) .sp Valid syslog_config values are \fBlogdir\fP, \fBloghost\fP, \fBdefault\-rotate\(ga, \(ga\(gadefault\-size\fP, \fBdefault\-timeout\fP, and \fBlogdir\-unique\fP\&. .TP .B config_value Value for the above parameter. For \fBloghost\fP, URLs or IP addresses to use for logging. Multiple log servers can be specified by listing them, comma\-separated, but without spaces before or after commas. .sp (reference: \fI\%https://blogs.vmware.com/vsphere/2012/04/configuring\-multiple\-syslog\-servers\-for\-esxi\-5.html\fP) .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B firewall Enable the firewall rule set for syslog. Defaults to \fBTrue\fP\&. .TP .B reset_service After a successful parameter set, reset the service. Defaults to \fBTrue\fP\&. .TP .B esxi_hosts If \fBhost\fP is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines. .TP .B credstore Optionally set to path to the credential store file. .UNINDENT .INDENT 7.0 .TP .B Returns Dictionary with a top\-level key of \(aqsuccess\(aq which indicates if all the parameters were reset, and individual keys for each parameter indicating which succeeded or failed, per host. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for ESXi host connection information salt \(aq*\(aq vsphere.set_syslog_config my.esxi.host root bad\-password loghost ssl://localhost:5432,tcp://10.1.0.1:1514 # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.set_syslog_config my.vcenter.location root bad\-password loghost ssl://localhost:5432,tcp://10.1.0.1:1514 esxi_hosts=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.syslog_service_reload(host, username, password, protocol=None, port=None, esxi_hosts=None, credstore=None) Reload the syslog service so it will pick up any changes. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B esxi_hosts If \fBhost\fP is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines. .TP .B credstore Optionally set to path to the credential store file. .UNINDENT .INDENT 7.0 .TP .B Returns A standard cmd.run_all dictionary. This dictionary will at least have a \fIretcode\fP key. If \fIretcode\fP is 0 the command was successful. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for ESXi host connection information salt \(aq*\(aq vsphere.syslog_service_reload my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.syslog_service_reload my.vcenter.location root bad\-password esxi_hosts=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.system_info(host, username, password, protocol=None, port=None, verify_ssl=True) Return system information about a VMware environment. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.system_info 1.2.3.4 root bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.test_vcenter_connection(service_instance=None) Checks if a connection is to a vCenter .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.test_vcenter_connection .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.unregister_vm(name, datacenter, placement=None, power_off=False, service_instance=None) Unregisters a virtual machine defined by name and placement .INDENT 7.0 .TP .B name Name of the virtual machine .TP .B datacenter Datacenter of the virtual machine .TP .B placement Placement information of the virtual machine .TP .B service_instance vCenter service instance for connection and configuration .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.unregister_vm name=my_vm datacenter=my_datacenter .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.update_cluster(cluster_dict, datacenter=None, cluster=None, service_instance=None) Updates a cluster. .INDENT 7.0 .TP .B config_dict Dictionary with the config values of the new cluster. .TP .B datacenter Name of datacenter containing the cluster. Ignored if already contained by proxy details. Default value is None. .TP .B cluster Name of cluster. Ignored if already contained by proxy details. Default value is None. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # esxdatacenter proxy salt \(aq*\(aq vsphere.update_cluster cluster_dict=$cluster_dict cluster=cl1 # esxcluster proxy salt \(aq*\(aq vsphere.update_cluster cluster_dict=$cluster_dict .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.update_dvportgroup(portgroup_dict, portgroup, dvs, service_instance=True) Updates a distributed virtual portgroup. .INDENT 7.0 .TP .B portgroup_dict Dictionary with the values the portgroup should be update with (example in salt.states.dvs). .TP .B portgroup Name of the portgroup to be updated. .TP .B dvs Name of the DVS containing the portgroups. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.update_dvportgroup portgroup_dict=<dict> portgroup=pg1 salt \(aq*\(aq vsphere.update_dvportgroup portgroup_dict=<dict> portgroup=pg1 dvs=dvs1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.update_dvs(dvs_dict, dvs, service_instance=None) Updates a distributed virtual switch (DVS). .INDENT 7.0 .TP .B Note: Updating the product info, capability, uplinks of a DVS is not supported so the corresponding entries in \fBdvs_dict\fP will be ignored. .TP .B dvs_dict Dictionary with the values the DVS should be update with (example in salt.states.dvs) .TP .B dvs Name of the DVS to be updated. .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.update_dvs dvs_dict=$dvs_dict dvs=dvs1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.update_host_datetime(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Update the date/time on the given host or list of host_names. This function should be used with caution since network delays and execution delays can result in time skews. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts should update their date/time. .sp If host_names is not provided, the date/time will be updated for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.update_date_time my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.update_date_time my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.update_host_password(host, username, password, new_password, protocol=None, port=None, verify_ssl=True) Update the password for a given host. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Currently only works with connections to ESXi hosts. Does not work with vCenter servers. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B host The location of the ESXi host. .TP .B username The username used to login to the ESXi host, such as \fBroot\fP\&. .TP .B password The password used to login to the ESXi host. .TP .B new_password The new password that will be updated for the provided username on the ESXi host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.update_host_password my.esxi.host root original\-bad\-password new\-bad\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.update_storage_policy(policy, policy_dict, service_instance=None) Updates a storage policy. .sp Supported capability types: scalar, set, range. .INDENT 7.0 .TP .B policy Name of the policy to update. .TP .B policy_dict Dictionary containing the changes to apply to the policy. (example in salt.states.pbm) .TP .B service_instance Service instance (vim.ServiceInstance) of the vCenter. Default is None. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.update_storage_policy policy=\(aqpolicy name\(aq policy_dict=\(dq$policy_dict\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.update_vm(vm_name, cpu=None, memory=None, image=None, version=None, interfaces=None, disks=None, scsi_devices=None, serial_ports=None, datacenter=None, datastore=None, cd_dvd_drives=None, sata_controllers=None, advanced_configs=None, service_instance=None) Updates the configuration of the virtual machine if the config differs .INDENT 7.0 .TP .B vm_name Virtual Machine name to be updated .TP .B cpu CPU configuration options .TP .B memory Memory configuration options .TP .B version Virtual machine container hardware version .TP .B image Virtual machine guest OS version identifier VirtualMachineGuestOsIdentifier .TP .B interfaces Network interfaces configuration options .TP .B disks Disks configuration options .TP .B scsi_devices SCSI devices configuration options .TP .B serial_ports Serial ports configuration options .TP .B datacenter Datacenter where the virtual machine is available .TP .B datastore Datastore where the virtual machine config files are available .TP .B cd_dvd_drives CD/DVD drives configuration options .TP .B advanced_config Advanced config parameters to be set for the virtual machine .TP .B service_instance vCenter service instance for connection and configuration .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.upload_ssh_key(host, username, password, ssh_key=None, ssh_key_file=None, protocol=None, port=None, certificate_verify=None) Upload an ssh key for root to an ESXi host via http PUT. This function only works for ESXi, not vCenter. Only one ssh key can be uploaded for root. Uploading a second key will replace any existing key. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhost\fP \-\- The location of the ESXi Host .IP \(bu 2 \fBusername\fP \-\- Username to connect as .IP \(bu 2 \fBpassword\fP \-\- Password for the ESXi web endpoint .IP \(bu 2 \fBssh_key\fP \-\- Public SSH key, will be added to authorized_keys on ESXi .IP \(bu 2 \fBssh_key_file\fP \-\- File containing the SSH key. Use \(aqssh_key\(aq or ssh_key_file, but not both. .IP \(bu 2 \fBprotocol\fP \-\- defaults to https, can be http if ssl is disabled on ESXi .IP \(bu 2 \fBport\fP \-\- defaults to 443 for https .IP \(bu 2 \fBcertificate_verify\fP \-\- If true require that the SSL connection present a valid certificate. Default: True .UNINDENT .TP .B Returns Dictionary with a \(aqstatus\(aq key, True if upload is successful. If upload is unsuccessful, \(aqstatus\(aq key will be False and an \(aqError\(aq key will have an informative message. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq vsphere.upload_ssh_key my.esxi.host root bad\-password ssh_key_file=\(aq/etc/salt/my_keys/my_key.pub\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.vmotion_disable(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Disable vMotion for a given host or list of host_names. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts should disable VMotion. .sp If host_names is not provided, VMotion will be disabled for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.vmotion_disable my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.vmotion_disable my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.vmotion_enable(host, username, password, protocol=None, port=None, host_names=None, device=\(aqvmk0\(aq, verify_ssl=True) Enable vMotion for a given host or list of host_names. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts should enable VMotion. .sp If host_names is not provided, VMotion will be enabled for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B device The device that uniquely identifies the VirtualNic that will be used for VMotion for each host. Defaults to \fBvmk0\fP\&. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.vmotion_enable my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.vmotion_enable my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.vsan_add_disks(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Add any VSAN\-eligible disks to the VSAN System for the given host or list of host_names. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts need to add any VSAN\-eligible disks to the host\(aqs VSAN system. .sp If host_names is not provided, VSAN\-eligible disks will be added to the hosts\(aqs VSAN system for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.vsan_add_disks my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.vsan_add_disks my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.vsan_disable(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Disable VSAN for a given host or list of host_names. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts should disable VSAN. .sp If host_names is not provided, VSAN will be disabled for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.vsan_disable my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.vsan_disable my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vsphere.vsan_enable(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Enable VSAN for a given host or list of host_names. .INDENT 7.0 .TP .B host The location of the host. .TP .B username The username used to login to the host, such as \fBroot\fP\&. .TP .B password The password used to login to the host. .TP .B protocol Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the host is not using the default port. Default port is \fB443\fP\&. .TP .B host_names List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts should enable VSAN. .sp If host_names is not provided, VSAN will be enabled for the \fBhost\fP location instead. This is useful for when service instance connection information is used for a single ESXi host. .TP .B verify_ssl Verify the SSL certificate. Default: True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Used for single ESXi host connection information salt \(aq*\(aq vsphere.vsan_enable my.esxi.host root bad\-password # Used for connecting to a vCenter Server salt \(aq*\(aq vsphere.vsan_enable my.vcenter.location root bad\-password host_names=\(aq[esxi\-1.host.com, esxi\-2.host.com]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.webutil .sp Support for htpasswd command. Requires the apache2\-utils package for Debian\-based distros. .sp New in version 2014.1.0. .sp The functions here will load inside the webutil module. This allows other functions that don\(aqt use htpasswd to use the webutil module name. .INDENT 0.0 .TP .B salt.modules.webutil.useradd(pwfile, user, password, opts=\(aq\(aq, runas=None) Add a user to htpasswd file using the htpasswd command. If the htpasswd file does not exist, it will be created. .INDENT 7.0 .TP .B pwfile Path to htpasswd file .TP .B user User name .TP .B password User password .TP .B opts Valid options that can be passed are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fIn\fP Don\(aqt update file; display results on stdout. .IP \(bu 2 \fIm\fP Force MD5 encryption of the password (default). .IP \(bu 2 \fId\fP Force CRYPT encryption of the password. .IP \(bu 2 \fIp\fP Do not encrypt the password (plaintext). .IP \(bu 2 \fIs\fP Force SHA encryption of the password. .UNINDENT .UNINDENT .UNINDENT .TP .B runas The system user to run htpasswd command with .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq webutil.useradd /etc/httpd/htpasswd larry badpassword salt \(aq*\(aq webutil.useradd /etc/httpd/htpasswd larry badpass opts=ns .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.webutil.userdel(pwfile, user, runas=None, all_results=False) Delete a user from the specified htpasswd file. .INDENT 7.0 .TP .B pwfile Path to htpasswd file .TP .B user User name .TP .B runas The system user to run htpasswd command with .TP .B all_results Return stdout, stderr, and retcode, not just stdout .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq webutil.userdel /etc/httpd/htpasswd larry .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.webutil.verify(pwfile, user, password, opts=\(aq\(aq, runas=None) Return True if the htpasswd file exists, the user has an entry, and their password matches. .INDENT 7.0 .TP .B pwfile Fully qualified path to htpasswd file .TP .B user User name .TP .B password User password .TP .B opts Valid options that can be passed are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fIm\fP Force MD5 encryption of the password (default). .IP \(bu 2 \fId\fP Force CRYPT encryption of the password. .IP \(bu 2 \fIp\fP Do not encrypt the password (plaintext). .IP \(bu 2 \fIs\fP Force SHA encryption of the password. .UNINDENT .UNINDENT .UNINDENT .TP .B runas The system user to run htpasswd command with .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq webutil.verify /etc/httpd/htpasswd larry maybepassword salt \(aq*\(aq webutil.verify /etc/httpd/htpasswd larry maybepassword opts=ns .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_appx .SS Manage provisioned apps .sp New in version 3007.0. .sp Provisioned apps are part of the image and are installed for every user the first time the user logs on. Provisioned apps are also updated and sometimes reinstalled when the system is updated. .sp Apps removed with this module will remove the app for all users and deprovision the app. Deprovisioned apps will neither be installed for new users nor will they be upgraded. .sp An app removed with this module can only be re\-provisioned on the machine, but it can\(aqt be re\-installed for all users. Also, once a package has been deprovisioned, the only way to reinstall it is to download the package. This is difficult. The steps are outlined below: .INDENT 0.0 .IP 1. 3 .INDENT 3.0 .TP .B Obtain the Microsoft Store URL for the app: .INDENT 7.0 .IP \(bu 2 Open the page for the app in the Microsoft Store .IP \(bu 2 Click the share button and copy the URL .UNINDENT .UNINDENT .IP 2. 3 .INDENT 3.0 .TP .B Look up the packages on \fI\%https://store.rg\-adguard.net/\fP: .INDENT 7.0 .IP \(bu 2 Ensure \fBURL (link)\fP is selected in the first dropdown .IP \(bu 2 Paste the URL in the search field .IP \(bu 2 Ensure Retail is selected in the 2nd dropdown .IP \(bu 2 Click the checkmark button .UNINDENT .UNINDENT .UNINDENT .sp This should return a list of URLs for the package and all dependencies for all architectures. Download the package and all dependencies for your system architecture. These will usually have one of the following file extensions: .INDENT 0.0 .IP \(bu 2 \fB\&.appx\fP .IP \(bu 2 \fB\&.appxbundle\fP .IP \(bu 2 \fB\&.msix\fP .IP \(bu 2 \fB\&.msixbundle\fP .UNINDENT .sp Dependencies will need to be installed first. .sp Not all packages can be found this way, but it seems like most of them can. .sp Use the \fBappx.install\fP function to provision the new app. .INDENT 0.0 .TP .B salt.modules.win_appx.install(package) This function uses \fBdism\fP to provision a package. This means that it will be made a part of the online image and added to new users on the system. If a package has dependencies, those must be installed first. .sp If a package installed using this function has been deprovisioned previously, the registry entry marking it as deprovisioned will be removed. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 There is no \fBappx.present\fP state. Instead, use the \fBdism.provisioned_package_installed\fP state. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBpackage\fP (\fI\%str\fP) \-\- .sp The full path to the package to install. Can be one of the following: .INDENT 7.0 .IP \(bu 2 \fB\&.appx\fP or \fB\&.appxbundle\fP .IP \(bu 2 \fB\&.msix\fP or \fB\&.msixbundle\fP .IP \(bu 2 \fB\&.ppkg\fP .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq appx.install \(dqC:\eTemp\eMicrosoft.ZuneMusic.msixbundle\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_appx.list_(query=None, field=\(aqName\(aq, include_store=False, frameworks=False, bundles=True) Get a list of Microsoft Store packages installed on the system. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBquery\fP (\fI\%str\fP) \-\- .sp The query string to use to filter packages to be listed. The string can match multiple packages. \fBNone\fP will return all packages. Here are some example strings: .INDENT 2.0 .IP \(bu 2 \fB*teams*\fP \- Returns Microsoft Teams .IP \(bu 2 \fB*zune*\fP \- Returns Windows Media Player and ZuneVideo .IP \(bu 2 \fB*zuneMusic*\fP \- Only returns Windows Media Player .IP \(bu 2 \fB*xbox*\fP \- Returns all xbox packages, there are 5 by default .IP \(bu 2 \fB*\fP \- Returns everything but the Microsoft Store, unless \fBinclude_store=True\fP .UNINDENT .IP \(bu 2 \fBfield\fP (\fI\%str\fP) \-\- .sp This function returns a list of packages on the system. It can display a short name or a full name. If \fBNone\fP is passed, a dictionary will be returned with some common fields. The default is \fBName\fP\&. Valid options are any fields returned by the powershell command \fBGet\-AppxPackage\fP\&. Here are some useful fields: .INDENT 2.0 .IP \(bu 2 Name .IP \(bu 2 Version .IP \(bu 2 PackageFullName .IP \(bu 2 PackageFamilyName .UNINDENT .IP \(bu 2 \fBinclude_store\fP (\fI\%bool\fP) \-\- Include the Microsoft Store in the results. Default is \fBFalse\fP .IP \(bu 2 \fBframeworks\fP (\fI\%bool\fP) \-\- Include frameworks in the results. Default is \fBFalse\fP .IP \(bu 2 \fBbundles\fP (\fI\%bool\fP) \-\- If \fBTrue\fP, this will return application bundles only. If \fBFalse\fP, this will return individual packages only, even if they are part of a bundle. .UNINDENT .TP .B Returns A list of packages ordered by the string passed in field list: A list of dictionaries of package information if field is \fBNone\fP .TP .B Return type \fI\%list\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If an error is encountered retrieving packages .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # List installed apps that contain the word \(dqcandy\(dq salt \(aq*\(aq appx.list *candy* # Return more information about the package salt \(aq*\(aq appx.list *candy* field=None # List all installed apps, including the Microsoft Store salt \(aq*\(aq appx.list include_store=True # List all installed apps, including frameworks salt \(aq*\(aq appx.list frameworks=True # List all installed apps that are bundles salt \(aq*\(aq appx.list bundles=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_appx.list_deprovisioned(query=None) When an app is deprovisioned, a registry key is created that will keep it from being reinstalled during a major system update. This function returns a list of keys for apps that have been deprovisioned. .INDENT 7.0 .TP .B Parameters \fBquery\fP (\fI\%str\fP) \-\- .sp The query string to use to filter packages to be listed. The string can match multiple packages. \fBNone\fP will return all packages. Here are some example strings: .INDENT 7.0 .IP \(bu 2 \fB*teams*\fP \- Returns Microsoft Teams .IP \(bu 2 \fB*zune*\fP \- Returns Windows Media Player and ZuneVideo .IP \(bu 2 \fB*zuneMusic*\fP \- Only returns Windows Media Player .IP \(bu 2 \fB*xbox*\fP \- Returns all xbox packages, there are 5 by default .IP \(bu 2 \fB*\fP \- Returns everything but the Microsoft Store, unless \fBinclude_store=True\fP .UNINDENT .TP .B Returns A list of packages matching the query criteria .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq appx.list_deprovisioned *zune* .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_appx.remove(query=None, include_store=False, frameworks=False, deprovision_only=False) Removes Microsoft Store packages from the system. If the package is part of a bundle, the entire bundle will be removed. .sp This function removes the package for all users on the system. It also deprovisions the package so that it isn\(aqt re\-installed by later system updates. To only deprovision a package and not remove it for all users, set \fBdeprovision_only=True\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBquery\fP (\fI\%str\fP) \-\- .sp The query string to use to select the packages to be removed. If the string matches multiple packages, they will all be removed. Here are some example strings: .INDENT 2.0 .IP \(bu 2 \fB*teams*\fP \- Remove Microsoft Teams .IP \(bu 2 \fB*zune*\fP \- Remove Windows Media Player and ZuneVideo .IP \(bu 2 \fB*zuneMusic*\fP \- Only remove Windows Media Player .IP \(bu 2 \fB*xbox*\fP \- Remove all xbox packages, there are 5 by default .IP \(bu 2 \fB*\fP \- Remove everything but the Microsoft Store, unless \fBinclude_store=True\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 Use the \fBappx.list\fP function to make sure your query is returning what you expect. Then use the same query to remove those packages .UNINDENT .UNINDENT .IP \(bu 2 \fBinclude_store\fP (\fI\%bool\fP) \-\- Include the Microsoft Store in the results of the query to be removed. Use this with caution. It is difficult to reinstall the Microsoft Store once it has been removed with this function. Default is \fBFalse\fP .IP \(bu 2 \fBframeworks\fP (\fI\%bool\fP) \-\- Include frameworks in the results of the query to be removed. Default is \fBFalse\fP .IP \(bu 2 \fBdeprovision_only\fP (\fI\%bool\fP) \-\- Only deprovision the package. The package will be removed from the current user and added to the list of deprovisioned packages. The package will not be re\-installed in future system updates. New users of the system will not have the package installed. However, the package will still be installed for existing users. Default is \fBFalse\fP .UNINDENT .TP .B Returns \fBTrue\fP if successful, \fBNone\fP if no packages found .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- On errors encountered removing the package .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq appx.remove *candy* .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_auditpol .sp A salt module for modifying the audit policies on the machine .sp Though this module does not set group policy for auditing, it displays how all auditing configuration is applied on the machine, either set directly or via local or domain group policy. .sp New in version 2018.3.4. .sp New in version 2019.2.1. .sp This module allows you to view and modify the audit settings as they are applied on the machine. The audit settings are broken down into nine categories: .INDENT 0.0 .IP \(bu 2 Account Logon .IP \(bu 2 Account Management .IP \(bu 2 Detailed Tracking .IP \(bu 2 DS Access .IP \(bu 2 Logon/Logoff .IP \(bu 2 Object Access .IP \(bu 2 Policy Change .IP \(bu 2 Privilege Use .IP \(bu 2 System .UNINDENT .sp The \fBget_settings\fP function will return the subcategories for all nine of the above categories in one dictionary along with their auditing status. .sp To modify a setting you only need to specify the subcategory name and the value you wish to set. Valid settings are: .INDENT 0.0 .IP \(bu 2 No Auditing .IP \(bu 2 Success .IP \(bu 2 Failure .IP \(bu 2 Success and Failure .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Get current state of all audit settings salt * auditpol.get_settings # Get the current state of all audit settings in the \(dqAccount Logon\(dq # category salt * auditpol.get_settings category=\(dqAccount Logon\(dq # Get current state of the \(dqCredential Validation\(dq setting salt * auditpol.get_setting name=\(dqCredential Validation\(dq # Set the state of the \(dqCredential Validation\(dq setting to Success and # Failure salt * auditpol.set_setting name=\(dqCredential Validation\(dq value=\(dqSuccess and Failure\(dq # Set the state of the \(dqCredential Validation\(dq setting to No Auditing salt * auditpol.set_setting name=\(dqCredential Validation\(dq value=\(dqNo Auditing\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_auditpol.get_setting(name) Get the current configuration for the named audit setting .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the setting to retrieve .TP .B Returns The current configuration for the named setting .TP .B Return type \fI\%str\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%KeyError\fP \-\- On invalid setting name .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If an error is encountered retrieving the settings .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Get current state of the \(dqCredential Validation\(dq setting salt * auditpol.get_setting \(dqCredential Validation\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_auditpol.get_settings(category=\(aqAll\(aq) Get the current configuration for all audit settings specified in the category .INDENT 7.0 .TP .B Parameters \fBcategory\fP (\fI\%str\fP) \-\- .sp One of the nine categories to return. Can also be \fBAll\fP to return the settings for all categories. Valid options are: .INDENT 7.0 .IP \(bu 2 Account Logon .IP \(bu 2 Account Management .IP \(bu 2 Detailed Tracking .IP \(bu 2 DS Access .IP \(bu 2 Logon/Logoff .IP \(bu 2 Object Access .IP \(bu 2 Policy Change .IP \(bu 2 Privilege Use .IP \(bu 2 System .IP \(bu 2 All .UNINDENT .sp Default value is \fBAll\fP .TP .B Returns .INDENT 7.0 .TP .B A dictionary containing all subcategories for the specified category along with their current configuration .UNINDENT .TP .B Return type \fI\%dict\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%KeyError\fP \-\- On invalid category .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If an error is encountered retrieving the settings .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Get current state of all audit settings salt * auditipol.get_settings # Get the current state of all audit settings in the \(dqAccount Logon\(dq # category salt * auditpol.get_settings \(dqAccount Logon\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_auditpol.set_setting(name, value) Set the configuration for the named audit setting .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the setting to configure .IP \(bu 2 \fBvalue\fP (\fI\%str\fP) \-\- .sp The configuration for the named value. Valid options are: .INDENT 2.0 .IP \(bu 2 No Auditing .IP \(bu 2 Success .IP \(bu 2 Failure .IP \(bu 2 Success and Failure .UNINDENT .UNINDENT .TP .B Returns True if successful .TP .B Return type \fI\%bool\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%KeyError\fP \-\- On invalid \fBname\fP or \fBvalue\fP .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If an error is encountered modifying the setting .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Set the state of the \(dqCredential Validation\(dq setting to Success and # Failure salt * auditpol.set_setting \(dqCredential Validation\(dq \(dqSuccess and Failure\(dq # Set the state of the \(dqCredential Validation\(dq setting to No Auditing salt * auditpol.set_setting \(dqCredential Validation\(dq \(dqNo Auditing\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_autoruns .sp Module for listing programs that automatically run on startup (very alpha...not tested on anything but my Win 7x64) .INDENT 0.0 .TP .B salt.modules.win_autoruns.list_() Get a list of automatically running programs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq autoruns.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_certutil .sp This module allows you to install certificates into the windows certificate manager. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq certutil.add_store salt://cert.cer \(dqTrustedPublisher\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_certutil.add_store(source, store, retcode=False, saltenv=\(aqbase\(aq) Add the cert to the given Certificate Store .INDENT 7.0 .TP .B source (str): The source certificate file. This is either the path to a local file or a file from the file server in the form of \fBsalt://path/to/file\fP .TP .B store (str): The certificate store to add the certificate to .TP .B retcode (bool): If \fBTrue\fP, return the retcode instead of stdout. Default is \fBFalse\fP .TP .B saltenv (str): The salt environment to use. This is ignored if the path is local .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq certutil.add_store salt://cert.cer TrustedPublisher salt \(aq*\(aq certutil.add_store C:\epath\eto\elocal.cer TrustedPublisher .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_certutil.del_store(source, store, retcode=False, saltenv=\(aqbase\(aq) Delete the cert from the given Certificate Store .INDENT 7.0 .TP .B source (str): The source certificate file. This is either the path to a local file or a file from the file server in the form of \fBsalt://path/to/file\fP .TP .B store (str): The certificate store to delete the certificate from .TP .B retcode (bool): If \fBTrue\fP, return the retcode instead of stdout. Default is \fBFalse\fP .TP .B saltenv (str): The salt environment to use. This is ignored if the path is local .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq certutil.del_store salt://cert.cer TrustedPublisher salt \(aq*\(aq certutil.del_store C:\epath\eto\elocal.cer TrustedPublisher .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_certutil.get_cert_serial(cert_file, saltenv=\(aqbase\(aq) Get the serial number of a certificate file .INDENT 7.0 .TP .B cert_file (str): The certificate file to find the serial for. Can be a local file or a a file on the file server (\fBsalt://\fP) .UNINDENT .INDENT 7.0 .TP .B Returns The serial number of the certificate if found, otherwise None .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq certutil.get_cert_serial <certificate name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_certutil.get_stored_cert_serials(store) Get all of the certificate serials in the specified store .INDENT 7.0 .TP .B store (str): The store to get all the certificate serials from .UNINDENT .INDENT 7.0 .TP .B Returns A list of serial numbers found, or an empty list if none found .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq certutil.get_stored_cert_serials <store> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_dacl .sp Manage DACLs on Windows .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 winreg Python module .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dacl.add_ace(path, objectType, user, permission, acetype, propagation) add an ace to an object .sp path: path to the object (i.e. c:\etemp\efile, HKEY_LOCAL_MACHINE\eSOFTWARE\eKEY, etc) user: user to add permission: permissions for the user acetype: either allow/deny for each user/permission (ALLOW, DENY) propagation: how the ACE applies to children for Registry Keys and Directories(KEY, KEY&SUBKEYS, SUBKEYS) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C allow domain\efakeuser full control on HKLM\e\eSOFTWARE\e\esomekey, propagate to this key and subkeys salt \(aqmyminion\(aq win_dacl.add_ace \(aqHKEY_LOCAL_MACHINE\e\eSOFTWARE\e\esomekey\(aq \(aqRegistry\(aq \(aqdomain\efakeuser\(aq \(aqFULLCONTROL\(aq \(aqALLOW\(aq \(aqKEY&SUBKEYS\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dacl.check_ace(path, objectType, user, permission=None, acetype=None, propagation=None, exactPermissionMatch=False) Checks a path to verify the ACE (access control entry) specified exists .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- path to the file/reg key .IP \(bu 2 \fBobjectType\fP \-\- The type of object (FILE, DIRECTORY, REGISTRY) .IP \(bu 2 \fBuser\fP \-\- user that the ACL is for .IP \(bu 2 \fBpermission\fP \-\- permission to test for (READ, FULLCONTROL, etc) .IP \(bu 2 \fBacetype\fP \-\- the type of ACE (ALLOW or DENY) .IP \(bu 2 \fBpropagation\fP \-\- the propagation type of the ACE (FILES, FOLDERS, KEY, KEY&SUBKEYS, SUBKEYS, etc) .IP \(bu 2 \fBexactPermissionMatch\fP \-\- the ACL must match exactly, IE if READ is specified, the user must have READ exactly and not FULLCONTROL (which also has the READ permission obviously) .UNINDENT .UNINDENT .sp Returns (dict): \(aqExists\(aq true if the ACE exists, false if it does not .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq win_dacl.check_ace c: emp directory <username> fullcontrol .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dacl.check_inheritance(path, objectType, user=None) Check a specified path to verify if inheritance is enabled .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- path of the registry key or file system object to check .IP \(bu 2 \fBobjectType\fP \-\- The type of object (FILE, DIRECTORY, REGISTRY) .IP \(bu 2 \fBuser\fP \-\- if provided, will consider only the ACEs for that user .UNINDENT .UNINDENT .sp Returns (bool): \(aqInheritance\(aq of True/False .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq win_dacl.check_inheritance c: emp directory <username> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.win_dacl.daclConstants DACL constants used throughout the module .INDENT 7.0 .TP .B getAceTypeBit(t) returns the acetype bit of a text value .UNINDENT .INDENT 7.0 .TP .B getAceTypeText(t) returns the textual representation of a acetype bit .UNINDENT .INDENT 7.0 .TP .B getObjectTypeBit(t) returns the bit value of the string object type .UNINDENT .INDENT 7.0 .TP .B getPermissionBit(t, m) returns a permission bit of the string permission value for the specified object type .UNINDENT .INDENT 7.0 .TP .B getPermissionText(t, m) returns the permission textual representation of a specified permission bit/object type .UNINDENT .INDENT 7.0 .TP .B getPropagationBit(t, p) returns the propagation bit of a text value .UNINDENT .INDENT 7.0 .TP .B getPropagationText(t, p) returns the textual representation of a propagation bit .UNINDENT .INDENT 7.0 .TP .B getSecurityHkey(s) returns the necessary string value for an HKEY for the win32security module .UNINDENT .INDENT 7.0 .TP .B processPath(path, objectType) .INDENT 7.0 .TP .B processes a path/object type combo and returns: registry types with the correct HKEY text representation files/directories with environment variables expanded .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dacl.disable_inheritance(path, objectType, copy=True) Disable inheritance on an object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- The path to the object .IP \(bu 2 \fBobjectType\fP \-\- The type of object (FILE, DIRECTORY, REGISTRY) .IP \(bu 2 \fBcopy\fP \-\- True will copy the Inherited ACEs to the DACL before disabling inheritance .UNINDENT .UNINDENT .sp Returns (dict): A dictionary containing the results .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq win_dacl.disable_inheritance c: emp directory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dacl.enable_inheritance(path, objectType, clear=False) enable/disable inheritance on an object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- The path to the object .IP \(bu 2 \fBobjectType\fP \-\- The type of object (FILE, DIRECTORY, REGISTRY) .IP \(bu 2 \fBclear\fP \-\- True will remove non\-Inherited ACEs from the ACL .UNINDENT .UNINDENT .sp Returns (dict): A dictionary containing the results .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq win_dacl.enable_inheritance c: emp directory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dacl.get(path, objectType, user=None) Get the ACL of an object. Will filter by user if one is provided. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- The path to the object .IP \(bu 2 \fBobjectType\fP \-\- The type of object (FILE, DIRECTORY, REGISTRY) .IP \(bu 2 \fBuser\fP \-\- A user name to filter by .UNINDENT .UNINDENT .sp Returns (dict): A dictionary containing the ACL .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq win_dacl.get c: emp directory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dacl.rm_ace(path, objectType, user, permission=None, acetype=None, propagation=None) remove an ace to an object .sp path: path to the object (i.e. c:\etemp\efile, HKEY_LOCAL_MACHINE\eSOFTWARE\eKEY, etc) user: user to remove permission: permissions for the user acetypes: either allow/deny for each user/permission (ALLOW, DENY) propagation: how the ACE applies to children for Registry Keys and Directories(KEY, KEY&SUBKEYS, SUBKEYS) .sp If any of the optional parameters are omitted (or set to None) they act as wildcards. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C remove allow domain\efakeuser full control on HKLM\e\eSOFTWARE\e\esomekey propagated to this key and subkeys salt \(aqmyminion\(aq win_dacl.rm_ace \(aqRegistry\(aq \(aqHKEY_LOCAL_MACHINE\e\eSOFTWARE\e\esomekey\(aq \(aqdomain\efakeuser\(aq \(aqFULLCONTROL\(aq \(aqALLOW\(aq \(aqKEY&SUBKEYS\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_disk .sp Module for gathering disk information on Windows .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 win32api Python module .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_disk.usage() Return usage information for volumes mounted on this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.usage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_dism .sp Install features/packages for Windows using DISM, which is useful for minions not running server versions\ of Windows. Some functions are only available on Windows 10. .INDENT 0.0 .TP .B salt.modules.win_dism.add_capability(capability, source=None, limit_access=False, image=None, restart=False) Install a capability .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcapability\fP (\fI\%str\fP) \-\- The capability to install .IP \(bu 2 \fBsource\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The optional source of the capability. Default is set by group policy and can be Windows Update. .IP \(bu 2 \fBlimit_access\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Prevent DISM from contacting Windows Update for the source package .IP \(bu 2 \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the install .UNINDENT .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%NotImplementedError\fP \-\- For all versions of Windows that are not Windows 10 .IP \(bu 2 \fBand later. Server editions\fP\fB of \fP\fBWindows use ServerManager instead.\fP \-\- .UNINDENT .TP .B Returns A dictionary containing the results of the command .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.add_capability Tools.Graphics.DirectX~~~~0.0.1.0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.add_feature(feature, package=None, source=None, limit_access=False, enable_parent=False, image=None, restart=False) Install a feature using DISM .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfeature\fP (\fI\%str\fP) \-\- The feature to install .IP \(bu 2 \fBpackage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The parent package for the feature. You do not have to specify the package if it is the Windows Foundation Package. Otherwise, use package to specify the parent package of the feature .IP \(bu 2 \fBsource\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The optional source of the capability. Default is set by group policy and can be Windows Update .IP \(bu 2 \fBlimit_access\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Prevent DISM from contacting Windows Update for the source package .IP \(bu 2 \fBenable_parent\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- True will enable all parent features of the specified feature .IP \(bu 2 \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the install .UNINDENT .TP .B Returns A dictionary containing the results of the command .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.add_feature NetFx3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.add_package(package, ignore_check=False, prevent_pending=False, image=None, restart=False) Install a package using DISM .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpackage\fP (\fI\%str\fP) \-\- .sp The package to install. Can be a .cab file, a .msu file, or a folder .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 An \fI\&.msu\fP package is supported only when the target image is offline, either mounted or applied. .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_check\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Skip installation of the package if the applicability checks fail .IP \(bu 2 \fBprevent_pending\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Skip the installation of the package if there are pending online actions .IP \(bu 2 \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fBNone\fP is passed, the running operating system is targeted. Default is None. .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the install .UNINDENT .TP .B Returns A dictionary containing the results of the command .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.add_package C:\ePackages\epackage.cab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.add_provisioned_package(package, image=None, restart=False) Provision a package using DISM. A provisioned package will install for new users on the system. It will also be reinstalled on each user if the system is updated. .sp New in version 3007.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpackage\fP (\fI\%str\fP) \-\- .sp The package to install. Can be one of the following: .INDENT 2.0 .IP \(bu 2 \fB\&.appx\fP or \fB\&.appxbundle\fP .IP \(bu 2 \fB\&.msix\fP or \fB\&.msixbundle\fP .IP \(bu 2 \fB\&.ppkg\fP .UNINDENT .IP \(bu 2 \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fBNone\fP is passed, the running operating system is targeted. Default is \fBNone\fP\&. .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the installation. Default is \fBFalse\fP .UNINDENT .TP .B Returns A dictionary containing the results of the command .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.add_provisioned_package C:\ePackages\epackage.appx salt \(aq*\(aq dism.add_provisioned_package C:\ePackages\epackage.appxbundle salt \(aq*\(aq dism.add_provisioned_package C:\ePackages\epackage.msix salt \(aq*\(aq dism.add_provisioned_package C:\ePackages\epackage.msixbundle salt \(aq*\(aq dism.add_provisioned_package C:\ePackages\epackage.ppkg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.available_capabilities(image=None) List the capabilities available on the system .INDENT 7.0 .TP .B Parameters \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%NotImplementedError\fP \-\- For all versions of Windows that are not Windows 10 .IP \(bu 2 \fBand later. Server editions\fP\fB of \fP\fBWindows use ServerManager instead.\fP \-\- .UNINDENT .TP .B Returns A list of available capabilities .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.installed_capabilities .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.available_features(image=None) List the features available on the system .INDENT 7.0 .TP .B Parameters \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .TP .B Returns A list of available features .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.available_features .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.get_capabilities(image=None) List all capabilities on the system .INDENT 7.0 .TP .B Parameters \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%NotImplementedError\fP \-\- For all versions of Windows that are not Windows 10 .IP \(bu 2 \fBand later. Server editions\fP\fB of \fP\fBWindows use ServerManager instead.\fP \-\- .UNINDENT .TP .B Returns A list of capabilities .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.get_capabilities .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.get_features(package=None, image=None) List features on the system or in a package .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpackage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- .sp The full path to the package. Can be either a \&.cab file or a folder. Should point to the original source of the package, not to where the file is installed. You cannot use this command to get package information for .msu files .sp This can also be the name of a package as listed in \fBdism.installed_packages\fP .IP \(bu 2 \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .UNINDENT .TP .B Returns A list of features .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Return all features on the system salt \(aq*\(aq dism.get_features # Return all features in package.cab salt \(aq*\(aq dism.get_features C:\epackages\epackage.cab # Return all features in the calc package salt \(aq*\(aq dism.get_features Microsoft.Windows.Calc.Demo~6595b6144ccf1df~x86~en~1.0.0.0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.get_kb_package_name(kb, image=None) Get the actual package name on the system based on the KB name .sp New in version 3006.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkb\fP (\fI\%str\fP) \-\- The name of the KB to remove. Can also be just the KB number .IP \(bu 2 \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .UNINDENT .TP .B Returns The name of the package found on the system None: If the package is not installed on the system .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Get the package name for KB1231231 salt \(aq*\(aq dism.get_kb_package_name KB1231231 # Get the package name for KB1231231 using just the number salt \(aq*\(aq dism.get_kb_package_name 1231231 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.installed_capabilities(image=None) List the capabilities installed on the system .INDENT 7.0 .TP .B Parameters \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%NotImplementedError\fP \-\- For all versions of Windows that are not Windows 10 .IP \(bu 2 \fBand later. Server editions\fP\fB of \fP\fBWindows use ServerManager instead.\fP \-\- .UNINDENT .TP .B Returns A list of installed capabilities .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.installed_capabilities .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.installed_features(image=None) List the features installed on the system .INDENT 7.0 .TP .B Parameters \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .TP .B Returns A list of installed features .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.installed_features .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.installed_packages(image=None) List the packages installed on the system .INDENT 7.0 .TP .B Parameters \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .TP .B Returns A list of installed packages .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.installed_packages .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.package_info(package, image=None) Display information about a package .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpackage\fP (\fI\%str\fP) \-\- The full path to the package. Can be either a .cab file or a folder. Should point to the original source of the package, not to where the file is installed. You cannot use this command to get package information for .msu files .IP \(bu 2 \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .UNINDENT .TP .B Returns A dictionary containing the results of the command .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.package_info C:\epackages\epackage.cab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.provisioned_packages(image=None) List the packages installed on the system .sp New in version 3007.0. .INDENT 7.0 .TP .B Parameters \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .TP .B Returns A list of installed packages .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.installed_packages .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.remove_capability(capability, image=None, restart=False) Uninstall a capability .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcapability\fP (\fI\%str\fP) \-\- The capability to be removed .IP \(bu 2 \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the install .UNINDENT .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%NotImplementedError\fP \-\- For all versions of Windows that are not Windows 10 .IP \(bu 2 \fBand later. Server editions\fP\fB of \fP\fBWindows use ServerManager instead.\fP \-\- .UNINDENT .TP .B Returns A dictionary containing the results of the command .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.remove_capability Tools.Graphics.DirectX~~~~0.0.1.0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.remove_feature(feature, remove_payload=False, image=None, restart=False) Disables the feature. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfeature\fP (\fI\%str\fP) \-\- The feature to uninstall .IP \(bu 2 \fBremove_payload\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Remove the feature\(aqs payload. Must supply source when enabling in the future. .IP \(bu 2 \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the install .UNINDENT .TP .B Returns A dictionary containing the results of the command .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dism.remove_feature NetFx3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.remove_kb(kb, image=None, restart=False) Remove a package by passing a KB number. This searches the installed packages to get the full package name of the KB. It then calls the \fBdism.remove_package\fP function to remove the package. .sp New in version 3006.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkb\fP (\fI\%str\fP) \-\- The name of the KB to remove. Can also be just the KB number .IP \(bu 2 \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the uninstall .UNINDENT .TP .B Returns A dictionary containing the results of the command .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Remove the KB5007575 just passing the number salt \(aq*\(aq dism.remove_kb 5007575 # Remove the KB5007575 just passing the full name salt \(aq*\(aq dism.remove_kb KB5007575 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dism.remove_package(package, image=None, restart=False) Uninstall a package .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpackage\fP (\fI\%str\fP) \-\- The full path to the package. Can be either a .cab file or a folder. Should point to the original source of the package, not to where the file is installed. This can also be the name of a package as listed in \fBdism.installed_packages\fP .IP \(bu 2 \fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If \fINone\fP is passed, the running operating system is targeted. Default is None. .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the uninstall .UNINDENT .TP .B Returns A dictionary containing the results of the command .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Remove the Calc Package salt \(aq*\(aq dism.remove_package Microsoft.Windows.Calc.Demo~6595b6144ccf1df~x86~en~1.0.0.0 # Remove the package.cab (does not remove C:\epackages\epackage.cab) salt \(aq*\(aq dism.remove_package C:\epackages\epackage.cab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_dns_client .sp Module for configuring DNS Client on Windows systems .INDENT 0.0 .TP .B salt.modules.win_dns_client.add_dns(ip, interface=\(aqLocal Area Connection\(aq, index=1) Add the DNS server to the network interface (index starts from 1) .sp Note: if the interface DNS is configured by DHCP, all the DNS servers will be removed from the interface and the requested DNS will be the only one .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_dns_client.add_dns <ip> <interface> <index> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dns_client.dns_dhcp(interface=\(aqLocal Area Connection\(aq) Configure the interface to get its DNS servers from the DHCP server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_dns_client.dns_dhcp <interface> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dns_client.get_dns_config(interface=\(aqLocal Area Connection\(aq) Get the type of DNS configuration (dhcp / static). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBinterface\fP (\fI\%str\fP) \-\- The name of the network interface. This is the .IP \(bu 2 \fBdevice\fP (\fIDescription in the Network Connection Details for the\fP) \-\- .UNINDENT .TP .B Returns \fBTrue\fP if DNS is configured, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_dns_client.get_dns_config \(aqLocal Area Connection\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dns_client.get_dns_servers(interface=\(aqLocal Area Connection\(aq) Return a list of the configured DNS servers of the specified interface .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBinterface\fP (\fI\%str\fP) \-\- The name of the network interface. This is the name as .IP \(bu 2 \fBConnections\fP (\fIit appears in the Control Panel under Network\fP) \-\- .UNINDENT .TP .B Returns A list of dns servers .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_dns_client.get_dns_servers \(aqLocal Area Connection\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dns_client.rm_dns(ip, interface=\(aqLocal Area Connection\(aq) Remove the DNS server from the network interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_dns_client.rm_dns <ip> <interface> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_dsc .sp Module for working with Windows PowerShell DSC (Desired State Configuration) .sp This module is Alpha .sp This module applies DSC Configurations in the form of PowerShell scripts or MOF (Managed Object Format) schema files. .sp Use the \fBpsget\fP module to manage PowerShell resources. .sp The idea is to leverage Salt to push DSC configuration scripts or MOF files to the Minion. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 PowerShell 5.0 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dsc.apply_config(path, source=None, salt_env=\(aqbase\(aq) Run an compiled DSC configuration (a folder containing a .mof file). The folder can be cached from the salt master using the \fBsource\fP option. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- Local path to the directory that contains the .mof configuration file to apply. Required. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- Path to the directory that contains the .mof file on the \fBfile_roots\fP\&. The source directory will be copied to the path directory and then executed. If the path and source directories differ, the source directory will be applied. If source is not passed, the config located at \fBpath\fP will be applied. Optional. .IP \(bu 2 \fBsalt_env\fP (\fI\%str\fP) \-\- The salt environment to use when copying your source. Default is \(aqbase\(aq .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .sp To apply a config that already exists on the system .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.apply_config C:\e\eDSC\e\eWebSiteConfiguration .ft P .fi .UNINDENT .UNINDENT .sp To cache a configuration from the master and apply it: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.apply_config C:\e\eDSC\e\eWebSiteConfiguration salt://dsc/configs/WebSiteConfiguration .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dsc.compile_config(path, source=None, config_name=None, config_data=None, config_data_source=None, script_parameters=None, salt_env=\(aqbase\(aq) Compile a config from a PowerShell script (\fB\&.ps1\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- Path (local) to the script that will create the \fB\&.mof\fP configuration file. If no source is passed, the file must exist locally. Required. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- Path to the script on \fBfile_roots\fP to cache at the location specified by \fBpath\fP\&. The source file will be cached locally and then executed. If source is not passed, the config script located at \fBpath\fP will be compiled. Optional. .IP \(bu 2 \fBconfig_name\fP (\fI\%str\fP) \-\- The name of the Configuration within the script to apply. If the script contains multiple configurations within the file a \fBconfig_name\fP must be specified. If the \fBconfig_name\fP is not specified, the name of the file will be used as the \fBconfig_name\fP to run. Optional. .IP \(bu 2 \fBconfig_data\fP (\fI\%str\fP) \-\- .sp Configuration data in the form of a hash table that will be passed to the \fBConfigurationData\fP parameter when the \fBconfig_name\fP is compiled. This can be the path to a \fB\&.psd1\fP file containing the proper hash table or the PowerShell code to create the hash table. .sp New in version 2017.7.0. .IP \(bu 2 \fBconfig_data_source\fP (\fI\%str\fP) \-\- .sp The path to the \fB\&.psd1\fP file on \fBfile_roots\fP to cache at the location specified by \fBconfig_data\fP\&. If this is specified, \fBconfig_data\fP must be a local path instead of a hash table. .sp New in version 2017.7.0. .IP \(bu 2 \fBscript_parameters\fP (\fI\%str\fP) \-\- .sp Any additional parameters expected by the configuration script. These must be defined in the script itself. .sp New in version 2017.7.0. .IP \(bu 2 \fBsalt_env\fP (\fI\%str\fP) \-\- The salt environment to use when copying the source. Default is \(aqbase\(aq .UNINDENT .TP .B Returns A dictionary containing the results of the compilation .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .sp To compile a config from a script that already exists on the system: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.compile_config C:\e\eDSC\e\eWebsiteConfig.ps1 .ft P .fi .UNINDENT .UNINDENT .sp To cache a config script to the system from the master and compile it: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.compile_config C:\e\eDSC\e\eWebsiteConfig.ps1 salt://dsc/configs/WebsiteConfig.ps1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dsc.get_config() Get the current DSC Configuration .INDENT 7.0 .TP .B Returns A dictionary representing the DSC Configuration on the machine .TP .B Return type \fI\%dict\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- On failure .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.get_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dsc.get_config_status() Get the status of the current DSC Configuration .INDENT 7.0 .TP .B Returns .INDENT 7.0 .TP .B A dictionary representing the status of the current DSC Configuration on the machine .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.get_config_status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dsc.get_lcm_config() Get the current Local Configuration Manager settings .INDENT 7.0 .TP .B Returns .INDENT 7.0 .TP .B A dictionary representing the Local Configuration Manager settings on the machine .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.get_lcm_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dsc.remove_config(reset=False) Remove the current DSC Configuration. Removes current, pending, and previous dsc configurations. .sp New in version 2017.7.5. .INDENT 7.0 .TP .B Parameters \fBreset\fP (\fI\%bool\fP) \-\- .sp Attempts to reset the DSC configuration by removing the following from \fBC:\eWindows\eSystem32\eConfiguration\fP: .INDENT 7.0 .IP \(bu 2 File: DSCStatusHistory.mof .IP \(bu 2 File: DSCEngineCache.mof .IP \(bu 2 Dir: ConfigurationStatus .UNINDENT .sp Default is False .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 \fBremove_config\fP may fail to reset the DSC environment if any of the files in the \fBConfigurationStatus\fP directory are in use. If you wait a few minutes and run again, it may complete successfully. .UNINDENT .UNINDENT .TP .B Returns True if successful .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- On failure .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.remove_config True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dsc.restore_config() Reapplies the previous configuration. .sp New in version 2017.7.5. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The current configuration will be come the previous configuration. If run a second time back\-to\-back it is like toggling between two configs. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns True if successfully restored .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- On failure .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.restore_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dsc.run_config(path, source=None, config_name=None, config_data=None, config_data_source=None, script_parameters=None, salt_env=\(aqbase\(aq) Compile a DSC Configuration in the form of a PowerShell script (.ps1) and apply it. The PowerShell script can be cached from the master using the \fBsource\fP option. If there is more than one config within the PowerShell script, the desired configuration can be applied by passing the name in the \fBconfig\fP option. .sp This command would be the equivalent of running \fBdsc.compile_config\fP followed by \fBdsc.apply_config\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The local path to the PowerShell script that contains the DSC Configuration. Required. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- The path to the script on \fBfile_roots\fP to cache at the location specified by \fBpath\fP\&. The source file will be cached locally and then executed. If source is not passed, the config script located at \fBpath\fP will be compiled. Optional. .IP \(bu 2 \fBconfig_name\fP (\fI\%str\fP) \-\- The name of the Configuration within the script to apply. If the script contains multiple configurations within the file a \fBconfig_name\fP must be specified. If the \fBconfig_name\fP is not specified, the name of the file will be used as the \fBconfig_name\fP to run. Optional. .IP \(bu 2 \fBconfig_data\fP (\fI\%str\fP) \-\- .sp Configuration data in the form of a hash table that will be passed to the \fBConfigurationData\fP parameter when the \fBconfig_name\fP is compiled. This can be the path to a \fB\&.psd1\fP file containing the proper hash table or the PowerShell code to create the hash table. .sp New in version 2017.7.0. .IP \(bu 2 \fBconfig_data_source\fP (\fI\%str\fP) \-\- .sp The path to the \fB\&.psd1\fP file on \fBfile_roots\fP to cache at the location specified by \fBconfig_data\fP\&. If this is specified, \fBconfig_data\fP must be a local path instead of a hash table. .sp New in version 2017.7.0. .IP \(bu 2 \fBscript_parameters\fP (\fI\%str\fP) \-\- .sp Any additional parameters expected by the configuration script. These must be defined in the script itself. Note that these are passed to the script (the outermost scope), and not to the dsc configuration inside the script (the inner scope). .sp New in version 2017.7.0. .IP \(bu 2 \fBsalt_env\fP (\fI\%str\fP) \-\- The salt environment to use when copying the source. Default is \(aqbase\(aq .UNINDENT .TP .B Returns True if successfully compiled and applied, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .sp To compile a config from a script that already exists on the system: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.run_config C:\e\eDSC\e\eWebsiteConfig.ps1 .ft P .fi .UNINDENT .UNINDENT .sp To cache a config script to the system from the master and compile it: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.run_config C:\e\eDSC\e\eWebsiteConfig.ps1 salt://dsc/configs/WebsiteConfig.ps1 .ft P .fi .UNINDENT .UNINDENT .sp To cache a config script to the system from the master and compile it, passing in \fIscript_parameters\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.run_config path=C:\e\eDSC\e\eWebsiteConfig.ps1 source=salt://dsc/configs/WebsiteConfig.ps1 script_parameters=\(dq\-hostname \(aqmy\-computer\(aq \-ip \(aq192.168.1.10\(aq \-DnsArray \(aq192.168.1.3\(aq,\(aq192.168.1.4\(aq,\(aq1.1.1.1\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dsc.set_lcm_config(config_mode=None, config_mode_freq=None, refresh_freq=None, reboot_if_needed=None, action_after_reboot=None, refresh_mode=None, certificate_id=None, configuration_id=None, allow_module_overwrite=None, debug_mode=False, status_retention_days=None) For detailed descriptions of the parameters see: \fI\%https://msdn.microsoft.com/en\-us/PowerShell/DSC/metaConfig\fP .INDENT 7.0 .TP .B config_mode (str): How the LCM applies the configuration. Valid values are: .INDENT 7.0 .IP \(bu 2 ApplyOnly .IP \(bu 2 ApplyAndMonitor .IP \(bu 2 ApplyAndAutoCorrect .UNINDENT .TP .B config_mode_freq (int): How often, in minutes, the current configuration is checked and applied. Ignored if config_mode is set to ApplyOnly. Default is 15. .UNINDENT .sp refresh_mode (str): How the LCM gets configurations. Valid values are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Disabled .IP \(bu 2 Push .IP \(bu 2 Pull .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B refresh_freq (int): How often, in minutes, the LCM checks for updated configurations. (pull mode only) Default is 30. .TP .B reboot_if_needed (bool): Reboot the machine if needed after a configuration is applied. Default is False. .TP .B action_after_reboot (str): Action to take after reboot. Valid values are: .INDENT 7.0 .IP \(bu 2 ContinueConfiguration .IP \(bu 2 StopConfiguration .UNINDENT .TP .B certificate_id (guid): A GUID that specifies a certificate used to access the configuration: (pull mode) .TP .B configuration_id (guid): A GUID that identifies the config file to get from a pull server. (pull mode) .TP .B allow_module_overwrite (bool): New configs are allowed to overwrite old ones on the target node. .UNINDENT .sp debug_mode (str): Sets the debug level. Valid values are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 None .IP \(bu 2 ForceModuleImport .IP \(bu 2 All .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B status_retention_days (int): Number of days to keep status of the current config. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Either \fBconfig_mode_freq\fP or \fBrefresh_freq\fP needs to be a multiple of the other. See documentation on MSDN for more details. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.set_lcm_config ApplyOnly .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_dsc.test_config() Tests the current applied DSC Configuration .INDENT 7.0 .TP .B Returns True if successfully applied, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dsc.test_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_event .sp A module for working with the Windows Event log system. \&.. versionadded:: 3006.0 .INDENT 0.0 .TP .B salt.modules.win_event.add(log_name, event_id, event_category=0, event_type=None, event_strings=None, event_data=None, event_sid=None) Adds an event to the application event log. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBlog_name\fP (\fI\%str\fP) \-\- The name of the application or source .IP \(bu 2 \fBevent_id\fP (\fI\%int\fP) \-\- The event ID .IP \(bu 2 \fBevent_category\fP (\fI\%int\fP) \-\- The event category .IP \(bu 2 \fBevent_type\fP (\fI\%str\fP) \-\- .sp The event category. Must be one of: .INDENT 2.0 .IP \(bu 2 Success .IP \(bu 2 Error .IP \(bu 2 Warning .IP \(bu 2 Information .IP \(bu 2 AuditSuccess .IP \(bu 2 AuditFailure .UNINDENT .IP \(bu 2 \fBevent_strings\fP (\fI\%list\fP) \-\- A list of strings .IP \(bu 2 \fBevent_data\fP (\fI\%bytes\fP) \-\- Event data. Strings will be converted to bytes .IP \(bu 2 \fBevent_sid\fP (\fIsid\fP) \-\- The SID for the event .UNINDENT .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- event_id is not an integer .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- event_category is not an integer .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- event_type is not one of the valid event types .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- event_strings is not a list or string .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # A simple Application event log warning entry salt \(aq*\(aq win_event.add Application 1234 12 Warning # A more complex System event log information entry salt \(aq*\(aq win_event.add System 1234 12 Information \(dq[\(aqEvent string data 1\(aq, \(aqEvent string data 2\(aq]\(dq \(dqSome event data\(dq # Log to the System Event log with the source \(dqService Control Manager\(dq salt \(aq*\(aq win_event.add \(dqService Control Manager\(dq 1234 12 Warning \(dq[\(aqEvent string data 1\(aq, \(aqEvent string data 2\(aq]\(dq \(dqSome event data\(dq # Log to the PowerShell event log with the source \(dqPowerShell (PowerShell)\(dq salt\-call \-\-local win_event.add \(dqPowerShell\(dq 6969 12 Warning .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_event.clear(log_name, backup=None) Clears the specified event log. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A clear log event will be added to the log after it is cleared. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBlog_name\fP (\fI\%str\fP) \-\- The name of the log to clear .IP \(bu 2 \fBbackup\fP (\fI\%str\fP) \-\- Path to backup file .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq win_event.clear Application .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_event.count(log_name) Gets the number of events in the specified. .INDENT 7.0 .TP .B Parameters \fBlog_name\fP (\fI\%str\fP) \-\- The name of the log .TP .B Returns The number of events the log contains .TP .B Return type \fI\%int\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq win_event.count Application .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_event.get(log_name) Get events from the specified log. Get a list of available logs using the \fI\%win_event.get_log_names\fP function. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Running this command on a log with thousands of events, such as the \fBApplications\fP log, can take a long time. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBlog_name\fP (\fI\%str\fP) \-\- The name of the log to retrieve. .UNINDENT .INDENT 7.0 .TP .B Returns tuple: A tuple of events as dictionaries .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_event.get Application .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_event.get_filtered(log_name, all_requirements=True, **kwargs) Will find events that match the fields and values specified in the kwargs. Kwargs can be any item in the return for the event. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Running this command on a log with thousands of events, such as the \fBApplications\fP log, can take a long time. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBlog_name\fP (\fI\%str\fP) \-\- The name of the log to retrieve .IP \(bu 2 \fBall_requirements\fP (\fI\%bool\fP) \-\- \fBTrue\fP matches all requirements. \fBFalse\fP matches any requirement. Default is \fBTrue\fP .UNINDENT .UNINDENT .sp Kwargs: .INDENT 7.0 .INDENT 3.5 eventID (int): The event ID number .INDENT 0.0 .TP .B eventType (int): The event type number. Valid options and their corresponding meaning are: .INDENT 7.0 .IP \(bu 2 0 : Success .IP \(bu 2 1 : Error .IP \(bu 2 2 : Warning .IP \(bu 2 4 : Information .IP \(bu 2 8 : Audit Success .IP \(bu 2 10 : Audit Failure .UNINDENT .UNINDENT .sp year (int): The year .sp month (int): The month .sp day (int): The day of the month .sp hour (int): The hour .sp minute (int): The minute .sp second (int): The second .sp eventCategory (int): The event category number .sp sid (sid): The SID of the user that created the event .sp sourceName (str): The name of the event source .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns A tuple of dicts of each filtered event .TP .B Return type \fI\%tuple\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Return all events from the Security log with an ID of 1100 salt \(dq*\(dq win_event.get_filtered Security eventID=1100 # Return all events from the System log with an Error (1) event type salt \(dq*\(dq win_event.get_filtered System eventType=1 # Return all events from System log with an Error (1) type, source is Service Control Manager, and data is netprofm salt \(dq*\(dq win_event.get_filtered System eventType=1 sourceName=\(dqService Control Manager\(dq data=\(dqnetprofm\(dq # Return events from the System log that match any of the kwargs below salt \(dq*\(dq win_event.get_filtered System eventType=1 sourceName=\(dqService Control Manager\(dq data=\(dqnetprofm\(dq all_requirements=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_event.get_log_names() Get a list of event logs available on the system .INDENT 7.0 .TP .B Returns A list of event logs available on the system .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(dq*\(dq win_event.get_log_names .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_event.query(log_name, query_text=None, records=20, latest=True, raw=False) Query a log for a specific event_id. Return the top number of records specified. Use the \fI\%win_event.get_log_names\fP to see a list of available logs on the system. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 You can use the Windows Event Viewer to create the XPath query for the \fBquery_text\fP parameter. Click on \fBFilter Current Log\fP, configure the filter, then click on the XML tab. Copy the text between the two \fB<Select>\fP tags. This will be the contents of the \fBquery_text\fP parameter. You will have to convert some codes. For example, \fB>\fP becomes \fB>\fP, \fB<\fP becomes \fB<\fP\&. Additionally, you\(aqll need to put spaces between comparison operators. For example: \fBthis >= that\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBlog_name\fP (\fI\%str\fP) \-\- The name of the log to query .IP \(bu 2 \fBquery_text\fP (\fI\%str\fP) \-\- The filter to apply to the log .IP \(bu 2 \fBrecords\fP (\fI\%int\fP) \-\- The number of records to return .IP \(bu 2 \fBlatest\fP (\fI\%bool\fP) \-\- \fBTrue\fP will return the newest events. \fBFalse\fP will return the oldest events. Default is \fBTrue\fP .IP \(bu 2 \fBraw\fP (\fI\%bool\fP) \-\- \fBTrue\fP will return the raw xml results. \fBFalse\fP will return the xml converted to a dictionary. Default is \fBFalse\fP .UNINDENT .TP .B Returns A list of dict objects that contain information about the event .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Return the 20 most recent events from the Application log with an event ID of 22 salt \(aq*\(aq win_event.query Application \(dq*[System[(EventID=22)]]\(dq # Return the 20 most recent events from the Application log with an event ID of 22 # Return raw xml salt \(aq*\(aq win_event.query Application \(dq*[System[(EventID=22)]]\(dq raw=True # Return the 20 oldest events from the Application log with an event ID of 22 salt \(aq*\(aq win_event.query Application \(dq*[System[(EventID=22)]]\(dq latest=False # Return the 20 most recent Critical (1) events from the Application log in the last 12 hours salt \(aq*\(dq win_event.query Application \(dq*[System[(Level=1) and TimeCreated[timediff(@SystemTime) <= 43200000]]]\(dq # Return the 5 most recent Error (2) events from the application log salt \(aq*\(dq win_event.query Application \(dq*[System[(Level=2)]]\(dq records=5 # Return the 20 most recent Warning (3) events from the Windows PowerShell log where the Event Source is PowerShell salt \(aq*\(dq win_event.query \(dqWindows PowerShell\(dq \(dq*[System[Provider[@Name=\(aqPowerShell\(aq] and (Level=3)]]\(dq # Return the 20 most recent Information (0 or 4) events from the Microsoft\-Windows\-PowerShell/Operational on 2022\-08\-24 with an Event ID of 4103 salt \(aq*\(dq win_event.query \(dqMicrosoft\-Windows\-PowerShell/Operational\(dq \(dq*[System[(Level=4 or Level=0) and (EventID=4103) and TimeCreated[@SystemTime >= \(aq2022\-08\-24T06:00:00.000Z\(aq]]]\(dq # Return the 20 most recent Information (0 or 4) events from the Microsoft\-Windows\-PowerShell/Operational within the last hour salt \(aq*\(dq win_event.query \(dqMicrosoft\-Windows\-PowerShell/Operational\(dq \(dq*[System[(Level=4 or Level=0) and TimeCreated[timediff(@SystemTime) <= 3600000]]]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_file .sp Manage information about files on the minion, set/read user, group data, modify the ACL of files/directories .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 win32api .IP \(bu 2 win32file .IP \(bu 2 win32con .IP \(bu 2 salt.utils.win_dacl .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.check_perms(path, ret=None, owner=None, grant_perms=None, deny_perms=None, inheritance=True, reset=False) Check owner and permissions for the passed directory. This function checks the permissions and sets them, returning the changes made. Used by the file state to populate the return dict .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The full path to the directory. .IP \(bu 2 \fBret\fP (\fI\%dict\fP) \-\- A dictionary to append changes to and return. If not passed, will create a new dictionary to return. .IP \(bu 2 \fBowner\fP (\fI\%str\fP) \-\- The owner to set for the directory. .IP \(bu 2 \fBgrant_perms\fP (\fI\%dict\fP) \-\- A dictionary containing the user/group and the basic permissions to check/grant, ie: \fB{\(aquser\(aq: {\(aqperms\(aq: \(aqbasic_permission\(aq}}\fP\&. Default is \fBNone\fP\&. .IP \(bu 2 \fBdeny_perms\fP (\fI\%dict\fP) \-\- A dictionary containing the user/group and permissions to check/deny. Default is \fBNone\fP\&. .IP \(bu 2 \fBinheritance\fP (\fI\%bool\fP) \-\- \fBTrue will check if inheritance is enabled and enable it. \(ga\(gaFalse\fP will check if inheritance is disabled and disable it. Default is \fBTrue\fP\&. .IP \(bu 2 \fBreset\fP (\fI\%bool\fP) \-\- \fBTrue\fP will show what permissions will be removed by resetting the DACL. \fBFalse\fP will do nothing. Default is \fBFalse\fP\&. .UNINDENT .TP .B Returns A dictionary of changes that have been made .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # To see changes to \(ga\(gaC:\eTemp\(ga\(ga if the \(aqUsers\(aq group is given \(aqread & execute\(aq permissions. salt \(aq*\(aq file.check_perms C:\eTemp\e {} Administrators \(dq{\(aqUsers\(aq: {\(aqperms\(aq: \(aqread_execute\(aq}}\(dq # Locally using salt call salt\-call file.check_perms C:\eTemp\e {} Administrators \(dq{\(aqUsers\(aq: {\(aqperms\(aq: \(aqread_execute\(aq, \(aqapplies_to\(aq: \(aqthis_folder_only\(aq}}\(dq # Specify advanced attributes with a list salt \(aq*\(aq file.check_perms C:\eTemp\e {} Administrators \(dq{\(aqjsnuffy\(aq: {\(aqperms\(aq: [\(aqread_attributes\(aq, \(aqread_ea\(aq], \(aqapplies_to\(aq: \(aqfiles_only\(aq}}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.chgrp(path, group) Change the group of a file .sp Under Windows, this will do nothing. .sp While a file in Windows does have a \(aqprimary group\(aq, this rarely used attribute generally has no bearing on permissions unless intentionally configured and is only used to support Unix compatibility features (e.g. Services For Unix, NFS services). .sp Salt, therefore, remaps this function to do nothing while still being compatible with Unix behavior. When managing Windows systems, this function is superfluous and will generate an info level log entry if used directly. .sp If you do actually want to set the \(aqprimary group\(aq of a file, use \fBfile \&.chpgrp\fP\&. .sp To set group permissions use \fBfile.set_perms\fP .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- The group (unused) .UNINDENT .TP .B Returns None .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.chgrp c:\etemp\etest.txt administrators .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.chown(path, user, group=None, pgroup=None, follow_symlinks=True) Chown a file, pass the file the desired user and group .sp Under Windows, the group parameter will be ignored. .sp This is because while files in Windows do have a \(aqprimary group\(aq property, this is rarely used. It generally has no bearing on permissions unless intentionally configured and is most commonly used to provide Unix compatibility (e.g. Services For Unix, NFS services). .sp If you do want to change the \(aqprimary group\(aq property and understand the implications, pass the Windows only parameter, pgroup, instead. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .IP \(bu 2 \fBuser\fP (\fI\%str\fP) \-\- The name of the user to own the file .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- The group (not used) .IP \(bu 2 \fBpgroup\fP (\fI\%str\fP) \-\- The primary group to assign .IP \(bu 2 \fBfollow_symlinks\fP (\fI\%bool\fP) \-\- If the object specified by \fBpath\fP is a symlink, get attributes of the linked file instead of the symlink itself. Default is True .UNINDENT .TP .B Returns True if successful, otherwise error .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.chown c:\etemp\etest.txt myusername salt \(aq*\(aq file.chown c:\etemp\etest.txt myusername pgroup=Administrators salt \(aq*\(aq file.chown c:\etemp\etest.txt myusername \(dqpgroup=\(aqNone\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.chpgrp(path, group) Change the group of a file .sp Under Windows, this will set the rarely used primary group of a file. This generally has no bearing on permissions unless intentionally configured and is most commonly used to provide Unix compatibility (e.g. Services For Unix, NFS services). .sp Ensure you know what you are doing before using this function. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .IP \(bu 2 \fBpgroup\fP (\fI\%str\fP) \-\- The primary group to assign .UNINDENT .TP .B Returns True if successful, otherwise error .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.chpgrp c:\etemp\etest.txt Administrators salt \(aq*\(aq file.chpgrp c:\etemp\etest.txt \(dq\(aqNone\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_attributes(path) Return a dictionary object with the Windows file attributes for a file. .INDENT 7.0 .TP .B Parameters \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .TP .B Returns A dictionary of file attributes .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_attributes c:\etemp\ea.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_gid(path, follow_symlinks=True) Return the id of the group that owns a given file .sp Under Windows, this will return the uid of the file. .sp While a file in Windows does have a \(aqprimary group\(aq, this rarely used attribute generally has no bearing on permissions unless intentionally configured and is only used to support Unix compatibility features (e.g. Services For Unix, NFS services). .sp Salt, therefore, remaps this function to provide functionality that somewhat resembles Unix behavior for API compatibility reasons. When managing Windows systems, this function is superfluous and will generate an info level log entry if used directly. .sp If you do actually want to access the \(aqprimary group\(aq of a file, use \fIfile.get_pgid\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .IP \(bu 2 \fBfollow_symlinks\fP (\fI\%bool\fP) \-\- If the object specified by \fBpath\fP is a symlink, get attributes of the linked file instead of the symlink itself. Default is True .UNINDENT .TP .B Returns The gid of the owner .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_gid c:\etemp\etest.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_group(path, follow_symlinks=True) Return the group that owns a given file .sp Under Windows, this will return the user (owner) of the file. .sp While a file in Windows does have a \(aqprimary group\(aq, this rarely used attribute generally has no bearing on permissions unless intentionally configured and is only used to support Unix compatibility features (e.g. Services For Unix, NFS services). .sp Salt, therefore, remaps this function to provide functionality that somewhat resembles Unix behavior for API compatibility reasons. When managing Windows systems, this function is superfluous and will generate an info level log entry if used directly. .sp If you do actually want to access the \(aqprimary group\(aq of a file, use \fIfile.get_pgroup\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .IP \(bu 2 \fBfollow_symlinks\fP (\fI\%bool\fP) \-\- If the object specified by \fBpath\fP is a symlink, get attributes of the linked file instead of the symlink itself. Default is True .UNINDENT .TP .B Returns The name of the owner .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_group c:\etemp\etest.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_mode(path) Return the mode of a file .sp Right now we\(aqre just returning None because Windows\(aq doesn\(aqt have a mode like Linux .INDENT 7.0 .TP .B Parameters \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .TP .B Returns None .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_mode /etc/passwd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_pgid(path, follow_symlinks=True) Return the id of the primary group that owns a given file (Windows only) .sp This function will return the rarely used primary group of a file. This generally has no bearing on permissions unless intentionally configured and is most commonly used to provide Unix compatibility (e.g. Services For Unix, NFS services). .sp Ensure you know what you are doing before using this function. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .IP \(bu 2 \fBfollow_symlinks\fP (\fI\%bool\fP) \-\- If the object specified by \fBpath\fP is a symlink, get attributes of the linked file instead of the symlink itself. Default is True .UNINDENT .TP .B Returns The gid of the primary group .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_pgid c:\etemp\etest.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_pgroup(path, follow_symlinks=True) Return the name of the primary group that owns a given file (Windows only) .sp This function will return the rarely used primary group of a file. This generally has no bearing on permissions unless intentionally configured and is most commonly used to provide Unix compatibility (e.g. Services For Unix, NFS services). .sp Ensure you know what you are doing before using this function. .sp The return value may be \(aqNone\(aq, e.g. if the user is not on a domain. This is a valid group \- do not confuse this with the Salt/Python value of None which means no value was returned. To be certain, use the \fIget_pgid\fP function which will return the SID, including for the system \(aqNone\(aq group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .IP \(bu 2 \fBfollow_symlinks\fP (\fI\%bool\fP) \-\- If the object specified by \fBpath\fP is a symlink, get attributes of the linked file instead of the symlink itself. Default is True .UNINDENT .TP .B Returns The name of the primary group .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_pgroup c:\etemp\etest.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_uid(path, follow_symlinks=True) Return the id of the user that owns a given file .sp Symlinks are followed by default to mimic Unix behavior. Specify \fIfollow_symlinks=False\fP to turn off this behavior. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .IP \(bu 2 \fBfollow_symlinks\fP (\fI\%bool\fP) \-\- If the object specified by \fBpath\fP is a symlink, get attributes of the linked file instead of the symlink itself. Default is True .UNINDENT .TP .B Returns The uid of the owner .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_uid c:\etemp\etest.txt salt \(aq*\(aq file.get_uid c:\etemp\etest.txt follow_symlinks=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_user(path, follow_symlinks=True) Return the user that owns a given file .sp Symlinks are followed by default to mimic Unix behavior. Specify \fIfollow_symlinks=False\fP to turn off this behavior. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .IP \(bu 2 \fBfollow_symlinks\fP (\fI\%bool\fP) \-\- If the object specified by \fBpath\fP is a symlink, get attributes of the linked file instead of the symlink itself. Default is True .UNINDENT .TP .B Returns The name of the owner .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_user c:\etemp\etest.txt salt \(aq*\(aq file.get_user c:\etemp\etest.txt follow_symlinks=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.gid_to_group(gid) Convert the group id to the group name on this system .sp Under Windows, because groups are just another ACL entity, this function behaves the same as uid_to_user. .sp For maintaining Windows systems, this function is superfluous and only exists for API compatibility with Unix. Use the uid_to_user function instead; an info level log entry will be generated if this function is used directly. .INDENT 7.0 .TP .B Parameters \fBgid\fP (\fI\%str\fP) \-\- The gid of the group .TP .B Returns The name of the group .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.gid_to_group S\-1\-5\-21\-626487655\-2533044672\-482107328\-1010 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.group_to_gid(group) Convert the group to the gid on this system .sp Under Windows, because groups are just another ACL entity, this function behaves the same as user_to_uid, except if None is given, \(aq\(aq is returned. .sp For maintaining Windows systems, this function is superfluous and only exists for API compatibility with Unix. Use the user_to_uid function instead; an info level log entry will be generated if this function is used directly. .INDENT 7.0 .TP .B Parameters \fBgroup\fP (\fI\%str\fP) \-\- The name of the group .TP .B Returns The gid of the group .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.group_to_gid administrators .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.is_link(path) Check if the path is a symlink .sp This is only supported on Windows Vista or later. .sp Inline with Unix behavior, this function will raise an error if the path is not a symlink, however, the error raised will be a SaltInvocationError, not an OSError. .INDENT 7.0 .TP .B Parameters \fBpath\fP (\fI\%str\fP) \-\- The path to a file or directory .TP .B Returns True if path is a symlink, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.is_link /path/to/link .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.lchown(path, user, group=None, pgroup=None) Chown a file, pass the file the desired user and group without following any symlinks. .sp Under Windows, the group parameter will be ignored. .sp This is because while files in Windows do have a \(aqprimary group\(aq property, this is rarely used. It generally has no bearing on permissions unless intentionally configured and is most commonly used to provide Unix compatibility (e.g. Services For Unix, NFS services). .sp If you do want to change the \(aqprimary group\(aq property and understand the implications, pass the Windows only parameter, pgroup, instead. .sp To set the primary group to \(aqNone\(aq, it must be specified in quotes. Otherwise Salt will interpret it as the Python value of None and no primary group changes will occur. See the example below. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .IP \(bu 2 \fBuser\fP (\fI\%str\fP) \-\- The name of the user to own the file .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- The group (not used) .IP \(bu 2 \fBpgroup\fP (\fI\%str\fP) \-\- The primary group to assign .UNINDENT .TP .B Returns True if successful, otherwise error .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.lchown c:\etemp\etest.txt myusername salt \(aq*\(aq file.lchown c:\etemp\etest.txt myusername pgroup=Administrators salt \(aq*\(aq file.lchown c:\etemp\etest.txt myusername \(dqpgroup=\(aqNone\(aq\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.makedirs_(path, owner=None, grant_perms=None, deny_perms=None, inheritance=True, reset=False) Ensure that the parent directory containing this path is available. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- .sp The full path to the directory. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The path must end with a trailing slash otherwise the directory(s) will be created up to the parent directory. For example if path is \fBC:\etemp\etest\fP, then it would be treated as \fBC:\etemp\e\fP but if the path ends with a trailing slash like \fBC:\etemp\etest\e\fP, then it would be treated as \fBC:\etemp\etest\e\fP\&. .UNINDENT .UNINDENT .IP \(bu 2 \fBowner\fP (\fI\%str\fP) \-\- The owner of the directory. If not passed, it will be the account that created the directory, likely SYSTEM. .IP \(bu 2 \fBgrant_perms\fP (\fI\%dict\fP) \-\- .sp A dictionary containing the user/group and the basic permissions to grant, ie: \fB{\(aquser\(aq: {\(aqperms\(aq: \(aqbasic_permission\(aq}}\fP\&. You can also set the \fBapplies_to\fP setting here. The default is \fBthis_folder_subfolders_files\fP\&. Specify another \fBapplies_to\fP setting like this: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C {\(aquser\(aq: {\(aqperms\(aq: \(aqfull_control\(aq, \(aqapplies_to\(aq: \(aqthis_folder\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp To set advanced permissions use a list for the \fBperms\fP parameter, ie: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C {\(aquser\(aq: {\(aqperms\(aq: [\(aqread_attributes\(aq, \(aqread_ea\(aq], \(aqapplies_to\(aq: \(aqthis_folder\(aq}} .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBdeny_perms\fP (\fI\%dict\fP) \-\- A dictionary containing the user/group and permissions to deny along with the \fBapplies_to\fP setting. Use the same format used for the \fBgrant_perms\fP parameter. Remember, deny permissions supersede grant permissions. .IP \(bu 2 \fBinheritance\fP (\fI\%bool\fP) \-\- If True the object will inherit permissions from the parent, if False, inheritance will be disabled. Inheritance setting will not apply to parent directories if they must be created. .IP \(bu 2 \fBreset\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP the existing DACL will be cleared and replaced with the settings defined in this function. If \fBFalse\fP, new entries will be appended to the existing DACL. Default is \fBFalse\fP\&. .sp New in version 2018.3.0. .UNINDENT .TP .B Returns True if successful .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If unsuccessful .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # To grant the \(aqUsers\(aq group \(aqread & execute\(aq permissions. salt \(aq*\(aq file.makedirs C:\eTemp\e Administrators \(dq{\(aqUsers\(aq: {\(aqperms\(aq: \(aqread_execute\(aq}}\(dq # Locally using salt call salt\-call file.makedirs C:\eTemp\e Administrators \(dq{\(aqUsers\(aq: {\(aqperms\(aq: \(aqread_execute\(aq, \(aqapplies_to\(aq: \(aqthis_folder_only\(aq}}\(dq # Specify advanced attributes with a list salt \(aq*\(aq file.makedirs C:\eTemp\e Administrators \(dq{\(aqjsnuffy\(aq: {\(aqperms\(aq: [\(aqread_attributes\(aq, \(aqread_ea\(aq], \(aqapplies_to\(aq: \(aqthis_folder_only\(aq}}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.makedirs_perms(path, owner=None, grant_perms=None, deny_perms=None, inheritance=True, reset=True) Set owner and permissions for each directory created. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The full path to the directory. .IP \(bu 2 \fBowner\fP (\fI\%str\fP) \-\- The owner of the directory. If not passed, it will be the account that created the directory, likely SYSTEM. .IP \(bu 2 \fBgrant_perms\fP (\fI\%dict\fP) \-\- .sp A dictionary containing the user/group and the basic permissions to grant, ie: \fB{\(aquser\(aq: {\(aqperms\(aq: \(aqbasic_permission\(aq}}\fP\&. You can also set the \fBapplies_to\fP setting here. The default is \fBthis_folder_subfolders_files\fP\&. Specify another \fBapplies_to\fP setting like this: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C {\(aquser\(aq: {\(aqperms\(aq: \(aqfull_control\(aq, \(aqapplies_to\(aq: \(aqthis_folder\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp To set advanced permissions use a list for the \fBperms\fP parameter, ie: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C {\(aquser\(aq: {\(aqperms\(aq: [\(aqread_attributes\(aq, \(aqread_ea\(aq], \(aqapplies_to\(aq: \(aqthis_folder\(aq}} .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBdeny_perms\fP (\fI\%dict\fP) \-\- A dictionary containing the user/group and permissions to deny along with the \fBapplies_to\fP setting. Use the same format used for the \fBgrant_perms\fP parameter. Remember, deny permissions supersede grant permissions. .IP \(bu 2 \fBinheritance\fP (\fI\%bool\fP) \-\- If \fBTrue\fP the object will inherit permissions from the parent, if \fBFalse\fP, inheritance will be disabled. Inheritance setting will not apply to parent directories if they must be created .IP \(bu 2 \fBreset\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP the existing DACL will be cleared and replaced with the settings defined in this function. If \fBFalse\fP, new entries will be appended to the existing DACL. Default is \fBFalse\fP\&. .sp New in version 2018.3.0. .UNINDENT .TP .B Returns True if successful, otherwise raises an error .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # To grant the \(aqUsers\(aq group \(aqread & execute\(aq permissions. salt \(aq*\(aq file.makedirs_perms C:\eTemp\e Administrators \(dq{\(aqUsers\(aq: {\(aqperms\(aq: \(aqread_execute\(aq}}\(dq # Locally using salt call salt\-call file.makedirs_perms C:\eTemp\e Administrators \(dq{\(aqUsers\(aq: {\(aqperms\(aq: \(aqread_execute\(aq, \(aqapplies_to\(aq: \(aqthis_folder_only\(aq}}\(dq # Specify advanced attributes with a list salt \(aq*\(aq file.makedirs_perms C:\eTemp\e Administrators \(dq{\(aqjsnuffy\(aq: {\(aqperms\(aq: [\(aqread_attributes\(aq, \(aqread_ea\(aq], \(aqapplies_to\(aq: \(aqthis_folder_files\(aq}}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.mkdir(path, owner=None, grant_perms=None, deny_perms=None, inheritance=True, reset=False) Ensure that the directory is available and permissions are set. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The full path to the directory. .IP \(bu 2 \fBowner\fP (\fI\%str\fP) \-\- The owner of the directory. If not passed, it will be the account that created the directory, likely SYSTEM .IP \(bu 2 \fBgrant_perms\fP (\fI\%dict\fP) \-\- .sp A dictionary containing the user/group and the basic permissions to grant, ie: \fB{\(aquser\(aq: {\(aqperms\(aq: \(aqbasic_permission\(aq}}\fP\&. You can also set the \fBapplies_to\fP setting here. The default is \fBthis_folder_subfolders_files\fP\&. Specify another \fBapplies_to\fP setting like this: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C {\(aquser\(aq: {\(aqperms\(aq: \(aqfull_control\(aq, \(aqapplies_to\(aq: \(aqthis_folder\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp To set advanced permissions use a list for the \fBperms\fP parameter, ie: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C {\(aquser\(aq: {\(aqperms\(aq: [\(aqread_attributes\(aq, \(aqread_ea\(aq], \(aqapplies_to\(aq: \(aqthis_folder\(aq}} .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBdeny_perms\fP (\fI\%dict\fP) \-\- A dictionary containing the user/group and permissions to deny along with the \fBapplies_to\fP setting. Use the same format used for the \fBgrant_perms\fP parameter. Remember, deny permissions supersede grant permissions. .IP \(bu 2 \fBinheritance\fP (\fI\%bool\fP) \-\- If True the object will inherit permissions from the parent, if \fBFalse\fP, inheritance will be disabled. Inheritance setting will not apply to parent directories if they must be created. .IP \(bu 2 \fBreset\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP the existing DACL will be cleared and replaced with the settings defined in this function. If \fBFalse\fP, new entries will be appended to the existing DACL. Default is \fBFalse\fP\&. .sp New in version 2018.3.0. .UNINDENT .TP .B Returns True if successful .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If unsuccessful .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # To grant the \(aqUsers\(aq group \(aqread & execute\(aq permissions. salt \(aq*\(aq file.mkdir C:\eTemp\e Administrators \(dq{\(aqUsers\(aq: {\(aqperms\(aq: \(aqread_execute\(aq}}\(dq # Locally using salt call salt\-call file.mkdir C:\eTemp\e Administrators \(dq{\(aqUsers\(aq: {\(aqperms\(aq: \(aqread_execute\(aq, \(aqapplies_to\(aq: \(aqthis_folder_only\(aq}}\(dq # Specify advanced attributes with a list salt \(aq*\(aq file.mkdir C:\eTemp\e Administrators \(dq{\(aqjsnuffy\(aq: {\(aqperms\(aq: [\(aqread_attributes\(aq, \(aqread_ea\(aq], \(aqapplies_to\(aq: \(aqthis_folder_only\(aq}}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.remove(path, force=False) Remove the named file or directory .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory to remove. .IP \(bu 2 \fBforce\fP (\fI\%bool\fP) \-\- Remove even if marked Read\-Only. Default is False .UNINDENT .TP .B Returns True if successful, False if unsuccessful .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.remove C:\eTemp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.set_attributes(path, archive=None, hidden=None, normal=None, notIndexed=None, readonly=None, system=None, temporary=None) Set file attributes for a file. Note that the normal attribute means that all others are false. So setting it will clear all others. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .IP \(bu 2 \fBarchive\fP (\fI\%bool\fP) \-\- Sets the archive attribute. Default is None .IP \(bu 2 \fBhidden\fP (\fI\%bool\fP) \-\- Sets the hidden attribute. Default is None .IP \(bu 2 \fBnormal\fP (\fI\%bool\fP) \-\- Resets the file attributes. Cannot be used in conjunction with any other attribute. Default is None .IP \(bu 2 \fBnotIndexed\fP (\fI\%bool\fP) \-\- Sets the indexed attribute. Default is None .IP \(bu 2 \fBreadonly\fP (\fI\%bool\fP) \-\- Sets the readonly attribute. Default is None .IP \(bu 2 \fBsystem\fP (\fI\%bool\fP) \-\- Sets the system attribute. Default is None .IP \(bu 2 \fBtemporary\fP (\fI\%bool\fP) \-\- Sets the temporary attribute. Default is None .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.set_attributes c:\etemp\ea.txt normal=True salt \(aq*\(aq file.set_attributes c:\etemp\ea.txt readonly=True hidden=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.set_mode(path, mode) Set the mode of a file .sp This just calls get_mode, which returns None because we don\(aqt use mode on Windows .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- The path to the file or directory .IP \(bu 2 \fBmode\fP \-\- The mode (not used) .UNINDENT .TP .B Returns None .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.set_mode /etc/passwd 0644 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.set_perms(path, grant_perms=None, deny_perms=None, inheritance=True, reset=False) Set permissions for the given path .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The full path to the directory. .IP \(bu 2 \fBgrant_perms\fP (\fI\%dict\fP) \-\- .sp A dictionary containing the user/group and the basic permissions to grant, ie: \fB{\(aquser\(aq: {\(aqperms\(aq: \(aqbasic_permission\(aq}}\fP\&. You can also set the \fBapplies_to\fP setting here for directories. The default for \fBapplies_to\fP is \fBthis_folder_subfolders_files\fP\&. Specify another \fBapplies_to\fP setting like this: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C {\(aquser\(aq: {\(aqperms\(aq: \(aqfull_control\(aq, \(aqapplies_to\(aq: \(aqthis_folder\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp To set advanced permissions use a list for the \fBperms\fP parameter, ie: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C {\(aquser\(aq: {\(aqperms\(aq: [\(aqread_attributes\(aq, \(aqread_ea\(aq], \(aqapplies_to\(aq: \(aqthis_folder\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp To see a list of available attributes and applies to settings see the documentation for salt.utils.win_dacl. .sp A value of \fBNone\fP will make no changes to the \fBgrant\fP portion of the DACL. Default is \fBNone\fP\&. .IP \(bu 2 \fBdeny_perms\fP (\fI\%dict\fP) \-\- .sp A dictionary containing the user/group and permissions to deny along with the \fBapplies_to\fP setting. Use the same format used for the \fBgrant_perms\fP parameter. Remember, deny permissions supersede grant permissions. .sp A value of \fBNone\fP will make no changes to the \fBdeny\fP portion of the DACL. Default is \fBNone\fP\&. .IP \(bu 2 \fBinheritance\fP (\fI\%bool\fP) \-\- If \fBTrue\fP the object will inherit permissions from the parent, if \fBFalse\fP, inheritance will be disabled. Inheritance setting will not apply to parent directories if they must be created. Default is \fBFalse\fP\&. .IP \(bu 2 \fBreset\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP the existing DCL will be cleared and replaced with the settings defined in this function. If \fBFalse\fP, new entries will be appended to the existing DACL. Default is \fBFalse\fP\&. .sp New in version 2018.3.0. .UNINDENT .TP .B Returns True if successful .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If unsuccessful .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # To grant the \(aqUsers\(aq group \(aqread & execute\(aq permissions. salt \(aq*\(aq file.set_perms C:\eTemp\e \(dq{\(aqUsers\(aq: {\(aqperms\(aq: \(aqread_execute\(aq}}\(dq # Locally using salt call salt\-call file.set_perms C:\eTemp\e \(dq{\(aqUsers\(aq: {\(aqperms\(aq: \(aqread_execute\(aq, \(aqapplies_to\(aq: \(aqthis_folder_only\(aq}}\(dq # Specify advanced attributes with a list salt \(aq*\(aq file.set_perms C:\eTemp\e \(dq{\(aqjsnuffy\(aq: {\(aqperms\(aq: [\(aqread_attributes\(aq, \(aqread_ea\(aq], \(aqapplies_to\(aq: \(aqthis_folder_only\(aq}}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.stats(path, hash_type=\(aqsha256\(aq, follow_symlinks=True) Return a dict containing the stats about a given file .sp Under Windows, \fIgid\fP will equal \fIuid\fP and \fIgroup\fP will equal \fIuser\fP\&. .sp While a file in Windows does have a \(aqprimary group\(aq, this rarely used attribute generally has no bearing on permissions unless intentionally configured and is only used to support Unix compatibility features (e.g. Services For Unix, NFS services). .sp Salt, therefore, remaps these properties to keep some kind of compatibility with Unix behavior. If the \(aqprimary group\(aq is required, it can be accessed in the \fIpgroup\fP and \fIpgid\fP properties. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path to the file or directory .IP \(bu 2 \fBhash_type\fP (\fI\%str\fP) \-\- The type of hash to return .IP \(bu 2 \fBfollow_symlinks\fP (\fI\%bool\fP) \-\- If the object specified by \fBpath\fP is a symlink, get attributes of the linked file instead of the symlink itself. Default is True .UNINDENT .TP .B Returns A dictionary of file/directory stats .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.stats /etc/passwd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.symlink(src, link, force=False, atomic=False, follow_symlinks=True) Create a symbolic link to a file .sp This is only supported with Windows Vista or later and must be executed by a user with the SeCreateSymbolicLink privilege. .sp The behavior of this function matches the Unix equivalent, with one exception \- invalid symlinks cannot be created. The source path must exist. If it doesn\(aqt, an error will be raised. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsrc\fP (\fI\%str\fP) \-\- The path to a file or directory .IP \(bu 2 \fBlink\fP (\fI\%str\fP) \-\- The path to the link. Must be an absolute path .IP \(bu 2 \fBforce\fP (\fI\%bool\fP) \-\- Overwrite an existing symlink with the same name \&.. versionadded:: 3005 .IP \(bu 2 \fBatomic\fP (\fI\%bool\fP) \-\- Use atomic file operations to create the symlink \&.. versionadded:: 3006.0 .IP \(bu 2 \fBfollow_symlinks\fP (\fI\%bool\fP) \-\- If set to \fBFalse\fP, use \fBos.path.lexists()\fP for existence checks instead of \fBos.path.exists()\fP\&. \&.. versionadded:: 3007.0 .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise raises \fBCommandExecutionError\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.symlink /path/to/file /path/to/link .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.uid_to_user(uid) Convert a uid to a user name .INDENT 7.0 .TP .B Parameters \fBuid\fP (\fI\%str\fP) \-\- The user id to lookup .TP .B Returns The name of the user .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.uid_to_user S\-1\-5\-21\-626487655\-2533044672\-482107328\-1010 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.user_to_uid(user) Convert user name to a uid .INDENT 7.0 .TP .B Parameters \fBuser\fP (\fI\%str\fP) \-\- The user to lookup .TP .B Returns The user id of the user .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.user_to_uid myusername .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.version(path) New in version 3005. .sp Get the version of a file. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Not all files have version information. The following are common file types that contain version information: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \&.exe .IP \(bu 2 \&.dll .IP \(bu 2 \&.sys .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBpath\fP (\fI\%str\fP) \-\- The path to the file. .TP .B Returns .INDENT 7.0 .TP .B The version of the file if the file contains it. Otherwise, an empty string will be returned. .UNINDENT .TP .B Return type \fI\%str\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If the file does not exist .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If the path is not a file .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt * file.version C:\eWindows\enotepad.exe .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.version_details(path) New in version 3005. .sp Get file details for a file. Similar to what\(aqs in the details tab on the file properties. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Not all files have version information. The following are common file types that contain version information: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \&.exe .IP \(bu 2 \&.dll .IP \(bu 2 \&.sys .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBpath\fP (\fI\%str\fP) \-\- The path to the file. .TP .B Returns .INDENT 7.0 .TP .B A dictionary containing details about the file related to version. An empty dictionary if the file contains no version information. .UNINDENT .TP .B Return type \fI\%dict\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If the file does not exist .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If the path is not a file .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt * file.version_details C:\eWindows\enotepad.exe .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_firewall .sp Module for configuring Windows Firewall using \fBnetsh\fP .INDENT 0.0 .TP .B salt.modules.win_firewall.add_rule(name, localport, protocol=\(aqtcp\(aq, action=\(aqallow\(aq, dir=\(aqin\(aq, remoteip=\(aqany\(aq) New in version 2015.5.0. .sp Add a new inbound or outbound rule to the firewall policy .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the rule. Must be unique and cannot be \(dqall\(dq. Required. .IP \(bu 2 \fBlocalport\fP (\fI\%int\fP) \-\- The port the rule applies to. Must be a number between 0 and 65535. Can be a range. Can specify multiple ports separated by commas. Required. .IP \(bu 2 \fBprotocol\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- .sp The protocol. Can be any of the following: .INDENT 2.0 .IP \(bu 2 A number between 0 and 255 .IP \(bu 2 icmpv4 .IP \(bu 2 icmpv6 .IP \(bu 2 tcp .IP \(bu 2 udp .IP \(bu 2 any .UNINDENT .IP \(bu 2 \fBaction\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- .sp The action the rule performs. Can be any of the following: .INDENT 2.0 .IP \(bu 2 allow .IP \(bu 2 block .IP \(bu 2 bypass .UNINDENT .IP \(bu 2 \fBdir\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The direction. Can be \fBin\fP or \fBout\fP\&. .IP \(bu 2 \fBremoteip\fP (\fIOptional\fP\fI [\fP\fI\%str\fP\fI]\fP) \-\- .sp The remote IP. Can be any of the following: .INDENT 2.0 .IP \(bu 2 any .IP \(bu 2 localsubnet .IP \(bu 2 dns .IP \(bu 2 dhcp .IP \(bu 2 wins .IP \(bu 2 defaultgateway .IP \(bu 2 Any valid IPv4 address (192.168.0.12) .IP \(bu 2 Any valid IPv6 address (2002:9b3b:1a31:4:208:74ff:fe39:6c43) .IP \(bu 2 Any valid subnet (192.168.1.0/24) .IP \(bu 2 Any valid range of IP addresses (192.168.0.1\-192.168.0.12) .IP \(bu 2 A list of valid IP addresses .UNINDENT .sp Can be combinations of the above separated by commas. .UNINDENT .TP .B Returns True if successful .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If the command fails .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewall.add_rule \(aqtest\(aq \(aq8080\(aq \(aqtcp\(aq salt \(aq*\(aq firewall.add_rule \(aqtest\(aq \(aq1\(aq \(aqicmpv4\(aq salt \(aq*\(aq firewall.add_rule \(aqtest_remote_ip\(aq \(aq8000\(aq \(aqtcp\(aq \(aqallow\(aq \(aqin\(aq \(aq192.168.0.1\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.delete_rule(name=None, localport=None, protocol=None, dir=None, remoteip=None) New in version 2015.8.0. .sp Delete an existing firewall rule identified by name and optionally by ports, protocols, direction, and remote IP. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the rule to delete. If the name \fBall\fP is used you must specify additional parameters. .IP \(bu 2 \fBlocalport\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The port of the rule. If protocol is not specified, protocol will be set to \fBtcp\fP .IP \(bu 2 \fBprotocol\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The protocol of the rule. Default is \fBtcp\fP when \fBlocalport\fP is specified .IP \(bu 2 \fBdir\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The direction of the rule. .IP \(bu 2 \fBremoteip\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The remote IP of the rule. .UNINDENT .TP .B Returns True if successful .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If the command fails .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Delete incoming tcp port 8080 in the rule named \(aqtest\(aq salt \(aq*\(aq firewall.delete_rule \(aqtest\(aq \(aq8080\(aq \(aqtcp\(aq \(aqin\(aq # Delete the incoming tcp port 8000 from 192.168.0.1 in the rule named # \(aqtest_remote_ip\(aq salt \(aq*\(aq firewall.delete_rule \(aqtest_remote_ip\(aq \(aq8000\(aq \(aqtcp\(aq \(aqin\(aq \(aq192.168.0.1\(aq # Delete all rules for local port 80: salt \(aq*\(aq firewall.delete_rule all 80 tcp # Delete a rule called \(aqallow80\(aq: salt \(aq*\(aq firewall.delete_rule allow80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.disable(profile=\(aqallprofiles\(aq) Disable firewall profile .INDENT 7.0 .TP .B Parameters \fBprofile\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- .sp The name of the profile to disable. Default is \fBallprofiles\fP\&. Valid options are: .INDENT 7.0 .IP \(bu 2 allprofiles .IP \(bu 2 domainprofile .IP \(bu 2 privateprofile .IP \(bu 2 publicprofile .UNINDENT .TP .B Returns True if successful .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If the command fails .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewall.disable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.enable(profile=\(aqallprofiles\(aq) New in version 2015.5.0. .sp Enable firewall profile .INDENT 7.0 .TP .B Parameters \fBprofile\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- .sp The name of the profile to enable. Default is \fBallprofiles\fP\&. Valid options are: .INDENT 7.0 .IP \(bu 2 allprofiles .IP \(bu 2 domainprofile .IP \(bu 2 privateprofile .IP \(bu 2 publicprofile .UNINDENT .TP .B Returns True if successful .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If the command fails .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewall.enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.get_all_profiles(store=\(aqlocal\(aq) Gets all properties for all profiles in the specified store .sp New in version 2018.3.4. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters \fBstore\fP (\fI\%str\fP) \-\- .sp The store to use. This is either the local firewall policy or the policy defined by local group policy. Valid options are: .INDENT 7.0 .IP \(bu 2 lgpo .IP \(bu 2 local .UNINDENT .sp Default is \fBlocal\fP .TP .B Returns A dictionary containing the specified settings for each profile .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Get all firewall settings for all profiles salt * firewall.get_all_settings # Get all firewall settings for all profiles as defined by local group # policy salt * firewall.get_all_settings lgpo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.get_all_settings(domain, store=\(aqlocal\(aq) Gets all the properties for the specified profile in the specified store .sp New in version 2018.3.4. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fI\%str\fP) \-\- .sp The firewall profile to query. Valid options are: .INDENT 2.0 .IP \(bu 2 domain .IP \(bu 2 public .IP \(bu 2 private .UNINDENT .IP \(bu 2 \fBstore\fP (\fI\%str\fP) \-\- .sp The store to use. This is either the local firewall policy or the policy defined by local group policy. Valid options are: .INDENT 2.0 .IP \(bu 2 lgpo .IP \(bu 2 local .UNINDENT .sp Default is \fBlocal\fP .UNINDENT .TP .B Returns A dictionary containing the specified settings .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Get all firewall settings for connections on the domain profile salt * win_firewall.get_all_settings domain # Get all firewall settings for connections on the domain profile as # defined by local group policy salt * win_firewall.get_all_settings domain lgpo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.get_config() Get the status of all the firewall profiles .INDENT 7.0 .TP .B Returns A dictionary of all profiles on the system .TP .B Return type \fI\%dict\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If the command fails .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewall.get_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.get_rule(name=\(aqall\(aq) New in version 2015.5.0. .sp Display all matching rules as specified by name .INDENT 7.0 .TP .B Parameters \fBname\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The full name of the rule. \fBall\fP will return all rules. Default is \fBall\fP .TP .B Returns A dictionary of all rules or rules that match the name exactly .TP .B Return type \fI\%dict\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If the command fails .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq firewall.get_rule \(aqMyAppPort\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.get_settings(profile, section, store=\(aqlocal\(aq) Get the firewall property from the specified profile in the specified store as returned by \fBnetsh advfirewall\fP\&. .sp New in version 2018.3.4. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fI\%str\fP) \-\- .sp The firewall profile to query. Valid options are: .INDENT 2.0 .IP \(bu 2 domain .IP \(bu 2 public .IP \(bu 2 private .UNINDENT .IP \(bu 2 \fBsection\fP (\fI\%str\fP) \-\- .sp The property to query within the selected profile. Valid options are: .INDENT 2.0 .IP \(bu 2 firewallpolicy : inbound/outbound behavior .IP \(bu 2 logging : firewall logging settings .IP \(bu 2 settings : firewall properties .IP \(bu 2 state : firewalls state (on | off) .UNINDENT .IP \(bu 2 \fBstore\fP (\fI\%str\fP) \-\- .sp The store to use. This is either the local firewall policy or the policy defined by local group policy. Valid options are: .INDENT 2.0 .IP \(bu 2 lgpo .IP \(bu 2 local .UNINDENT .sp Default is \fBlocal\fP .UNINDENT .TP .B Returns A dictionary containing the properties for the specified profile .TP .B Return type \fI\%dict\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If an error occurs .IP \(bu 2 \fI\%ValueError\fP \-\- If the parameters are incorrect .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Get the inbound/outbound firewall settings for connections on the # local domain profile salt * win_firewall.get_settings domain firewallpolicy # Get the inbound/outbound firewall settings for connections on the # domain profile as defined by local group policy salt * win_firewall.get_settings domain firewallpolicy lgpo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.rule_exists(name) New in version 2016.11.6. .sp Checks if a firewall rule exists in the firewall policy .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the rule .TP .B Returns True if exists, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Is there a rule named RemoteDesktop salt \(aq*\(aq firewall.rule_exists RemoteDesktop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.set_firewall_settings(profile, inbound=None, outbound=None, store=\(aqlocal\(aq) Set the firewall inbound/outbound settings for the specified profile and store .sp New in version 2018.3.4. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fI\%str\fP) \-\- .sp The firewall profile to query. Valid options are: .INDENT 2.0 .IP \(bu 2 domain .IP \(bu 2 public .IP \(bu 2 private .UNINDENT .IP \(bu 2 \fBinbound\fP (\fI\%str\fP) \-\- .sp The inbound setting. If \fBNone\fP is passed, the setting will remain unchanged. Valid values are: .INDENT 2.0 .IP \(bu 2 blockinbound .IP \(bu 2 blockinboundalways .IP \(bu 2 allowinbound .IP \(bu 2 notconfigured .UNINDENT .sp Default is \fBNone\fP .IP \(bu 2 \fBoutbound\fP (\fI\%str\fP) \-\- .sp The outbound setting. If \fBNone\fP is passed, the setting will remain unchanged. Valid values are: .INDENT 2.0 .IP \(bu 2 allowoutbound .IP \(bu 2 blockoutbound .IP \(bu 2 notconfigured .UNINDENT .sp Default is \fBNone\fP .IP \(bu 2 \fBstore\fP (\fI\%str\fP) \-\- .sp The store to use. This is either the local firewall policy or the policy defined by local group policy. Valid options are: .INDENT 2.0 .IP \(bu 2 lgpo .IP \(bu 2 local .UNINDENT .sp Default is \fBlocal\fP .UNINDENT .TP .B Returns \fBTrue\fP if successful .TP .B Return type \fI\%bool\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If an error occurs .IP \(bu 2 \fI\%ValueError\fP \-\- If the parameters are incorrect .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Set the inbound setting for the domain profile to block inbound # connections salt * firewall.set_firewall_settings domain=\(aqdomain\(aq inbound=\(aqblockinbound\(aq # Set the outbound setting for the domain profile to allow outbound # connections salt * firewall.set_firewall_settings domain=\(aqdomain\(aq outbound=\(aqallowoutbound\(aq # Set inbound/outbound settings for the domain profile in the group # policy to block inbound and allow outbound salt * firewall.set_firewall_settings domain=\(aqdomain\(aq inbound=\(aqblockinbound\(aq outbound=\(aqallowoutbound\(aq store=\(aqlgpo\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.set_logging_settings(profile, setting, value, store=\(aqlocal\(aq) Configure logging settings for the Windows firewall. .sp New in version 2018.3.4. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fI\%str\fP) \-\- .sp The firewall profile to configure. Valid options are: .INDENT 2.0 .IP \(bu 2 domain .IP \(bu 2 public .IP \(bu 2 private .UNINDENT .IP \(bu 2 \fBsetting\fP (\fI\%str\fP) \-\- .sp The logging setting to configure. Valid options are: .INDENT 2.0 .IP \(bu 2 allowedconnections .IP \(bu 2 droppedconnections .IP \(bu 2 filename .IP \(bu 2 maxfilesize .UNINDENT .IP \(bu 2 \fBvalue\fP (\fI\%str\fP) \-\- .sp The value to apply to the setting. Valid values are dependent upon the setting being configured. Valid options are: .sp allowedconnections: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 enable .IP \(bu 2 disable .IP \(bu 2 notconfigured .UNINDENT .UNINDENT .UNINDENT .sp droppedconnections: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 enable .IP \(bu 2 disable .IP \(bu 2 notconfigured .UNINDENT .UNINDENT .UNINDENT .sp filename: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Full path and name of the firewall log file .IP \(bu 2 notconfigured .UNINDENT .UNINDENT .UNINDENT .sp maxfilesize: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 1 \- 32767 .IP \(bu 2 notconfigured .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 \fBnotconfigured\fP can only be used when using the lgpo store .UNINDENT .UNINDENT .IP \(bu 2 \fBstore\fP (\fI\%str\fP) \-\- .sp The store to use. This is either the local firewall policy or the policy defined by local group policy. Valid options are: .INDENT 2.0 .IP \(bu 2 lgpo .IP \(bu 2 local .UNINDENT .sp Default is \fBlocal\fP .UNINDENT .TP .B Returns \fBTrue\fP if successful .TP .B Return type \fI\%bool\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If an error occurs .IP \(bu 2 \fI\%ValueError\fP \-\- If the parameters are incorrect .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Log allowed connections and set that in local group policy salt * firewall.set_logging_settings domain allowedconnections enable lgpo # Don\(aqt log dropped connections salt * firewall.set_logging_settings profile=private setting=droppedconnections value=disable # Set the location of the log file salt * firewall.set_logging_settings domain filename C:\ewindows\elogs\efirewall.log # You can also use environment variables salt * firewall.set_logging_settings domain filename %systemroot%\esystem32\eLogFiles\eFirewall\epfirewall.log # Set the max file size of the log to 2048 Kb salt * firewall.set_logging_settings domain maxfilesize 2048 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.set_settings(profile, setting, value, store=\(aqlocal\(aq) Configure firewall settings. .sp New in version 2018.3.4. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fI\%str\fP) \-\- .sp The firewall profile to configure. Valid options are: .INDENT 2.0 .IP \(bu 2 domain .IP \(bu 2 public .IP \(bu 2 private .UNINDENT .IP \(bu 2 \fBsetting\fP (\fI\%str\fP) \-\- .sp The firewall setting to configure. Valid options are: .INDENT 2.0 .IP \(bu 2 localfirewallrules .IP \(bu 2 localconsecrules .IP \(bu 2 inboundusernotification .IP \(bu 2 remotemanagement .IP \(bu 2 unicastresponsetomulticast .UNINDENT .IP \(bu 2 \fBvalue\fP (\fI\%str\fP) \-\- .sp The value to apply to the setting. Valid options are .INDENT 2.0 .IP \(bu 2 enable .IP \(bu 2 disable .IP \(bu 2 notconfigured .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 \fBnotconfigured\fP can only be used when using the lgpo store .UNINDENT .UNINDENT .IP \(bu 2 \fBstore\fP (\fI\%str\fP) \-\- .sp The store to use. This is either the local firewall policy or the policy defined by local group policy. Valid options are: .INDENT 2.0 .IP \(bu 2 lgpo .IP \(bu 2 local .UNINDENT .sp Default is \fBlocal\fP .UNINDENT .TP .B Returns \fBTrue\fP if successful .TP .B Return type \fI\%bool\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If an error occurs .IP \(bu 2 \fI\%ValueError\fP \-\- If the parameters are incorrect .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Merge local rules with those distributed through group policy salt * firewall.set_settings domain localfirewallrules enable # Allow remote management of Windows Firewall salt * firewall.set_settings domain remotemanagement enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_firewall.set_state(profile, state, store=\(aqlocal\(aq) Configure the firewall state. .sp New in version 2018.3.4. .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprofile\fP (\fI\%str\fP) \-\- .sp The firewall profile to configure. Valid options are: .INDENT 2.0 .IP \(bu 2 domain .IP \(bu 2 public .IP \(bu 2 private .UNINDENT .IP \(bu 2 \fBstate\fP (\fI\%str\fP) \-\- .sp The firewall state. Valid options are: .INDENT 2.0 .IP \(bu 2 on .IP \(bu 2 off .IP \(bu 2 notconfigured .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 \fBnotconfigured\fP can only be used when using the lgpo store .UNINDENT .UNINDENT .IP \(bu 2 \fBstore\fP (\fI\%str\fP) \-\- .sp The store to use. This is either the local firewall policy or the policy defined by local group policy. Valid options are: .INDENT 2.0 .IP \(bu 2 lgpo .IP \(bu 2 local .UNINDENT .sp Default is \fBlocal\fP .UNINDENT .TP .B Returns \fBTrue\fP if successful .TP .B Return type \fI\%bool\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If an error occurs .IP \(bu 2 \fI\%ValueError\fP \-\- If the parameters are incorrect .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Turn the firewall off when the domain profile is active salt * firewall.set_state domain off # Turn the firewall on when the public profile is active and set that in # the local group policy salt * firewall.set_state public on lgpo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_groupadd .sp Manage groups on Windows .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_groupadd.add(name, **kwargs) Add the specified group .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the group to add .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.add foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_groupadd.adduser(name, username, **kwargs) Add a user to a group .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the group to modify .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- The name of the user to add to the group .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.adduser foo username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_groupadd.delete(name, **kwargs) Remove the named group .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the group to remove .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .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.win_groupadd.deluser(name, username, **kwargs) Remove a user from a group .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the group to modify .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- The name of the user to remove from the group .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.deluser foo username .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_groupadd.getent(refresh=False) Return info on all groups .INDENT 7.0 .TP .B Parameters \fBrefresh\fP (\fI\%bool\fP) \-\- Refresh the info for all groups in \fB__context__\fP\&. If False only the groups in \fB__context__\fP will be returned. If True the \fB__context__\fP will be refreshed with current data and returned. Default is False .TP .B Returns A list of groups and their information .UNINDENT .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.win_groupadd.info(name) Return information about a group .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the group for which to get information .TP .B Returns A dictionary of information about the group .TP .B Return type \fI\%dict\fP .UNINDENT .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.win_groupadd.list_groups(refresh=False) Return a list of groups .INDENT 7.0 .TP .B Parameters \fBrefresh\fP (\fI\%bool\fP) \-\- Refresh the info for all groups in \fB__context__\fP\&. If False only the groups in \fB__context__\fP will be returned. If True, the \fB__context__\fP will be refreshed with current data and returned. Default is False .TP .B Returns A list of groups on the machine .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.list_groups .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_groupadd.members(name, members_list, **kwargs) Ensure a group contains only the members in the list .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the group to modify .IP \(bu 2 \fBmembers_list\fP (\fI\%str\fP) \-\- A single user or a comma separated list of users. The group will contain only the users specified in this list. .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.members foo \(aquser1,user2,user3\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_iis .sp Microsoft IIS site management via WebAdministration powershell module .INDENT 0.0 .TP .B maintainer Shane Lee <\fI\%slee@saltstack.com\fP>, Robert Booth <\fI\%rbooth@saltstack.com\fP> .TP .B platform Windows .TP .B depends PowerShell .TP .B depends WebAdministration module (PowerShell) (IIS) .UNINDENT .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.modules.win_iis.create_app(name, site, sourcepath, apppool=None) Create an IIS application. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function only validates against the application name, and will return True even if the application already exists with a different configuration. It will not modify the configuration of an existing application. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The IIS application. .IP \(bu 2 \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .IP \(bu 2 \fBsourcepath\fP (\fI\%str\fP) \-\- The physical path. .IP \(bu 2 \fBapppool\fP (\fI\%str\fP) \-\- The name of the IIS application pool. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.create_app name=\(aqapp0\(aq site=\(aqsite0\(aq sourcepath=\(aqC:\esite0\(aq apppool=\(aqsite0\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.create_apppool(name) Create an IIS application pool. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function only validates against the application pool name, and will return True even if the application pool already exists with a different configuration. It will not modify the configuration of an existing application pool. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the IIS application pool. .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.create_apppool name=\(aqMyTestPool\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.create_backup(name) Backup an IIS Configuration on the System. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Backups are stored in the \fB$env:Windir\eSystem32\einetsrv\ebackup\fP folder. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name to give the backup .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.create_backup good_config_20170209 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.create_binding(site, hostheader=\(aq\(aq, ipaddress=\(aq*\(aq, port=80, protocol=\(aqhttp\(aq, sslflags=None) Create an IIS Web Binding. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function only validates against the binding ipaddress:port:hostheader combination, and will return True even if the binding already exists with a different configuration. It will not modify the configuration of an existing binding. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .IP \(bu 2 \fBhostheader\fP (\fI\%str\fP) \-\- The host header of the binding. Usually a hostname. .IP \(bu 2 \fBipaddress\fP (\fI\%str\fP) \-\- The IP address of the binding. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The TCP port of the binding. .IP \(bu 2 \fBprotocol\fP (\fI\%str\fP) \-\- The application protocol of the binding. .IP \(bu 2 \fBsslflags\fP (\fI\%str\fP) \-\- The flags representing certificate type and storage of the binding. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.create_binding site=\(aqsite0\(aq hostheader=\(aqexample.com\(aq ipaddress=\(aq*\(aq port=\(aq80\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.create_cert_binding(name, site, hostheader=\(aq\(aq, ipaddress=\(aq*\(aq, port=443, sslflags=0) Assign a certificate to an IIS Web Binding. .sp New in version 2016.11.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The web binding that the certificate is being assigned to must already exist. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The thumbprint of the certificate. .IP \(bu 2 \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .IP \(bu 2 \fBhostheader\fP (\fI\%str\fP) \-\- The host header of the binding. .IP \(bu 2 \fBipaddress\fP (\fI\%str\fP) \-\- The IP address of the binding. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The TCP port of the binding. .IP \(bu 2 \fBsslflags\fP (\fI\%int\fP) \-\- Flags representing certificate type and certificate storage of the binding. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.create_cert_binding name=\(aqAAA000\(aq site=\(aqsite0\(aq hostheader=\(aqexample.com\(aq ipaddress=\(aq*\(aq port=\(aq443\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.create_site(name, sourcepath, apppool=\(aq\(aq, hostheader=\(aq\(aq, ipaddress=\(aq*\(aq, port=80, protocol=\(aqhttp\(aq) Create a basic website in IIS. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function only validates against the site name, and will return True even if the site already exists with a different configuration. It will not modify the configuration of an existing site. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The IIS site name. .IP \(bu 2 \fBsourcepath\fP (\fI\%str\fP) \-\- The physical path of the IIS site. .IP \(bu 2 \fBapppool\fP (\fI\%str\fP) \-\- The name of the IIS application pool. .IP \(bu 2 \fBhostheader\fP (\fI\%str\fP) \-\- The host header of the binding. Usually the hostname or website name, ie: www.contoso.com .IP \(bu 2 \fBipaddress\fP (\fI\%str\fP) \-\- The IP address of the binding. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The TCP port of the binding. .IP \(bu 2 \fBprotocol\fP (\fI\%str\fP) \-\- The application protocol of the binding. (http, https, etc.) .UNINDENT .TP .B Returns True if successful, otherwise False. .TP .B Return type \fI\%bool\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If an application pool is specified, and that application pool does not already exist, it will be created. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.create_site name=\(aqMy Test Site\(aq sourcepath=\(aqc:\estage\(aq apppool=\(aqTestPool\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.create_vdir(name, site, sourcepath, app=\(aq/\(aq) Create an IIS virtual directory. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function only validates against the virtual directory name, and will return True even if the virtual directory already exists with a different configuration. It will not modify the configuration of an existing virtual directory. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The virtual directory name. .IP \(bu 2 \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .IP \(bu 2 \fBsourcepath\fP (\fI\%str\fP) \-\- The physical path. .IP \(bu 2 \fBapp\fP (\fI\%str\fP) \-\- The IIS application. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.create_vdir name=\(aqvd0\(aq site=\(aqsite0\(aq sourcepath=\(aqC:\einetpub\evdirs\evd0\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.get_container_setting(name, container, settings) Get the value of the setting for the IIS container. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the IIS container. .IP \(bu 2 \fBcontainer\fP (\fI\%str\fP) \-\- The type of IIS container. The container types are: AppPools, Sites, SslBindings .IP \(bu 2 \fBsettings\fP (\fI\%dict\fP) \-\- A dictionary of the setting names and their values. .UNINDENT .TP .B Returns A dictionary of the provided settings and their values. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.get_container_setting name=\(aqMyTestPool\(aq container=\(aqAppPools\(aq settings=\(dq[\(aqprocessModel.identityType\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.get_webapp_settings(name, site, settings) New in version 2017.7.0. .sp Get the value of the setting for the IIS web application. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Params are case sensitive .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the IIS web application. .IP \(bu 2 \fBsite\fP (\fI\%str\fP) \-\- The site name contains the web application. Example: Default Web Site .IP \(bu 2 \fBsettings\fP (\fI\%str\fP) \-\- A dictionary of the setting names and their values. Available settings: physicalPath, applicationPool, userName, password .UNINDENT .TP .B Returns A dictionary of the provided settings and their values. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.get_webapp_settings name=\(aqapp0\(aq site=\(aqDefault Web Site\(aq settings=\(dq[\(aqphysicalPath\(aq,\(aqapplicationPool\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.get_webconfiguration_settings(name, settings) Get the webconfiguration settings for the IIS PSPath. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The PSPath of the IIS webconfiguration settings. .IP \(bu 2 \fBsettings\fP (\fI\%list\fP) \-\- A list of dictionaries containing setting name and filter. .UNINDENT .TP .B Returns A list of dictionaries containing setting name, filter and value. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.get_webconfiguration_settings name=\(aqIIS:\e\(aq settings=\(dq[{\(aqname\(aq: \(aqenabled\(aq, \(aqfilter\(aq: \(aqsystem.webServer/security/authentication/anonymousAuthentication\(aq}]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.list_apppools() List all configured IIS application pools. .INDENT 7.0 .TP .B Returns A dictionary of IIS application pools and their details. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.list_apppools .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.list_apps(site) Get all configured IIS applications for the specified site. .INDENT 7.0 .TP .B Parameters \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .UNINDENT .sp Returns: A dictionary of the application names and properties. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.list_apps site .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.list_backups() List the IIS Configuration Backups on the System. .sp New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Backups are made when a configuration is edited. Manual backups are stored in the \fB$env:Windir\eSystem32\einetsrv\ebackup\fP folder. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of IIS Configurations backed up on the system. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.list_backups .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.list_bindings(site) Get all configured IIS bindings for the specified site. .INDENT 7.0 .TP .B Parameters \fBsite\fP (\fI\%str\fP) \-\- The name if the IIS Site .TP .B Returns A dictionary of the binding names and properties. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.list_bindings site .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.list_cert_bindings(site) List certificate bindings for an IIS site. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .TP .B Returns A dictionary of the binding names and properties. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.list_bindings site .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.list_sites() List all the currently deployed websites. .INDENT 7.0 .TP .B Returns A dictionary of the IIS sites and their properties. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.list_sites .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.list_vdirs(site, app=\(aq/\(aq) Get all configured IIS virtual directories for the specified site, or for the combination of site and application. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .IP \(bu 2 \fBapp\fP (\fI\%str\fP) \-\- The IIS application. .UNINDENT .TP .B Returns A dictionary of the virtual directory names and properties. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.list_vdirs site .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.list_worker_processes(apppool) Returns a list of worker processes that correspond to the passed application pool. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B Parameters \fBapppool\fP (\fI\%str\fP) \-\- The application pool to query .TP .B Returns A dictionary of worker processes with their process IDs .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.list_worker_processes \(aqMy App Pool\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.modify_binding(site, binding, hostheader=None, ipaddress=None, port=None, sslflags=None) Modify an IIS Web Binding. Use \fBsite\fP and \fBbinding\fP to target the binding. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .IP \(bu 2 \fBbinding\fP (\fI\%str\fP) \-\- The binding to edit. This is a combination of the IP address, port, and hostheader. It is in the following format: ipaddress:port:hostheader. For example, \fB*:80:\fP or \fB*:80:salt.com\fP .IP \(bu 2 \fBhostheader\fP (\fI\%str\fP) \-\- The host header of the binding. Usually the hostname. .IP \(bu 2 \fBipaddress\fP (\fI\%str\fP) \-\- The IP address of the binding. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The TCP port of the binding. .IP \(bu 2 \fBsslflags\fP (\fI\%str\fP) \-\- The flags representing certificate type and storage of the binding. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .sp The following will seat the host header of binding \fB*:80:\fP for \fBsite0\fP to \fBexample.com\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.modify_binding site=\(aqsite0\(aq binding=\(aq*:80:\(aq hostheader=\(aqexample.com\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.modify_site(name, sourcepath=None, apppool=None) Modify a basic website in IIS. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The IIS site name. .IP \(bu 2 \fBsourcepath\fP (\fI\%str\fP) \-\- The physical path of the IIS site. .IP \(bu 2 \fBapppool\fP (\fI\%str\fP) \-\- The name of the IIS application pool. .UNINDENT .TP .B Returns True if successful, otherwise False. .TP .B Return type \fI\%bool\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If an application pool is specified, and that application pool does not already exist, it will be created. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.modify_site name=\(aqMy Test Site\(aq sourcepath=\(aqc:\enew_path\(aq apppool=\(aqNewTestPool\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.remove_app(name, site) Remove an IIS application. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The application name. .IP \(bu 2 \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.remove_app name=\(aqapp0\(aq site=\(aqsite0\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.remove_apppool(name) Remove an IIS application pool. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the IIS application pool. .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.remove_apppool name=\(aqMyTestPool\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.remove_backup(name) Remove an IIS Configuration backup from the System. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the backup to remove .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.remove_backup backup_20170209 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.remove_binding(site, hostheader=\(aq\(aq, ipaddress=\(aq*\(aq, port=80) Remove an IIS binding. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .IP \(bu 2 \fBhostheader\fP (\fI\%str\fP) \-\- The host header of the binding. .IP \(bu 2 \fBipaddress\fP (\fI\%str\fP) \-\- The IP address of the binding. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The TCP port of the binding. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.remove_binding site=\(aqsite0\(aq hostheader=\(aqexample.com\(aq ipaddress=\(aq*\(aq port=\(aq80\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.remove_cert_binding(name, site, hostheader=\(aq\(aq, ipaddress=\(aq*\(aq, port=443) Remove a certificate from an IIS Web Binding. .sp New in version 2016.11.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function only removes the certificate from the web binding. It does not remove the web binding itself. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The thumbprint of the certificate. .IP \(bu 2 \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .IP \(bu 2 \fBhostheader\fP (\fI\%str\fP) \-\- The host header of the binding. .IP \(bu 2 \fBipaddress\fP (\fI\%str\fP) \-\- The IP address of the binding. .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- The TCP port of the binding. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.remove_cert_binding name=\(aqAAA000\(aq site=\(aqsite0\(aq hostheader=\(aqexample.com\(aq ipaddress=\(aq*\(aq port=\(aq443\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.remove_site(name) Delete a website from IIS. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The IIS site name. .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This will not remove the application pool used by the site. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.remove_site name=\(aqMy Test Site\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.remove_vdir(name, site, app=\(aq/\(aq) Remove an IIS virtual directory. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The virtual directory name. .IP \(bu 2 \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .IP \(bu 2 \fBapp\fP (\fI\%str\fP) \-\- The IIS application. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.remove_vdir name=\(aqvdir0\(aq site=\(aqsite0\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.restart_apppool(name) Restart an IIS application pool. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the IIS application pool. .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.restart_apppool name=\(aqMyTestPool\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.restart_site(name) Restart a Web Site in IIS. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the website to restart. .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.restart_site name=\(aqMy Test Site\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.set_container_setting(name, container, settings) Set the value of the setting for an IIS container. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the IIS container. .IP \(bu 2 \fBcontainer\fP (\fI\%str\fP) \-\- The type of IIS container. The container types are: AppPools, Sites, SslBindings .IP \(bu 2 \fBsettings\fP (\fI\%dict\fP) \-\- A dictionary of the setting names and their values. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.set_container_setting name=\(aqMyTestPool\(aq container=\(aqAppPools\(aq settings=\(dq{\(aqmanagedPipeLineMode\(aq: \(aqIntegrated\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.set_webapp_settings(name, site, settings) New in version 2017.7.0. .sp Configure an IIS application. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function only configures an existing app. Params are case sensitive. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The IIS application. .IP \(bu 2 \fBsite\fP (\fI\%str\fP) \-\- The IIS site name. .IP \(bu 2 \fBsettings\fP (\fI\%str\fP) \-\- A dictionary of the setting names and their values. \- physicalPath: The physical path of the webapp. \- applicationPool: The application pool for the webapp. \- userName: \(dqconnectAs\(dq user \- password: \(dqconnectAs\(dq password for user .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 win_iis.set_webapp_settings name=\(aqapp0\(aq site=\(aqsite0\(aq settings=\(dq{\(aqphysicalPath\(aq: \(aqC:\esite0\(aq, \(aqapppool\(aq: \(aqsite0\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.set_webconfiguration_settings(name, settings) Set the value of the setting for an IIS container. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The PSPath of the IIS webconfiguration settings. .IP \(bu 2 \fBsettings\fP (\fI\%list\fP) \-\- A list of dictionaries containing setting name, filter and value. .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.set_webconfiguration_settings name=\(aqIIS:\e\(aq settings=\(dq[{\(aqname\(aq: \(aqenabled\(aq, \(aqfilter\(aq: \(aqsystem.webServer/security/authentication/anonymousAuthentication\(aq, \(aqvalue\(aq: False}]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.start_apppool(name) Start an IIS application pool. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the App Pool to start. .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.start_apppool name=\(aqMyTestPool\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.start_site(name) Start a Web Site in IIS. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the website to start. .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.start_site name=\(aqMy Test Site\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.stop_apppool(name) Stop an IIS application pool. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the App Pool to stop. .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.stop_apppool name=\(aqMyTestPool\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_iis.stop_site(name) Stop a Web Site in IIS. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the website to stop. .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_iis.stop_site name=\(aqMy Test Site\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_ip .sp The networking module for Windows based systems .INDENT 0.0 .TP .B salt.modules.win_ip.disable(iface) Disable an interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.disable \(aqLocal Area Connection #2\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.enable(iface) Enable an interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.enable \(aqLocal Area Connection #2\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.get_all_interfaces() Return configs for all interfaces .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.get_all_interfaces .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.get_default_gateway() Set DNS source to DHCP on Windows .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.get_default_gateway .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.get_interface(iface) Return the configuration of a network interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.get_interface \(aqLocal Area Connection\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.get_subnet_length(mask) Convenience function to convert the netmask to the CIDR subnet length .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.get_subnet_length 255.255.255.0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.is_disabled(iface) Returns \fBTrue\fP if interface is disabled, otherwise \fBFalse\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.is_disabled \(aqLocal Area Connection #2\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.is_enabled(iface) Returns \fBTrue\fP if interface is enabled, otherwise \fBFalse\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.is_enabled \(aqLocal Area Connection #2\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.raw_interface_configs() Return raw configs for all interfaces .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.raw_interface_configs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.set_dhcp_all(iface) Set both IP Address and DNS to DHCP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.set_dhcp_all \(aqLocal Area Connection\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.set_dhcp_dns(iface) Set DNS source to DHCP on Windows .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.set_dhcp_dns \(aqLocal Area Connection\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.set_dhcp_ip(iface) Set Windows NIC to get IP from DHCP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.set_dhcp_ip \(aqLocal Area Connection\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.set_static_dns(iface, *addrs) Set static DNS configuration on a Windows NIC .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiface\fP (\fI\%str\fP) \-\- The name of the interface to set .IP \(bu 2 \fBaddrs\fP \-\- One or more DNS servers to be added. To clear the list of DNS servers pass an empty list (\fB[]\fP). If undefined or \fBNone\fP no changes will be made. .UNINDENT .TP .B Returns A dictionary containing the new DNS settings .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.set_static_dns \(aqLocal Area Connection\(aq \(aq192.168.1.1\(aq salt \-G \(aqos_family:Windows\(aq ip.set_static_dns \(aqLocal Area Connection\(aq \(aq192.168.1.252\(aq \(aq192.168.1.253\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ip.set_static_ip(iface, addr, gateway=None, append=False) Set static IP configuration on a Windows NIC .INDENT 7.0 .TP .B iface The name of the interface to manage .TP .B addr IP address with subnet length (ex. \fB10.1.2.3/24\fP). The \fI\%ip.get_subnet_length\fP function can be used to calculate the subnet length from a netmask. .TP .B gateway None If specified, the default gateway will be set to this value. .TP .B append False If \fBTrue\fP, this IP address will be added to the interface. Default is \fBFalse\fP, which overrides any existing configuration for the interface and sets \fBaddr\fP as the only address on the interface. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos_family:Windows\(aq ip.set_static_ip \(aqLocal Area Connection\(aq 10.1.2.3/24 gateway=10.1.2.1 salt \-G \(aqos_family:Windows\(aq ip.set_static_ip \(aqLocal Area Connection\(aq 10.1.2.4/24 append=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_lgpo .sp Manage Local Policy on Windows .sp This module allows configuring local group policy (i.e. \fBgpedit.msc\fP) on a Windows machine. .sp New in version 2016.11.0. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Local Group Policy will always be superseded by Domain Group policy. If policies are configured with Local Group Policy that are also configured with Domain Group policy, the Domain Group policy will take precedence. .UNINDENT .UNINDENT .SS Administrative Templates .sp Administrative template policies are dynamically read from ADMX/ADML files on the server. .SS Windows Settings .sp Policies contained in the \(dqWindows Settings\(dq section of the \fBgpedit.msc\fP GUI are statically defined in this module. Each policy is configured for the section (Machine/User) in the module\(aqs _policy_info class. The \fB_policy_info\fP class contains a \(dqpolicies\(dq dict on how the module will configure the policy, where the policy resides in the GUI (for display purposes), data validation data, data transformation data, etc. .SS Current known limitations .INDENT 0.0 .IP \(bu 2 At this time, start/shutdown scripts policies are displayed, but are not configurable. .IP \(bu 2 Not all \(dqSecurity Settings\(dq policies exist in the _policy_info class .UNINDENT .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 pywin32 Python module .IP \(bu 2 lxml .IP \(bu 2 uuid .IP \(bu 2 struct .IP \(bu 2 salt.utils.win_reg .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo.clear_policy_cache() Clears the policy definitions and resource stored in \fB__context__\fP\&. They will be rebuilt the next time a policy is applied. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lgpo.clear_policy_cache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo.get(policy_class=None, return_full_policy_names=True, hierarchical_return=False, adml_language=\(aqen\-US\(aq, return_not_configured=False) Get a policy value .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpolicy_class\fP (\fI\%str\fP) \-\- Some policies are both user and computer, by default all policies will be pulled, but this can be used to retrieve only a specific policy class User/USER/user = retrieve user policies Machine/MACHINE/machine/Computer/COMPUTER/computer = retrieve machine/computer policies .IP \(bu 2 \fBreturn_full_policy_names\fP (\fI\%bool\fP) \-\- True/False to return the policy name as it is seen in the \fBgpedit.msc\fP GUI or to only return the policy key/id. .IP \(bu 2 \fBhierarchical_return\fP (\fI\%bool\fP) \-\- True/False to return the policy data in the hierarchy as seen in the \fBgpedit.msc\fP GUI. The default of False will return data split only into User/Computer configuration sections .IP \(bu 2 \fBadml_language\fP (\fI\%str\fP) \-\- The ADML language to use for processing display/descriptive names and enumeration values of ADMX template data, defaults to en\-US .IP \(bu 2 \fBreturn_not_configured\fP (\fI\%bool\fP) \-\- Include Administrative Template policies that are \(aqNot Configured\(aq in the return data .UNINDENT .TP .B Returns A dictionary containing the policy values for the specified class .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lgpo.get machine return_full_policy_names=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo.get_policy(policy_name, policy_class, adml_language=\(aqen\-US\(aq, return_value_only=True, return_full_policy_names=True, hierarchical_return=False) Get the current settings for a single policy on the machine .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpolicy_name\fP (\fI\%str\fP) \-\- The name of the policy to retrieve. Can be the any of the names or alieses returned by \fBlgpo.get_policy_info\fP .IP \(bu 2 \fBpolicy_class\fP (\fI\%str\fP) \-\- The policy class. Must be one of \fBmachine\fP or \fBuser\fP .IP \(bu 2 \fBadml_language\fP (\fI\%str\fP) \-\- The language code for the adml file to use for localization. The default is \fBen\-US\fP .IP \(bu 2 \fBreturn_value_only\fP (\fI\%bool\fP) \-\- \fBTrue\fP will return only the value for the policy, without the name of the policy. \fBreturn_full_policy_names\fP and \fBhierarchical_return\fP will be ignored. Default is \fBTrue\fP .IP \(bu 2 \fBreturn_full_policy_names\fP (\fI\%bool\fP) \-\- .sp Returns the full policy name regardless of what was passed in \fBpolicy_name\fP .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This setting applies to sub\-elements of the policy if they exist. The value passed in \fBpolicy_name\fP will always be used as the policy name when this setting is \fBFalse\fP .UNINDENT .UNINDENT .IP \(bu 2 \fBhierarchical_return\fP (\fI\%bool\fP) \-\- Returns a hierarchical view of the policy showing its parents .UNINDENT .TP .B Returns A dictionary containing the policy settings .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Using the policy id salt * lgpo.get_policy LockoutDuration machine salt * lgpo.get_policy AutoUpdateCfg machine # Using the full name salt * lgpo.get_policy \(dqAccount lockout duration\(dq machine salt * lgpo.get_policy \(dqConfigure Automatic Updates\(dq machine # Using full path and name salt * lgpo.get_policy \(dqWindows Components\eWindows Update\eConfigure Automatic Updates\(dq machine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo.get_policy_info(policy_name, policy_class, adml_language=\(aqen\-US\(aq) Returns information about a specified policy .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpolicy_name\fP (\fI\%str\fP) \-\- The name of the policy to lookup .IP \(bu 2 \fBpolicy_class\fP (\fI\%str\fP) \-\- The class of policy, i.e. machine, user, both .IP \(bu 2 \fBadml_language\fP (\fI\%str\fP) \-\- The ADML language to use for Administrative Template data lookup .UNINDENT .TP .B Returns Information about the specified policy .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lgpo.get_policy_info \(aqMaximum password age\(aq machine .ft P .fi .UNINDENT .UNINDENT .sp You can use \fBlgpo.get_policy_info\fP to get all the possible names that could be used in a state file or from the command line (along with elements that need to be set/etc). The key is to match the text you see in the \fBgpedit.msc\fP gui exactly, including quotes around words or phrases. The \(dqfull path\(dq style is really only needed when there are multiple policies that use the same base name. For example, \fBAccess data sources across domains\fP exists in ~10 different paths. If you put that through \fBget_policy_info\fP you\(aqll get back a message that it is used for multiple policies and you need to be more specific. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local lgpo.get_policy_info ShellRemoveOrderPrints_2 machine local: \-\-\-\-\-\-\-\-\-\- message: policy_aliases: \- Turn off the \(dqOrder Prints\(dq picture task \- ShellRemoveOrderPrints_2 \- System\eInternet Communication Management\eInternet Communication settings\eTurn off the \(dqOrder Prints\(dq picture task policy_class: machine policy_elements: policy_found: True policy_name: ShellRemoveOrderPrints_2 rights_assignment: False .ft P .fi .UNINDENT .UNINDENT .sp Escaping can get tricky in cmd/Powershell. The following is an example of escaping in Powershell using backquotes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C PS>salt\-call \-\-local lgpo.get_policy_info \(dqTurn off the \(ga\e\(ga\(dqOrder Prints\(ga\e\(ga\(dq picture task\(dq machine local: \-\-\-\-\-\-\-\-\-\- message: policy_aliases: \- Turn off the \(dqOrder Prints\(dq picture task \- ShellRemoveOrderPrints_2 \- System\eInternet Communication Management\eInternet Communication settings\eTurn off the \(dqOrder Prints\(dq picture task policy_class: machine policy_elements: policy_found: True policy_name: Turn off the \(dqOrder Prints\(dq picture task rights_assignment: False .ft P .fi .UNINDENT .UNINDENT .sp This function can then be used to get the options available for specifying Group Policy Objects to be used in state files. Based on the above any of these \fIshould\fP be usable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C internet_communications_settings: lgpo.set: \- computer_policy: Turn off the \(dqOrder Prints\(dq picture task: Enabled .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C internet_communications_settings: lgpo.set: \- computer_policy: ShellRemoveOrderPrints_2: Enabled .ft P .fi .UNINDENT .UNINDENT .sp When using the full path, it might be a good idea to use single quotes around the path: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C internet_communications_settings: lgpo.set: \- computer_policy: \(aqSystem\eInternet Communication Management\eInternet Communication settings\eTurn off the \(dqOrder Prints\(dq picture task\(aq: \(aqEnabled\(aq .ft P .fi .UNINDENT .UNINDENT .sp If you struggle to find the policy from \fBget_policy_info\fP using the name as you see in \fBgpedit.msc\fP, the names such as \(dqShellRemoveOrderPrints_2\(dq come from the \fB\&.admx\fP files. If you know nothing about \fB\&.admx/.adml\fP relationships (ADML holds what you see in the GUI, ADMX holds the more technical details), then this may be a little bit too much info, but here is an example with the above policy using Powershell: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C PS>Get\-ChildItem \-Path C:\eWindows\ePolicyDefinitions \-Recurse \-Filter *.adml | Select\-String \(dqOrder Prints\(dq C:\ewindows\ePolicyDefinitions\een\-US\eICM.adml:152: <string id=\(dqShellRemoveOrderPrints\(dq>Turn off the \(dqOrder Prints\(dq picture task</string> C:\ewindows\ePolicyDefinitions\een\-US\eICM.adml:153: <string id=\(dqShellRemoveOrderPrints_Help\(dq>This policy setting specifies whether the \(dqOrder Prints Online\(dq task is available from Picture Tasks in Windows folders. C:\ewindows\ePolicyDefinitions\een\-US\eICM.adml:155:The Order Prints Online Wizard is used to download a list of providers and allow users to order prints online. C:\ewindows\ePolicyDefinitions\een\-US\eICM.adml:157:If you enable this policy setting, the task \(dqOrder Prints Online\(dq is removed from Picture Tasks in File Explorer folders. .ft P .fi .UNINDENT .UNINDENT .sp From this grep, we can see id \(dqShellRemoveOrderPrints\(dq is the ID of the string used to describe this policy, then we search for it in the ADMX: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C PS>Get\-ChildItem \-Path C:\eWindows\ePolicyDefinitions \-Recurse \-Filter *.admx | Select\-String \(dqShellRemoveOrderPrints\(dq C:\ewindows\ePolicyDefinitions\eICM.admx:661: <policy name=\(dqShellRemoveOrderPrints_1\(dq class=\(dqUser\(dq displayName=\(dq$(string.ShellRemoveOrderPrints)\(dq explainText=\(dq$(string.ShellRemoveOrderPrints_Help)\(dq key=\(dqSoftware\eMicrosoft\eWindows\eCurrentVersion\ePolicies\eExplorer\(dq valueName=\(dqNoOnlinePrintsWizard\(dq> C:\ewindows\ePolicyDefinitions\eICM.admx:671: <policy name=\(dqShellRemoveOrderPrints_2\(dq class=\(dqMachine\(dq displayName=\(dq$(string.ShellRemoveOrderPrints)\(dq explainText=\(dq$(string.ShellRemoveOrderPrints_Help)\(dq key=\(dqSoftware\eMicrosoft\eWindows\eCurrentVersion\ePolicies\eExplorer\(dq valueName=\(dqNoOnlinePrintsWizard\(dq> .ft P .fi .UNINDENT .UNINDENT .sp Now we have two to pick from. And if you notice the \fBclass=\(dqMachine\(dq\fP and \fBclass=\(dqUser\(dq\fP (which details if it is a computer policy or user policy respectively) the \fBShellRemoveOrderPrints_2\fP is the \(dqshort name\(dq we could use to pass through \fBget_policy_info\fP to see what the module itself is expecting. .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo.set_(computer_policy=None, user_policy=None, cumulative_rights_assignments=True, adml_language=\(aqen\-US\(aq) Set a local server policy. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcomputer_policy\fP (\fI\%dict\fP) \-\- .sp A dictionary of \(dqpolicyname: value\(dq pairs of computer policies to set. \(aqvalue\(aq should be how it is displayed in the gpedit GUI, i.e. if a setting can be \(aqEnabled\(aq/\(aqDisabled\(aq, then that should be passed .sp Administrative Template data may require dicts within dicts, to specify each element of the Administrative Template policy. Administrative Templates policies are always cumulative. .sp Policy names can be specified in a number of ways based on the type of policy: .INDENT 2.0 .INDENT 3.5 Windows Settings Policies: .INDENT 0.0 .INDENT 3.5 These policies can be specified using the GUI display name or the key name from the _policy_info class in this module. The GUI display name is also contained in the _policy_info class in this module. .UNINDENT .UNINDENT .sp Administrative Template Policies: .INDENT 0.0 .INDENT 3.5 These can be specified using the policy name as displayed in the GUI (case sensitive). Some policies have the same name, but a different location (for example, \(dqAccess data sources across domains\(dq). These can be differentiated by the \(dqpath\(dq in the GUI (for example, \(dqWindows ComponentsInternet ExplorerInternet Control PanelSecurity PageInternet ZoneAccess data sources across domains\(dq). .sp Additionally, policies can be specified using the \(dqname\(dq and \(dqid\(dq attributes from the ADMX files. .sp For Administrative Templates that have policy elements, each element can be specified using the text string as seen in the GUI or using the ID attribute from the ADMX file. Due to the way some of the GUI text is laid out, some policy element names could include descriptive text that appears lbefore the policy element in the GUI. .sp Use the get_policy_info function for the policy name to view the element ID/names that the module will accept. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBuser_policy\fP (\fI\%dict\fP) \-\- The same setup as the computer_policy, except with data to configure the local user policy. .IP \(bu 2 \fBcumulative_rights_assignments\fP (\fI\%bool\fP) \-\- .sp Determine how user rights assignment policies are configured. .sp If True, user right assignment specifications are simply added to the existing policy .sp If False, only the users specified will get the right (any existing will have the right revoked) .IP \(bu 2 \fBadml_language\fP (\fI\%str\fP) \-\- The language files to use for looking up Administrative Template policy data (i.e. how the policy is displayed in the GUI). Defaults to \(aqen\-US\(aq (U.S. English). .UNINDENT .TP .B Returns True is successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lgpo.set computer_policy=\(dq{\(aqLockoutDuration\(aq: 2, \(aqRestrictAnonymous\(aq: \(aqEnabled\(aq, \(aqAuditProcessTracking\(aq: \(aqSucces, Failure\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo.set_computer_policy(name, setting, cumulative_rights_assignments=True, adml_language=\(aqen\-US\(aq) Set a single computer policy .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the policy to configure .IP \(bu 2 \fBsetting\fP (\fI\%str\fP) \-\- The setting to configure the named policy with .IP \(bu 2 \fBcumulative_rights_assignments\fP (\fI\%bool\fP) \-\- Determine how user rights assignment policies are configured. If True, user right assignment specifications are simply added to the existing policy. If False, only the users specified will get the right (any existing will have the right revoked) .IP \(bu 2 \fBadml_language\fP (\fI\%str\fP) \-\- The language files to use for looking up Administrative Template policy data (i.e. how the policy is displayed in the GUI). Defaults to \(aqen\-US\(aq (U.S. English). .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lgpo.set_computer_policy LockoutDuration 1440 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo.set_user_policy(name, setting, adml_language=\(aqen\-US\(aq) Set a single user policy .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the policy to configure .IP \(bu 2 \fBsetting\fP (\fI\%str\fP) \-\- The setting to configure the named policy with .IP \(bu 2 \fBadml_language\fP (\fI\%str\fP) \-\- The language files to use for looking up Administrative Template policy data (i.e. how the policy is displayed in the GUI). Defaults to \(aqen\-US\(aq (U.S. English). .UNINDENT .TP .B Returns True if successful, Otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lgpo.set_user_policy \(dqControl Panel\eDisplay\eDisable the Display Control Panel\(dq Enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_lgpo_reg .SS LGPO \- Registry.pol .sp New in version 3006.0. .sp A module for working with registry based policies in Windows Local Group Policy (LGPO). This module contains functions for working with the \fBRegistry.pol\fP file. The \fBRegistry.pol\fP file is the source of truth for registry settings and LGPO. .sp Group Policy is refreshed every 90 seconds by default. During that refresh the contents of the \fBRegistry.pol\fP file are applied to the Registry. If the setting is changed outside of Group Policy to something other than what is contained in the \fBRegistry.pol\fP file, it will be changed back during the next refresh. .sp In the Group Policy Editor (\fBgpedit.msc\fP) these policies can be set to three states: .INDENT 0.0 .IP \(bu 2 Not Configured .IP \(bu 2 Enabled .IP \(bu 2 Disabled .UNINDENT .sp A policy that is \(dqNot Configured\(dq does not have an entry in the \fBRegistry.pol\fP file. A Group Policy refresh will not make any changes to key/value pairs in the registry that are not specified in the \fBRegistry.pol\fP file. .sp An \(dqEnabled\(dq policy will have an entry in the \fBRegistry.pol\fP files that contains its key path, value name, value type, value size, and value data. When Group Policy is refreshed, existing values will be overwritten with those contained in the \fBRegistry.pol\fP file. .sp A \(dqDisabled\(dq policy will have an entry in the \fBRegistry.pol\fP file with the key path and the value name, but the value name will be prepended with \fB**del.\fP\&. When Group Policy is refreshed the key/value will be deleted from the registry. If the key contains no values, it will also be deleted. .SS Working with LGPO Reg .sp The easiest way to figure out the values needed for this module is to set the policy using the Group Policy Editor (\fBgpedit.msc\fP) and then run the \fBlgpo_reg.read_reg_pol\fP function. This function will display a dictionary of all registry\-based policies in the \fBRegistry.pol\fP file. From its return you can get the \fBkey\fP, \fBv_name\fP, \fBv_type\fP, and \fBv_data\fP required to \(dqenable\(dq that policy. Use those values to set/disable/delete policies using this module. The same values can also be used to create states for setting these policies. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Not all policies in the Group Policy Editor (\fBgpedit.msc\fP) that write to the registry make that change in the \fBRegistry.pol\fP file. Those policies could still be enforced via the \fBRegistry.pol\fP file... theoretically. But you will have to find the values needed to set them with this module using a different method. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo_reg.delete_value(key, v_name, policy_class=\(aqMachine\(aq) Delete a key/value pair from the Registry.pol file. This bypasses the admx/adml style policies. This is the equivalent of setting the policy to \fBNot Configured\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The registry key path .IP \(bu 2 \fBv_name\fP (\fI\%str\fP) \-\- The registry value name within the key .IP \(bu 2 \fBpolicy_class\fP (\fI\%str\fP) \-\- .sp The registry class to write to. Can be one of the following: .INDENT 2.0 .IP \(bu 2 Computer .IP \(bu 2 Machine .IP \(bu 2 User .UNINDENT .sp Default is \fBMachine\fP .UNINDENT .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%SaltInvocationError\fP \-\- Invalid policy_class .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- On failure .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP None: Key/value not present .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Delete all values under a key salt \(aq*\(aq lgpo_reg.delete_value \(dqSOFTWARE\eMyKey\(dq \(dqMyValue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo_reg.disable_value(key, v_name, policy_class=\(aqmachine\(aq) Mark a registry value for deletion in the registry.pol file. This bypasses the admx/adml style policies. This is the equivalent of setting the policy to \fBDisabled\fP in the Group Policy editor (\fBgpedit.msc\fP) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The registry key path .IP \(bu 2 \fBv_name\fP (\fI\%str\fP) \-\- The registry value name within the key .IP \(bu 2 \fBpolicy_class\fP (\fI\%str\fP) \-\- .sp The registry class to write to. Can be one of the following: .INDENT 2.0 .IP \(bu 2 Computer .IP \(bu 2 Machine .IP \(bu 2 User .UNINDENT .sp Default is \fBMachine\fP .UNINDENT .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%SaltInvocationError\fP \-\- Invalid policy_class .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- On failure .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP None: If already disabled .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Delete a value salt \(aq*\(aq lgpo_reg.delete_value \(dqSOFTWARE\eMyKey\(dq \(dqMyValue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo_reg.get_key(key, policy_class=\(aqMachine\(aq) Get all the values set in a key in the \fBRegistry.pol\fP file. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The registry key where the values reside .IP \(bu 2 \fBpolicy_class\fP (\fI\%str\fP) \-\- The registry class to read from. Can be one of the following: .UNINDENT .TP .B Raises \fI\%SaltInvocationError\fP \-\- Invalid policy class .TP .B Returns A dictionary containing the value data and the value type .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Get all values from a key salt \(aq*\(aq lgpo_reg.get_key \(dqSOFTWARE\eMyKey\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo_reg.get_value(key, v_name, policy_class=\(aqMachine\(aq) Get the value of a single value pair as set in the \fBRegistry.pol\fP file. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The registry key where the value name resides .IP \(bu 2 \fBv_name\fP (\fI\%str\fP) \-\- The value name to retrieve .IP \(bu 2 \fBpolicy_class\fP (\fI\%str\fP) \-\- The registry class to read from. Can be one of the following: .UNINDENT .TP .B Raises \fI\%SaltInvocationError\fP \-\- Invalid policy class .TP .B Returns A dictionary containing the value data and the value type found .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Get a value salt \(aq*\(aq lgpo_reg.get_value \(dqSOFTWARE\eMyKey\(dq \(dqMyValue\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo_reg.read_reg_pol(policy_class=\(aqMachine\(aq) Read the contents of the Registry.pol file. Display the contents as a human\-readable dictionary. .INDENT 7.0 .TP .B Parameters \fBpolicy_class\fP (\fI\%str\fP) \-\- .sp The registry class to retrieve. Can be one of the following: .INDENT 7.0 .IP \(bu 2 Computer .IP \(bu 2 Machine .IP \(bu 2 User .UNINDENT .sp Default is \fBMachine\fP .TP .B Raises \fI\%SaltInvocationError\fP \-\- Invalid policy class .TP .B Returns A dictionary representing the contents of the Registry.pol file .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Read the machine Registry.pol salt \(aq*\(aq lgpo_reg.read_reg_pol .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo_reg.set_value(key, v_name, v_data, v_type=\(aqREG_DWORD\(aq, policy_class=\(aqMachine\(aq) Add a key/value pair to the registry.pol file. This bypasses the admx/adml style policies. This is the equivalent of setting a policy to \fBEnabled\fP .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The registry key path .IP \(bu 2 \fBv_name\fP (\fI\%str\fP) \-\- The registry value name within the key .IP \(bu 2 \fBv_data\fP (\fI\%str\fP) \-\- The registry value .IP \(bu 2 \fBv_type\fP (\fI\%str\fP) \-\- .sp The registry value type. Must be one of the following: .INDENT 2.0 .IP \(bu 2 REG_BINARY .IP \(bu 2 REG_DWORD .IP \(bu 2 REG_EXPAND_SZ .IP \(bu 2 REG_MULTI_SZ .IP \(bu 2 REG_QWORD .IP \(bu 2 REG_SZ .UNINDENT .sp Default is REG_DWORD .IP \(bu 2 \fBpolicy_class\fP (\fI\%str\fP) \-\- .sp The registry class to write to. Can be one of the following: .INDENT 2.0 .IP \(bu 2 Computer .IP \(bu 2 Machine .IP \(bu 2 User .UNINDENT .sp Default is \fBMachine\fP .UNINDENT .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%SaltInvocationError\fP \-\- Invalid policy_class .IP \(bu 2 \fI\%SaltInvocationError\fP \-\- Invalid v_type .IP \(bu 2 \fI\%SaltInvocationError\fP \-\- v_data doesn\(aqt match v_type .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Set REG_DWORD value (default) salt \(aq*\(aq lgpo_reg.set_value \(dqSOFTWARE\eMyKey\(dq \(dqMyValue\(dq 1 # Set REG_SZ value salt \(aq*\(aq lgpo_reg.set_value \(dqSOFTWARE\eMyKey\(dq \(dqMyValue\(dq \(dqstring value\(dq \(dqREG_SZ\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_lgpo_reg.write_reg_pol(data, policy_class=\(aqMachine\(aq) Write data to the Registry.pol file. The data is a dictionary that is then converted to the appropriate bytes format expected by Registry.pol .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdata\fP (\fI\%dict\fP) \-\- A dictionary containing Registry.pol data .IP \(bu 2 \fBpolicy_class\fP (\fI\%str\fP) \-\- .sp The registry class to write to. Can be one of the following: .INDENT 2.0 .IP \(bu 2 Computer .IP \(bu 2 Machine .IP \(bu 2 User .UNINDENT .sp Default is \fBMachine\fP .UNINDENT .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%SaltInvocationError\fP \-\- Invalid policy class .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- On failure .UNINDENT .TP .B Returns True if successful .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Write to Machine Registry.pol salt \(aq*\(aq lgpo_reg.write_reg_pol \(dq{\(aqSOFTWARE\eMyKey\(aq: {\(aqMyValue\(aq: \(aqdata\(aq: 1, \(aqtype\(aq: \(aqREG_DWORD\(aq}}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_license .sp This module allows you to manage windows licensing via slmgr.vbs .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq license.install XXXXX\-XXXXX\-XXXXX\-XXXXX\-XXXXX .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_license.activate() Attempt to activate the current machine via Windows Activation .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq license.activate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_license.info() Return information about the license, if the license is not correctly activated this will return None. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq license.info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_license.install(product_key) Install the given product key .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq license.install XXXXX\-XXXXX\-XXXXX\-XXXXX\-XXXXX .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_license.installed(product_key) Check to see if the product key is already installed. .INDENT 7.0 .TP .B Note: This is not 100% accurate as we can only see the last 5 digits of the license. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq license.installed XXXXX\-XXXXX\-XXXXX\-XXXXX\-XXXXX .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_license.licensed() Return true if the current machine is licensed correctly .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq license.licensed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_license.uninstall() Uninstall the current product key .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq license.uninstall .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_network .sp Module for gathering and managing network information .INDENT 0.0 .TP .B salt.modules.win_network.connect(host, port=None, **kwargs) Test connectivity to a host using a particular port from the minion. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.connect archlinux.org 80 salt \(aq*\(aq network.connect archlinux.org 80 timeout=3 salt \(aq*\(aq network.connect archlinux.org 80 timeout=3 family=ipv4 salt \(aq*\(aq network.connect google\-public\-dns\-a.google.com port=53 proto=udp timeout=3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.dig(host) Performs a DNS lookup with dig .sp Note: dig must be installed on the Windows minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.dig archlinux.org .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.get_route(ip) Return routing information for given destination ip .sp New in version 2016.11.5. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.get_route 10.10.10.10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.hw_addr(iface) Return the hardware address (a.k.a. MAC address) for a given interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.hw_addr \(aqWireless Connection #1\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.hwaddr(iface) This function is an alias of \fBhw_addr\fP\&. .INDENT 7.0 .INDENT 3.5 Return the hardware address (a.k.a. MAC address) for a given interface .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.hw_addr \(aqWireless Connection #1\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.in_subnet(cidr) Returns True if host is within specified subnet, otherwise False .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.in_subnet 10.0.0.0/16 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.interfaces() Return a dictionary of information about all the interfaces on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.interfaces .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.interfaces_names() Return a list of all the interfaces names .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.interfaces_names .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.ip_addrs(interface=None, include_loopback=False, cidr=None, type=None) Returns a list of IPv4 addresses assigned to the host. .INDENT 7.0 .TP .B interface Only IP addresses from that interface will be returned. .TP .B include_loopback False Include loopback 127.0.0.1 IPv4 address. .TP .B cidr .INDENT 7.0 .INDENT 3.5 Describes subnet using CIDR notation and only IPv4 addresses that belong to this subnet will be returned. .UNINDENT .UNINDENT .sp Changed in version 2019.2.0. .TP .B type If option set to \(aqpublic\(aq then only public addresses will be returned. Ditto for \(aqprivate\(aq. .sp Changed in version 2019.2.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_addrs salt \(aq*\(aq network.ip_addrs cidr=10.0.0.0/8 salt \(aq*\(aq network.ip_addrs cidr=192.168.0.0/16 type=private .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.ip_addrs6(interface=None, include_loopback=False, cidr=None) Returns a list of IPv6 addresses assigned to the host. .INDENT 7.0 .TP .B interface Only IP addresses from that interface will be returned. .TP .B include_loopback False Include loopback ::1 IPv6 address. .TP .B cidr Describes subnet using CIDR notation and only IPv6 addresses that belong to this subnet will be returned. .sp Changed in version 2019.2.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_addrs6 salt \(aq*\(aq network.ip_addrs6 cidr=2000::/3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.ipaddrs(interface=None, include_loopback=False, cidr=None, type=None) This function is an alias of \fBip_addrs\fP\&. .INDENT 7.0 .INDENT 3.5 Returns a list of IPv4 addresses assigned to the host. .INDENT 0.0 .TP .B interface Only IP addresses from that interface will be returned. .TP .B include_loopback False Include loopback 127.0.0.1 IPv4 address. .TP .B cidr .INDENT 7.0 .INDENT 3.5 Describes subnet using CIDR notation and only IPv4 addresses that belong to this subnet will be returned. .UNINDENT .UNINDENT .sp Changed in version 2019.2.0. .TP .B type If option set to \(aqpublic\(aq then only public addresses will be returned. Ditto for \(aqprivate\(aq. .sp Changed in version 2019.2.0. .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_addrs salt \(aq*\(aq network.ip_addrs cidr=10.0.0.0/8 salt \(aq*\(aq network.ip_addrs cidr=192.168.0.0/16 type=private .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.ipaddrs6(interface=None, include_loopback=False, cidr=None) This function is an alias of \fBip_addrs6\fP\&. .INDENT 7.0 .INDENT 3.5 Returns a list of IPv6 addresses assigned to the host. .INDENT 0.0 .TP .B interface Only IP addresses from that interface will be returned. .TP .B include_loopback False Include loopback ::1 IPv6 address. .TP .B cidr Describes subnet using CIDR notation and only IPv6 addresses that belong to this subnet will be returned. .sp Changed in version 2019.2.0. .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ip_addrs6 salt \(aq*\(aq network.ip_addrs6 cidr=2000::/3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.is_private(ip_addr) Check if the given IP address is a private address .sp New in version 2019.2.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.is_private 10.0.0.3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.netstat() Return information on open ports and states .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.netstat .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.nslookup(host) Query DNS for information about a domain or ip address .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.nslookup archlinux.org .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.ping(host, timeout=False, return_boolean=False) Performs a ping to a host .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ping archlinux.org .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .sp Return a True or False instead of ping output. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ping archlinux.org return_boolean=True .ft P .fi .UNINDENT .UNINDENT .sp Set the time to wait for a response in seconds. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.ping archlinux.org timeout=3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.subnets() Returns a list of subnets to which the host belongs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.subnets .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.traceroute(host) Performs a traceroute to a 3rd party host .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.traceroute archlinux.org .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_ntp .sp Management of NTP servers on Windows .sp New in version 2014.1.0. .INDENT 0.0 .TP .B salt.modules.win_ntp.get_servers() Get list of configured NTP servers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ntp.get_servers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_ntp.set_servers(*servers) Set Windows to use a list of NTP servers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ntp.set_servers \(aqpool.ntp.org\(aq \(aqus.pool.ntp.org\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_path .sp Manage the Windows System PATH .sp Note that not all Windows applications will rehash the PATH environment variable, Only the ones that listen to the WM_SETTINGCHANGE message. .INDENT 0.0 .TP .B salt.modules.win_path.add(path, index=None, **kwargs) Add the directory to the SYSTEM path in the index location. Returns \fBTrue\fP if successful, otherwise \fBFalse\fP\&. .INDENT 7.0 .TP .B path Directory to add to path .TP .B index Optionally specify an index at which to insert the directory .TP .B rehash True If the registry was updated, and this value is set to \fBTrue\fP, sends a WM_SETTINGCHANGE broadcast to refresh the environment variables. Set this to \fBFalse\fP to skip this broadcast. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Will add to the beginning of the path salt \(aq*\(aq win_path.add \(aqc:\epython27\(aq 0 # Will add to the end of the path salt \(aq*\(aq win_path.add \(aqc:\epython27\(aq index=\(aq\-1\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_path.exists(path) Check if the directory is configured in the SYSTEM path Case\-insensitive and ignores trailing backslash .INDENT 7.0 .TP .B Returns boolean True if path exists, False if not .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_path.exists \(aqc:\epython27\(aq salt \(aq*\(aq win_path.exists \(aqc:\epython27\e\(aq salt \(aq*\(aq win_path.exists \(aqC:\epyThon27\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_path.get_path() Returns a list of items in the SYSTEM path .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_path.get_path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_path.rehash() Send a WM_SETTINGCHANGE Broadcast to Windows to refresh the Environment variables for new processes. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This will only affect new processes that aren\(aqt launched by services. To apply changes to the path to services, the host must be restarted. The \fBsalt\-minion\fP, if running as a service, will not see changes to the environment until the system is restarted. See \fI\%MSDN Documentation\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_path.rehash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_path.remove(path, **kwargs) Remove the directory from the SYSTEM path .INDENT 7.0 .TP .B Returns boolean True if successful, False if unsuccessful .UNINDENT .INDENT 7.0 .TP .B rehash True If the registry was updated, and this value is set to \fBTrue\fP, sends a WM_SETTINGCHANGE broadcast to refresh the environment variables. Set this to \fBFalse\fP to skip this broadcast. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Will remove C:\ePython27 from the path salt \(aq*\(aq win_path.remove \(aqc:\e\epython27\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_pkg .sp A module to manage software on Windows .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .sp The following functions require the existence of a \fI\%windows repository\fP metadata DB, typically created by running \fI\%pkg.refresh_db\fP: .INDENT 0.0 .IP \(bu 2 \fI\%pkg.get_repo_data\fP .IP \(bu 2 \fI\%pkg.install\fP .IP \(bu 2 \fI\%pkg.latest_version\fP .IP \(bu 2 \fI\%pkg.list_available\fP .IP \(bu 2 \fI\%pkg.list_pkgs\fP .IP \(bu 2 \fI\%pkg.list_upgrades\fP .IP \(bu 2 \fI\%pkg.remove\fP .UNINDENT .sp If a metadata DB does not already exist and one of these functions is run, then one will be created from the repo SLS files that are present. .sp As the creation of this metadata can take some time, the \fI\%winrepo_cache_expire_min\fP minion config option can be used to suppress refreshes when the metadata is less than a given number of seconds old. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Version numbers can be \fBversion number string\fP, \fBlatest\fP and \fBNot Found\fP, where \fBNot Found\fP means this module was not able to determine the version of the software installed, it can also be used as the version number in sls definitions file in these cases. Versions numbers are sorted in order of 0, \fBNot Found\fP, \fBorder version numbers\fP, ..., \fBlatest\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.compare_versions(ver1=\(aq\(aq, oper=\(aq==\(aq, ver2=\(aq\(aq) Compare software package versions. Made public for use with Jinja .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBver1\fP (\fI\%str\fP) \-\- A software version to compare .IP \(bu 2 \fBoper\fP (\fI\%str\fP) \-\- The operand to use to compare .IP \(bu 2 \fBver2\fP (\fI\%str\fP) \-\- A software version to compare .UNINDENT .TP .B Returns True if the comparison is valid, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.compare_versions 1.2 >= 1.3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.genrepo(**kwargs) Generate package metadata db based on files within the winrepo_source_dir .sp Kwargs: .INDENT 7.0 .INDENT 3.5 saltenv (str): Salt environment. Default: \fBbase\fP .INDENT 0.0 .TP .B verbose (bool): Return verbose data structure which includes \(aqsuccess_list\(aq, a list of all sls files and the package names contained within. Default \fBFalse\fP\&. .TP .B failhard (bool): If \fBTrue\fP, an error will be raised if any repo SLS files failed to process. If \fBFalse\fP, no error will be raised, and a dictionary containing the full results will be returned. .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Hidden directories (directories beginning with \(aq\fI\&.\fP\(aq, such as \(aq\fI\&.git\fP\(aq) will be ignored. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of the results of the command .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run pkg.genrepo salt \-G \(aqos:windows\(aq pkg.genrepo verbose=true failhard=false salt \-G \(aqos:windows\(aq pkg.genrepo saltenv=base .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.get_package_info(name, saltenv=\(aqbase\(aq) Get information about the package as found in the winrepo database .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- The salt environment to use. Default is \(dqbase\(dq .UNINDENT .TP .B Returns A dictionary of package info, empty if package not available .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.get_package_info chrome .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.get_repo_data(saltenv=\(aqbase\(aq) Returns the existing package metadata db. Will create it, if it does not exist, however will not refresh it. .INDENT 7.0 .TP .B Parameters \fBsaltenv\fP (\fI\%str\fP) \-\- Salt environment. Default \fBbase\fP .TP .B Returns A dict containing contents of metadata db. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.get_repo_data .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.install(name=None, refresh=False, pkgs=None, **kwargs) Install the passed package(s) on the system using winrepo .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of a single package, or a comma\-separated list of packages to install. (no spaces after the commas) .IP \(bu 2 \fBrefresh\fP (\fI\%bool\fP) \-\- Boolean value representing whether or not to refresh the winrepo db. Default \fBFalse\fP\&. .IP \(bu 2 \fBpkgs\fP (\fI\%list\fP) \-\- .sp A list of packages to install from a software repository. All packages listed under \fBpkgs\fP will be installed via a single command. .sp You can specify a version by passing the item as a dict: .sp CLI Example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C # will install the latest version of foo and bar salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq # will install the latest version of foo and version 1.2.3 of bar salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, {\(dqbar\(dq: \(dq1.2.3\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Kwargs: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B version (str): The specific version to install. If omitted, the latest version will be installed. Recommend for use when installing a single package. .sp If passed with a list of packages in the \fBpkgs\fP parameter, the version will be ignored. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Version is ignored salt \(aq*\(aq pkg.install pkgs=\(dq[\(aqfoo\(aq, \(aqbar\(aq]\(dq version=1.2.3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp If passed with a comma separated list in the \fBname\fP parameter, the version will apply to all packages in the list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Version 1.2.3 will apply to packages foo and bar salt \(aq*\(aq pkg.install foo,bar version=1.2.3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B extra_install_flags (str): Additional install flags that will be appended to the \fBinstall_flags\fP defined in the software definition file. Only applies when single package is passed. .TP .B saltenv (str): Salt environment. Default \(aqbase\(aq .TP .B report_reboot_exit_codes (bool): If the installer exits with a recognized exit code indicating that a reboot is required, the module function .INDENT 7.0 .INDENT 3.5 \fIwin_system.set_reboot_required_witnessed\fP .UNINDENT .UNINDENT .sp will be called, preserving the knowledge of this event for the remainder of the current boot session. For the time being, 3010 is the only recognized exit code. The value of this param defaults to True. .sp New in version 2016.11.0. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns Return a dict containing the new package names and versions. If the package is already installed, an empty dict is returned. .sp If the package is installed by \fBpkg.install\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp The following example will refresh the winrepo and install a single package, 7zip. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install 7zip refresh=True .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install 7zip salt \(aq*\(aq pkg.install 7zip,filezilla salt \(aq*\(aq pkg.install pkgs=\(aq[\(dq7zip\(dq,\(dqfilezilla\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .sp WinRepo Definition File Examples: .sp The following example demonstrates the use of \fBcache_file\fP\&. This would be used if you have multiple installers in the same directory that use the same \fBinstall.ini\fP file and you don\(aqt want to download the additional installers. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ntp: 4.2.8: installer: \(aqsalt://win/repo/ntp/ntp\-4.2.8\-win32\-setup.exe\(aq full_name: Meinberg NTP Windows Client locale: en_US reboot: False cache_file: \(aqsalt://win/repo/ntp/install.ini\(aq install_flags: \(aq/USEFILE=C:\esalt\evar\ecache\esalt\eminion\efiles\ebase\ewin\erepo\entp\einstall.ini\(aq uninstaller: \(aqNTP/uninst.exe\(aq .ft P .fi .UNINDENT .UNINDENT .sp The following example demonstrates the use of \fBcache_dir\fP\&. It assumes a file named \fBinstall.ini\fP resides in the same directory as the installer. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ntp: 4.2.8: installer: \(aqsalt://win/repo/ntp/ntp\-4.2.8\-win32\-setup.exe\(aq full_name: Meinberg NTP Windows Client locale: en_US reboot: False cache_dir: True install_flags: \(aq/USEFILE=C:\esalt\evar\ecache\esalt\eminion\efiles\ebase\ewin\erepo\entp\einstall.ini\(aq uninstaller: \(aqNTP/uninst.exe\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.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 \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Since this is looking for the latest version available, a refresh_db will be triggered by default. This can take some time. To avoid this set \fBrefresh\fP to \fBFalse\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBnames\fP (\fI\%str\fP) \-\- A single or multiple names to lookup .UNINDENT .INDENT 7.0 .TP .B Kwargs: saltenv (str): Salt environment. Default \fBbase\fP refresh (bool): Refresh package metadata. Default \fBTrue\fP .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of packages with the latest version available .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.list_available(*names, **kwargs) Return a list of available versions of the specified package. .INDENT 7.0 .TP .B Parameters \fBnames\fP (\fI\%str\fP) \-\- One or more package names .UNINDENT .sp Kwargs: .INDENT 7.0 .INDENT 3.5 saltenv (str): The salt environment to use. Default \fBbase\fP\&. .sp refresh (bool): Refresh package metadata. Default \fBFalse\fP\&. .INDENT 0.0 .TP .B return_dict_always (bool): Default \fBFalse\fP dict when a single package name is queried. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns The package name with its available versions .TP .B Return type \fI\%dict\fP .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package name>\(aq: [\(aq<version>\(aq, \(aq<version>\(aq, ]} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_available <package name> return_dict_always=True salt \(aq*\(aq pkg.list_available <package name01> <package name02> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.list_pkgs(versions_as_list=False, include_components=True, include_updates=True, **kwargs) List the packages currently installed. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To view installed software as displayed in the Add/Remove Programs, set \fBinclude_components\fP and \fBinclude_updates\fP to False. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBversions_as_list\fP (\fI\%bool\fP) \-\- Returns the versions as a list .IP \(bu 2 \fBinclude_components\fP (\fI\%bool\fP) \-\- Include sub components of installed software. Default is \fBTrue\fP .IP \(bu 2 \fBinclude_updates\fP (\fI\%bool\fP) \-\- Include software updates and Windows updates. Default is \fBTrue\fP .UNINDENT .UNINDENT .sp Kwargs: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B saltenv (str): The salt environment to use. Default \fBbase\fP .TP .B refresh (bool): Refresh package metadata. Default \fBFalse\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of installed software with versions installed .TP .B Return type \fI\%dict\fP .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(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.win_pkg.list_upgrades(refresh=True, **kwargs) List all available package upgrades on this system .INDENT 7.0 .TP .B Parameters \fBrefresh\fP (\fI\%bool\fP) \-\- Refresh package metadata. Default \fBTrue\fP .UNINDENT .INDENT 7.0 .TP .B Kwargs: saltenv (str): Salt environment. Default \fBbase\fP .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of packages with available upgrades .TP .B Return type \fI\%dict\fP .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.win_pkg.normalize_name(name) Nothing to do on Windows. We need this function so that Salt doesn\(aqt go through every module looking for \fBpkg.normalize_name\fP\&. .sp New in version 3006.0. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the package .TP .B Returns The name of the package .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.normalize_name git .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.purge(name=None, pkgs=None, **kwargs) Package purges are not supported on Windows, this function is identical to \fBremove()\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 At some point in the future, \fBpkg.purge\fP may direct the installer to remove all configs and settings for software packages that support that option. .UNINDENT .UNINDENT .sp New in version 0.16.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be deleted. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- The version of the package to be deleted. If this option is used in combination with the \fBpkgs\fP option below, then this version will be applied to all targeted packages. .IP \(bu 2 \fBpkgs\fP (\fI\%list\fP) \-\- 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 .UNINDENT .INDENT 7.0 .TP .B Kwargs: saltenv (str): Salt environment. Default \fBbase\fP refresh (bool): Refresh package metadata. Default \fBFalse\fP .UNINDENT .INDENT 7.0 .TP .B Returns A dict containing the changes. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.purge <package name> salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3> salt \(aq*\(aq pkg.purge pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.refresh_db(**kwargs) Generates the local software metadata database (\fIwinrepo.p\fP) on the minion. The database is stored in a serialized format located by default at the following location: .sp \fBC:\eProgramData\eSalt Project\eSalt\evar\ecache\esalt\eminion\efiles\ebase\ewin\erepo\-ng\ewinrepo.p\fP .sp This module performs the following steps to generate the software metadata database: .INDENT 7.0 .IP \(bu 2 Fetch the package definition files (.sls) from \fIwinrepo_source_dir\fP (default \fIsalt://win/repo\-ng\fP) and cache them in \fI<cachedir>files<saltenv><winrepo_source_dir>\fP (default: \fBC:\eProgramData\eSalt Project\eSalt\evar\ecache\esalt\eminion\efiles\ebase\ewin\erepo\-ng\fP) .IP \(bu 2 Call \fI\%pkg.genrepo\fP to parse the package definition files and generate the repository metadata database file (\fIwinrepo.p\fP) .IP \(bu 2 Return the report received from \fI\%pkg.genrepo\fP .UNINDENT .sp The default winrepo directory on the master is \fI/srv/salt/win/repo\-ng\fP\&. All files that end with \fI\&.sls\fP in this and all subdirectories will be used to generate the repository metadata database (\fIwinrepo.p\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Hidden directories (directories beginning with \(aq\fI\&.\fP\(aq, such as \(aq\fI\&.git\fP\(aq) will be ignored. .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 There is no need to call \fIpkg.refresh_db\fP every time you work with the pkg module. Automatic refresh will occur based on the following minion configuration settings: .INDENT 0.0 .IP \(bu 2 \fIwinrepo_cache_expire_min\fP .IP \(bu 2 \fIwinrepo_cache_expire_max\fP .UNINDENT .sp However, if the package definition files have changed, as would be the case if you are developing a new package definition, this function should be called to ensure the minion has the latest information about packages available to it. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Directories and files fetched from <winrepo_source_dir> (\fI/srv/salt/win/repo\-ng\fP) will be processed in alphabetical order. If two or more software definition files contain the same name, the last one processed replaces all data from the files processed before it. .UNINDENT .UNINDENT .sp For more information see \fI\%Windows Software Repository\fP .sp Arguments: .sp saltenv (str): Salt environment. Default: \fBbase\fP .INDENT 7.0 .TP .B verbose (bool): Return a verbose data structure which includes \(aqsuccess_list\(aq, a list of all sls files and the package names contained within. Default is \(aqFalse\(aq .TP .B failhard (bool): If \fBTrue\fP, an error will be raised if any repo SLS files fails to process. If \fBFalse\fP, no error will be raised, and a dictionary containing the full results will be returned. .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary containing the results of the database refresh. .TP .B Return type \fI\%dict\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A result with a \fItotal: 0\fP generally means that the files are in the wrong location on the master. Try running the following command on the minion: \fIsalt\-call \-l debug pkg.refresh saltenv=base\fP .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 When calling this command from a state using \fImodule.run\fP be sure to pass \fIfailhard: False\fP\&. Otherwise, the state will report failure if it encounters a bad software definition file. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db salt \(aq*\(aq pkg.refresh_db saltenv=base .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.remove(name=None, pkgs=None, **kwargs) Remove the passed package(s) from the system using winrepo .sp New in version 0.16.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name(s) of the package(s) to be uninstalled. Can be a single package or a comma delimited list of packages, no spaces. .IP \(bu 2 \fBpkgs\fP (\fI\%list\fP) \-\- 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 .UNINDENT .sp Kwargs: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B version (str): The version of the package to be uninstalled. If this option is used to to uninstall multiple packages, then this version will be applied to all targeted packages. Recommended using only when uninstalling a single package. If this parameter is omitted, the latest version will be uninstalled. .UNINDENT .sp saltenv (str): Salt environment. Default \fBbase\fP refresh (bool): Refresh package metadata. Default \fBFalse\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns Returns a dict containing the changes. .sp If the package is removed by \fBpkg.remove\fP: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .UNINDENT .UNINDENT .UNINDENT .sp If the package is already uninstalled: .INDENT 7.0 .INDENT 3.5 {\(aq<package>\(aq: {\(aqcurrent\(aq: \(aqnot installed\(aq}} .UNINDENT .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.upgrade(**kwargs) Upgrade all software. Currently not implemented .INDENT 7.0 .TP .B Kwargs: saltenv (str): The salt environment to use. Default \fBbase\fP\&. refresh (bool): Refresh package metadata. Default \fBTrue\fP\&. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This feature is not yet implemented for Windows. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns Empty dict, until implemented .TP .B Return type \fI\%dict\fP .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.win_pkg.upgrade_available(name, **kwargs) Check whether or not an upgrade is available for a given package .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of a single package .UNINDENT .INDENT 7.0 .TP .B Kwargs: refresh (bool): Refresh package metadata. Default \fBTrue\fP saltenv (str): The salt environment. Default \fBbase\fP .UNINDENT .INDENT 7.0 .TP .B Returns True if new version available, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pkg.version(*names, **kwargs) Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- One or more package names .UNINDENT .INDENT 7.0 .TP .B Kwargs: saltenv (str): The salt environment to use. Default \fBbase\fP\&. refresh (bool): Refresh package metadata. Default \fBFalse\fP\&. .UNINDENT .INDENT 7.0 .TP .B Returns version string when a single package is specified. dict: The package name(s) with the installed versions. .TP .B Return type \fI\%str\fP .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {[\(aq<version>\(aq, \(aq<version>\(aq, ]} OR {\(aq<package name>\(aq: [\(aq<version>\(aq, \(aq<version>\(aq, ]} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version <package name> salt \(aq*\(aq pkg.version <package name01> <package name02> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_pki .sp Microsoft certificate management via the PKI Client PowerShell module. \fI\%https://technet.microsoft.com/en\-us/itpro/powershell/windows/pkiclient/pkiclient\fP .sp The PKI Client PowerShell module is only available on Windows 8+ and Windows Server 2012+. \fI\%https://technet.microsoft.com/en\-us/library/hh848636(v=wps.620).aspx\fP .INDENT 0.0 .TP .B platform Windows .TP .B depends .INDENT 7.0 .IP \(bu 2 PowerShell 4 .IP \(bu 2 PKI Client Module (Windows 8+ / Windows Server 2012+) .UNINDENT .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.modules.win_pki.export_cert(name, thumbprint, cert_format=\(aqcer\(aq, context=\(aqLocalMachine\(aq, store=\(aqMy\(aq, password=\(aq\(aq) Export the certificate to a file from the given certificate store. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The destination path for the exported certificate file. .IP \(bu 2 \fBthumbprint\fP (\fI\%str\fP) \-\- The thumbprint value of the target certificate. .IP \(bu 2 \fBcert_format\fP (\fI\%str\fP) \-\- The certificate format. Specify \(aqcer\(aq for X.509, or \(aqpfx\(aq for PKCS #12. .IP \(bu 2 \fBcontext\fP (\fI\%str\fP) \-\- The name of the certificate store location context. .IP \(bu 2 \fBstore\fP (\fI\%str\fP) \-\- The name of the certificate store. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The password of the certificate. Only applicable to pfx format. Note that if used interactively, the password will be seen by all minions. To protect the password, use a state and get the password from pillar. .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 win_pki.export_cert name=\(aqC:\ecerts\eexample.cer\(aq thumbprint=\(aqAAA000\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pki.get_cert_file(name, cert_format=\(aqcer\(aq, password=\(aq\(aq) Get the details of the certificate file. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The filesystem path of the certificate file. .IP \(bu 2 \fBcert_format\fP (\fI\%str\fP) \-\- The certificate format. Specify \(aqcer\(aq for X.509, or \(aqpfx\(aq for PKCS #12. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The password of the certificate. Only applicable to pfx format. Note that if used interactively, the password will be seen by all minions. To protect the password, use a state and get the password from pillar. .UNINDENT .TP .B Returns A dictionary of the certificate thumbprints and properties. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_pki.get_cert_file name=\(aqC:\ecerts\eexample.cer\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pki.get_certs(context=\(aqLocalMachine\(aq, store=\(aqMy\(aq) Get the available certificates in the given store. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontext\fP (\fI\%str\fP) \-\- The name of the certificate store location context. .IP \(bu 2 \fBstore\fP (\fI\%str\fP) \-\- The name of the certificate store. .UNINDENT .TP .B Returns A dictionary of the certificate thumbprints and properties. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_pki.get_certs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pki.get_stores() Get the certificate location contexts and their corresponding stores. .INDENT 7.0 .TP .B Returns A dictionary of the certificate location contexts and stores. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_pki.get_stores .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pki.import_cert(name, cert_format=\(aqcer\(aq, context=\(aqLocalMachine\(aq, store=\(aqMy\(aq, exportable=True, password=\(aq\(aq, saltenv=\(aqbase\(aq) Import the certificate file into the given certificate store. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The path of the certificate file to import. .IP \(bu 2 \fBcert_format\fP (\fI\%str\fP) \-\- The certificate format. Specify \(aqcer\(aq for X.509, or \(aqpfx\(aq for PKCS #12. .IP \(bu 2 \fBcontext\fP (\fI\%str\fP) \-\- The name of the certificate store location context. .IP \(bu 2 \fBstore\fP (\fI\%str\fP) \-\- The name of the certificate store. .IP \(bu 2 \fBexportable\fP (\fI\%bool\fP) \-\- Mark the certificate as exportable. Only applicable to pfx format. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The password of the certificate. Only applicable to pfx format. Note that if used interactively, the password will be seen by all minions. To protect the password, use a state and get the password from pillar. .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 win_pki.import_cert name=\(aqsalt://cert.cer\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pki.remove_cert(thumbprint, context=\(aqLocalMachine\(aq, store=\(aqMy\(aq) Remove the certificate from the given certificate store. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBthumbprint\fP (\fI\%str\fP) \-\- The thumbprint value of the target certificate. .IP \(bu 2 \fBcontext\fP (\fI\%str\fP) \-\- The name of the certificate store location context. .IP \(bu 2 \fBstore\fP (\fI\%str\fP) \-\- The name of the certificate store. .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 win_pki.remove_cert thumbprint=\(aqAAA000\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_pki.test_cert(thumbprint, context=\(aqLocalMachine\(aq, store=\(aqMy\(aq, untrusted_root=False, dns_name=\(aq\(aq, eku=\(aq\(aq) Check the certificate for validity. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBthumbprint\fP (\fI\%str\fP) \-\- The thumbprint value of the target certificate. .IP \(bu 2 \fBcontext\fP (\fI\%str\fP) \-\- The name of the certificate store location context. .IP \(bu 2 \fBstore\fP (\fI\%str\fP) \-\- The name of the certificate store. .IP \(bu 2 \fBuntrusted_root\fP (\fI\%bool\fP) \-\- Whether the root certificate is required to be trusted in chain building. .IP \(bu 2 \fBdns_name\fP (\fI\%str\fP) \-\- The DNS name to verify as valid for the certificate. .IP \(bu 2 \fBeku\fP (\fI\%str\fP) \-\- The enhanced key usage object identifiers to verify for the certificate chain. .UNINDENT .TP .B Returns A boolean representing whether the certificate was considered valid. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_pki.test_cert thumbprint=\(aqAAA000\(aq dns_name=\(aqexample.test\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_powercfg .sp This module allows you to control the power settings of a windows minion via powercfg. .sp New in version 2015.8.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Set monitor to never turn off on Battery power salt \(aq*\(aq powercfg.set_monitor_timeout 0 power=dc # Set disk timeout to 120 minutes on AC power salt \(aq*\(aq powercfg.set_disk_timeout 120 power=ac .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_powercfg.get_disk_timeout(scheme=None) Get the current disk timeout of the given scheme .INDENT 7.0 .TP .B Parameters \fBscheme\fP (\fI\%str\fP) \-\- .sp The scheme to use, leave as \fBNone\fP to use the current. Default is \fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known Aliases are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBSCHEME_BALANCED\fP \- Balanced .IP \(bu 2 \fBSCHEME_MAX\fP \- Power saver .IP \(bu 2 \fBSCHEME_MIN\fP \- High performance .UNINDENT .UNINDENT .UNINDENT .TP .B Returns A dictionary of both the AC and DC settings .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq powercfg.get_disk_timeout .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_powercfg.get_hibernate_timeout(scheme=None) Get the current hibernate timeout of the given scheme .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B scheme (str): The scheme to use, leave as \fBNone\fP to use the current. Default is \fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known Aliases are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBSCHEME_BALANCED\fP \- Balanced .IP \(bu 2 \fBSCHEME_MAX\fP \- Power saver .IP \(bu 2 \fBSCHEME_MIN\fP \- High performance .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of both the AC and DC settings .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq powercfg.get_hibernate_timeout .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_powercfg.get_monitor_timeout(scheme=None) Get the current monitor timeout of the given scheme .INDENT 7.0 .TP .B Parameters \fBscheme\fP (\fI\%str\fP) \-\- .sp The scheme to use, leave as \fBNone\fP to use the current. Default is \fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known Aliases are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBSCHEME_BALANCED\fP \- Balanced .IP \(bu 2 \fBSCHEME_MAX\fP \- Power saver .IP \(bu 2 \fBSCHEME_MIN\fP \- High performance .UNINDENT .UNINDENT .UNINDENT .TP .B Returns A dictionary of both the AC and DC settings .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq powercfg.get_monitor_timeout .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_powercfg.get_standby_timeout(scheme=None) Get the current standby timeout of the given scheme .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B scheme (str): The scheme to use, leave as \fBNone\fP to use the current. Default is \fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known Aliases are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBSCHEME_BALANCED\fP \- Balanced .IP \(bu 2 \fBSCHEME_MAX\fP \- Power saver .IP \(bu 2 \fBSCHEME_MIN\fP \- High performance .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of both the AC and DC settings .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq powercfg.get_standby_timeout .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_powercfg.set_disk_timeout(timeout, power=\(aqac\(aq, scheme=None) Set the disk timeout in minutes for the given power scheme .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- The amount of time in minutes before the disk will timeout .IP \(bu 2 \fBpower\fP (\fI\%str\fP) \-\- .sp Set the value for AC or DC power. Default is \fBac\fP\&. Valid options are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBac\fP (AC Power) .IP \(bu 2 \fBdc\fP (Battery) .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBscheme\fP (\fI\%str\fP) \-\- .sp The scheme to use, leave as \fBNone\fP to use the current. Default is \fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known Aliases are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBSCHEME_BALANCED\fP \- Balanced .IP \(bu 2 \fBSCHEME_MAX\fP \- Power saver .IP \(bu 2 \fBSCHEME_MIN\fP \- High performance .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Sets the disk timeout to 30 minutes on battery salt \(aq*\(aq powercfg.set_disk_timeout 30 power=dc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_powercfg.set_hibernate_timeout(timeout, power=\(aqac\(aq, scheme=None) Set the hibernate timeout in minutes for the given power scheme .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- The amount of time in minutes before the computer hibernates .IP \(bu 2 \fBpower\fP (\fI\%str\fP) \-\- .sp Set the value for AC or DC power. Default is \fBac\fP\&. Valid options are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBac\fP (AC Power) .IP \(bu 2 \fBdc\fP (Battery) .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBscheme\fP (\fI\%str\fP) \-\- .sp The scheme to use, leave as \fBNone\fP to use the current. Default is \fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known Aliases are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBSCHEME_BALANCED\fP \- Balanced .IP \(bu 2 \fBSCHEME_MAX\fP \- Power saver .IP \(bu 2 \fBSCHEME_MIN\fP \- High performance .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Sets the hibernate timeout to 30 minutes on Battery salt \(aq*\(aq powercfg.set_hibernate_timeout 30 power=dc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_powercfg.set_monitor_timeout(timeout, power=\(aqac\(aq, scheme=None) Set the monitor timeout in minutes for the given power scheme .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- The amount of time in minutes before the monitor will timeout .IP \(bu 2 \fBpower\fP (\fI\%str\fP) \-\- .sp Set the value for AC or DC power. Default is \fBac\fP\&. Valid options are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBac\fP (AC Power) .IP \(bu 2 \fBdc\fP (Battery) .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBscheme\fP (\fI\%str\fP) \-\- .sp The scheme to use, leave as \fBNone\fP to use the current. Default is \fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known Aliases are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBSCHEME_BALANCED\fP \- Balanced .IP \(bu 2 \fBSCHEME_MAX\fP \- Power saver .IP \(bu 2 \fBSCHEME_MIN\fP \- High performance .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Sets the monitor timeout to 30 minutes salt \(aq*\(aq powercfg.set_monitor_timeout 30 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_powercfg.set_standby_timeout(timeout, power=\(aqac\(aq, scheme=None) Set the standby timeout in minutes for the given power scheme .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- The amount of time in minutes before the computer sleeps .IP \(bu 2 \fBpower\fP (\fI\%str\fP) \-\- .sp Set the value for AC or DC power. Default is \fBac\fP\&. Valid options are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBac\fP (AC Power) .IP \(bu 2 \fBdc\fP (Battery) .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBscheme\fP (\fI\%str\fP) \-\- .sp The scheme to use, leave as \fBNone\fP to use the current. Default is \fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known Aliases are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBSCHEME_BALANCED\fP \- Balanced .IP \(bu 2 \fBSCHEME_MAX\fP \- Power saver .IP \(bu 2 \fBSCHEME_MIN\fP \- High performance .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Sets the system standby timeout to 30 minutes on Battery salt \(aq*\(aq powercfg.set_standby_timeout 30 power=dc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_psget .sp Module for managing PowerShell through PowerShellGet (PSGet) .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 PowerShell 5.0 .IP \(bu 2 PSGet .UNINDENT .UNINDENT .sp Support for PowerShell .INDENT 0.0 .TP .B salt.modules.win_psget.avail_modules(desc=False) List available modules in registered Powershell module repositories. .INDENT 7.0 .TP .B Parameters \fBdesc\fP (\fBbool\fP) \-\- If \fBTrue\fP, the verbose description will be returned. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqwin01\(aq psget.avail_modules salt \(aqwin01\(aq psget.avail_modules desc=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_psget.bootstrap() Make sure that nuget\-anycpu.exe is installed. This will download the official nuget\-anycpu.exe from the internet. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqwin01\(aq psget.bootstrap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_psget.get_repository(name) Get the details of a local PSGet repository .INDENT 7.0 .TP .B Parameters \fBname\fP (\fBstr\fP) \-\- Name of the repository .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqwin01\(aq psget.get_repository MyRepo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_psget.install(name, minimum_version=None, required_version=None, scope=None, repository=None) Install a Powershell module from powershell gallery on the system. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Name of a Powershell module .IP \(bu 2 \fBminimum_version\fP (\fBstr\fP) \-\- The maximum version to install, e.g. 1.23.2 .IP \(bu 2 \fBrequired_version\fP (\fBstr\fP) \-\- Install a specific version .IP \(bu 2 \fBscope\fP (\fBstr\fP) \-\- The scope to install the module to, e.g. CurrentUser, Computer .IP \(bu 2 \fBrepository\fP (\fBstr\fP) \-\- The friendly name of a private repository, e.g. MyREpo .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqwin01\(aq psget.install PowerPlan .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_psget.list_modules(desc=False) List currently installed PSGet Modules on the system. .INDENT 7.0 .TP .B Parameters \fBdesc\fP (\fBbool\fP) \-\- If \fBTrue\fP, the verbose description will be returned. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqwin01\(aq psget.list_modules salt \(aqwin01\(aq psget.list_modules desc=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_psget.register_repository(name, location, installation_policy=None) Register a PSGet repository on the local machine .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- The name for the repository .IP \(bu 2 \fBlocation\fP (\fBstr\fP) \-\- The URI for the repository .IP \(bu 2 \fBinstallation_policy\fP (\fBstr\fP) \-\- The installation policy for packages, e.g. Trusted, Untrusted .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqwin01\(aq psget.register_repository MyRepo https://myrepo.mycompany.com/packages .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_psget.remove(name) Remove a Powershell DSC module from the system. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fBstr\fP) \-\- Name of a Powershell DSC module .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqwin01\(aq psget.remove PowerPlan .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_psget.update(name, maximum_version=None, required_version=None) Update a PowerShell module to a specific version, or the newest .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Name of a Powershell module .IP \(bu 2 \fBmaximum_version\fP (\fBstr\fP) \-\- The maximum version to install, e.g. 1.23.2 .IP \(bu 2 \fBrequired_version\fP (\fBstr\fP) \-\- Install a specific version .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqwin01\(aq psget.update PowerPlan .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_servermanager .sp Manage Windows features via the ServerManager powershell module. Can list available and installed roles/features. Can install and remove roles/features. .INDENT 0.0 .TP .B maintainer Shane Lee <\fI\%slee@saltstack.com\fP> .TP .B platform Windows Server 2008R2 or greater .TP .B depends PowerShell module \fBServerManager\fP .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_servermanager.install(feature, recurse=False, restart=False, source=None, exclude=None) Install a feature .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Some features require reboot after un/installation, if so until the server is restarted other features can not be installed! .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Some features take a long time to complete un/installation, set \-t with a long timeout .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfeature\fP (\fI\%str\fP\fI, \fP\fI\%list\fP) \-\- .sp The name of the feature(s) to install. This can be a single feature, a string of features in a comma delimited list (no spaces), or a list of features. .sp New in version 2018.3.0: Added the ability to pass a list of features to be installed. .IP \(bu 2 \fBrecurse\fP (\fIOptions\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Install all sub\-features. Default is False .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Restarts the computer when installation is complete, if required by the role/feature installed. Will also trigger a reboot if an item in \fBexclude\fP requires a reboot to be properly removed. Default is False .IP \(bu 2 \fBsource\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- Path to the source files if missing from the target system. None means that the system will use windows update services to find the required files. Default is None .IP \(bu 2 \fBexclude\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- .sp The name of the feature to exclude when installing the named feature. This can be a single feature, a string of features in a comma\-delimited list (no spaces), or a list of features. .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 As there is no exclude option for the \fBAdd\-WindowsFeature\fP or \fBInstall\-WindowsFeature\fP PowerShell commands the features named in \fBexclude\fP will be installed with other sub\-features and will then be removed. \fBIf the feature named in \(ga\(gaexclude\(ga\(ga is not a sub\-feature of one of the installed items it will still be removed.\fP .UNINDENT .UNINDENT .UNINDENT .TP .B Returns A dictionary containing the results of the install .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Install the Telnet Client passing a single string salt \(aq*\(aq win_servermanager.install Telnet\-Client # Install the TFTP Client and the SNMP Service passing a comma\-delimited # string. Install all sub\-features salt \(aq*\(aq win_servermanager.install TFTP\-Client,SNMP\-Service recurse=True # Install the TFTP Client from d:\eside\-by\-side salt \(aq*\(aq win_servermanager.install TFTP\-Client source=d:\e\eside\-by\-side # Install the XPS Viewer, SNMP Service, and Remote Access passing a # list. Install all sub\-features, but exclude the Web Server salt \(aq*\(aq win_servermanager.install \(dq[\(aqXPS\-Viewer\(aq, \(aqSNMP\-Service\(aq, \(aqRemoteAccess\(aq]\(dq True recurse=True exclude=\(dqWeb\-Server\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_servermanager.list_available() List available features to install .INDENT 7.0 .TP .B Returns A list of available features as returned by the \fBGet\-WindowsFeature\fP PowerShell command .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_servermanager.list_available .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_servermanager.list_installed() List installed features. Supported on Windows Server 2008 and Windows 8 and newer. .INDENT 7.0 .TP .B Returns A dictionary of installed features .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_servermanager.list_installed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_servermanager.remove(feature, remove_payload=False, restart=False) Remove an installed feature .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Some features require a reboot after installation/uninstallation. If one of these features are modified, then other features cannot be installed until the server is restarted. Additionally, some features take a while to complete installation/uninstallation, so it is a good idea to use the \fB\-t\fP option to set a longer timeout. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfeature\fP (\fI\%str\fP\fI, \fP\fI\%list\fP) \-\- .sp The name of the feature(s) to remove. This can be a single feature, a string of features in a comma delimited list (no spaces), or a list of features. .sp New in version 2018.3.0: Added the ability to pass a list of features to be removed. .IP \(bu 2 \fBremove_payload\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- True will cause the feature to be removed from the side\-by\-side store (\fB%SystemDrive%:\eWindows\eWinSxS\fP). Default is False .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Restarts the computer when uninstall is complete, if required by the role/feature removed. Default is False .UNINDENT .TP .B Returns A dictionary containing the results of the uninstall .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-t 600 \(aq*\(aq win_servermanager.remove Telnet\-Client .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_service .sp Windows Service module. .sp Changed in version 2016.11.0: Rewritten to use PyWin32 .INDENT 0.0 .TP .B salt.modules.win_service.available(name) Check if a service is available on the system. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .TP .B Returns \fBTrue\fP if the service is available, \fBFalse\fP otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.create(name, bin_path, exe_args=None, display_name=None, description=None, service_type=\(aqown\(aq, start_type=\(aqmanual\(aq, start_delayed=False, error_control=\(aqnormal\(aq, load_order_group=None, dependencies=None, account_name=\(aq.\e\eLocalSystem\(aq, account_password=None, run_interactive=False, **kwargs) Create the named service. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Specifies the service name. This is not the display_name .IP \(bu 2 \fBbin_path\fP (\fI\%str\fP) \-\- Specifies the path to the service binary file. Backslashes must be escaped, eg: \fBC:\epath\eto\ebinary.exe\fP .IP \(bu 2 \fBexe_args\fP (\fI\%str\fP) \-\- Any additional arguments required by the service binary. .IP \(bu 2 \fBdisplay_name\fP (\fI\%str\fP) \-\- The name to be displayed in the service manager. If not passed, the \fBname\fP will be used .IP \(bu 2 \fBdescription\fP (\fI\%str\fP) \-\- A description of the service .IP \(bu 2 \fBservice_type\fP (\fI\%str\fP) \-\- .sp Specifies the service type. Default is \fBown\fP\&. Valid options are as follows: .INDENT 2.0 .IP \(bu 2 kernel: Driver service .IP \(bu 2 filesystem: File system driver service .IP \(bu 2 adapter: Adapter driver service (reserved) .IP \(bu 2 recognizer: Recognizer driver service (reserved) .IP \(bu 2 own (default): Service runs in its own process .IP \(bu 2 share: Service shares a process with one or more other services .UNINDENT .IP \(bu 2 \fBstart_type\fP (\fI\%str\fP) \-\- .sp Specifies the service start type. Valid options are as follows: .INDENT 2.0 .IP \(bu 2 boot: Device driver that is loaded by the boot loader .IP \(bu 2 system: Device driver that is started during kernel initialization .IP \(bu 2 auto: Service that automatically starts .IP \(bu 2 manual (default): Service must be started manually .IP \(bu 2 disabled: Service cannot be started .UNINDENT .IP \(bu 2 \fBstart_delayed\fP (\fI\%bool\fP) \-\- Set the service to Auto(Delayed Start). Only valid if the start_type is set to \fBAuto\fP\&. If service_type is not passed, but the service is already set to \fBAuto\fP, then the flag will be set. Default is \fBFalse\fP .IP \(bu 2 \fBerror_control\fP (\fI\%str\fP) \-\- .sp The severity of the error, and action taken, if this service fails to start. Valid options are as follows: .INDENT 2.0 .IP \(bu 2 normal (normal): Error is logged and a message box is displayed .IP \(bu 2 severe: Error is logged and computer attempts a restart with the last known good configuration .IP \(bu 2 critical: Error is logged, computer attempts to restart with the last known good configuration, system halts on failure .IP \(bu 2 ignore: Error is logged and startup continues, no notification is given to the user .UNINDENT .IP \(bu 2 \fBload_order_group\fP (\fI\%str\fP) \-\- The name of the load order group to which this service belongs .IP \(bu 2 \fBdependencies\fP (\fI\%list\fP) \-\- A list of services or load ordering groups that must start before this service .IP \(bu 2 \fBaccount_name\fP (\fI\%str\fP) \-\- .sp The name of the account under which the service should run. For \fBown\fP type services this should be in the \fBdomain\eusername\fP format. The following are examples of valid built\-in service accounts: .INDENT 2.0 .IP \(bu 2 NT AuthorityLocalService .IP \(bu 2 NT AuthorityNetworkService .IP \(bu 2 NT AuthorityLocalSystem .IP \(bu 2 \&.LocalSystem .UNINDENT .IP \(bu 2 \fBaccount_password\fP (\fI\%str\fP) \-\- The password for the account name specified in \fBaccount_name\fP\&. For the above built\-in accounts, this can be None. Otherwise a password must be specified. .IP \(bu 2 \fBrun_interactive\fP (\fI\%bool\fP) \-\- If this setting is True, the service will be allowed to interact with the user. Not recommended for services that run with elevated privileges. .UNINDENT .TP .B Returns A dictionary containing information about the new service .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.create <service name> <path to exe> display_name=\(aq<display name>\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.create_win_salt_restart_task() Create a task in Windows task scheduler to enable restarting the salt\-minion .INDENT 7.0 .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.create_win_salt_restart_task() .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.delete(name, timeout=90) Delete the named service .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to delete .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- .sp The time in seconds to wait for the service to be deleted before returning. This is necessary because a service must be stopped before it can be deleted. Default is 90 seconds .sp New in version 2017.7.9,2018.3.4. .UNINDENT .TP .B Returns .INDENT 7.0 .TP .B \fBTrue\fP if successful, otherwise \fBFalse\fP\&. Also returns \fBTrue\fP if the service is not present .UNINDENT .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.delete <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.disable(name, **kwargs) Disable the named service to start at boot .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the service to disable .TP .B Returns \fBTrue\fP if disabled, \fBFalse\fP otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.disabled(name) Check to see if the named service is disabled to start on boot .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .TP .B Returns True if the service is disabled .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.enable(name, start_type=\(aqauto\(aq, start_delayed=False, **kwargs) Enable the named service to start at boot .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to enable. .IP \(bu 2 \fBstart_type\fP (\fI\%str\fP) \-\- .sp Specifies the service start type. Valid options are as follows: .INDENT 2.0 .IP \(bu 2 boot: Device driver that is loaded by the boot loader .IP \(bu 2 system: Device driver that is started during kernel initialization .IP \(bu 2 auto: Service that automatically starts .IP \(bu 2 manual: Service must be started manually .IP \(bu 2 disabled: Service cannot be started .UNINDENT .IP \(bu 2 \fBstart_delayed\fP (\fI\%bool\fP) \-\- Set the service to Auto(Delayed Start). Only valid if the start_type is set to \fBAuto\fP\&. If service_type is not passed, but the service is already set to \fBAuto\fP, then the flag will be set. .UNINDENT .TP .B Returns \fBTrue\fP if successful, \fBFalse\fP otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.enabled(name, **kwargs) Check to see if the named service is enabled to start on boot .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .TP .B Returns True if the service is set to start .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.execute_salt_restart_task() Run the Windows Salt restart task .INDENT 7.0 .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.execute_salt_restart_task() .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.get_all() Return all installed services .INDENT 7.0 .TP .B Returns Returns a list of all services on the system. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.get_disabled() Return a list of disabled services. Disabled is defined as a service that is marked \(aqDisabled\(aq or \(aqManual\(aq. .INDENT 7.0 .TP .B Returns A list of disabled services. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.get_enabled() Return a list of enabled services. Enabled is defined as a service that is marked to Auto Start. .INDENT 7.0 .TP .B Returns A list of enabled services .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.get_service_name(*args) The Display Name is what is displayed in Windows when services.msc is executed. Each Display Name has an associated Service Name which is the actual name of the service. This function allows you to discover the Service Name by returning a dictionary of Display Names and Service Names, or filter by adding arguments of Display Names. .sp If no args are passed, return a dict of all services where the keys are the service Display Names and the values are the Service Names. .sp If arguments are passed, create a dict of Display Names and Service Names .INDENT 7.0 .TP .B Returns A dictionary of display names and service names .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_service_name salt \(aq*\(aq service.get_service_name \(aqGoogle Update Service (gupdate)\(aq \(aqDHCP Client\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.getsid(name) Return the SID for this windows service .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the service for which to return the SID .TP .B Returns A string representing the SID for the service .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.getsid <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.info(name) Get information about a service on the system .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the service. This is not the display name. Use \fBget_service_name\fP to find the service name. .TP .B Returns A dictionary containing information about the service. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.info spooler .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.missing(name) The inverse of service.available. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .TP .B Returns \fBTrue\fP if the service is missing, \fBFalse\fP otherwise .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.modify(name, bin_path=None, exe_args=None, display_name=None, description=None, service_type=None, start_type=None, start_delayed=None, error_control=None, load_order_group=None, dependencies=None, account_name=None, account_password=None, run_interactive=None) Modify a service\(aqs parameters. Changes will not be made for parameters that are not passed. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service. Can be found using the \fBservice.get_service_name\fP function .IP \(bu 2 \fBbin_path\fP (\fI\%str\fP) \-\- The path to the service executable. Backslashes must be escaped, eg: \fBC:\epath\eto\ebinary.exe\fP .IP \(bu 2 \fBexe_args\fP (\fI\%str\fP) \-\- Any arguments required by the service executable .IP \(bu 2 \fBdisplay_name\fP (\fI\%str\fP) \-\- The name to display in the service manager .IP \(bu 2 \fBdescription\fP (\fI\%str\fP) \-\- The description to display for the service .IP \(bu 2 \fBservice_type\fP (\fI\%str\fP) \-\- .sp Specifies the service type. Default is \fBown\fP\&. Valid options are as follows: .INDENT 2.0 .IP \(bu 2 kernel: Driver service .IP \(bu 2 filesystem: File system driver service .IP \(bu 2 adapter: Adapter driver service (reserved) .IP \(bu 2 recognizer: Recognizer driver service (reserved) .IP \(bu 2 own (default): Service runs in its own process .IP \(bu 2 share: Service shares a process with one or more other services .UNINDENT .IP \(bu 2 \fBstart_type\fP (\fI\%str\fP) \-\- .sp Specifies the service start type. Valid options are as follows: .INDENT 2.0 .IP \(bu 2 boot: Device driver that is loaded by the boot loader .IP \(bu 2 system: Device driver that is started during kernel initialization .IP \(bu 2 auto: Service that automatically starts .IP \(bu 2 manual: Service must be started manually .IP \(bu 2 disabled: Service cannot be started .UNINDENT .IP \(bu 2 \fBstart_delayed\fP (\fI\%bool\fP) \-\- Set the service to Auto(Delayed Start). Only valid if the start_type is set to \fBAuto\fP\&. If service_type is not passed, but the service is already set to \fBAuto\fP, then the flag will be set. .IP \(bu 2 \fBerror_control\fP (\fI\%str\fP) \-\- .sp The severity of the error, and action taken, if this service fails to start. Valid options are as follows: .INDENT 2.0 .IP \(bu 2 normal: Error is logged and a message box is displayed .IP \(bu 2 severe: Error is logged and computer attempts a restart with the last known good configuration .IP \(bu 2 critical: Error is logged, computer attempts to restart with the last known good configuration, system halts on failure .IP \(bu 2 ignore: Error is logged and startup continues, no notification is given to the user .UNINDENT .IP \(bu 2 \fBload_order_group\fP (\fI\%str\fP) \-\- The name of the load order group to which this service belongs .IP \(bu 2 \fBdependencies\fP (\fI\%list\fP) \-\- A list of services or load ordering groups that must start before this service .IP \(bu 2 \fBaccount_name\fP (\fI\%str\fP) \-\- .sp The name of the account under which the service should run. For \fBown\fP type services this should be in the \fBdomain\eusername\fP format. The following are examples of valid built\-in service accounts: .INDENT 2.0 .IP \(bu 2 NT AuthorityLocalService .IP \(bu 2 NT AuthorityNetworkService .IP \(bu 2 NT AuthorityLocalSystem .IP \(bu 2 \&.LocalSystem .UNINDENT .IP \(bu 2 \fBaccount_password\fP (\fI\%str\fP) \-\- The password for the account name specified in \fBaccount_name\fP\&. For the above built\-in accounts, this can be None. Otherwise a password must be specified. .IP \(bu 2 \fBrun_interactive\fP (\fI\%bool\fP) \-\- If this setting is True, the service will be allowed to interact with the user. Not recommended for services that run with elevated privileges. .UNINDENT .TP .B Returns a dictionary of changes made .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.modify spooler start_type=disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.restart(name, timeout=90) Restart the named service. This issues a stop command followed by a start. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- .sp The name of the service to restart. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 If the name passed is \fBsalt\-minion\fP a scheduled task is created and executed to restart the salt\-minion service. .UNINDENT .UNINDENT .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- .sp The time in seconds to wait for the service to stop and start before returning. Default is 90 seconds .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The timeout is cumulative meaning it is applied to the stop and then to the start command. A timeout of 90 could take up to 180 seconds if the service is long in stopping and starting .UNINDENT .UNINDENT .sp New in version 2017.7.9,2018.3.4. .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.start(name, timeout=90) Start the specified service. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 You cannot start a disabled service in Windows. If the service is disabled, it will be changed to \fBManual\fP start. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to start .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- .sp The time in seconds to wait for the service to start before returning. Default is 90 seconds .sp New in version 2017.7.9,2018.3.4. .UNINDENT .TP .B Returns .INDENT 7.0 .TP .B \fBTrue\fP if successful, otherwise \fBFalse\fP\&. Also returns \fBTrue\fP if the service is already started .UNINDENT .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.status(name, *args, **kwargs) Return the status for a service. If the name contains globbing, a dict mapping service name to True/False values is returned. .sp Changed in version 2018.3.0: The service name can now be a glob (e.g. \fBsalt*\fP) .sp Changed in version 3006.0: Returns \(dqNot Found\(dq if the service is not found on the system .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the service to check .TP .B Returns True if running, False otherwise dict: Maps service name to True if running, False otherwise str: Not Found if the service is not found on the system .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.stop(name, timeout=90) Stop the specified service .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the service to stop .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- .sp The time in seconds to wait for the service to stop before returning. Default is 90 seconds .sp New in version 2017.7.9,2018.3.4. .UNINDENT .TP .B Returns .INDENT 7.0 .TP .B \fBTrue\fP if successful, otherwise \fBFalse\fP\&. Also returns \fBTrue\fP if the service is already stopped .UNINDENT .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_shadow .sp Manage the shadow file .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage passwords on a minion, and it is using a different module (or gives an error similar to \fI\(aqshadow.info\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_shadow.info(name) Return information for the specified user This is just returns dummy data so that salt states can work. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the user account to show. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.info root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_shadow.require_password_change(name) Require the user to change their password the next time they log in. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the user account to require a password change. .TP .B Returns True if successful. False if unsuccessful. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.require_password_change <username> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_shadow.set_expire(name, expire) Set the expiration date for a user account. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the user account to edit. .IP \(bu 2 \fBexpire\fP \-\- The date the account will expire. .UNINDENT .TP .B Returns True if successful. False if unsuccessful. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_expire <username> 2016/7/1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_shadow.set_password(name, password) Set the password for a named user. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the user account .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The new password .UNINDENT .TP .B Returns True if successful. False if unsuccessful. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_password root mysecretpassword .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_shadow.unlock_account(name) Unlocks a user account. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the user account to unlock. .TP .B Returns True if successful. False if unsuccessful. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.unlock_account <username> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_shortcut .sp Execution module for creating shortcuts on Windows. Handles file shortcuts (\fI\&.lnk\fP) and url shortcuts (\fI\&.url\fP). Allows for the configuration of icons and hot keys on file shortcuts. Changing the icon and hot keys are unsupported for url shortcuts. .sp New in version 3005. .INDENT 0.0 .TP .B salt.modules.win_shortcut.create(path, target, arguments=\(aq\(aq, description=\(aq\(aq, hot_key=\(aq\(aq, icon_index=0, icon_location=\(aq\(aq, window_style=\(aqNormal\(aq, working_dir=\(aq\(aq, backup=False, force=False, make_dirs=False, user=None) Create a new shortcut. This can be a file shortcut (\fB\&.lnk\fP) or a url shortcut (\fB\&.url\fP). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The full path to the shortcut. Must have a \fI\&.lnk\fP or \fI\&.url\fP file extension. .IP \(bu 2 \fBtarget\fP (\fI\%str\fP) \-\- The full path to the target .IP \(bu 2 \fBarguments\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- Any arguments to be passed to the target .IP \(bu 2 \fBdescription\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The description for the shortcut. This is shown in the \fBComment\fP field of the dialog box. Default is an empty string .IP \(bu 2 \fBhot_key\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- .sp A combination of hot Keys to trigger this shortcut. This is something like \fBCtrl+Alt+D\fP\&. This is shown in the \fBShortcut key\fP field in the dialog box. Default is an empty string. Available options are: .INDENT 2.0 .IP \(bu 2 Ctrl .IP \(bu 2 Alt .IP \(bu 2 Shift .IP \(bu 2 Ext .UNINDENT .IP \(bu 2 \fBicon_index\fP (\fI\%int\fP\fI, \fP\fIoptional\fP) \-\- The index for the icon to use in files that contain multiple icons. Default is 0 .IP \(bu 2 \fBicon_location\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The full path to a file containing icons. This is shown in the \fBChange Icon\fP dialog box by clicking the \fBChange Icon\fP button. If no file is specified and a binary is passed as the target, Windows will attempt to get the icon from the binary file. Default is an empty string .IP \(bu 2 \fBwindow_style\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- .sp The window style the program should start in. This is shown in the \fBRun\fP field of the dialog box. Default is \fBNormal\fP\&. Valid options are: .INDENT 2.0 .IP \(bu 2 Normal .IP \(bu 2 Minimized .IP \(bu 2 Maximized .UNINDENT .IP \(bu 2 \fBworking_dir\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The full path to the working directory for the program to run in. This is shown in the \fBStart in\fP field of the dialog box. .IP \(bu 2 \fBbackup\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- If there is already a shortcut with the same name, set this value to \fBTrue\fP to backup the existing shortcut and continue creating the new shortcut. Default is \fBFalse\fP .IP \(bu 2 \fBforce\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- If there is already a shortcut with the same name and you aren\(aqt backing up the shortcut, set this value to \fBTrue\fP to remove the existing shortcut and create a new with these settings. Default is \fBFalse\fP .IP \(bu 2 \fBmake_dirs\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- If the parent directory structure does not exist for the new shortcut, create it. Default is \fBFalse\fP .IP \(bu 2 \fBuser\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The user to be the owner of any directories created by setting \fBmake_dirs\fP to \fBTrue\fP\&. If no value is passed Salt will use the user account that it is running under. Default is an empty string. .UNINDENT .TP .B Returns True if successful .TP .B Return type \fI\%bool\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If the path is not a \fB\&.lnk\fP or \fB\&.url\fP file extension. .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If there is an existing shortcut with the same name and \fBbackup\fP and \fBforce\fP are both \fBFalse\fP .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If the parent directory is not created and \fBmake_dirs\fP is \fBFalse\fP .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- If there was an error creating the parent directories .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Create a shortcut and set the \(ga\(gaShortcut key\(ga\(ga (\(ga\(gahot_key\(ga\(ga) salt * shortcut.create \(dqC:\epath\eto\eshortcut.lnk\(dq \(dqC:\eWindows\enotepad.exe\(dq hot_key=\(dqCtrl+Alt+N\(dq # Create a shortcut and change the icon to the 3rd one in the icon file salt * shortcut.create \(dqC:\epath\eto\eshortcut.lnk\(dq \(dqC:\eWindows\enotepad.exe\(dq icon_location=\(dqC:\epath\eto\eicon.ico\(dq icon_index=2 # Create a shortcut and change the startup mode to full screen salt * shortcut.create \(dqC:\epath\eto\eshortcut.lnk\(dq \(dqC:\eWindows\enotepad.exe\(dq window_style=\(dqMaximized\(dq # Create a shortcut and change the icon salt * shortcut.create \(dqC:\epath\eto\eshortcut.lnk\(dq \(dqC:\eWindows\enotepad.exe\(dq icon_location=\(dqC:\epath\eto\eicon.ico\(dq # Create a shortcut and force it to overwrite an existing shortcut salt * shortcut.create \(dqC:\epath\eto\eshortcut.lnk\(dq \(dqC:\eWindows\enotepad.exe\(dq force=True # Create a shortcut and create any parent directories if they are missing salt * shortcut.create \(dqC:\epath\eto\eshortcut.lnk\(dq \(dqC:\eWindows\enotepad.exe\(dq make_dirs=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_shortcut.get(path) Gets the properties for a shortcut .INDENT 7.0 .TP .B Parameters \fBpath\fP (\fI\%str\fP) \-\- The path to the shortcut. Must have a \fI\&.lnk\fP or \fI\&.url\fP file extension. .TP .B Returns .INDENT 7.0 .TP .B A dictionary containing all available properties for the specified shortcut .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt * shortcut.get path=\(dqC:\epath\eto\eshortcut.lnk\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_shortcut.modify(path, target=\(aq\(aq, arguments=\(aq\(aq, description=\(aq\(aq, hot_key=\(aq\(aq, icon_index=0, icon_location=\(aq\(aq, window_style=\(aqNormal\(aq, working_dir=\(aq\(aq) Modify an existing shortcut. This can be a file shortcut (\fB\&.lnk\fP) or a url shortcut (\fB\&.url\fP). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The full path to the shortcut. Must have a \fI\&.lnk\fP or \fI\&.url\fP file extension. .IP \(bu 2 \fBtarget\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The full path to the target .IP \(bu 2 \fBarguments\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- Any arguments to be passed to the target .IP \(bu 2 \fBdescription\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The description for the shortcut. This is shown in the \fBComment\fP field of the dialog box. Default is an empty string .IP \(bu 2 \fBhot_key\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- .sp A combination of hot Keys to trigger this shortcut. This is something like \fBCtrl+Alt+D\fP\&. This is shown in the \fBShortcut key\fP field in the dialog box. Default is an empty string. Available options are: .INDENT 2.0 .IP \(bu 2 Ctrl .IP \(bu 2 Alt .IP \(bu 2 Shift .IP \(bu 2 Ext .UNINDENT .IP \(bu 2 \fBicon_index\fP (\fI\%int\fP\fI, \fP\fIoptional\fP) \-\- The index for the icon to use in files that contain multiple icons. Default is 0 .IP \(bu 2 \fBicon_location\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The full path to a file containing icons. This is shown in the \fBChange Icon\fP dialog box by clicking the \fBChange Icon\fP button. If no file is specified and a binary is passed as the target, Windows will attempt to get the icon from the binary file. Default is an empty string .IP \(bu 2 \fBwindow_style\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- .sp The window style the program should start in. This is shown in the \fBRun\fP field of the dialog box. Default is \fBNormal\fP\&. Valid options are: .INDENT 2.0 .IP \(bu 2 Normal .IP \(bu 2 Minimized .IP \(bu 2 Maximized .UNINDENT .IP \(bu 2 \fBworking_dir\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The full path to the working directory for the program to run in. This is shown in the \fBStart in\fP field of the dialog box. .UNINDENT .TP .B Returns True if successful .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Modify an existing shortcut. Set it to target notepad.exe salt * shortcut.modify \(dqC:\epath\eto\eshortcut.lnk\(dq \(dqC:\eWindows\enotepad.exe\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_smtp_server .sp Module for managing IIS SMTP server configuration on Windows servers. The Windows features \(aqSMTP\-Server\(aq and \(aqWeb\-WMI\(aq must be installed. .INDENT 0.0 .TP .B depends wmi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_smtp_server.get_connection_ip_list(as_wmi_format=False, server=\(aqSmtpSvc/1\(aq) Get the IPGrant list for the SMTP virtual server. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBas_wmi_format\fP (\fI\%bool\fP) \-\- Returns the connection IPs as a list in the format WMI expects. .IP \(bu 2 \fBserver\fP (\fI\%str\fP) \-\- The SMTP server name. .UNINDENT .TP .B Returns A dictionary of the IP and subnet pairs. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_smtp_server.get_connection_ip_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_smtp_server.get_log_format(server=\(aqSmtpSvc/1\(aq) Get the active log format for the SMTP virtual server. .INDENT 7.0 .TP .B Parameters \fBserver\fP (\fI\%str\fP) \-\- The SMTP server name. .TP .B Returns A string of the log format name. .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_smtp_server.get_log_format .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_smtp_server.get_log_format_types() Get all available log format names and ids. .INDENT 7.0 .TP .B Returns A dictionary of the log format names and ids. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_smtp_server.get_log_format_types .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_smtp_server.get_relay_ip_list(server=\(aqSmtpSvc/1\(aq) Get the RelayIpList list for the SMTP virtual server. .INDENT 7.0 .TP .B Parameters \fBserver\fP (\fI\%str\fP) \-\- The SMTP server name. .TP .B Returns A list of the relay IPs. .TP .B Return type \fI\%list\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A return value of None corresponds to the restrictive \(aqOnly the list below\(aq GUI parameter with an empty access list, and setting an empty list/tuple corresponds to the more permissive \(aqAll except the list below\(aq GUI parameter. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_smtp_server.get_relay_ip_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_smtp_server.get_server_setting(settings, server=\(aqSmtpSvc/1\(aq) Get the value of the setting for the SMTP virtual server. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsettings\fP (\fI\%str\fP) \-\- A list of the setting names. .IP \(bu 2 \fBserver\fP (\fI\%str\fP) \-\- The SMTP server name. .UNINDENT .TP .B Returns A dictionary of the provided settings and their values. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_smtp_server.get_server_setting settings=\(dq[\(aqMaxRecipients\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_smtp_server.get_servers() Get the SMTP virtual server names. .INDENT 7.0 .TP .B Returns A list of the SMTP virtual servers. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_smtp_server.get_servers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_smtp_server.set_connection_ip_list(addresses=None, grant_by_default=False, server=\(aqSmtpSvc/1\(aq) Set the IPGrant list for the SMTP virtual server. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBaddresses\fP (\fI\%str\fP) \-\- A dictionary of IP + subnet pairs. .IP \(bu 2 \fBgrant_by_default\fP (\fI\%bool\fP) \-\- Whether the addresses should be a blacklist or whitelist. .IP \(bu 2 \fBserver\fP (\fI\%str\fP) \-\- The SMTP server name. .UNINDENT .TP .B Returns A boolean representing whether the change 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 win_smtp_server.set_connection_ip_list addresses=\(dq{\(aq127.0.0.1\(aq: \(aq255.255.255.255\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_smtp_server.set_log_format(log_format, server=\(aqSmtpSvc/1\(aq) Set the active log format for the SMTP virtual server. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBlog_format\fP (\fI\%str\fP) \-\- The log format name. .IP \(bu 2 \fBserver\fP (\fI\%str\fP) \-\- The SMTP server name. .UNINDENT .TP .B Returns A boolean representing whether the change 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 win_smtp_server.set_log_format \(aqMicrosoft IIS Log File Format\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_smtp_server.set_relay_ip_list(addresses=None, server=\(aqSmtpSvc/1\(aq) Set the RelayIpList list for the SMTP virtual server. .sp Due to the unusual way that Windows stores the relay IPs, it is advisable to retrieve the existing list you wish to set from a pre\-configured server. .sp For example, setting \(aq127.0.0.1\(aq as an allowed relay IP through the GUI would generate an actual relay IP list similar to the following: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [\(aq24.0.0.128\(aq, \(aq32.0.0.128\(aq, \(aq60.0.0.128\(aq, \(aq68.0.0.128\(aq, \(aq1.0.0.0\(aq, \(aq76.0.0.0\(aq, \(aq0.0.0.0\(aq, \(aq0.0.0.0\(aq, \(aq1.0.0.0\(aq, \(aq1.0.0.0\(aq, \(aq2.0.0.0\(aq, \(aq2.0.0.0\(aq, \(aq4.0.0.0\(aq, \(aq0.0.0.0\(aq, \(aq76.0.0.128\(aq, \(aq0.0.0.0\(aq, \(aq0.0.0.0\(aq, \(aq0.0.0.0\(aq, \(aq0.0.0.0\(aq, \(aq255.255.255.255\(aq, \(aq127.0.0.1\(aq] .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Setting the list to None corresponds to the restrictive \(aqOnly the list below\(aq GUI parameter with an empty access list configured, and setting an empty list/tuple corresponds to the more permissive \(aqAll except the list below\(aq GUI parameter. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBaddresses\fP (\fI\%str\fP) \-\- A list of the relay IPs. The order of the list is important. .IP \(bu 2 \fBserver\fP (\fI\%str\fP) \-\- The SMTP server name. .UNINDENT .TP .B Returns A boolean representing whether the change 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 win_smtp_server.set_relay_ip_list addresses=\(dq[\(aq192.168.1.1\(aq, \(aq172.16.1.1\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_smtp_server.set_server_setting(settings, server=\(aqSmtpSvc/1\(aq) Set the value of the setting for the SMTP virtual server. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The setting names are case\-sensitive. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsettings\fP (\fI\%str\fP) \-\- A dictionary of the setting names and their values. .IP \(bu 2 \fBserver\fP (\fI\%str\fP) \-\- The SMTP server name. .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 win_smtp_server.set_server_setting settings=\(dq{\(aqMaxRecipients\(aq: \(aq500\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_snmp .sp Module for managing SNMP service settings on Windows servers. The Windows feature \(aqSNMP\-Service\(aq must be installed. .INDENT 0.0 .TP .B salt.modules.win_snmp.get_agent_service_types() Get the sysServices types that can be configured. .INDENT 7.0 .TP .B Returns A list of service types. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_snmp.get_agent_service_types .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_snmp.get_agent_settings() Determine the value of the SNMP sysContact, sysLocation, and sysServices settings. .INDENT 7.0 .TP .B Returns A dictionary of the agent settings. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_snmp.get_agent_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_snmp.get_auth_traps_enabled() Determine whether the host is configured to send authentication traps. .INDENT 7.0 .TP .B Returns True if traps are enabled, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_snmp.get_auth_traps_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_snmp.get_community_names() Get the current accepted SNMP community names and their permissions. .sp If community names are being managed by Group Policy, those values will be returned instead like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C TestCommunity: Managed by GPO .ft P .fi .UNINDENT .UNINDENT .sp Community names managed normally will denote the permission instead: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C TestCommunity: Read Only .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary of community names and permissions. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_snmp.get_community_names .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_snmp.get_permission_types() Get the permission types that can be configured for communities. .INDENT 7.0 .TP .B Returns A list of permission types. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_snmp.get_permission_types .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_snmp.set_agent_settings(contact=None, location=None, services=None) Manage the SNMP sysContact, sysLocation, and sysServices settings. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontact\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The SNMP contact. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The SNMP location. .IP \(bu 2 \fBservices\fP (\fI\%list\fP\fI, \fP\fIoptional\fP) \-\- A list of selected services. The possible service names can be found via \fBwin_snmp.get_agent_service_types\fP\&. To disable all services pass a list of None, ie: [\(aqNone\(aq] .UNINDENT .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_snmp.set_agent_settings contact=\(aqContact Name\(aq location=\(aqPlace\(aq services=\(dq[\(aqPhysical\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_snmp.set_auth_traps_enabled(status=True) Manage the sending of authentication traps. .INDENT 7.0 .TP .B Parameters \fBstatus\fP (\fI\%bool\fP) \-\- True to enable traps. False to disable. .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_snmp.set_auth_traps_enabled status=\(aqTrue\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_snmp.set_community_names(communities) Manage the SNMP accepted community names and their permissions. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Settings managed by Group Policy will always take precedence over those set using the SNMP interface. Therefore if this function finds Group Policy settings it will raise a CommandExecutionError .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBcommunities\fP (\fI\%dict\fP) \-\- A dictionary of SNMP community names and permissions. The possible permissions can be found via \fBwin_snmp.get_permission_types\fP\&. .TP .B Returns True if successful, otherwise False .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If SNMP settings are being managed by Group Policy .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_snmp.set_community_names communities=\(dq{\(aqTestCommunity\(aq: \(aqRead Only\(aq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_status .sp Module for returning various status data about a minion. These data can be useful for compiling into stats later, or for problem solving if your minion is having problems. .sp New in version 0.12.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 wmi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.win_status.SYSTEM_PERFORMANCE_INFORMATION .INDENT 7.0 .TP .B AvailablePagedPoolPages Structure/Union member .UNINDENT .INDENT 7.0 .TP .B AvailablePages Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CacheIoCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CacheReadCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CacheTransitionCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcCopyReadNoWait Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcCopyReadNoWaitMiss Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcCopyReadWait Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcCopyReadWaitMiss Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcDataFlushes Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcDataPages Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcDirtyPagesThreshold Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcFastMdlReadNoWait Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcFastMdlReadNotPossible Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcFastMdlReadResourceMiss Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcFastMdlReadWait Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcFastReadNoWait Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcFastReadNotPossible Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcFastReadResourceMiss Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcFastReadWait Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcLazyWriteIos Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcLazyWritePages Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcMapDataNoWait Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcMapDataNoWaitMiss Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcMapDataWait Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcMapDataWaitMiss Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcMdlReadNoWait Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcMdlReadNoWaitMiss Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcMdlReadWait Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcMdlReadWaitMiss Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcPinMappedDataCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcPinReadNoWait Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcPinReadNoWaitMiss Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcPinReadWait Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcPinReadWaitMiss Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcReadAheadIos Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CcTotalDirtyPages Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CommitLimit Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CommittedPages Structure/Union member .UNINDENT .INDENT 7.0 .TP .B ContextSwitches Structure/Union member .UNINDENT .INDENT 7.0 .TP .B CopyOnWriteCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B DemandZeroCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B DirtyPagesWriteCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B DirtyWriteIoCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B FirstLevelTbFills Structure/Union member .UNINDENT .INDENT 7.0 .TP .B FreeSystemPtes Structure/Union member .UNINDENT .INDENT 7.0 .TP .B IdleProcessTime Structure/Union member .UNINDENT .INDENT 7.0 .TP .B IoOtherOperationCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B IoOtherTransferCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B IoReadOperationCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B IoReadTransferCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B IoWriteOperationCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B IoWriteTransferCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B MappedPagesWriteCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B MappedWriteIoCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B NonPagedPoolAllocs Structure/Union member .UNINDENT .INDENT 7.0 .TP .B NonPagedPoolFrees Structure/Union member .UNINDENT .INDENT 7.0 .TP .B NonPagedPoolLookasideHits Structure/Union member .UNINDENT .INDENT 7.0 .TP .B NonPagedPoolPages Structure/Union member .UNINDENT .INDENT 7.0 .TP .B PageFaultCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B PageReadCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B PageReadIoCount Structure/Union member .UNINDENT .INDENT 7.0 .TP .B PagedPoolAllocs Structure/Union member .UNINDENT .INDENT 7.0 .TP .B PagedPoolFrees Structure/Union member .UNINDENT .INDENT 7.0 .TP .B PagedPoolLookasideHits Structure/Union member .UNINDENT .INDENT 7.0 .TP .B PagedPoolPages Structure/Union member .UNINDENT .INDENT 7.0 .TP .B PeakCommitment Structure/Union member .UNINDENT .INDENT 7.0 .TP .B ResidentAvailablePages Structure/Union member .UNINDENT .INDENT 7.0 .TP .B ResidentPagedPoolPage Structure/Union member .UNINDENT .INDENT 7.0 .TP .B ResidentSystemCachePage Structure/Union member .UNINDENT .INDENT 7.0 .TP .B ResidentSystemCodePage Structure/Union member .UNINDENT .INDENT 7.0 .TP .B ResidentSystemDriverPage Structure/Union member .UNINDENT .INDENT 7.0 .TP .B SecondLevelTbFills Structure/Union member .UNINDENT .INDENT 7.0 .TP .B SharedCommittedPages Structure/Union member .UNINDENT .INDENT 7.0 .TP .B SystemCalls Structure/Union member .UNINDENT .INDENT 7.0 .TP .B TotalSystemCodePages Structure/Union member .UNINDENT .INDENT 7.0 .TP .B TotalSystemDriverPages Structure/Union member .UNINDENT .INDENT 7.0 .TP .B TransitionCount Structure/Union member .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_status.cpuload() New in version 2015.8.0. .sp Return the processor load as a percentage .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.cpuload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_status.cpustats() Return information about the CPU. .INDENT 7.0 .TP .B Returns dict: A dictionary containing information about the CPU stats .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt * status.cpustats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_status.diskusage(human_readable=False, path=None) New in version 2015.8.0. .sp Return the disk usage for this minion .INDENT 7.0 .TP .B human_readable False If \fBTrue\fP, usage will be in KB/MB/GB etc. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.diskusage path=c:/salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_status.loadavg() Returns counter information related to the load of the machine .INDENT 7.0 .TP .B Returns A dictionary of counters .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt * status.loadavg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_status.master(master=None, connected=True) New in version 2015.5.0. .sp Fire an event if the minion gets disconnected from its master. This function is meant to be run via a scheduled job from the minion. If master_ip is an FQDN/Hostname, is must be resolvable to a valid IPv4 address. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_status.meminfo() Return information about physical and virtual memory on the system .INDENT 7.0 .TP .B Returns A dictionary of information about memory on the system .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt * status.meminfo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_status.procs(count=False) Return the process data .INDENT 7.0 .TP .B count False If \fBTrue\fP, this function will simply return the number of processes. .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.procs salt \(aq*\(aq status.procs count .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_status.saltmem(human_readable=False) New in version 2015.8.0. .sp Returns the amount of memory that salt is using .INDENT 7.0 .TP .B human_readable False return the value in a nicely formatted number .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.saltmem salt \(aq*\(aq status.saltmem human_readable=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_status.uptime(human_readable=False) New in version 2015.8.0. .sp Return the system uptime for the machine .INDENT 7.0 .TP .B Parameters \fBhuman_readable\fP (\fI\%bool\fP) \-\- .sp Return uptime in human readable format if \fBTrue\fP, otherwise return seconds. Default is \fBFalse\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Human readable format is \fBdays, hours:min:sec\fP\&. Days will only be displayed if more than 0 .UNINDENT .UNINDENT .TP .B Returns The uptime in seconds or human readable format depending on the value of \fBhuman_readable\fP .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq status.uptime salt \(aq*\(aq status.uptime human_readable=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_status.vmstats() Return information about the virtual memory on the machine .INDENT 7.0 .TP .B Returns A dictionary of virtual memory stats .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt * status.vmstats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_system .sp Module for managing Windows systems and getting Windows system information. Support for reboot, shutdown, join domain, rename .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 pywintypes .IP \(bu 2 win32api .IP \(bu 2 win32con .IP \(bu 2 win32net .IP \(bu 2 wmi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_computer_desc() Get the Windows computer description .INDENT 7.0 .TP .B Returns Returns the computer description if found. Otherwise returns \fBFalse\fP\&. .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.get_computer_desc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_computer_description() This function is an alias of \fBget_computer_desc\fP\&. .INDENT 7.0 .INDENT 3.5 Get the Windows computer description .INDENT 0.0 .TP .B Returns: str: Returns the computer description if found. Otherwise returns \fBFalse\fP\&. .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.get_computer_desc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_computer_name() Get the Windows computer name .INDENT 7.0 .TP .B Returns Returns the computer name if found. Otherwise returns \fBFalse\fP\&. .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.get_computer_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_domain_workgroup() Get the domain or workgroup the computer belongs to. .sp New in version 2015.5.7. .sp New in version 2015.8.2. .INDENT 7.0 .TP .B Returns The name of the domain or workgroup .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.get_domain_workgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_hostname() Get the hostname of the windows minion .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Returns Returns the hostname of the windows minion .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.get_hostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_pending_component_servicing() Determine whether there are pending Component Based Servicing tasks that require a reboot. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Returns \fBTrue\fP if there are pending Component Based Servicing tasks, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_pending_component_servicing .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_pending_computer_name() Get a pending computer name. If the computer name has been changed, and the change is pending a system reboot, this function will return the pending computer name. Otherwise, \fBNone\fP will be returned. If there was an error retrieving the pending computer name, \fBFalse\fP will be returned, and an error message will be logged to the minion log. .INDENT 7.0 .TP .B Returns Returns the pending name if pending restart. Returns \fBNone\fP if not pending restart. .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.get_pending_computer_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_pending_domain_join() Determine whether there is a pending domain join action that requires a reboot. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Returns \fBTrue\fP if there is a pending domain join action, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_pending_domain_join .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_pending_file_rename() Determine whether there are pending file rename operations that require a reboot. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Returns \fBTrue\fP if there are pending file rename operations, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_pending_file_rename .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_pending_reboot() Determine whether there is a reboot pending. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Returns \fBTrue\fP if the system is pending reboot, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_pending_reboot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_pending_reboot_details() Determine which check is signalling that the system is pending a reboot. Useful in determining why your system is signalling that it needs a reboot. .sp New in version 3001. .INDENT 7.0 .TP .B Returns A dictionary of the results of each system that would indicate a pending reboot .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_pending_reboot_details .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_pending_servermanager() Determine whether there are pending Server Manager tasks that require a reboot. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Returns \fBTrue\fP if there are pending Server Manager tasks, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_pending_servermanager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_pending_update() Determine whether there are pending updates that require a reboot. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Returns \fBTrue\fP if there are pending updates, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_pending_update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_pending_windows_update() Check the Windows Update system for a pending reboot state. .sp This leverages the Windows Update System to determine if the system is pending a reboot. .sp New in version 3001. .INDENT 7.0 .TP .B Returns \fBTrue\fP if the Windows Update system reports a pending update, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_pending_windows_update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_reboot_required_witnessed() Determine if at any time during the current boot session the salt minion witnessed an event indicating that a reboot is required. .sp This function will return \fBTrue\fP if an install completed with exit code 3010 during the current boot session and can be extended where appropriate in the future. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Returns \fBTrue\fP if the \fBRequires reboot\fP registry flag is set to \fB1\fP, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_reboot_required_witnessed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_system_date() Get the Windows system date .INDENT 7.0 .TP .B Returns Returns the system date .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.get_system_date .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_system_info() Get system information. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Not all system info is available across all versions of Windows. If it is not available on an older version, it will be skipped .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns Dictionary containing information about the system to include name, description, version, etc... .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.get_system_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.get_system_time() Get the system time. .INDENT 7.0 .TP .B Returns Returns the system time in HH:MM:SS AM/PM format. .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.get_system_time .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.halt(timeout=5, in_seconds=False) Halt a running system. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- Number of seconds before halting the system. Default is 5 seconds. .IP \(bu 2 \fBin_seconds\fP (\fI\%bool\fP) \-\- .sp Whether to treat timeout as seconds or minutes. .sp New in version 2015.8.0. .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.halt 5 True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.init(runlevel) Change the system runlevel on sysV compatible systems. Not applicable to Windows .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.init 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.join_domain(domain, username=None, password=None, account_ou=None, account_exists=False, restart=False) Join a computer to an Active Directory domain. Requires a reboot. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain\fP (\fI\%str\fP) \-\- The domain to which the computer should be joined, e.g. \fBexample.com\fP .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- Username of an account which is authorized to join computers to the specified domain. Needs to be either fully qualified like \fBuser@domain.tld\fP or simply \fBuser\fP .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- Password of the specified user .IP \(bu 2 \fBaccount_ou\fP (\fI\%str\fP) \-\- The DN of the OU below which the account for this computer should be created when joining the domain, e.g. \fBou=computers,ou=departm_432,dc=my\-company,dc=com\fP .IP \(bu 2 \fBaccount_exists\fP (\fI\%bool\fP) \-\- If set to \fBTrue\fP the computer will only join the domain if the account already exists. If set to \fBFalse\fP the computer account will be created if it does not exist, otherwise it will use the existing account. Default is \fBFalse\fP .IP \(bu 2 \fBrestart\fP (\fI\%bool\fP) \-\- .sp \fBTrue\fP will restart the computer after a successful join. Default is \fBFalse\fP .sp New in version 2015.5.7,2015.8.2. .UNINDENT .TP .B Returns Returns a dictionary if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.join_domain domain=\(aqdomain.tld\(aq \e username=\(aqjoinuser\(aq password=\(aqjoinpassword\(aq \e account_ou=\(aqou=clients,ou=org,dc=domain,dc=tld\(aq \e account_exists=False, restart=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.lock() Lock the workstation. .INDENT 7.0 .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.lock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.poweroff(timeout=5, in_seconds=False) Power off a running system. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- Number of seconds before powering off the system. Default is 5 seconds. .IP \(bu 2 \fBin_seconds\fP (\fI\%bool\fP) \-\- .sp Whether to treat timeout as seconds or minutes. .sp New in version 2015.8.0. .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.poweroff 5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.reboot(timeout=5, in_seconds=False, wait_for_reboot=False, only_on_pending_reboot=False) Reboot a running system. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- The number of minutes/seconds before rebooting the system. Use of minutes or seconds depends on the value of \fBin_seconds\fP\&. Default is 5 minutes. .IP \(bu 2 \fBin_seconds\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B \fBTrue\fP will cause the \fBtimeout\fP parameter to be in seconds. \fBFalse\fP will be in minutes. Default is \fBFalse\fP\&. .UNINDENT .sp New in version 2015.8.0. .IP \(bu 2 \fBwait_for_reboot\fP (\fI\%bool\fP) \-\- .sp \fBTrue\fP will sleep for timeout + 30 seconds after reboot has been initiated. This is useful for use in a highstate. For example, you may have states that you want to apply only after the reboot. Default is \fBFalse\fP\&. .sp New in version 2015.8.0. .IP \(bu 2 \fBonly_on_pending_reboot\fP (\fI\%bool\fP) \-\- If this is set to \fBTrue\fP, then the reboot will only proceed if the system reports a pending reboot. Setting this parameter to \fBTrue\fP could be useful when calling this function from a final housekeeping state intended to be executed at the end of a state run (using \fIorder: last\fP). Default is \fBFalse\fP\&. .UNINDENT .TP .B Returns \fBTrue\fP if successful (a reboot will occur), otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.reboot 5 salt \(aq*\(aq system.reboot 5 True .ft P .fi .UNINDENT .UNINDENT .sp Invoking this function from a final housekeeping state: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C final_housekeeping: module.run: \- name: system.reboot \- only_on_pending_reboot: True \- order: last .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.set_computer_desc(desc=None) Set the Windows computer description .INDENT 7.0 .TP .B Parameters \fBdesc\fP (\fI\%str\fP) \-\- The computer description .TP .B Returns Description if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.set_computer_desc \(aqThis computer belongs to Dave!\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.set_computer_description(desc=None) This function is an alias of \fBset_computer_desc\fP\&. .INDENT 7.0 .INDENT 3.5 Set the Windows computer description .sp Args: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B desc (str): The computer description .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Returns: str: Description if successful, otherwise \fBFalse\fP .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.set_computer_desc \(aqThis computer belongs to Dave!\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.set_computer_name(name) Set the Windows computer name .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The new name to give the computer. Requires a reboot to take effect. .TP .B Returns Returns a dictionary containing the old and new names if successful. \fBFalse\fP if not. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.set_computer_name \(aqDavesComputer\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.set_domain_workgroup(workgroup) Set the domain or workgroup the computer belongs to. .sp New in version 3001. .INDENT 7.0 .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.set_domain_workgroup LOCAL .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.set_hostname(hostname) Set the hostname of the windows minion, requires a restart before this will be updated. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters \fBhostname\fP (\fI\%str\fP) \-\- The hostname to set .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.set_hostname newhostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.set_reboot_required_witnessed() This function is used to remember that an event indicating that a reboot is required was witnessed. This function relies on the salt\-minion\(aqs ability to create the following volatile registry key in the \fIHKLM\fP hive: .INDENT 7.0 .INDENT 3.5 \fISYSTEM\eCurrentControlSet\eServices\esalt\-minion\eVolatile\-Data\fP .UNINDENT .UNINDENT .sp Because this registry key is volatile, it will not persist beyond the current boot session. Also, in the scope of this key, the name \fI\(aqReboot required\(aq\fP will be assigned the value of \fI1\fP\&. .sp For the time being, this function is being used whenever an install completes with exit code 3010 and can be extended where appropriate in the future. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_reboot_required_witnessed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.set_system_date(newdate) Set the Windows system date. Use <mm\-dd\-yy> format for the date. .INDENT 7.0 .TP .B Parameters \fBnewdate\fP (\fI\%str\fP) \-\- .sp The date to set. Can be any of the following formats .INDENT 7.0 .IP \(bu 2 YYYY\-MM\-DD .IP \(bu 2 MM\-DD\-YYYY .IP \(bu 2 MM\-DD\-YY .IP \(bu 2 MM/DD/YYYY .IP \(bu 2 MM/DD/YY .IP \(bu 2 YYYY/MM/DD .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_system_date \(aq03\-28\-13\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.set_system_date_time(years=None, months=None, days=None, hours=None, minutes=None, seconds=None) Set the system date and time. Each argument is an element of the date, but not required. If an element is not passed, the current system value for that element will be used. For example, if you don\(aqt pass the year, the current system year will be used. (Used by set_system_date and set_system_time) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fByears\fP (\fI\%int\fP) \-\- Years digit, ie: 2015 .IP \(bu 2 \fBmonths\fP (\fI\%int\fP) \-\- Months digit: 1 \- 12 .IP \(bu 2 \fBdays\fP (\fI\%int\fP) \-\- Days digit: 1 \- 31 .IP \(bu 2 \fBhours\fP (\fI\%int\fP) \-\- Hours digit: 0 \- 23 .IP \(bu 2 \fBminutes\fP (\fI\%int\fP) \-\- Minutes digit: 0 \- 59 .IP \(bu 2 \fBseconds\fP (\fI\%int\fP) \-\- Seconds digit: 0 \- 59 .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.set_system_date_ time 2015 5 12 11 37 53 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.set_system_time(newtime) Set the system time. .INDENT 7.0 .TP .B Parameters \fBnewtime\fP (\fI\%str\fP) \-\- .sp The time to set. Can be any of the following formats: .INDENT 7.0 .IP \(bu 2 HH:MM:SS AM/PM .IP \(bu 2 HH:MM AM/PM .IP \(bu 2 HH:MM:SS (24 hour) .IP \(bu 2 HH:MM (24 hour) .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.set_system_time 12:01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.shutdown(message=None, timeout=5, force_close=True, reboot=False, in_seconds=False, only_on_pending_reboot=False) Shutdown a running system. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmessage\fP (\fI\%str\fP) \-\- The message to display to the user before shutting down. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- .sp The length of time (in seconds) that the shutdown dialog box should be displayed. While this dialog box is displayed, the shutdown can be aborted using the \fBsystem.shutdown_abort\fP function. .sp If timeout is not zero, InitiateSystemShutdown displays a dialog box on the specified computer. The dialog box displays the name of the user who called the function, the message specified by the lpMessage parameter, and prompts the user to log off. The dialog box beeps when it is created and remains on top of other windows (system modal). The dialog box can be moved but not closed. A timer counts down the remaining time before the shutdown occurs. .sp If timeout is zero, the computer shuts down immediately without displaying the dialog box and cannot be stopped by \fBsystem.shutdown_abort\fP\&. .sp Default is 5 minutes .IP \(bu 2 \fBin_seconds\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .TP .B \fBTrue\fP will cause the \fBtimeout\fP parameter to be in seconds. \fBFalse\fP will be in minutes. Default is \fBFalse\fP\&. .UNINDENT .sp New in version 2015.8.0. .IP \(bu 2 \fBforce_close\fP (\fI\%bool\fP) \-\- \fBTrue\fP will force close all open applications. \fBFalse\fP will display a dialog box instructing the user to close open applications. Default is \fBTrue\fP\&. .IP \(bu 2 \fBreboot\fP (\fI\%bool\fP) \-\- \fBTrue\fP restarts the computer immediately after shutdown. \fBFalse\fP powers down the system. Default is \fBFalse\fP\&. .IP \(bu 2 \fBonly_on_pending_reboot\fP (\fI\%bool\fP) \-\- If this is set to True, then the shutdown will only proceed if the system reports a pending reboot. To optionally shutdown in a highstate, consider using the shutdown state instead of this module. .IP \(bu 2 \fBonly_on_pending_reboot\fP \-\- If \fBTrue\fP the shutdown will only proceed if there is a reboot pending. \fBFalse\fP will shutdown the system. Default is \fBFalse\fP\&. .UNINDENT .TP .B Returns \fBTrue\fP if successful (a shutdown or reboot will occur), otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.shutdown \(dqSystem will shutdown in 5 minutes\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.shutdown_abort() Abort a shutdown. Only available while the dialog box is being displayed to the user. Once the shutdown has initiated, it cannot be aborted. .INDENT 7.0 .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.shutdown_abort .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.shutdown_hard() Shutdown a running system with no timeout or warning. .INDENT 7.0 .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.shutdown_hard .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.start_time_service() Start the Windows time service .INDENT 7.0 .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.start_time_service .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.stop_time_service() Stop the Windows time service .INDENT 7.0 .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq system.stop_time_service .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_system.unjoin_domain(username=None, password=None, domain=None, workgroup=\(aqWORKGROUP\(aq, disable=False, restart=False) Unjoin a computer from an Active Directory Domain. Requires a restart. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- Username of an account which is authorized to manage computer accounts on the domain. Needs to be a fully qualified name like \fBuser@domain.tld\fP or \fBdomain.tld\euser\fP\&. If the domain is not specified, the passed domain will be used. If the computer account doesn\(aqt need to be disabled after the computer is unjoined, this can be \fBNone\fP\&. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The password of the specified user .IP \(bu 2 \fBdomain\fP (\fI\%str\fP) \-\- The domain from which to unjoin the computer. Can be \fBNone\fP .IP \(bu 2 \fBworkgroup\fP (\fI\%str\fP) \-\- .sp The workgroup to join the computer to. Default is \fBWORKGROUP\fP .sp New in version 2015.5.7,2015.8.2. .IP \(bu 2 \fBdisable\fP (\fI\%bool\fP) \-\- \fBTrue\fP to disable the computer account in Active Directory. Default is \fBFalse\fP .IP \(bu 2 \fBrestart\fP (\fI\%bool\fP) \-\- .sp \fBTrue\fP will restart the computer after successful unjoin. Default is \fBFalse\fP .sp New in version 2015.5.7,2015.8.2. .UNINDENT .TP .B Returns Returns a dictionary if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq system.unjoin_domain restart=True salt \(aqminion\-id\(aq system.unjoin_domain username=\(aqunjoinuser\(aq \e password=\(aqunjoinpassword\(aq disable=True \e restart=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_task .sp Windows Task Scheduler Module \&.. versionadded:: 2016.3.0 .sp A module for working with the Windows Task Scheduler. You can add and edit existing tasks. You can add and clear triggers and actions. You can list all tasks, folders, triggers, and actions. .INDENT 0.0 .TP .B salt.modules.win_task.add_action(name=None, location=\(aq\e\e\(aq, action_type=\(aqExecute\(aq, **kwargs) Add an action to a task. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task to which to add the action. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .IP \(bu 2 \fBaction_type\fP (\fI\%str\fP) \-\- .sp The type of action to add. There are three action types. Each one requires its own set of Keyword Arguments (kwargs). Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Execute .IP \(bu 2 Email .IP \(bu 2 Message .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Required arguments for each action_type: .sp \fBExecute\fP .INDENT 7.0 .INDENT 3.5 Execute a command or an executable .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B cmd (str): (required) The command or executable to run. .TP .B arguments (str): (optional) Arguments to be passed to the command or executable. To launch a script the first command will need to be the interpreter for the script. For example, to run a vbscript you would pass \fBcscript.exe\fP in the \fBcmd\fP parameter and pass the script in the \fBarguments\fP parameter as follows: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBcmd=\(aqcscript.exe\(aq arguments=\(aqc:\escripts\emyscript.vbs\(aq\fP .UNINDENT .UNINDENT .UNINDENT .sp Batch files do not need an interpreter and may be passed to the cmd parameter directly. .TP .B start_in (str): (optional) The current working directory for the command. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBEmail\fP .INDENT 7.0 .INDENT 3.5 Send and email. Requires \fBserver\fP, \fBfrom\fP, and \fBto\fP or \fBcc\fP\&. .INDENT 0.0 .INDENT 3.5 from (str): The sender .sp reply_to (str): Who to reply to .sp to (str): The recipient .sp cc (str): The CC recipient .sp bcc (str): The BCC recipient .sp subject (str): The subject of the email .sp body (str): The Message Body of the email .sp server (str): The server used to send the email .INDENT 0.0 .TP .B attachments (list): A list of attachments. These will be the paths to the files to attach. ie: \fBattachments=\(dq[\(aqC:\eattachment1.txt\(aq, \(aqC:\eattachment2.txt\(aq]\(dq\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBMessage\fP .INDENT 7.0 .INDENT 3.5 Display a dialog box. The task must be set to \(dqRun only when user is logged on\(dq in order for the dialog box to display. Both parameters are required. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B title (str): The dialog box title. .TP .B message (str): The dialog box message body .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary containing the task configuration .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq task.add_action <task_name> cmd=\(aqdel /Q /S C:\e\eTemp\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.add_trigger(name=None, location=\(aq\e\e\(aq, trigger_type=None, trigger_enabled=True, start_date=None, start_time=None, end_date=None, end_time=None, random_delay=None, repeat_interval=None, repeat_duration=None, repeat_stop_at_duration_end=False, execution_time_limit=None, delay=None, **kwargs) Add a trigger to a Windows Scheduled task .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Arguments are parsed by the YAML loader and are subject to yaml\(aqs idiosyncrasies. Therefore, time values in some formats (\fB%H:%M:%S\fP and \fB%H:%M\fP) should to be quoted. See \fI\%YAML IDIOSYNCRASIES\fP for more details. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task to which to add the trigger. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .IP \(bu 2 \fBtrigger_type\fP (\fI\%str\fP) \-\- .sp The type of trigger to create. This is defined when the trigger is created and cannot be changed later. Options are as follows: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Event .IP \(bu 2 Once .IP \(bu 2 Daily .IP \(bu 2 Weekly .IP \(bu 2 Monthly .IP \(bu 2 MonthlyDay .IP \(bu 2 OnIdle .IP \(bu 2 OnTaskCreation .IP \(bu 2 OnBoot .IP \(bu 2 OnLogon .IP \(bu 2 OnSessionChange .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBtrigger_enabled\fP (\fI\%bool\fP) \-\- Boolean value that indicates whether the trigger is enabled. .IP \(bu 2 \fBstart_date\fP (\fI\%str\fP) \-\- .sp The date when the trigger is activated. If no value is passed, the current date will be used. Can be one of the following formats: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 %Y\-%m\-%d .IP \(bu 2 %m\-%d\-%y .IP \(bu 2 %m\-%d\-%Y .IP \(bu 2 %m/%d/%y .IP \(bu 2 %m/%d/%Y .IP \(bu 2 %Y/%m/%d .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBstart_time\fP (\fI\%str\fP) \-\- .sp The time when the trigger is activated. If no value is passed, midnight will be used. Can be one of the following formats: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 %I:%M:%S %p .IP \(bu 2 %I:%M %p .IP \(bu 2 %H:%M:%S .IP \(bu 2 %H:%M .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBend_date\fP (\fI\%str\fP) \-\- .sp The date when the trigger is deactivated. The trigger cannot start the task after it is deactivated. Can be one of the following formats: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 %Y\-%m\-%d .IP \(bu 2 %m\-%d\-%y .IP \(bu 2 %m\-%d\-%Y .IP \(bu 2 %m/%d/%y .IP \(bu 2 %m/%d/%Y .IP \(bu 2 %Y/%m/%d .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBend_time\fP (\fI\%str\fP) \-\- .sp The time when the trigger is deactivated. If this is not passed with \fBend_date\fP it will be set to midnight. Can be one of the following formats: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 %I:%M:%S %p .IP \(bu 2 %I:%M %p .IP \(bu 2 %H:%M:%S .IP \(bu 2 %H:%M .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBrandom_delay\fP (\fI\%str\fP) \-\- .sp The delay time that is randomly added to the start time of the trigger. Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 30 seconds .IP \(bu 2 1 minute .IP \(bu 2 30 minutes .IP \(bu 2 1 hour .IP \(bu 2 8 hours .IP \(bu 2 1 day .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This parameter applies to the following trigger types .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Once .IP \(bu 2 Daily .IP \(bu 2 Weekly .IP \(bu 2 Monthly .IP \(bu 2 MonthlyDay .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBrepeat_interval\fP (\fI\%str\fP) \-\- .sp The amount of time between each restart of the task. Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 5 minutes .IP \(bu 2 10 minutes .IP \(bu 2 15 minutes .IP \(bu 2 30 minutes .IP \(bu 2 1 hour .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBrepeat_duration\fP (\fI\%str\fP) \-\- .sp How long the pattern is repeated. Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Indefinitely .IP \(bu 2 15 minutes .IP \(bu 2 30 minutes .IP \(bu 2 1 hour .IP \(bu 2 12 hours .IP \(bu 2 1 day .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBrepeat_stop_at_duration_end\fP (\fI\%bool\fP) \-\- Boolean value that indicates if a running instance of the task is stopped at the end of the repetition pattern duration. .IP \(bu 2 \fBexecution_time_limit\fP (\fI\%str\fP) \-\- .sp The maximum amount of time that the task launched by the trigger is allowed to run. Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 30 minutes .IP \(bu 2 1 hour .IP \(bu 2 2 hours .IP \(bu 2 4 hours .IP \(bu 2 8 hours .IP \(bu 2 12 hours .IP \(bu 2 1 day .IP \(bu 2 3 days (default) .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBdelay\fP (\fI\%str\fP) \-\- .sp The time the trigger waits after its activation to start the task. Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 15 seconds .IP \(bu 2 30 seconds .IP \(bu 2 1 minute .IP \(bu 2 30 minutes .IP \(bu 2 1 hour .IP \(bu 2 8 hours .IP \(bu 2 1 day .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This parameter applies to the following trigger types: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 OnLogon .IP \(bu 2 OnBoot .IP \(bu 2 Event .IP \(bu 2 OnTaskCreation .IP \(bu 2 OnSessionChange .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBkwargs\fP .sp There are optional keyword arguments determined by the type of trigger being defined. They are as follows: .sp \fIEvent\fP .INDENT 7.0 .INDENT 3.5 The trigger will be fired by an event. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B subscription (str): An event definition in xml format that fires the trigger. The easiest way to get this would is to create an event in Windows Task Scheduler and then copy the xml text. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fIOnce\fP .INDENT 7.0 .INDENT 3.5 No special parameters required. .UNINDENT .UNINDENT .sp \fIDaily\fP .INDENT 7.0 .INDENT 3.5 The task will run daily. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B days_interval (int): The interval between days in the schedule. An interval of 1 produces a daily schedule. An interval of 2 produces an every\-other day schedule. If no interval is specified, 1 is used. Valid entries are 1 \- 999. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fIWeekly\fP .INDENT 7.0 .INDENT 3.5 The task will run weekly. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B weeks_interval (int): The interval between weeks in the schedule. An interval of 1 produces a weekly schedule. An interval of 2 produces an every\-other week schedule. If no interval is specified, 1 is used. Valid entries are 1 \- 52. .TP .B days_of_week (list): Sets the days of the week on which the task runs. Should be a list. ie: \fB[\(aqMonday\(aq,\(aqWednesday\(aq,\(aqFriday\(aq]\fP\&. Valid entries are the names of the days of the week. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fIMonthly\fP .INDENT 7.0 .INDENT 3.5 The task will run monthly. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B months_of_year (list): Sets the months of the year during which the task runs. Should be a list. ie: \fB[\(aqJanuary\(aq,\(aqJuly\(aq]\fP\&. Valid entries are the full names of all the months. .TP .B days_of_month (list): Sets the days of the month during which the task runs. Should be a list. ie: \fB[1, 15, \(aqLast\(aq]\fP\&. Options are all days of the month 1 \- 31 and the word \(aqLast\(aq to indicate the last day of the month. .TP .B last_day_of_month (bool): Boolean value that indicates that the task runs on the last day of the month regardless of the actual date of that day. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 You can set the task to run on the last day of the month by either including the word \(aqLast\(aq in the list of days, or setting the parameter \(aqlast_day_of_month\(aq equal to \fBTrue\fP\&. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fIMonthlyDay\fP .INDENT 7.0 .INDENT 3.5 The task will run monthly on the specified day. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B months_of_year (list): Sets the months of the year during which the task runs. Should be a list. ie: \fB[\(aqJanuary\(aq,\(aqJuly\(aq]\fP\&. Valid entries are the full names of all the months. .TP .B weeks_of_month (list): Sets the weeks of the month during which the task runs. Should be a list. ie: \fB[\(aqFirst\(aq,\(aqThird\(aq]\fP\&. Valid options are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 First .IP \(bu 2 Second .IP \(bu 2 Third .IP \(bu 2 Fourth .UNINDENT .UNINDENT .UNINDENT .TP .B last_week_of_month (bool): Boolean value that indicates that the task runs on the last week of the month. .TP .B days_of_week (list): Sets the days of the week during which the task runs. Should be a list. ie: \fB[\(aqMonday\(aq,\(aqWednesday\(aq,\(aqFriday\(aq]\fP\&. Valid entries are the names of the days of the week. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fIOnIdle\fP .INDENT 7.0 .INDENT 3.5 No special parameters required. .UNINDENT .UNINDENT .sp \fIOnTaskCreation\fP .INDENT 7.0 .INDENT 3.5 No special parameters required. .UNINDENT .UNINDENT .sp \fIOnBoot\fP .INDENT 7.0 .INDENT 3.5 No special parameters required. .UNINDENT .UNINDENT .sp \fIOnLogon\fP .INDENT 7.0 .INDENT 3.5 No special parameters required. .UNINDENT .UNINDENT .sp \fIOnSessionChange\fP .INDENT 7.0 .INDENT 3.5 The task will be triggered by a session change. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B session_user_name (str): Sets the user for the Terminal Server session. When a session state change is detected for this user, a task is started. To detect session status change for any user, do not pass this parameter. .TP .B state_change (str): Sets the kind of Terminal Server session change that would trigger a task launch. Valid options are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 ConsoleConnect: When you connect to a user session (switch users) .IP \(bu 2 ConsoleDisconnect: When you disconnect a user session (switch users) .IP \(bu 2 RemoteConnect: When a user connects via Remote Desktop .IP \(bu 2 RemoteDisconnect: When a user disconnects via Remote Desktop .IP \(bu 2 SessionLock: When the workstation is locked .IP \(bu 2 SessionUnlock: When the workstation is unlocked .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq task.add_trigger <task_name> trigger_type=Once trigger_enabled=True start_date=2016/12/1 start_time=\(aq\(dq12:01\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.clear_triggers(name, location=\(aq\e\e\(aq) Remove all triggers from the task. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task from which to clear all triggers. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq task.clear_trigger <task_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.create_folder(name, location=\(aq\e\e\(aq) Create a folder in which to create tasks. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the folder. This will be displayed in the task scheduler. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location in which to create the folder. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq task.create_folder <folder_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.create_task(name, location=\(aq\e\e\(aq, user_name=\(aqSystem\(aq, password=None, force=False, **kwargs) Create a new task in the designated location. This function has many keyword arguments that are not listed here. For additional arguments see: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%edit_task()\fP .IP \(bu 2 \fI\%add_action()\fP .IP \(bu 2 \fI\%add_trigger()\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task. This will be displayed in the task scheduler. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location in which to create the task. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .IP \(bu 2 \fBuser_name\fP (\fI\%str\fP) \-\- The user account under which to run the task. To specify the \(aqSystem\(aq account, use \(aqSystem\(aq. The password will be ignored. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The password to use for authentication. This should set the task to run whether the user is logged in or not, but is currently not working. .IP \(bu 2 \fBforce\fP (\fI\%bool\fP) \-\- If the task exists, overwrite the existing task. .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq task.create_task <task_name> user_name=System force=True action_type=Execute cmd=\(aqdel /Q /S C:\e\eTemp\(aq trigger_type=Once start_date=2016\-12\-1 start_time=\(aq\(dq01:00\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.create_task_from_xml(name, location=\(aq\e\e\(aq, xml_text=None, xml_path=None, user_name=\(aqSystem\(aq, password=None) Create a task based on XML. Source can be a file or a string of XML. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task. This will be displayed in the task scheduler. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location in which to create the task. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .IP \(bu 2 \fBxml_text\fP (\fI\%str\fP) \-\- A string of xml representing the task to be created. This will be overridden by \fBxml_path\fP if passed. .IP \(bu 2 \fBxml_path\fP (\fI\%str\fP) \-\- The path to an XML file on the local system containing the xml that defines the task. This will override \fBxml_text\fP .IP \(bu 2 \fBuser_name\fP (\fI\%str\fP) \-\- The user account under which to run the task. To specify the \(aqSystem\(aq account, use \(aqSystem\(aq. The password will be ignored. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The password to use for authentication. This should set the task to run whether the user is logged in or not, but is currently not working. .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP str: A string with the error message if there is an error .TP .B Return type \fI\%bool\fP .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%ArgumentValueError\fP \-\- If arguments are invalid .IP \(bu 2 \fI\%CommandExecutionError\fP \-\- .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq task.create_task_from_xml <task_name> xml_path=C:\etask.xml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.delete_folder(name, location=\(aq\e\e\(aq) Delete a folder from the task scheduler. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the folder to delete. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the folder. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq task.delete_folder <folder_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.delete_task(name, location=\(aq\e\e\(aq) Delete a task from the task scheduler. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task to delete. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq task.delete_task <task_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.edit_task(name=None, location=\(aq\e\e\(aq, user_name=None, password=None, description=None, enabled=None, hidden=None, run_if_idle=None, idle_duration=None, idle_wait_timeout=None, idle_stop_on_end=None, idle_restart=None, ac_only=None, stop_if_on_batteries=None, wake_to_run=None, run_if_network=None, network_id=None, network_name=None, allow_demand_start=None, start_when_available=None, restart_every=None, restart_count=3, execution_time_limit=None, force_stop=None, delete_after=None, multiple_instances=None, **kwargs) Edit the parameters of a task. Triggers and Actions cannot be edited yet. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task. This will be displayed in the task scheduler. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location in which to create the task. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .IP \(bu 2 \fBuser_name\fP (\fI\%str\fP) \-\- The user account under which to run the task. To specify the \(aqSystem\(aq account, use \(aqSystem\(aq. The password will be ignored. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- .sp The password to use for authentication. This should set the task to run whether the user is logged in or not, but is currently not working. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The combination of user_name and password determine how the task runs. For example, if a username is passed without at password the task will only run when the user is logged in. If a password is passed as well the task will run whether the user is logged on or not. If you pass \(aqSystem\(aq as the username the task will run as the system account (the password parameter is ignored). .UNINDENT .UNINDENT .IP \(bu 2 \fBdescription\fP (\fI\%str\fP) \-\- A string representing the text that will be displayed in the description field in the task scheduler. .IP \(bu 2 \fBenabled\fP (\fI\%bool\fP) \-\- A boolean value representing whether or not the task is enabled. .IP \(bu 2 \fBhidden\fP (\fI\%bool\fP) \-\- A boolean value representing whether or not the task is hidden. .IP \(bu 2 \fBrun_if_idle\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the Task Scheduler will run the task only if the computer is in an idle state. .IP \(bu 2 \fBidle_duration\fP (\fI\%str\fP) \-\- .sp A value that indicates the amount of time that the computer must be in an idle state before the task is run. Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 1 minute .IP \(bu 2 5 minutes .IP \(bu 2 10 minutes .IP \(bu 2 15 minutes .IP \(bu 2 30 minutes .IP \(bu 2 1 hour .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBidle_wait_timeout\fP (\fI\%str\fP) \-\- .sp A value that indicates the amount of time that the Task Scheduler will wait for an idle condition to occur. Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Do not wait .IP \(bu 2 1 minute .IP \(bu 2 5 minutes .IP \(bu 2 10 minutes .IP \(bu 2 15 minutes .IP \(bu 2 30 minutes .IP \(bu 2 1 hour .IP \(bu 2 2 hours .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBidle_stop_on_end\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the Task Scheduler will terminate the task if the idle condition ends before the task is completed. .IP \(bu 2 \fBidle_restart\fP (\fI\%bool\fP) \-\- Boolean value that indicates whether the task is restarted when the computer cycles into an idle condition more than once. .IP \(bu 2 \fBac_only\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the Task Scheduler will launch the task only while on AC power. .IP \(bu 2 \fBstop_if_on_batteries\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the task will be stopped if the computer begins to run on battery power. .IP \(bu 2 \fBwake_to_run\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the Task Scheduler will wake the computer when it is time to run the task. .IP \(bu 2 \fBrun_if_network\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the Task Scheduler will run the task only when a network is available. .IP \(bu 2 \fBnetwork_id\fP (\fIguid\fP) \-\- GUID value that identifies a network profile. .IP \(bu 2 \fBnetwork_name\fP (\fI\%str\fP) \-\- Sets the name of a network profile. The name is used for display purposes. .IP \(bu 2 \fBallow_demand_start\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the task can be started by using either the Run command or the Context menu. .IP \(bu 2 \fBstart_when_available\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the Task Scheduler can start the task at any time after its scheduled time has passed. .IP \(bu 2 \fBrestart_every\fP (\fI\%str\fP) \-\- .sp A value that specifies the interval between task restart attempts. Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 False (to disable) .IP \(bu 2 1 minute .IP \(bu 2 5 minutes .IP \(bu 2 10 minutes .IP \(bu 2 15 minutes .IP \(bu 2 30 minutes .IP \(bu 2 1 hour .IP \(bu 2 2 hours .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBrestart_count\fP (\fI\%int\fP) \-\- The number of times the Task Scheduler will attempt to restart the task. Valid values are integers 1 \- 999. .IP \(bu 2 \fBexecution_time_limit\fP (\fI\%bool\fP\fI, \fP\fI\%str\fP) \-\- .sp The amount of time allowed to complete the task. Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 False (to disable) .IP \(bu 2 1 hour .IP \(bu 2 2 hours .IP \(bu 2 4 hours .IP \(bu 2 8 hours .IP \(bu 2 12 hours .IP \(bu 2 1 day .IP \(bu 2 3 days .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBforce_stop\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the task may be terminated by using TerminateProcess. .IP \(bu 2 \fBdelete_after\fP (\fI\%bool\fP\fI, \fP\fI\%str\fP) \-\- .sp The amount of time that the Task Scheduler will wait before deleting the task after it expires. Requires a trigger with an expiration date. Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 False (to disable) .IP \(bu 2 Immediately .IP \(bu 2 30 days .IP \(bu 2 90 days .IP \(bu 2 180 days .IP \(bu 2 365 days .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBmultiple_instances\fP (\fI\%str\fP) \-\- .sp Sets the policy that defines how the Task Scheduler deals with multiple instances of the task. Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Parallel .IP \(bu 2 Queue .IP \(bu 2 No New Instance .IP \(bu 2 Stop Existing .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq task.edit_task <task_name> description=\(aqThis task is awesome\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.info(name, location=\(aq\e\e\(aq) Get the details about a task in the task scheduler. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task for which to return the status .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .UNINDENT .TP .B Returns A dictionary containing the task configuration .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq task.info <task_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.list_actions(name, location=\(aq\e\e\(aq) List all actions that pertain to a task in the specified location. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task for which list actions. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task from which to list actions. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .UNINDENT .TP .B Returns Returns a list of actions. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # List all actions for a task in the default location salt \(aqminion\-id\(aq task.list_actions <task_name> # List all actions for the XblGameSaveTask in the Microsoft\eXblGameSave # location salt \(aqminion\-id\(aq task.list_actions XblGameSaveTask Microsoft\eXblGameSave .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.list_folders(location=\(aq\e\e\(aq) List all folders located in a specific location in the task scheduler. .INDENT 7.0 .TP .B Parameters \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the folder from which you want to list tasks. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .TP .B Returns Returns a list of folders. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # List all folders in the default location salt \(aqminion\-id\(aq task.list_folders # List all folders in the Microsoft directory salt \(aqminion\-id\(aq task.list_folders Microsoft .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.list_tasks(location=\(aq\e\e\(aq) List all tasks located in a specific location in the task scheduler. .INDENT 7.0 .TP .B Parameters \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the folder from which you want to list tasks. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .TP .B Returns Returns a list of tasks .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # List all tasks in the default location salt \(aqminion\-id\(aq task.list_tasks # List all tasks in the Microsoft\eXblGameSave Directory salt \(aqminion\-id\(aq task.list_tasks Microsoft\eXblGameSave .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.list_triggers(name, location=\(aq\e\e\(aq) List all triggers that pertain to a task in the specified location. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task for which list triggers. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task from which to list triggers. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .UNINDENT .TP .B Returns Returns a list of triggers. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # List all triggers for a task in the default location salt \(aqminion\-id\(aq task.list_triggers <task_name> # List all triggers for the XblGameSaveTask in the Microsoft\eXblGameSave # location salt \(aq*\(aq task.list_triggers XblGameSaveTask Microsoft\eXblGameSave .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.run(name, location=\(aq\e\e\(aq) Run a scheduled task manually. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task to run. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq task.run <task_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.run_wait(name, location=\(aq\e\e\(aq) Run a scheduled task and return when the task finishes .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task to run. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq task.run_wait <task_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.status(name, location=\(aq\e\e\(aq) Determine the status of a task. Is it Running, Queued, Ready, etc. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task for which to return the status .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .UNINDENT .TP .B Returns The current status of the task. Will be one of the following: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Unknown .IP \(bu 2 Disabled .IP \(bu 2 Queued .IP \(bu 2 Ready .IP \(bu 2 Running .UNINDENT .UNINDENT .UNINDENT .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq task.list_status <task_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_task.stop(name, location=\(aq\e\e\(aq) Stop a scheduled task. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the task to stop. .IP \(bu 2 \fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task. Default is \fB\e\fP which is the root for the task scheduler (\fBC:\eWindows\eSystem32\etasks\fP). .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq task.list_stop <task_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_timezone .sp Module for managing timezone on Windows systems. .INDENT 0.0 .TP .B class salt.modules.win_timezone.TzMapper(unix_to_win) .INDENT 7.0 .TP .B add(k, v) .UNINDENT .INDENT 7.0 .TP .B get_unix(key, default=None) .UNINDENT .INDENT 7.0 .TP .B get_win(key, default=None) .UNINDENT .INDENT 7.0 .TP .B list_unix() .UNINDENT .INDENT 7.0 .TP .B list_win() .UNINDENT .INDENT 7.0 .TP .B remove(k) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_timezone.get_hwclock() Get current hardware clock setting (UTC or localtime) .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The hardware clock is always local time on Windows so this will always return \(dqlocaltime\(dq .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_hwclock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_timezone.get_offset() Get current numeric timezone offset from UTC (i.e. \-0700) .INDENT 7.0 .TP .B Returns Offset from UTC .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_offset .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_timezone.get_zone() Get current timezone (i.e. America/Denver) .INDENT 7.0 .TP .B Returns Timezone in unix format .TP .B Return type \fI\%str\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If timezone could not be gathered .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_timezone.get_zonecode() Get current timezone (i.e. PST, MDT, etc) .INDENT 7.0 .TP .B Returns An abbreviated timezone code .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.get_zonecode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_timezone.list(unix_style=True) Return a list of Timezones that this module supports. These can be in either Unix or Windows format. .sp New in version 2018.3.3. .INDENT 7.0 .TP .B Parameters \fBunix_style\fP (\fI\%bool\fP) \-\- \fBTrue\fP returns Unix\-style timezones. \fBFalse\fP returns Windows\-style timezones. Default is \fBTrue\fP .TP .B Returns A list of supported timezones .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Unix\-style timezones salt \(aq*\(aq timezone.list # Windows\-style timezones salt \(aq*\(aq timezone.list unix_style=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_timezone.set_hwclock(clock) Sets the hardware clock to be either UTC or localtime .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The hardware clock is always local time on Windows so this will always return \fBFalse\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.set_hwclock UTC .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_timezone.set_zone(timezone) Sets the timezone using the tzutil. .INDENT 7.0 .TP .B Parameters \fBtimezone\fP (\fI\%str\fP) \-\- A valid timezone .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If invalid timezone is passed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.set_zone \(aqAmerica/Denver\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_timezone.zone_compare(timezone) Compares the given timezone with the machine timezone. Mostly useful for running state checks. .INDENT 7.0 .TP .B Parameters \fBtimezone\fP (\fI\%str\fP) \-\- The timezone to compare. This can be in Windows or Unix format. Can be any of the values returned by the \fBtimezone.list\fP function .TP .B Returns \fBTrue\fP if they match, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq timezone.zone_compare \(aqAmerica/Denver\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_useradd .sp Module for managing Windows Users. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage users on a minion, and it is using a different module (or gives an error similar to \fI\(aquser.info\(aq is not available\fP), see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 pywintypes .IP \(bu 2 win32api .IP \(bu 2 win32con .IP \(bu 2 win32net .IP \(bu 2 win32netcon .IP \(bu 2 win32profile .IP \(bu 2 win32security .IP \(bu 2 win32ts .IP \(bu 2 wmi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This currently only works with local user accounts, not domain accounts .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.add(name, password=None, fullname=None, description=None, groups=None, home=None, homedrive=None, profile=None, logonscript=None) Add a user to the minion. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The username for the new account .IP \(bu 2 \fBpassword\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- User\(aqs password in plain text. .IP \(bu 2 \fBfullname\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The user\(aqs full name. .IP \(bu 2 \fBdescription\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- A brief description of the user account. .IP \(bu 2 \fBgroups\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- A list of groups to add the user to. (see chgroups) .IP \(bu 2 \fBhome\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The path to the user\(aqs home directory. .IP \(bu 2 \fBhomedrive\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The drive letter to assign to the home directory. Must be the Drive Letter followed by a colon. ie: U: .IP \(bu 2 \fBprofile\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- An explicit path to a profile. Can be a UNC or a folder on the system. If left blank, windows uses its default profile directory. .IP \(bu 2 \fBlogonscript\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- Path to a login script to run when the user logs on. .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.add name password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.addgroup(name, group) Add user to a group .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The username to add to the group .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- The name of the group to which to add the user .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.addgroup jsnuffy \(aqPower Users\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.chfullname(name, fullname) Change the full name of the user .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The username for which to change the full name .IP \(bu 2 \fBfullname\fP (\fI\%str\fP) \-\- The new value for the full name .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chfullname user \(aqFirst Last\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.chgroups(name, groups, append=True) Change the groups this user belongs to, add append=False to make the user a member of only the specified groups .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The username for which to change groups .IP \(bu 2 \fBgroups\fP (\fI\%str\fP\fI, \fP\fI\%list\fP) \-\- A single group or a list of groups to assign to the user. For multiple groups this can be a comma delimited string or a list. .IP \(bu 2 \fBappend\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- True adds the passed groups to the user\(aqs current groups. False sets the user\(aqs groups to the passed groups only. Default is True. .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chgroups jsnuffy Administrators,Users True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.chhome(name, home, **kwargs) Change the home directory of the user, pass True for persist to move files to the new home directory if the old home directory exist. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the user whose home directory you wish to change .IP \(bu 2 \fBhome\fP (\fI\%str\fP) \-\- The new location of the home directory .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chhome foo \e\efileserver\ehome\efoo True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.chprofile(name, profile) Change the profile directory of the user .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the user whose profile you wish to change .IP \(bu 2 \fBprofile\fP (\fI\%str\fP) \-\- The new location of the profile .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.chprofile foo \e\efileserver\eprofiles\efoo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.current(sam=False) Get the username that salt\-minion is running under. If salt\-minion is running as a service it should return the Local System account. If salt is running from a command prompt it should return the username that started the command prompt. .sp New in version 2015.5.6. .INDENT 7.0 .TP .B Parameters \fBsam\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- False returns just the username without any domain notation. True returns the domain with the username in the SAM format. Ie: \fBdomain\eusername\fP .TP .B Returns Returns username .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.current .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.delete(name, purge=False, force=False) Remove a user from the minion .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the user to delete .IP \(bu 2 \fBpurge\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- Boolean value indicating that the user profile should also be removed when the user account is deleted. If set to True the profile will be removed. Default is False. .IP \(bu 2 \fBforce\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- Boolean value indicating that the user account should be deleted even if the user is logged in. True will log the user out and delete user. .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.delete name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.getUserSid(username) Deprecated function. Please use get_user_sid instead .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.get_user_sid jsnuffy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.get_user_sid(username) Get the Security ID for the user .INDENT 7.0 .TP .B Parameters \fBusername\fP (\fI\%str\fP) \-\- The username for which to look up the SID .TP .B Returns The user SID .TP .B Return type \fI\%str\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.get_user_sid jsnuffy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.getent(refresh=False) Return the list of all info for all users .INDENT 7.0 .TP .B Parameters \fBrefresh\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- Refresh the cached user information. Useful when used from within a state function. Default is False. .TP .B Returns A dictionary containing information about all users on the system .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.getent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.info(name) Return user information .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- Username for which to display information .TP .B Returns .INDENT 7.0 .TP .B A dictionary containing user information .INDENT 7.0 .IP \(bu 2 fullname .IP \(bu 2 username .IP \(bu 2 SID .IP \(bu 2 passwd (will always return None) .IP \(bu 2 comment (same as description, left here for backwards compatibility) .IP \(bu 2 description .IP \(bu 2 active .IP \(bu 2 logonscript .IP \(bu 2 profile .IP \(bu 2 home .IP \(bu 2 homedrive .IP \(bu 2 groups .IP \(bu 2 password_changed .IP \(bu 2 successful_logon_attempts .IP \(bu 2 failed_logon_attempts .IP \(bu 2 last_logon .IP \(bu 2 account_disabled .IP \(bu 2 account_locked .IP \(bu 2 expiration_date .IP \(bu 2 password_never_expires .IP \(bu 2 disallow_change_password .IP \(bu 2 gid .UNINDENT .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.info jsnuffy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.list_groups(name) Return a list of groups the named user belongs to .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The username for which to list groups .TP .B Returns A list of groups to which the user belongs .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.list_groups foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.list_users() Return a list of all users on Windows .INDENT 7.0 .TP .B Returns A list of all users on the system .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.list_users .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.removegroup(name, group) Remove user from a group .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The username to remove from the group .IP \(bu 2 \fBgroup\fP (\fI\%str\fP) \-\- The name of the group from which to remove the user .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.removegroup jsnuffy \(aqPower Users\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.rename(name, new_name) Change the username for a named user .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The username to change .IP \(bu 2 \fBnew_name\fP (\fI\%str\fP) \-\- The new name for the current user .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.rename jsnuffy jshmoe .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.setpassword(name, password) Set the user\(aqs password .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The username for which to set the password .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The new password .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.setpassword jsnuffy sup3rs3cr3t .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.update(name, password=None, fullname=None, description=None, home=None, homedrive=None, logonscript=None, profile=None, expiration_date=None, expired=None, account_disabled=None, unlock_account=None, password_never_expires=None, disallow_change_password=None) Updates settings for the Windows user. Name is the only required parameter. Settings will only be changed if the parameter is passed a value. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The username to update. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- New user password in plain text. .IP \(bu 2 \fBfullname\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The user\(aqs full name. .IP \(bu 2 \fBdescription\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- A brief description of the user account. .IP \(bu 2 \fBhome\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The path to the user\(aqs home directory. .IP \(bu 2 \fBhomedrive\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The drive letter to assign to the home directory. Must be the Drive Letter followed by a colon. ie: U: .IP \(bu 2 \fBlogonscript\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The path to the logon script. .IP \(bu 2 \fBprofile\fP (\fI\%str\fP\fI, \fP\fIoptional\fP) \-\- The path to the user\(aqs profile directory. .IP \(bu 2 \fBexpiration_date\fP (\fIdate\fP\fI, \fP\fIoptional\fP) \-\- The date and time when the account expires. Can be a valid date/time string. To set to never expire pass the string \(aqNever\(aq. .IP \(bu 2 \fBexpired\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- Pass \fITrue\fP to expire the account. The user will be prompted to change their password at the next logon. Pass \fIFalse\fP to mark the account as \(aqnot expired\(aq. You can\(aqt use this to negate the expiration if the expiration was caused by the account expiring. You\(aqll have to change the \fIexpiration_date\fP as well. .IP \(bu 2 \fBaccount_disabled\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- True disables the account. False enables the account. .IP \(bu 2 \fBunlock_account\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- True unlocks a locked user account. False is ignored. .IP \(bu 2 \fBpassword_never_expires\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- True sets the password to never expire. False allows the password to expire. .IP \(bu 2 \fBdisallow_change_password\fP (\fI\%bool\fP\fI, \fP\fIoptional\fP) \-\- True blocks the user from changing the password. False allows the user to change the password. .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq user.update bob password=secret profile=C:\eUsers\eBob home=\eserver\ehomeshare\ebob homedrive=U: .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_wua .sp Module for managing Windows Updates using the Windows Update Agent. .sp List updates on the system using the following functions: .INDENT 0.0 .IP \(bu 2 \fI\%win_wua.available\fP .IP \(bu 2 \fBwin_wua.list\fP .UNINDENT .sp This is an easy way to find additional information about updates available to to the system, such as the GUID, KB number, or description. .sp Once you have the GUID or a KB number for the update you can get information about the update, download, install, or uninstall it using these functions: .INDENT 0.0 .IP \(bu 2 \fI\%win_wua.get\fP .IP \(bu 2 \fI\%win_wua.download\fP .IP \(bu 2 \fI\%win_wua.install\fP .IP \(bu 2 \fI\%win_wua.uninstall\fP .UNINDENT .sp The get function expects a name in the form of a GUID, KB, or Title and should return information about a single update. The other functions accept either a single item or a list of items for downloading/installing/uninstalling a specific list of items. .sp The \fBwin_wua.list\fP and \fI\%win_wua.get\fP functions are utility functions. In addition to returning information about updates they can also download and install updates by setting \fBdownload=True\fP or \fBinstall=True\fP\&. So, with py:func:\fIwin_wua.list <salt.modules.win_wua.list_>\fP for example, you could run the function with the filters you want to see what is available. Then just add \fBinstall=True\fP to install everything on that list. .sp If you want to download, install, or uninstall specific updates, use \fI\%win_wua.download\fP, \fI\%win_wua.install\fP, or \fI\%win_wua.uninstall\fP\&. To update your system with the latest updates use \fBwin_wua.list\fP and set \fBinstall=True\fP .sp You can also adjust the Windows Update settings using the \fI\%win_wua.set_wu_settings\fP function. This function is only supported on the following operating systems: .INDENT 0.0 .IP \(bu 2 Windows Vista / Server 2008 .IP \(bu 2 Windows 7 / Server 2008R2 .IP \(bu 2 Windows 8 / Server 2012 .IP \(bu 2 Windows 8.1 / Server 2012R2 .UNINDENT .sp As of Windows 10 and Windows Server 2016, the ability to modify the Windows Update settings has been restricted. The settings can be modified in the Local Group Policy using the \fBlgpo\fP module. .sp New in version 2015.8.0. .INDENT 0.0 .TP .B depends salt.utils.win_update .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wua.available(software=True, drivers=True, summary=False, skip_installed=True, skip_hidden=True, skip_mandatory=False, skip_reboot=False, categories=None, severities=None, online=True) New in version 2017.7.0. .sp List updates that match the passed criteria. This allows for more filter options than \fI\%list()\fP\&. Good for finding a specific GUID or KB. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsoftware\fP (\fI\%bool\fP) \-\- Include software updates in the results. Default is \fBTrue\fP .IP \(bu 2 \fBdrivers\fP (\fI\%bool\fP) \-\- Include driver updates in the results. Default is \fBTrue\fP .IP \(bu 2 \fBsummary\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .IP \(bu 2 \fBTrue\fP: Return a summary of updates available for each category. .IP \(bu 2 \fBFalse\fP (default): Return a detailed list of available updates. .UNINDENT .IP \(bu 2 \fBskip_installed\fP (\fI\%bool\fP) \-\- Skip updates that are already installed. Default is \fBTrue\fP .IP \(bu 2 \fBskip_hidden\fP (\fI\%bool\fP) \-\- Skip updates that have been hidden. Default is \fBTrue\fP .IP \(bu 2 \fBskip_mandatory\fP (\fI\%bool\fP) \-\- Skip mandatory updates. Default is \fBFalse\fP .IP \(bu 2 \fBskip_reboot\fP (\fI\%bool\fP) \-\- Skip updates that require a reboot. Default is \fBFalse\fP .IP \(bu 2 \fBcategories\fP (\fI\%list\fP) \-\- .sp Specify the categories to list. Must be passed as a list. All categories returned by default. .sp Categories include the following: .INDENT 2.0 .IP \(bu 2 Critical Updates .IP \(bu 2 Definition Updates .IP \(bu 2 Drivers (make sure you set \fBdrivers=True\fP) .IP \(bu 2 Feature Packs .IP \(bu 2 Security Updates .IP \(bu 2 Update Rollups .IP \(bu 2 Updates .IP \(bu 2 Update Rollups .IP \(bu 2 Windows 7 .IP \(bu 2 Windows 8.1 .IP \(bu 2 Windows 8.1 drivers .IP \(bu 2 Windows 8.1 and later drivers .IP \(bu 2 Windows Defender .UNINDENT .IP \(bu 2 \fBseverities\fP (\fI\%list\fP) \-\- .sp Specify the severities to include. Must be passed as a list. All severities returned by default. .sp Severities include the following: .INDENT 2.0 .IP \(bu 2 Critical .IP \(bu 2 Important .UNINDENT .IP \(bu 2 \fBonline\fP (\fI\%bool\fP) \-\- .sp Tells the Windows Update Agent go online to update its local update database. \fBTrue\fP will go online. \fBFalse\fP will use the local update database as is. Default is \fBTrue\fP .sp New in version 3001. .UNINDENT .TP .B Returns Returns a dict containing either a summary or a list of updates: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Dict of Updates: {\(aq<GUID>\(aq: { \(aqTitle\(aq: <title>, \(aqKB\(aq: <KB>, \(aqGUID\(aq: <the globally unique identifier for the update>, \(aqDescription\(aq: <description>, \(aqDownloaded\(aq: <has the update been downloaded>, \(aqInstalled\(aq: <has the update been installed>, \(aqMandatory\(aq: <is the update mandatory>, \(aqUserInput\(aq: <is user input required>, \(aqEULAAccepted\(aq: <has the EULA been accepted>, \(aqSeverity\(aq: <update severity>, \(aqNeedsReboot\(aq: <is the update installed and awaiting reboot>, \(aqRebootBehavior\(aq: <will the update require a reboot>, \(aqCategories\(aq: [ \(aq<category 1>\(aq, \(aq<category 2>\(aq, ... ] }} Summary of Updates: {\(aqTotal\(aq: <total number of updates returned>, \(aqAvailable\(aq: <updates that are not downloaded or installed>, \(aqDownloaded\(aq: <updates that are downloaded but not installed>, \(aqInstalled\(aq: <updates installed (usually 0 unless installed=True)>, \(aqCategories\(aq: { <category 1>: <total for that category>, <category 2>: <total for category 2>, ... } } .ft P .fi .UNINDENT .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Normal Usage (list all software updates) salt \(aq*\(aq win_wua.available # List all updates with categories of Critical Updates and Drivers salt \(aq*\(aq win_wua.available categories=[\(dqCritical Updates\(dq,\(dqDrivers\(dq] # List all Critical Security Updates salt \(aq*\(aq win_wua.available categories=[\(dqSecurity Updates\(dq] severities=[\(dqCritical\(dq] # List all updates with a severity of Critical salt \(aq*\(aq win_wua.available severities=[\(dqCritical\(dq] # A summary of all available updates salt \(aq*\(aq win_wua.available summary=True # A summary of all Feature Packs and Windows 8.1 Updates salt \(aq*\(aq win_wua.available categories=[\(dqFeature Packs\(dq,\(dqWindows 8.1\(dq] summary=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wua.download(names) New in version 2017.7.0. .sp Downloads updates that match the list of passed identifiers. It\(aqs easier to use this function by using list_updates and setting \fBdownload=True\fP\&. .INDENT 7.0 .TP .B Parameters \fBnames\fP (\fI\%str\fP\fI, \fP\fI\%list\fP) \-\- .sp A single update or a list of updates to download. This can be any combination of GUIDs, KB numbers, or names. GUIDs or KBs are preferred. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 An error will be raised if there are more results than there are items in the names parameter .UNINDENT .UNINDENT .TP .B Returns A dictionary containing the details about the downloaded updates .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Normal Usage salt \(aq*\(aq win_wua.download names=[\(aq12345678\-abcd\-1234\-abcd\-1234567890ab\(aq, \(aqKB2131233\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wua.get(name, download=False, install=False, online=True) New in version 2017.7.0. .sp Returns details for the named update .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the update you\(aqre searching for. This can be the GUID, a KB number, or any part of the name of the update. GUIDs and KBs are preferred. Run \fBlist\fP to get the GUID for the update you\(aqre looking for. .IP \(bu 2 \fBdownload\fP (\fI\%bool\fP) \-\- Download the update returned by this function. Run this function first to see if the update exists, then set \fBdownload=True\fP to download the update. .IP \(bu 2 \fBinstall\fP (\fI\%bool\fP) \-\- Install the update returned by this function. Run this function first to see if the update exists, then set \fBinstall=True\fP to install the update. .IP \(bu 2 \fBonline\fP (\fI\%bool\fP) \-\- .sp Tells the Windows Update Agent go online to update its local update database. \fBTrue\fP will go online. \fBFalse\fP will use the local update database as is. Default is \fBTrue\fP .sp New in version 3001. .UNINDENT .TP .B Returns .INDENT 7.0 .TP .B Returns a dict containing a list of updates that match the name if download and install are both set to False. Should usually be a single update, but can return multiple if a partial name is given. .UNINDENT .sp If download or install is set to true it will return the results of the operation. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Dict of Updates: {\(aq<GUID>\(aq: { \(aqTitle\(aq: <title>, \(aqKB\(aq: <KB>, \(aqGUID\(aq: <the globally unique identifier for the update>, \(aqDescription\(aq: <description>, \(aqDownloaded\(aq: <has the update been downloaded>, \(aqInstalled\(aq: <has the update been installed>, \(aqMandatory\(aq: <is the update mandatory>, \(aqUserInput\(aq: <is user input required>, \(aqEULAAccepted\(aq: <has the EULA been accepted>, \(aqSeverity\(aq: <update severity>, \(aqNeedsReboot\(aq: <is the update installed and awaiting reboot>, \(aqRebootBehavior\(aq: <will the update require a reboot>, \(aqCategories\(aq: [ \(aq<category 1>\(aq, \(aq<category 2>\(aq, ... ] }} .ft P .fi .UNINDENT .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Recommended Usage using GUID without braces # Use this to find the status of a specific update salt \(aq*\(aq win_wua.get 12345678\-abcd\-1234\-abcd\-1234567890ab # Use the following if you don\(aqt know the GUID: # Using a KB number # Not all updates have an associated KB salt \(aq*\(aq win_wua.get KB3030298 # Using part or all of the name of the update # Could possibly return multiple results # Not all updates have an associated KB salt \(aq*\(aq win_wua.get \(aqMicrosoft Camera Codec Pack\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wua.get_needs_reboot() Determines if the system needs to be rebooted. .INDENT 7.0 .TP .B Returns \fBTrue\fP if the system requires a reboot, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_wua.get_needs_reboot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wua.get_wu_settings() Get current Windows Update settings. .INDENT 7.0 .TP .B Returns A dictionary of Windows Update settings: .INDENT 7.0 .TP .B Featured Updates: Boolean value that indicates whether to display notifications for featured updates. .TP .B Group Policy Required (Read\-only): Boolean value that indicates whether Group Policy requires the Automatic Updates service. .TP .B Microsoft Update: Boolean value that indicates whether to turn on Microsoft Update for other Microsoft Products .TP .B Needs Reboot: Boolean value that indicates whether the machine is in a reboot pending state. .TP .B Non Admins Elevated: Boolean value that indicates whether non\-administrators can perform some update\-related actions without administrator approval. .UNINDENT .sp Notification Level: .INDENT 7.0 .INDENT 3.5 Number 1 to 4 indicating the update level: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 Never check for updates .IP 2. 3 Check for updates but let me choose whether to download and install them .IP 3. 3 Download updates but let me choose whether to install them .IP 4. 3 Install updates automatically .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Read Only (Read\-only): Boolean value that indicates whether the Automatic Update settings are read\-only. .TP .B Recommended Updates: Boolean value that indicates whether to include optional or recommended updates when a search for updates and installation of updates is performed. .TP .B Scheduled Day: Days of the week on which Automatic Updates installs or uninstalls updates. .TP .B Scheduled Time: Time at which Automatic Updates installs or uninstalls updates. .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_wua.get_wu_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wua.install(names) New in version 2017.7.0. .sp Installs updates that match the list of identifiers. It may be easier to use the list_updates function and set \fBinstall=True\fP\&. .INDENT 7.0 .TP .B Parameters \fBnames\fP (\fI\%str\fP\fI, \fP\fI\%list\fP) \-\- A single update or a list of updates to install. This can be any combination of GUIDs, KB numbers, or names. GUIDs or KBs are preferred. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 An error will be raised if there are more results than there are items in the names parameter .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns A dictionary containing the details about the installed updates .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Normal Usage salt \(aq*\(aq win_wua.install KB12323211 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wua.installed(summary=False, kbs_only=False) New in version 3001. .sp Get a list of all updates that are currently installed on the system. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This list may not necessarily match the Update History on the machine. This will only show the updates that apply to the current build of Windows. So, for example, the system may have shipped with Windows 10 Build 1607. That machine received updates to the 1607 build. Later the machine was upgraded to a newer feature release, 1803 for example. Then more updates were applied. This will only return the updates applied to the 1803 build and not those applied when the system was at the 1607 build. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsummary\fP (\fI\%bool\fP) \-\- Return a summary instead of a detailed list of updates. \fBTrue\fP will return a Summary, \fBFalse\fP will return a detailed list of installed updates. Default is \fBFalse\fP .IP \(bu 2 \fBkbs_only\fP (\fI\%bool\fP) \-\- Only return a list of KBs installed on the system. If this parameter is passed, the \fBsummary\fP parameter will be ignored. Default is \fBFalse\fP .UNINDENT .TP .B Returns .INDENT 7.0 .TP .B Returns a dictionary of either a Summary or a detailed list of updates installed on the system when \fBkbs_only=False\fP .TP .B list: Returns a list of KBs installed on the system when \fBkbs_only=True\fP .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Get a detailed list of all applicable updates installed on the system salt \(aq*\(aq win_wua.installed # Get a summary of all applicable updates installed on the system salt \(aq*\(aq win_wua.installed summary=True # Get a simple list of KBs installed on the system salt \(aq*\(aq win_wua.installed kbs_only=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wua.list(software=True, drivers=False, summary=False, skip_installed=True, categories=None, severities=None, download=False, install=False, online=True) New in version 2017.7.0. .sp Returns a detailed list of available updates or a summary. If \fBdownload\fP or \fBinstall\fP is \fBTrue\fP the same list will be downloaded and/or installed. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsoftware\fP (\fI\%bool\fP) \-\- Include software updates in the results. Default is \fBTrue\fP .IP \(bu 2 \fBdrivers\fP (\fI\%bool\fP) \-\- Include driver updates in the results. Default is \fBFalse\fP .IP \(bu 2 \fBsummary\fP (\fI\%bool\fP) \-\- .INDENT 2.0 .IP \(bu 2 \fBTrue\fP: Return a summary of updates available for each category. .IP \(bu 2 \fBFalse\fP (default): Return a detailed list of available updates. .UNINDENT .IP \(bu 2 \fBskip_installed\fP (\fI\%bool\fP) \-\- Skip installed updates in the results. Default is \fBTrue\fP .IP \(bu 2 \fBdownload\fP (\fI\%bool\fP) \-\- (Overrides reporting functionality) Download the list of updates returned by this function. Run this function first with \fBdownload=False\fP to see what will be downloaded, then set \fBdownload=True\fP to download the updates. Default is \fBFalse\fP .IP \(bu 2 \fBinstall\fP (\fI\%bool\fP) \-\- (Overrides reporting functionality) Install the list of updates returned by this function. Run this function first with \fBinstall=False\fP to see what will be installed, then set \fBinstall=True\fP to install the updates. Default is \fBFalse\fP .IP \(bu 2 \fBcategories\fP (\fI\%list\fP) \-\- .sp Specify the categories to list. Must be passed as a list. All categories returned by default. .sp Categories include the following: .INDENT 2.0 .IP \(bu 2 Critical Updates .IP \(bu 2 Definition Updates .IP \(bu 2 Drivers (make sure you set \fBdrivers=True\fP) .IP \(bu 2 Feature Packs .IP \(bu 2 Security Updates .IP \(bu 2 Update Rollups .IP \(bu 2 Updates .IP \(bu 2 Update Rollups .IP \(bu 2 Windows 7 .IP \(bu 2 Windows 8.1 .IP \(bu 2 Windows 8.1 drivers .IP \(bu 2 Windows 8.1 and later drivers .IP \(bu 2 Windows Defender .UNINDENT .IP \(bu 2 \fBseverities\fP (\fI\%list\fP) \-\- .sp Specify the severities to include. Must be passed as a list. All severities returned by default. .sp Severities include the following: .INDENT 2.0 .IP \(bu 2 Critical .IP \(bu 2 Important .UNINDENT .IP \(bu 2 \fBonline\fP (\fI\%bool\fP) \-\- .sp Tells the Windows Update Agent go online to update its local update database. \fBTrue\fP will go online. \fBFalse\fP will use the local update database as is. Default is \fBTrue\fP .sp New in version 3001. .UNINDENT .TP .B Returns Returns a dict containing either a summary or a list of updates: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Dict of Updates: {\(aq<GUID>\(aq: { \(aqTitle\(aq: <title>, \(aqKB\(aq: <KB>, \(aqGUID\(aq: <the globally unique identifier for the update>, \(aqDescription\(aq: <description>, \(aqDownloaded\(aq: <has the update been downloaded>, \(aqInstalled\(aq: <has the update been installed>, \(aqMandatory\(aq: <is the update mandatory>, \(aqUserInput\(aq: <is user input required>, \(aqEULAAccepted\(aq: <has the EULA been accepted>, \(aqSeverity\(aq: <update severity>, \(aqNeedsReboot\(aq: <is the update installed and awaiting reboot>, \(aqRebootBehavior\(aq: <will the update require a reboot>, \(aqCategories\(aq: [ \(aq<category 1>\(aq, \(aq<category 2>\(aq, ... ] }} Summary of Updates: {\(aqTotal\(aq: <total number of updates returned>, \(aqAvailable\(aq: <updates that are not downloaded or installed>, \(aqDownloaded\(aq: <updates that are downloaded but not installed>, \(aqInstalled\(aq: <updates installed (usually 0 unless installed=True)>, \(aqCategories\(aq: { <category 1>: <total for that category>, <category 2>: <total for category 2>, ... } } .ft P .fi .UNINDENT .UNINDENT .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Normal Usage (list all software updates) salt \(aq*\(aq win_wua.list # List all updates with categories of Critical Updates and Drivers salt \(aq*\(aq win_wua.list categories=[\(aqCritical Updates\(aq,\(aqDrivers\(aq] # List all Critical Security Updates salt \(aq*\(aq win_wua.list categories=[\(aqSecurity Updates\(aq] severities=[\(aqCritical\(aq] # List all updates with a severity of Critical salt \(aq*\(aq win_wua.list severities=[\(aqCritical\(aq] # A summary of all available updates salt \(aq*\(aq win_wua.list summary=True # A summary of all Feature Packs and Windows 8.1 Updates salt \(aq*\(aq win_wua.list categories=[\(aqFeature Packs\(aq,\(aqWindows 8.1\(aq] summary=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wua.set_wu_settings(level=None, recommended=None, featured=None, elevated=None, msupdate=None, day=None, time=None) Change Windows Update settings. If no parameters are passed, the current value will be returned. .INDENT 7.0 .TP .B Supported: .INDENT 7.0 .IP \(bu 2 Windows Vista / Server 2008 .IP \(bu 2 Windows 7 / Server 2008R2 .IP \(bu 2 Windows 8 / Server 2012 .IP \(bu 2 Windows 8.1 / Server 2012R2 .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBlevel\fP (\fI\%int\fP) \-\- .sp Number from 1 to 4 indicating the update level: .INDENT 2.0 .IP 1. 3 Never check for updates .IP 2. 3 Check for updates but let me choose whether to download and install them .IP 3. 3 Download updates but let me choose whether to install them .IP 4. 3 Install updates automatically .UNINDENT .IP \(bu 2 \fBrecommended\fP (\fI\%bool\fP) \-\- Boolean value that indicates whether to include optional or recommended updates when a search for updates and installation of updates is performed. .IP \(bu 2 \fBfeatured\fP (\fI\%bool\fP) \-\- Boolean value that indicates whether to display notifications for featured updates. .IP \(bu 2 \fBelevated\fP (\fI\%bool\fP) \-\- Boolean value that indicates whether non\-administrators can perform some update\-related actions without administrator approval. .IP \(bu 2 \fBmsupdate\fP (\fI\%bool\fP) \-\- Boolean value that indicates whether to turn on Microsoft Update for other Microsoft products .IP \(bu 2 \fBday\fP (\fI\%str\fP) \-\- .sp Days of the week on which Automatic Updates installs or uninstalls updates. Accepted values: .INDENT 2.0 .IP \(bu 2 Everyday .IP \(bu 2 Monday .IP \(bu 2 Tuesday .IP \(bu 2 Wednesday .IP \(bu 2 Thursday .IP \(bu 2 Friday .IP \(bu 2 Saturday .UNINDENT .IP \(bu 2 \fBtime\fP (\fI\%str\fP) \-\- Time at which Automatic Updates installs or uninstalls updates. Must be in the ##:## 24hr format, eg. 3:00 PM would be 15:00. Must be in 1 hour increments. .UNINDENT .TP .B Returns Returns a dictionary containing the results. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq win_wua.set_wu_settings level=4 recommended=True featured=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wua.uninstall(names) New in version 2017.7.0. .sp Uninstall updates. .INDENT 7.0 .TP .B Parameters \fBnames\fP (\fI\%str\fP\fI, \fP\fI\%list\fP) \-\- A single update or a list of updates to uninstall. This can be any combination of GUIDs, KB numbers, or names. GUIDs or KBs are preferred. .TP .B Returns A dictionary containing the details about the uninstalled updates .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Normal Usage salt \(aq*\(aq win_wua.uninstall KB3121212 # As a list salt \(aq*\(aq win_wua.uninstall guid=[\(aq12345678\-abcd\-1234\-abcd\-1234567890ab\(aq, \(aqKB1231231\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.win_wusa .sp Microsoft Update files management via wusa.exe .INDENT 0.0 .TP .B maintainer Thomas Lemarchand .TP .B platform Windows .TP .B depends PowerShell .UNINDENT .sp New in version 2018.3.4. .INDENT 0.0 .TP .B salt.modules.win_wusa.install(path, restart=False) Install a KB from a .msu file. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The full path to the msu file to install .IP \(bu 2 \fBrestart\fP (\fI\%bool\fP) \-\- \fBTrue\fP to force a restart if required by the installation. Adds the \fB/forcerestart\fP switch to the \fBwusa.exe\fP command. \fBFalse\fP will add the \fB/norestart\fP switch instead. Default is \fBFalse\fP .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If the package is already installed or an error is encountered .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq wusa.install C:/temp/KB123456.msu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wusa.is_installed(name) Check if a specific KB is installed. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the KB to check .TP .B Returns \fBTrue\fP if installed, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq wusa.is_installed KB123456 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wusa.list_() Get a list of updates installed on the machine .INDENT 7.0 .TP .B Returns A list of installed updates .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq wusa.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_wusa.uninstall(path, restart=False) Uninstall a specific KB. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The full path to the msu file to uninstall. This can also be just the name of the KB to uninstall .IP \(bu 2 \fBrestart\fP (\fI\%bool\fP) \-\- \fBTrue\fP to force a restart if required by the installation. Adds the \fB/forcerestart\fP switch to the \fBwusa.exe\fP command. \fBFalse\fP will add the \fB/norestart\fP switch instead. Default is \fBFalse\fP .UNINDENT .TP .B Returns \fBTrue\fP if successful, otherwise \fBFalse\fP .TP .B Return type \fI\%bool\fP .TP .B Raises \fI\%CommandExecutionError\fP \-\- If an error is encountered .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq wusa.uninstall KB123456 # or salt \(aq*\(aq wusa.uninstall C:/temp/KB123456.msu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.winrepo .sp Module to manage Windows software repo on a Standalone Minion .sp \fBfile_client: local\fP must be set in the minion config file. .sp For documentation on Salt\(aqs Windows Repo feature, see \fI\%here\fP\&. .INDENT 0.0 .TP .B salt.modules.winrepo.genrepo() Generate winrepo_cachefile based on sls files in the winrepo_dir .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call winrepo.genrepo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.winrepo.show_sls(name, saltenv=\(aqbase\(aq) New in version 2015.8.0. .sp Display the rendered software definition from a specific sls file in the local winrepo cache. This will parse all Jinja. Run pkg.refresh_db to pull the latest software definitions from the master. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function does not ask a master for an sls file to render. Instead it directly processes the file specified in \fIname\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstr\fP (\fIsaltenv\fP) \-\- The name/path of the package you want to view. This can be the .IP \(bu 2 \fBlocal\fP (\fIfull path to a file on the minion file system\fP\fI or \fP\fIa file on the\fP) \-\- .IP \(bu 2 \fBcache.\fP (\fIminion\fP) \-\- .IP \(bu 2 \fBstr\fP \-\- The default environment is \fBbase\fP .UNINDENT .TP .B Returns Returns a dictionary containing the rendered data structure .TP .B Return type \fI\%dict\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To use a file from the minion cache start from the local winrepo root (\fBC:\esalt\evar\ecache\esalt\eminion\efiles\ebase\ewin\erepo\-ng\fP). If you have \fB\&.sls\fP files organized in subdirectories you\(aqll have to denote them with \fB\&.\fP\&. For example, if you have a \fBtest\fP directory in the winrepo root with a \fBgvim.sls\fP file inside, would target that file like so: \fBtest.gvim\fP\&. Directories can be targeted as well as long as they contain an \fBinit.sls\fP inside. For example, if you have a \fBnode\fP directory with an \fBinit.sls\fP inside, target that like so: \fBnode\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq winrepo.show_sls gvim salt \(aq*\(aq winrepo.show_sls test.npp salt \(aq*\(aq winrepo.show_sls C:\etest\egvim.sls .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.winrepo.update_git_repos(clean=False) Checkout git repos containing \fI\%Windows Software Package Definitions\fP\&. .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 This function requires \fI\%Git for Windows\fP to be installed in order to work. When installing, make sure to select an installation option which permits the git executable to be run from the Command Prompt. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B clean False Clean repo cachedirs which are not configured under \fI\%winrepo_remotes\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option only applies if either \fI\%pygit2\fP or \fI\%GitPython\fP is installed into Salt\(aqs bundled Python. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This argument should not be set to \fBTrue\fP if a mix of git and non\-git repo definitions are being used, as it will result in the non\-git repo definitions being removed. .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call winrepo.update_git_repos .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.wordpress .sp This module is used to manage Wordpress installations .INDENT 0.0 .TP .B depends wp binary from \fI\%http://wp\-cli.org/\fP .UNINDENT .INDENT 0.0 .TP .B class salt.modules.wordpress.Plugin(name, status, update, versino) .INDENT 7.0 .TP .B name Alias for field number 0 .UNINDENT .INDENT 7.0 .TP .B status Alias for field number 1 .UNINDENT .INDENT 7.0 .TP .B update Alias for field number 2 .UNINDENT .INDENT 7.0 .TP .B versino Alias for field number 3 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.wordpress.activate(name, path, user) Activate a wordpress plugin .INDENT 7.0 .TP .B name Wordpress plugin name .TP .B path path to wordpress install location .TP .B user user to run the command as .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq wordpress.activate HyperDB /var/www/html apache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.wordpress.deactivate(name, path, user) Deactivate a wordpress plugin .INDENT 7.0 .TP .B name Wordpress plugin name .TP .B path path to wordpress install location .TP .B user user to run the command as .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq wordpress.deactivate HyperDB /var/www/html apache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.wordpress.install(path, user, admin_user, admin_password, admin_email, title, url) Run the initial setup functions for a wordpress install .INDENT 7.0 .TP .B path path to wordpress install location .TP .B user user to run the command as .TP .B admin_user Username for the Administrative user for the wordpress install .TP .B admin_password Initial Password for the Administrative user for the wordpress install .TP .B admin_email Email for the Administrative user for the wordpress install .TP .B title Title of the wordpress website for the wordpress install .TP .B url Url for the wordpress install .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq wordpress.install /var/www/html apache dwallace password123 dwallace@example.com \(dqDaniel\(aqs Awesome Blog\(dq https://blog.dwallace.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.wordpress.is_installed(path, user=None) Check if wordpress is installed and setup .INDENT 7.0 .TP .B path path to wordpress install location .TP .B user user to run the command as .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq wordpress.is_installed /var/www/html apache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.wordpress.list_plugins(path, user) List plugins in an installed wordpress path .INDENT 7.0 .TP .B path path to wordpress install location .TP .B user user to run the command as .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq wordpress.list_plugins /var/www/html apache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.wordpress.show_plugin(name, path, user) Show a plugin in a wordpress install and check if it is installed .INDENT 7.0 .TP .B name Wordpress plugin name .TP .B path path to wordpress install location .TP .B user user to run the command as .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq wordpress.show_plugin HyperDB /var/www/html apache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.x509 .sp Manage X509 certificates .sp New in version 2015.8.0. .INDENT 0.0 .TP .B depends M2Crypto .UNINDENT .sp Deprecated since version 3006.0. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module has been deprecated and will be removed in Salt 3009 (Potassium). Please migrate to the replacement modules. For breaking changes between both versions, you can refer to the \fI\%x509_v2 execution module docs\fP\&. .sp They will become the default \fBx509\fP modules in Salt 3008 (Argon). You can explicitly switch to the new modules before that release by setting \fBfeatures: {x509_v2: true}\fP in your minion configuration. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.create_certificate(path=None, text=False, overwrite=True, ca_server=None, **kwargs) Create an X509 certificate. .INDENT 7.0 .TP .B path: Path to write the certificate to. .TP .B text: If \fBTrue\fP, return the PEM text without writing to a file. Default \fBFalse\fP\&. .TP .B overwrite: If \fBTrue\fP (default), create_certificate will overwrite the entire PEM file. Set False to preserve existing private keys and dh params that may exist in the PEM file. .TP .B kwargs: Any of the properties below can be included as additional keyword arguments. .TP .B ca_server: Request a remotely signed certificate from ca_server. For this to work, a \fBsigning_policy\fP must be specified, and that same policy must be configured on the ca_server. See \fBsigning_policy\fP for details. Also, the salt master must permit peers to call the \fBsign_remote_certificate\fP function. .sp Example: .sp /etc/salt/master.d/peer.conf .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C peer: .*: \- x509.sign_remote_certificate .ft P .fi .UNINDENT .UNINDENT .TP .B subject properties: Any of the values below can be included to set subject properties Any other subject properties supported by OpenSSL should also work. .INDENT 7.0 .TP .B C: 2 letter Country code .TP .B CN: Certificate common name, typically the FQDN. .TP .B Email: Email address .TP .B GN: Given Name .TP .B L: Locality .TP .B O: Organization .TP .B OU: Organization Unit .TP .B SN: SurName .TP .B ST: State or Province .UNINDENT .TP .B signing_private_key: A path or string of the private key in PEM format that will be used to sign this certificate. If neither \fBsigning_cert\fP, \fBpublic_key\fP, or \fBcsr\fP are included, it will be assumed that this is a self\-signed certificate, and the public key matching \fBsigning_private_key\fP will be used to create the certificate. .TP .B signing_private_key_passphrase: Passphrase used to decrypt the signing_private_key. .TP .B signing_cert: A certificate matching the private key that will be used to sign this certificate. This is used to populate the issuer values in the resulting certificate. Do not include this value for self\-signed certificates. .TP .B public_key: The public key to be included in this certificate. This can be sourced from a public key, certificate, CSR or private key. If a private key is used, the matching public key from the private key will be generated before any processing is done. This means you can request a certificate from a remote CA using a private key file as your public_key and only the public key will be sent across the network to the CA. If neither \fBpublic_key\fP or \fBcsr\fP are specified, it will be assumed that this is a self\-signed certificate, and the public key derived from \fBsigning_private_key\fP will be used. Specify either \fBpublic_key\fP or \fBcsr\fP, not both. Because you can input a CSR as a public key or as a CSR, it is important to understand the difference. If you import a CSR as a public key, only the public key will be added to the certificate, subject or extension information in the CSR will be lost. .TP .B public_key_passphrase: If the public key is supplied as a private key, this is the passphrase used to decrypt it. .TP .B csr: A file or PEM string containing a certificate signing request. This will be used to supply the subject, extensions and public key of a certificate. Any subject or extensions specified explicitly will overwrite any in the CSR. .TP .B basicConstraints: X509v3 Basic Constraints extension. .TP .B extensions: The following arguments set X509v3 Extension values. If the value starts with \fBcritical\fP, the extension will be marked as critical. .sp Some special extensions are \fBsubjectKeyIdentifier\fP and \fBauthorityKeyIdentifier\fP\&. .sp \fBsubjectKeyIdentifier\fP can be an explicit value or it can be the special string \fBhash\fP\&. \fBhash\fP will set the subjectKeyIdentifier equal to the SHA1 hash of the modulus of the public key in this certificate. Note that this is not the exact same hashing method used by OpenSSL when using the hash value. .sp \fBauthorityKeyIdentifier\fP Use values acceptable to the openssl CLI tools. This will automatically populate \fBauthorityKeyIdentifier\fP with the \fBsubjectKeyIdentifier\fP of \fBsigning_cert\fP\&. If this is a self\-signed cert these values will be the same. .INDENT 7.0 .TP .B basicConstraints: X509v3 Basic Constraints .TP .B keyUsage: X509v3 Key Usage .TP .B extendedKeyUsage: X509v3 Extended Key Usage .TP .B subjectKeyIdentifier: X509v3 Subject Key Identifier .TP .B issuerAltName: X509v3 Issuer Alternative Name .TP .B subjectAltName: X509v3 Subject Alternative Name .TP .B crlDistributionPoints: X509v3 CRL Distribution Points .TP .B issuingDistributionPoint: X509v3 Issuing Distribution Point .TP .B certificatePolicies: X509v3 Certificate Policies .TP .B policyConstraints: X509v3 Policy Constraints .TP .B inhibitAnyPolicy: X509v3 Inhibit Any Policy .TP .B nameConstraints: X509v3 Name Constraints .TP .B noCheck: X509v3 OCSP No Check .TP .B nsComment: Netscape Comment .TP .B nsCertType: Netscape Certificate Type .UNINDENT .TP .B days_valid: The number of days this certificate should be valid. This sets the \fBnotAfter\fP property of the certificate. Defaults to 365. .TP .B version: The version of the X509 certificate. Defaults to 3. This is automatically converted to the version value, so \fBversion=3\fP sets the certificate version field to 0x2. .TP .B serial_number: The serial number to assign to this certificate. If omitted a random serial number of size \fBserial_bits\fP is generated. .TP .B serial_bits: The number of bits to use when randomly generating a serial number. Defaults to 64. .TP .B algorithm: The hashing algorithm to be used for signing this certificate. Defaults to sha256. .TP .B copypath: An additional path to copy the resulting certificate to. Can be used to maintain a copy of all certificates issued for revocation purposes. .TP .B prepend_cn: If set to True, the CN and a dash will be prepended to the copypath\(aqs filename. .INDENT 7.0 .TP .B Example: /etc/pki/issued_certs/www.example.com\-DE:CA:FB:AD:00:00:00:00.crt .UNINDENT .TP .B signing_policy: A signing policy that should be used to create this certificate. Signing policies should be defined in the minion configuration, or in a minion pillar. It should be a YAML formatted list of arguments which will override any arguments passed to this function. If the \fBminions\fP key is included in the signing policy, only minions matching that pattern (see match.glob and match.compound) will be permitted to remotely request certificates from that policy. In order to \fBmatch.compound\fP to work salt master must peers permit peers to call it. .sp Example: .sp /etc/salt/master.d/peer.conf .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C peer: .*: \- match.compound .ft P .fi .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C x509_signing_policies: www: \- minions: \(aqwww*\(aq \- signing_private_key: /etc/pki/ca.key \- signing_cert: /etc/pki/ca.crt \- C: US \- ST: Utah \- L: Salt Lake City \- basicConstraints: \(dqcritical CA:false\(dq \- keyUsage: \(dqcritical cRLSign, keyCertSign\(dq \- subjectKeyIdentifier: hash \- authorityKeyIdentifier: keyid,issuer:always \- days_valid: 90 \- copypath: /etc/pki/issued_certs/ .ft P .fi .UNINDENT .UNINDENT .sp The above signing policy can be invoked with \fBsigning_policy=www\fP .TP .B not_before: Initial validity date for the certificate. This date must be specified in the format \(aq%Y\-%m\-%d %H:%M:%S\(aq. .sp New in version 3001. .TP .B not_after: Final validity date for the certificate. This date must be specified in the format \(aq%Y\-%m\-%d %H:%M:%S\(aq. .sp New in version 3001. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.create_certificate path=/etc/pki/myca.crt signing_private_key=\(aq/etc/pki/myca.key\(aq csr=\(aq/etc/pki/myca.csr\(aq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.create_crl(path=None, text=False, signing_private_key=None, signing_private_key_passphrase=None, signing_cert=None, revoked=None, include_expired=False, days_valid=100, digest=\(aq\(aq) Create a CRL .INDENT 7.0 .TP .B Depends .INDENT 7.0 .IP \(bu 2 PyOpenSSL Python module .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path: Path to write the CRL to. .TP .B text: If \fBTrue\fP, return the PEM text without writing to a file. Default \fBFalse\fP\&. .TP .B signing_private_key: A path or string of the private key in PEM format that will be used to sign the CRL. This is required. .TP .B signing_private_key_passphrase: Passphrase to decrypt the private key. .TP .B signing_cert: A certificate matching the private key that will be used to sign the CRL. This is required. .TP .B revoked: A list of dicts containing all the certificates to revoke. Each dict represents one certificate. A dict must contain either the key \fBserial_number\fP with the value of the serial number to revoke, or \fBcertificate\fP with either the PEM encoded text of the certificate, or a path to the certificate to revoke. .sp The dict can optionally contain the \fBrevocation_date\fP key. If this key is omitted the revocation date will be set to now. If should be a string in the format \(dq%Y\-%m\-%d %H:%M:%S\(dq. .sp The dict can also optionally contain the \fBnot_after\fP key. This is redundant if the \fBcertificate\fP key is included. If the \fBCertificate\fP key is not included, this can be used for the logic behind the \fBinclude_expired\fP parameter. If should be a string in the format \(dq%Y\-%m\-%d %H:%M:%S\(dq. .sp The dict can also optionally contain the \fBreason\fP key. This is the reason code for the revocation. Available choices are \fBunspecified\fP, \fBkeyCompromise\fP, \fBCACompromise\fP, \fBaffiliationChanged\fP, \fBsuperseded\fP, \fBcessationOfOperation\fP and \fBcertificateHold\fP\&. .TP .B include_expired: Include expired certificates in the CRL. Default is \fBFalse\fP\&. .TP .B days_valid: The number of days that the CRL should be valid. This sets the Next Update field in the CRL. .TP .B digest: The digest to use for signing the CRL. This has no effect on versions of pyOpenSSL less than 0.14 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.create_crl path=/etc/pki/mykey.key \e signing_private_key=/etc/pki/ca.key \e signing_cert=/etc/pki/ca.crt \e revoked=\(dq{\(aqcompromized\-web\-key\(aq: {\(aqcertificate\(aq: \(aq/etc/pki/certs/www1.crt\(aq, \(aqrevocation_date\(aq: \(aq2015\-03\-01 00:00:00\(aq}}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.create_csr(path=None, text=False, **kwargs) Create a certificate signing request. .INDENT 7.0 .TP .B path: Path to write the certificate to. .TP .B text: If \fBTrue\fP, return the PEM text without writing to a file. Default \fBFalse\fP\&. .TP .B algorithm: The hashing algorithm to be used for signing this request. Defaults to sha256. .TP .B kwargs: The subject, extension and version arguments from \fI\%x509.create_certificate\fP can be used. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.create_csr path=/etc/pki/myca.csr public_key=\(aq/etc/pki/myca.key\(aq CN=\(aqMy Cert\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.create_private_key(path=None, text=False, bits=2048, passphrase=None, cipher=\(aqaes_128_cbc\(aq, verbose=True) Creates a private key in PEM format. .INDENT 7.0 .TP .B path: The path to write the file to, either \fBpath\fP or \fBtext\fP are required. .TP .B text: If \fBTrue\fP, return the PEM text without writing to a file. Default \fBFalse\fP\&. .TP .B bits: Length of the private key in bits. Default 2048 .TP .B passphrase: Passphrase for encrypting the private key .TP .B cipher: Cipher for encrypting the private key. Has no effect if passphrase is None. .TP .B verbose: Provide visual feedback on stdout. Default True .sp New in version 2016.11.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.create_private_key path=/etc/pki/mykey.key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.expired(certificate) Returns a dict containing limited details of a certificate and whether the certificate has expired. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B certificate: The certificate to be read. Can be a path to a certificate file, or a string containing the PEM formatted text of the certificate. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.expired \(dq/etc/pki/mycert.crt\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.get_pem_entries(glob_path) Returns a dict containing PEM entries in files matching a glob .INDENT 7.0 .TP .B glob_path: A path to certificates to be read and returned. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.get_pem_entries \(dq/etc/pki/*.crt\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.get_pem_entry(text, pem_type=None) Returns a properly formatted PEM string from the input text fixing any whitespace or line\-break issues .INDENT 7.0 .TP .B text: Text containing the X509 PEM entry to be returned or path to a file containing the text. .TP .B pem_type: If specified, this function will only return a pem of a certain type, for example \(aqCERTIFICATE\(aq or \(aqCERTIFICATE REQUEST\(aq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.get_pem_entry \(dq\-\-\-\-\-BEGIN CERTIFICATE REQUEST\-\-\-\-\-MIICyzCC Ar8CAQI...\-\-\-\-\-END CERTIFICATE REQUEST\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.get_private_key_size(private_key, passphrase=None) Returns the bit length of a private key in PEM format. .INDENT 7.0 .TP .B private_key: A path or PEM encoded string containing a private key. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.get_private_key_size /etc/pki/mycert.key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.get_public_key(key, passphrase=None, asObj=False) Returns a string containing the public key in PEM format. .INDENT 7.0 .TP .B key: A path or PEM encoded string containing a CSR, Certificate or Private Key from which a public key can be retrieved. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.get_public_key /etc/pki/mycert.cer .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.get_signing_policy(signing_policy_name) Returns the details of a names signing policy, including the text of the public key that will be used to sign it. Does not return the private key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.get_signing_policy www .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.read_certificate(certificate) Returns a dict containing details of a certificate. Input can be a PEM string or file path. .INDENT 7.0 .TP .B certificate: The certificate to be read. Can be a path to a certificate file, or a string containing the PEM formatted text of the certificate. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.read_certificate /etc/pki/mycert.crt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.read_certificates(glob_path) Returns a dict containing details of all certificates matching a glob .INDENT 7.0 .TP .B glob_path: A path to certificates to be read and returned. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.read_certificates \(dq/etc/pki/*.crt\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.read_crl(crl) Returns a dict containing details of a certificate revocation list. Input can be a PEM string or file path. .INDENT 7.0 .TP .B Depends .INDENT 7.0 .IP \(bu 2 OpenSSL command line tool .UNINDENT .UNINDENT .INDENT 7.0 .TP .B crl: A path or PEM encoded string containing the CRL to read. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.read_crl /etc/pki/mycrl.crl .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.read_csr(csr) Returns a dict containing details of a certificate request. .INDENT 7.0 .TP .B Depends .INDENT 7.0 .IP \(bu 2 OpenSSL command line tool .UNINDENT .UNINDENT .INDENT 7.0 .TP .B csr: A path or PEM encoded string containing the CSR to read. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.read_csr /etc/pki/mycert.csr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.sign_remote_certificate(argdic, **kwargs) Request a certificate to be remotely signed according to a signing policy. .INDENT 7.0 .TP .B argdic: A dict containing all the arguments to be passed into the create_certificate function. This will become kwargs when passed to create_certificate. .TP .B kwargs: kwargs delivered from publish.publish .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.sign_remote_certificate argdic=\(dq{\(aqpublic_key\(aq: \(aq/etc/pki/www.key\(aq, \(aqsigning_policy\(aq: \(aqwww\(aq}\(dq __pub_id=\(aqwww1\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.verify_crl(crl, cert) Validate a CRL against a certificate. Parses openssl command line output, this is a workaround for M2Crypto\(aqs inability to get them from CSR objects. .INDENT 7.0 .TP .B crl: The CRL to verify .TP .B cert: The certificate to verify the CRL against .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.verify_crl crl=/etc/pki/myca.crl cert=/etc/pki/myca.crt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.verify_private_key(private_key, public_key, passphrase=None) Verify that \(aqprivate_key\(aq matches \(aqpublic_key\(aq .INDENT 7.0 .TP .B private_key: The private key to verify, can be a string or path to a private key in PEM format. .TP .B public_key: The public key to verify, can be a string or path to a PEM formatted certificate, CSR, or another private key. .TP .B passphrase: Passphrase to decrypt the private key. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.verify_private_key private_key=/etc/pki/myca.key \e public_key=/etc/pki/myca.crt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.verify_signature(certificate, signing_pub_key=None, signing_pub_key_passphrase=None) Verify that \fBcertificate\fP has been signed by \fBsigning_pub_key\fP .INDENT 7.0 .TP .B certificate: The certificate to verify. Can be a path or string containing a PEM formatted certificate. .TP .B signing_pub_key: The public key to verify, can be a string or path to a PEM formatted certificate, CSR, or private key. .TP .B signing_pub_key_passphrase: Passphrase to the signing_pub_key if it is an encrypted private key. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.verify_signature /etc/pki/mycert.pem \e signing_pub_key=/etc/pki/myca.crt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.will_expire(certificate, days) Returns a dict containing details of a certificate and whether the certificate will expire in the specified number of days. Input can be a PEM string or file path. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B certificate: The certificate to be read. Can be a path to a certificate file, or a string containing the PEM formatted text of the certificate. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.will_expire \(dq/etc/pki/mycert.crt\(dq days=30 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509.write_pem(text, path, overwrite=True, pem_type=None) Writes out a PEM string fixing any formatting or whitespace issues before writing. .INDENT 7.0 .TP .B text: PEM string input to be written out. .TP .B path: Path of the file to write the PEM out to. .TP .B overwrite: If \fBTrue\fP (default), write_pem will overwrite the entire PEM file. Set False to preserve existing private keys and dh params that may exist in the PEM file. .TP .B pem_type: The PEM type to be saved, for example \fBCERTIFICATE\fP or \fBPUBLIC KEY\fP\&. Adding this will allow the function to take input that may contain multiple PEM types. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.write_pem \(dq\-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\-MIIGMzCCBBugA...\(dq path=/etc/pki/mycert.crt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.x509_v2 .SS Manage X.509 certificates .INDENT 0.0 .TP .B depends cryptography .UNINDENT .sp New in version 3006.0: This module represents a complete rewrite of the original \fBx509\fP modules and is named \fBx509_v2\fP since it introduces breaking changes. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 PKCS12\-related operations require at least cryptography release 36. .IP \(bu 2 PKCS12\-related operations with Edwards\-curve keys require at least cryptography release 37. .IP \(bu 2 PKCS7\-related operations require at least cryptography release 37. .UNINDENT .UNINDENT .UNINDENT .SS Configuration .SS Explicit activation .sp Since this module uses the same virtualname as the previous \fBx509\fP modules, but is incompatible with them, it needs to be explicitly activated on each minion by including the following line in the minion configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/minion.d/x509.conf features: x509_v2: true .ft P .fi .UNINDENT .UNINDENT .SS Peer communication .sp To be able to remotely sign certificates, it is required to configure the Salt master to allow \fI\%Peer Communication\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/master.d/peer.conf peer: .*: \- x509.sign_remote_certificate .ft P .fi .UNINDENT .UNINDENT .sp In order for the \fI\%Compound Matcher\fP to work with restricting signing policies to a subset of minions, in addition calls to \fI\%match.compound_matches\fP by the minion acting as the CA must be permitted: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/master.d/peer.conf peer: .*: \- x509.sign_remote_certificate peer_run: ca_server: \- match.compound_matches .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When compound match expressions are employed, pillar values can only be matched literally. This is a barrier to enumeration attacks by the CA server. .sp Also note that compound matching requires a minion data cache on the master. Any certificate signing request will be denied if \fI\%minion_data_cache\fP is disabled (it is enabled by default). .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since grain values are controlled by minions, you should avoid using them to restrict certificate issuance. .sp See \fI\%Is Targeting using Grain Data Secure?\fP\&. .UNINDENT .UNINDENT .sp Changed in version 3007.0: Previously, a compound expression match was validated by the requesting minion itself via peer publishing, which did not protect from compromised minions. The new match validation takes place on the master using peer running. .SS Signing policies .sp In addition, the minion representing the CA needs to have at least one signing policy configured, remote calls not referencing one are always rejected. .sp The parameters specified in this signing policy override any parameters passed from the minion requesting the certificate. It can be configured in the CA minion\(aqs pillar, which takes precedence, or any location \fI\%config.get\fP looks up in. Signing policies are defined under \fBx509_signing_policies\fP\&. .sp You can restrict which minions can request a certificate under a configured signing policy by specifying a matcher in \fBminions\fP\&. This can be a glob or compound matcher (for the latter, see the notes above). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C x509_signing_policies: www: \- minions: \(aqwww*\(aq \- signing_private_key: /etc/pki/ca.key \- signing_cert: /etc/pki/ca.crt \- C: US \- ST: Utah \- L: Salt Lake City \- basicConstraints: \(dqcritical, CA:false\(dq \- keyUsage: \(dqcritical, cRLSign, keyCertSign\(dq \- subjectKeyIdentifier: hash \- authorityKeyIdentifier: keyid,issuer:always \- days_valid: 90 \- copypath: /etc/pki/issued_certs/ .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The following semantics are applied regarding the order of preference for specifying the subject name: .INDENT 0.0 .IP \(bu 2 If neither \fBsubject\fP nor any name attributes (like \fBCN\fP) are part of the policy, issued certificates can contain any requested ones. .IP \(bu 2 If any name attributes are specified in the signing policy, \fBsubject\fP contained in requests is ignored. .IP \(bu 2 If \fBsubject\fP is specified in the signing policy, any name attributes are ignored. If the request contains the same data type for \fBsubject\fP as the signing policy (for dicts and lists, and only then), merging is performed, otherwise \fBsubject\fP is taken from the signing policy. Dicts are merged and list items are appended, with the items taken from the signing policy having priority. .UNINDENT .UNINDENT .UNINDENT .SS Breaking changes versus the previous \fBx509\fP modules .INDENT 0.0 .IP \(bu 2 The output format has changed for all \fBread_*\fP functions as well as the state return dict. .IP \(bu 2 The formatting of some extension definitions might have changed, but should be stable for most basic use cases. .IP \(bu 2 The default ordering of RDNs/Name Attributes in the subject\(aqs Distinguished Name has been adapted to industry standards. This might cause a reissuance during the first state run. .IP \(bu 2 For \fBx509.private_key_managed\fP, the file mode defaults to \fB0400\fP\&. This should be considered a bug fix because writing private keys with world\-readable permissions by default is a security issue. .IP \(bu 2 Restricting signing policies using compound match expressions requires peer run permissions instead of peer publishing permissions: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # x509, x509_v2 in 3006.* peer: ca_server: \- match.compound # x509_v2 from 3007.0 onwards peer_run: ca_server: \- match.compound_matches .ft P .fi .UNINDENT .UNINDENT .sp Note that when a \fBca_server\fP is involved, both peers must use the updated module version. .INDENT 0.0 .TP .B salt.modules.x509_v2.create_certificate(ca_server=None, signing_policy=None, encoding=\(aqpem\(aq, append_certs=None, pkcs12_passphrase=None, pkcs12_encryption_compat=False, pkcs12_friendlyname=None, path=None, overwrite=True, raw=False, **kwargs) Create an X.509 certificate and return an encoded version of it. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 All parameters that take a public key, private key or certificate can be specified either as a PEM/hex/base64 string or a path to a local file encoded in all supported formats for the type. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.create_certificate signing_private_key=\(aq/etc/pki/myca.key\(aq csr=\(aq/etc/pki/my.csr\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B ca_server Request a remotely signed certificate from ca_server. For this to work, a \fBsigning_policy\fP must be specified, and that same policy must be configured on the ca_server. See \fI\%Signing policies\fP for details. Also, the Salt master must permit peers to call the \fBsign_remote_certificate\fP function, see \fI\%Peer communication\fP\&. .TP .B signing_policy The name of a configured signing policy. Parameters specified in there are hardcoded and cannot be overridden. This is required for remote signing, otherwise optional. See \fI\%Signing policies\fP for details. .TP .B encoding Specify the encoding of the resulting certificate. It can be returned as a \fBpem\fP (or \fBpkcs7_pem\fP) string or several (base64\-encoded) binary formats (\fBder\fP, \fBpkcs7_der\fP, \fBpkcs12\fP). Defaults to \fBpem\fP\&. .TP .B append_certs A list of additional certificates to append to the new one, e.g. to create a CA chain. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Mind that when \fBder\fP encoding is in use, appending certificatees is prohibited. .UNINDENT .UNINDENT .TP .B copypath Create a copy of the issued certificate in PEM format in this directory. The file will be named \fB<serial_number>.crt\fP if prepend_cn is False. .TP .B prepend_cn When \fBcopypath\fP is set, prepend the common name of the certificate to the file name like so: \fB<CN>\-<serial_number>.crt\fP\&. Defaults to false. .TP .B pkcs12_passphrase When encoding a certificate as \fBpkcs12\fP, encrypt it with this passphrase. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 PKCS12 encryption is very weak and \fI\%should not be relied on for security\fP\&. .UNINDENT .UNINDENT .TP .B pkcs12_encryption_compat OpenSSL 3 and cryptography v37 switched to a much more secure default encryption for PKCS12, which might be incompatible with some systems. This forces the legacy encryption. Defaults to False. .TP .B pkcs12_friendlyname When encoding a certificate as \fBpkcs12\fP, a name for the certificate can be included. .TP .B path Instead of returning the certificate, write it to this file path. .TP .B overwrite If \fBpath\fP is specified and the file exists, overwrite it. Defaults to true. .TP .B raw Return the encoded raw bytes instead of a string. Defaults to false. .TP .B digest The hashing algorithm to use for the signature. Valid values are: sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224, sha3_256, sha3_384, sha3_512. Defaults to \fBsha256\fP\&. This will be ignored for \fBed25519\fP and \fBed448\fP key types. .TP .B private_key The private key corresponding to the public key the certificate should be issued for. This is one way of specifying the public key that will be included in the certificate, the other ones being \fBpublic_key\fP and \fBcsr\fP\&. .TP .B private_key_passphrase If \fBprivate_key\fP is specified and encrypted, the passphrase to decrypt it. .TP .B public_key The public key the certificate should be issued for. Other ways of passing the required information are \fBprivate_key\fP and \fBcsr\fP\&. If neither are set, the public key of the \fBsigning_private_key\fP will be included, i.e. a self\-signed certificate is generated. .TP .B csr A certificate signing request to use as a base for generating the certificate. The following information will be respected, depending on configuration: * public key * extensions, if not otherwise specified (arguments, signing_policy) .TP .B signing_cert The CA certificate to be used for signing the issued certificate. .TP .B signing_private_key The private key corresponding to the public key in \fBsigning_cert\fP\&. Required. .TP .B signing_private_key_passphrase If \fBsigning_private_key\fP is encrypted, the passphrase to decrypt it. .TP .B serial_number A serial number to be embedded in the certificate. If unspecified, will autogenerate one. This should be an integer, either in decimal or hexadecimal notation. .TP .B not_before Set a specific date the certificate should not be valid before. The format should follow \fB%Y\-%m\-%d %H:%M:%S\fP and will be interpreted as GMT/UTC. Defaults to the time of issuance. .TP .B not_after Set a specific date the certificate should not be valid after. The format should follow \fB%Y\-%m\-%d %H:%M:%S\fP and will be interpreted as GMT/UTC. If unspecified, defaults to the current time plus \fBdays_valid\fP days. .TP .B days_valid If \fBnot_after\fP is unspecified, the number of days from the time of issuance the certificate should be valid for. Defaults to \fB30\fP\&. .TP .B subject The subject\(aqs distinguished name embedded in the certificate. This is one way of passing this information (see \fBkwargs\fP below for the other). This argument will be preferred and allows to control the order of RDNs in the DN as well as to embed RDNs with multiple attributes. This can be specified as an RFC4514\-encoded string (\fBCN=example.com,O=Example Inc,C=US\fP, mind that the rendered order is reversed from what is embedded), a list of RDNs encoded as in RFC4514 (\fB[\(dqC=US\(dq, \(dqO=Example Inc\(dq, \(dqCN=example.com\(dq]\fP) or a dictionary (\fB{\(dqCN\(dq: \(dqexample.com\(dq, \(dqC\(dq: \(dqUS\(dq, \(dqO\(dq: \(dqExample Inc\(dq}\fP, default ordering). Multiple name attributes per RDN are concatenated with a \fB+\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Parsing of RFC4514 strings requires at least cryptography release 37. .UNINDENT .UNINDENT .TP .B kwargs Embedded X.509v3 extensions and the subject\(aqs distinguished name can be controlled via supplemental keyword arguments. See the following for an overview. .TP .B Subject properties in kwargs C, ST, L, STREET, O, OU, CN, MAIL, SN, GN, UID, SERIALNUMBER .TP .B X.509v3 extensions in kwargs Most extensions can be configured using the same string format as OpenSSL, while some require adjustments. In general, since the strings are parsed to dicts/lists, you can always use the latter formats directly. Marking an extension as critical is done by including it at the beginning of the configuration string, in the list or as a key in the dictionary with the value \fBtrue\fP\&. .sp Examples (some showcase dict/list correspondance): .INDENT 7.0 .TP .B basicConstraints \fBcritical, CA:TRUE, pathlen:1\fP or .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- basicConstraints: critical: true ca: true pathlen: 1 .ft P .fi .UNINDENT .UNINDENT .TP .B keyUsage \fBcritical, cRLSign, keyCertSign\fP or .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- keyUsage: \- critical \- cRLSign \- keyCertSign .ft P .fi .UNINDENT .UNINDENT .TP .B subjectKeyIdentifier This can be an explicit value or \fBhash\fP, in which case the value will be set to the SHA1 hash of some encoding of the associated public key, depending on the underlying algorithm (RSA/ECDSA/EdDSA). .TP .B authorityKeyIdentifier \fBkeyid:always, issuer\fP .TP .B subjectAltName There is support for all OpenSSL\-defined types except \fBotherName\fP\&. .sp \fBemail:me@example.com,DNS:example.com\fP or .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # mind this being a list, not a dict \- subjectAltName: \- email:me@example.com \- DNS:example.com .ft P .fi .UNINDENT .UNINDENT .TP .B issuerAltName The syntax is the same as for \fBsubjectAltName\fP, except that the additional value \fBissuer:copy\fP is supported, which will copy the values of \fBsubjectAltName\fP in the issuer\(aqs certificate. .TP .B authorityInfoAccess \fBOCSP;URI:http://ocsp.example.com/,caIssuers;URI:http://myca.example.com/ca.cer\fP .TP .B crlDistributionPoints When set to a string value, items are interpreted as fullnames: .sp \fBURI:http://example.com/myca.crl, URI:http://example.org/my.crl\fP .sp There is also support for more attributes using the full form: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- crlDistributionPoints: \- fullname: URI:http://example.com/myca.crl crlissuer: DNS:example.org reasons: \- keyCompromise \- URI:http://example.org/my.crl .ft P .fi .UNINDENT .UNINDENT .TP .B certificatePolicies \fBcritical, 1.2.4.5, 1.1.3.4\fP .sp Again, there is support for more attributes using the full form: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- certificatePolicies: critical: true 1.2.3.4.5: https://my.ca.com/pratice_statement 1.2.4.5.6: \- https://my.ca.com/pratice_statement \- organization: myorg noticeNumbers: [1, 2, 3] text: mytext .ft P .fi .UNINDENT .UNINDENT .TP .B policyConstraints \fBrequireExplicitPolicy:3,inhibitPolicyMapping:1\fP .TP .B inhibitAnyPolicy The value is just an integer: \fB\- inhibitAnyPolicy: 1\fP .TP .B nameConstraints \fBcritical,permitted;IP:192.168.0.0/255.255.0.0,permitted;email:.example.com,excluded;email:.com\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- nameConstraints: critical: true permitted: \- IP:192.168.0.0/24 \- email:.example.com excluded: \- email:.com .ft P .fi .UNINDENT .UNINDENT .TP .B noCheck This extension does not take any values, except \fBcritical\fP\&. Just the presence in the keyword args will include it. .TP .B tlsfeature \fBstatus_request\fP .UNINDENT .sp For more information, visit the \fI\%OpenSSL docs\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.create_crl(signing_private_key, revoked, signing_cert=None, signing_private_key_passphrase=None, include_expired=False, days_valid=None, digest=\(aqsha256\(aq, encoding=\(aqpem\(aq, extensions=None, path=None, raw=False, **kwargs) Create a certificate revocation list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.create_crl signing_cert=/etc/pki/ca.crt signing_private_key=/etc/pki/ca.key revoked=\(dq[{\(aqcertificate\(aq: \(aq/etc/pki/certs/www1.crt\(aq, \(aqrevocation_date\(aq: \(aq2015\-03\-01 00:00:00\(aq}]\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B signing_private_key Your certificate authority\(aqs private key. It will be used to sign the CRL. Required. .TP .B revoked A list of dicts containing all the certificates to revoke. Each dict represents one certificate. A dict must contain either the key \fBserial_number\fP with the value of the serial number to revoke, or \fBcertificate\fP with some reference to the certificate to revoke. .sp The dict can optionally contain the \fBrevocation_date\fP key. If this key is omitted, the revocation date will be set to now. It should be a string in the format \(dq%Y\-%m\-%d %H:%M:%S\(dq. .sp The dict can also optionally contain the \fBnot_after\fP key. This is redundant if the \fBcertificate\fP key is included, since it will be sourced from the certificate. If the \fBcertificate\fP key is not included, this can be used for the logic behind the \fBinclude_expired\fP parameter. It should be a string in the format \(dq%Y\-%m\-%d %H:%M:%S\(dq. .sp The dict can also optionally contain the \fBextensions\fP key, which allows to set CRL entry\-specific extensions. The following extensions are supported: .INDENT 7.0 .TP .B certificateIssuer Identifies the certificate issuer associated with an entry in an indirect CRL. The format is the same as for subjectAltName. .TP .B CRLReason Identifies the reason for certificate revocation. Available choices are \fBunspecified\fP, \fBkeyCompromise\fP, \fBCACompromise\fP, \fBaffiliationChanged\fP, \fBsuperseded\fP, \fBcessationOfOperation\fP, \fBcertificateHold\fP, \fBprivilegeWithdrawn\fP, \fBaACompromise\fP and \fBremoveFromCRL\fP\&. .TP .B invalidityDate Provides the date on which the certificate likely became invalid. The value should be a string in the same format as \fBrevocation_date\fP\&. .UNINDENT .TP .B signing_cert The CA certificate to be used for signing the CRL. .TP .B signing_private_key_passphrase If \fBsigning_private_key\fP is encrypted, the passphrase to decrypt it. .TP .B include_expired Also include already expired certificates in the CRL. Defaults to false. .TP .B days_valid The number of days the CRL should be valid for. This sets the \fBNext Update\fP field. Defaults to \fB100\fP (until v3009) or \fB7\fP (from v3009 onwards). .TP .B digest The hashing algorithm to use for the signature. Valid values are: sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224, sha3_256, sha3_384, sha3_512. Defaults to \fBsha256\fP\&. This will be ignored for \fBed25519\fP and \fBed448\fP key types. .TP .B encoding Specify the encoding of the resulting certificate revocation list. It can be returned as a \fBpem\fP string or base64\-encoded \fBder\fP\&. Defaults to \fBpem\fP\&. .TP .B extensions Add CRL extensions. The following are available: .INDENT 7.0 .TP .B authorityKeyIdentifier See \fI\%x509.create_certificate\fP\&. .TP .B authorityInfoAccess See \fI\%x509.create_certificate\fP\&. .TP .B cRLNumber Specifies a sequential number for each CRL issued by a CA. Values must be integers. .TP .B deltaCRLIndicator If the CRL is a delta CRL, this value points to the cRLNumber of the base cRL. Values must be integers. .TP .B freshestCRL Identifies how delta CRL information is obtained. The format is the same as \fBcrlDistributionPoints\fP\&. .TP .B issuerAltName See \fI\%x509.create_certificate\fP\&. .TP .B issuingDistributionPoint Identifies the CRL distribution point for a particular CRL and indicates what kinds of revocation it covers. The format is comparable to \fBcrlDistributionPoints\fP\&. Specify as follows: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C issuingDistributionPoint: fullname: # or relativename with RDN \- URI:http://example.com/myca.crl onlysomereasons: \- keyCompromise onlyuser: true onlyCA: true onlyAA: true indirectCRL: false .ft P .fi .UNINDENT .UNINDENT .UNINDENT .TP .B path Instead of returning the CRL, write it to this file path. .TP .B raw Return the encoded raw bytes instead of a string. Defaults to false. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.create_csr(private_key, private_key_passphrase=None, digest=\(aqsha256\(aq, encoding=\(aqpem\(aq, path=None, raw=False, **kwargs) Create a certificate signing request. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.create_csr private_key=\(aq/etc/pki/myca.key\(aq CN=\(aqMy Cert\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B private_key The private key corresponding to the public key the certificate should be issued for. The CSR will be signed by it. Required. .TP .B private_key_passphrase If \fBprivate_key\fP is encrypted, the passphrase to decrypt it. .TP .B digest The hashing algorithm to use for the signature. Valid values are: sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224, sha3_256, sha3_384, sha3_512. Defaults to \fBsha256\fP\&. This will be ignored for \fBed25519\fP and \fBed448\fP key types. .TP .B encoding Specify the encoding of the resulting certificate signing request. It can be returned as a \fBpem\fP string or base64\-encoded \fBder\fP\&. Defaults to \fBpem\fP\&. .TP .B path Instead of returning the CSR, write it to this file path. .TP .B raw Return the encoded raw bytes instead of a string. Defaults to false. .TP .B kwargs Embedded X.509v3 extensions and the subject\(aqs distinguished name can be controlled via supplemental keyword arguments. See \fI\%x509.create_certificate\fP for an overview. Mind that some extensions are not available for CSR (\fBauthorityInfoAccess\fP, \fBauthorityKeyIdentifier\fP, \fBissuerAltName\fP, \fBcrlDistributionPoints\fP). .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.create_private_key(algo=\(aqrsa\(aq, keysize=None, passphrase=None, encoding=\(aqpem\(aq, pkcs12_encryption_compat=False, path=None, raw=False, **kwargs) Create a private key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.create_private_key algo=ec keysize=384 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B algo The digital signature scheme the private key should be based on. Available: \fBrsa\fP, \fBec\fP, \fBed25519\fP, \fBed448\fP\&. Defaults to \fBrsa\fP\&. .TP .B keysize For \fBrsa\fP, specifies the bitlength of the private key (2048, 3072, 4096). For \fBec\fP, specifies the NIST curve to use (256, 384, 521). Irrelevant for Edwards\-curve schemes (\fBed25519\fP, \fBed448\fP). Defaults to 2048 for RSA and 256 for EC. .TP .B passphrase If this is specified, the private key will be encrypted using this passphrase. The encryption algorithm cannot be selected, it will be determined automatically as the best available one. .TP .B encoding Specify the encoding of the resulting private key. It can be returned as a \fBpem\fP string, base64\-encoded \fBder\fP or base64\-encoded \fBpkcs12\fP\&. Defaults to \fBpem\fP\&. .TP .B pkcs12_encryption_compat Some operating systems are incompatible with the encryption defaults for PKCS12 used since OpenSSL v3. This switch triggers a fallback to \fBPBESv1SHA1And3KeyTripleDESCBC\fP\&. Please consider the \fI\%notes on PKCS12 encryption\fP\&. .TP .B path Instead of returning the private key, write it to this file path. Note that this does not use safe permissions and should be avoided. .TP .B raw Return the encoded raw bytes instead of a string. Defaults to false. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.encode_certificate(certificate, encoding=\(aqpem\(aq, append_certs=None, private_key=None, private_key_passphrase=None, pkcs12_passphrase=None, pkcs12_encryption_compat=False, pkcs12_friendlyname=None, raw=False) Create an encoded representation of a certificate, optionally including other structures. This can be used to create certificate chains, convert a certificate into a different encoding or embed the corresponding private key (for \fBpkcs12\fP). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.encode_certificate /etc/pki/my.crt pem /etc/pki/ca.crt .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B certificate The certificate to encode. .TP .B encoding Specify the encoding of the resulting certificate. It can be returned as a \fBpem\fP (or \fBpkcs7_pem\fP) string or several (base64\-encoded) binary formats (\fBder\fP, \fBpkcs7_der\fP, \fBpkcs12\fP). Defaults to \fBpem\fP\&. .TP .B append_certs A list of additional certificates to encode with the new one, e.g. to create a CA chain. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Mind that when \fBder\fP encoding is in use, appending certificatees is prohibited. .UNINDENT .UNINDENT .TP .B private_key For \fBpkcs12\fP, the private key corresponding to the public key of the \fBcertificate\fP to be embedded. .TP .B private_key_passphrase For \fBpkcs12\fP, if the private key to embed is encrypted, specify the corresponding passphrase. .TP .B pkcs12_passphrase For \fBpkcs12\fP, the container can be encrypted. Specify the passphrase to use here. Mind that PKCS12 encryption should not be relied on for security purposes, see note above in \fI\%x509.create_certificate\fP\&. .TP .B pkcs12_encryption_compat OpenSSL 3 and cryptography v37 switched to a much more secure default encryption for PKCS12, which might be incompatible with some systems. This forces the legacy encryption. Defaults to False. .TP .B pkcs12_friendlyname When encoding a certificate as \fBpkcs12\fP, a name for the certificate can be included. .TP .B raw Return the encoded raw bytes instead of a string. Defaults to false. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.encode_crl(crl, encoding=\(aqpem\(aq, raw=False) Create an encoded representation of a certificate revocation list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.encode_crl /etc/pki/my.crl der .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B crl The certificate revocation list to encode. .TP .B encoding Specify the encoding of the resulting certificate revocation list. It can be returned as a \fBpem\fP string or base64\-encoded \fBder\fP\&. Defaults to \fBpem\fP\&. .TP .B raw Return the encoded raw bytes instead of a string. Defaults to false. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.encode_csr(csr, encoding=\(aqpem\(aq, raw=False) Create an encoded representation of a certificate signing request. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.encode_csr /etc/pki/my.csr der .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B csr The certificate signing request to encode. .TP .B encoding Specify the encoding of the resulting certificate signing request. It can be returned as a \fBpem\fP string or base64\-encoded \fBder\fP\&. Defaults to \fBpem\fP\&. .TP .B raw Return the encoded raw bytes instead of a string. Defaults to false. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.encode_private_key(private_key, encoding=\(aqpem\(aq, passphrase=None, private_key_passphrase=None, pkcs12_encryption_compat=False, raw=False) Create an encoded representation of a private key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.encode_private_key /etc/pki/my.key der .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B private_key The private key to encode. .TP .B encoding Specify the encoding of the resulting private key. It can be returned as a \fBpem\fP string, base64\-encoded \fBder\fP and base64\-encoded \fBpkcs12\fP\&. Defaults to \fBpem\fP\&. .TP .B passphrase If this is specified, the private key will be encrypted using this passphrase. The encryption algorithm cannot be selected, it will be determined automatically as the best available one. .TP .B private_key_passphrase New in version 3006.2. .sp If the current \fBprivate_key\fP is encrypted, the passphrase to decrypt it. .TP .B pkcs12_encryption_compat Some operating systems are incompatible with the encryption defaults for PKCS12 used since OpenSSL v3. This switch triggers a fallback to \fBPBESv1SHA1And3KeyTripleDESCBC\fP\&. Please consider the \fI\%notes on PKCS12 encryption\fP\&. .TP .B raw Return the encoded raw bytes instead of a string. Defaults to false. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.expired(certificate) Returns a dict containing limited details of a certificate and whether the certificate has expired. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.expired /etc/pki/mycert.crt .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B certificate The certificate to check. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.expires(certificate, days=0) Determine whether a certificate will expire or has expired already. Returns a boolean only. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.expires /etc/pki/my.crt days=7 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B certificate The certificate to check. .TP .B days If specified, determine expiration x days in the future. Defaults to \fB0\fP, which checks for the current time. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.get_pem_entries(glob_path) Returns a dict containing PEM entries in files matching a glob. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.get_pem_entries \(dq/etc/pki/*.crt\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B glob_path A path representing certificates to be read and returned. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.get_pem_entry(text, pem_type=None) Returns a properly formatted PEM string from the input text, fixing any whitespace or line\-break issues. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.get_pem_entry \(dq\-\-\-\-\-BEGIN CERTIFICATE REQUEST\-\-\-\-\-MIICyzCC Ar8CAQI...\-\-\-\-\-END CERTIFICATE REQUEST\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B text Text containing the X509 PEM entry to be returned or path to a file containing the text. .TP .B pem_type If specified, this function will only return a pem of a certain type, for example \(aqCERTIFICATE\(aq or \(aqCERTIFICATE REQUEST\(aq. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.get_private_key_size(private_key, passphrase=None) Return information about the keysize of a private key (RSA/EC). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.get_private_key_size /etc/pki/my.key .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B private_key The private key to check. .TP .B passphrase If \fBprivate_key\fP is encrypted, the passphrase to decrypt it. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.get_public_key(key, passphrase=None, asObj=None) Returns a PEM\-encoded public key derived from some reference. The reference should be a public key, certificate, private key or CSR. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.get_public_key /etc/pki/my.key .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B key A reference to the structure to look the public key up for. .TP .B passphrase If \fBkey\fP is encrypted, the passphrase to decrypt it. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.get_signing_policy(signing_policy, ca_server=None) Returns the specified named signing policy. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.get_signing_policy www .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B signing_policy The name of the signing policy to return. .TP .B ca_server If this is set, the CA server will be queried for the signing policy instead of looking it up locally. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.read_certificate(certificate) Returns a dict containing details of a certificate. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.read_certificate /etc/pki/mycert.crt .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B certificate The certificate to read. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.read_certificates(glob_path) Returns a dict containing details of all certificates matching a glob. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.read_certificates \(dq/etc/pki/*.crt\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B glob_path A path to certificates to be read and returned. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.read_crl(crl) Returns a dict containing details of a certificate revocation list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.read_crl /etc/pki/my.crl .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B crl The certificate revocation list to read. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.read_csr(csr) Returns a dict containing details of a certificate signing request. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.read_csr /etc/pki/mycert.csr .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B csr The certificate signing request to read. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.sign_remote_certificate(signing_policy, kwargs, get_signing_policy_only=False, **more_kwargs) Request a certificate to be remotely signed according to a signing policy. This is mostly for internal use and does not make much sense on the CLI. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.sign_remote_certificate www kwargs=\(dq{\(aqpublic_key\(aq: \(aq/etc/pki/www.key\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B signing_policy The name of the signing policy to use. Required. .TP .B kwargs A dict containing all the arguments to be passed into the \fI\%x509.create_certificate\fP function. .TP .B get_signing_policy_only Only return the named signing policy. Defaults to false. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.verify_crl(crl, cert) Verify that a signature on a certificate revocation list was made by the private key corresponding to the public key associated with the specified certificate. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.verify_crl /etc/pki/my.crl /etc/pki/my.crt .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B crl The certificate revocation list to check the signature on. .TP .B cert The certificate (or any reference that can be passed to \fBget_public_key\fP) to retrieve the public key from. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.verify_private_key(private_key, public_key, passphrase=None) Verify that a private key belongs to the specified public key. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.verify_private_key /etc/pki/my.key /etc/pki/my.crt .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B private_key The private key to check. .TP .B public_key The certificate (or any reference that can be passed to \fBget_public_key\fP) to retrieve the public key from. .TP .B passphrase If \fBprivate_key\fP is encrypted, the passphrase to decrypt it. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.verify_signature(certificate, signing_pub_key=None, signing_pub_key_passphrase=None) Verify that a signature on a certificate was made by the private key corresponding to the public key associated with the specified certificate. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.verify_signature /etc/pki/my.key /etc/pki/my.crt .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B certificate The certificate to check the signature on. .TP .B signing_pub_key Any reference that can be passed to \fBget_public_key\fP to retrieve the public key of the signing entity from. If unspecified, will take the public key of \fBcertificate\fP, i.e. verify a self\-signed certificate. .UNINDENT .sp signing_pub_key_passphrase .INDENT 7.0 .INDENT 3.5 If \fBsigning_pub_key\fP is encrypted, the passphrase to decrypt it. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.will_expire(certificate, days) Returns a dict containing details of a certificate and whether the certificate will expire in the specified number of days. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.will_expire \(dq/etc/pki/mycert.crt\(dq days=30 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B certificate The certificate to check. .TP .B days The number of days in the future to check the validity for. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.x509_v2.write_pem(text, path, overwrite=True, pem_type=None) Writes out a PEM string, fixing any formatting or whitespace issues before writing. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq x509.write_pem \(dq\-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\-MIIGMzCCBBugA...\(dq path=/etc/pki/mycert.crt .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B text PEM string input to be written out. .TP .B path Path of the file to write the PEM out to. .TP .B overwrite If \fBTrue\fP (default), write_pem will overwrite the entire PEM file. Set to \fBFalse\fP to preserve existing private keys and DH params that may exist in the PEM file. .TP .B pem_type The PEM type to be saved, for example \fBCERTIFICATE\fP or \fBPUBLIC KEY\fP\&. Adding this will allow the function to take input that may contain multiple PEM types. .UNINDENT .UNINDENT .SS salt.modules.xapi_virt .sp This module (mostly) uses the XenAPI to manage Xen virtual machines. .sp Big fat warning: the XenAPI used in this file is the one bundled with Xen Source, NOT XenServer nor Xen Cloud Platform. As a matter of fact it \fIwill\fP fail under those platforms. From what I\(aqve read, little work is needed to adapt this code to XS/XCP, mostly playing with XenAPI version, but as XCP is not taking precedence on Xen Source on many platforms, please keep compatibility in mind. .sp Useful documentation: .sp \&. \fI\%http://downloads.xen.org/Wiki/XenAPI/xenapi\-1.0.6.pdf\fP \&. \fI\%http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/\fP \&. \fI\%https://github.com/xapi\-project/xen\-api/tree/master/scripts/examples/python\fP \&. \fI\%http://xenbits.xen.org/gitweb/?p=xen.git;a=tree;f=tools/python/xen/xm;hb=HEAD\fP .INDENT 0.0 .TP .B salt.modules.xapi_virt.freecpu() Return an int representing the number of unallocated cpus on this hypervisor .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.freecpu .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.freemem() Return an int representing the amount of memory that has not been given to virtual machines on this node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.freemem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.full_info() Return the node_info, vm_info and freemem .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.full_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.get_disks(vm_) Return the disks of a named vm .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.get_disks <vm name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.get_macs(vm_) Return a list off MAC addresses from the named vm .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.get_macs <vm name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.get_nics(vm_) Return info about the network interfaces of a named vm .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.get_nics <vm name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.is_hyper() Returns a bool whether or not this node is a hypervisor of any kind .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.is_hyper .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.list_domains() Return a list of virtual machine names on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.list_domains .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.migrate(vm_, target, live=1, port=0, node=\-1, ssl=None, change_home_server=0) Migrates the virtual machine to another hypervisor .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.migrate <vm name> <target hypervisor> [live] [port] [node] [ssl] [change_home_server] .ft P .fi .UNINDENT .UNINDENT .sp Optional values: .INDENT 7.0 .TP .B live Use live migration .TP .B port Use a specified port .TP .B node Use specified NUMA node on target .TP .B ssl use ssl connection for migration .TP .B change_home_server change home server for managed domains .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.node_info() Return a dict with information about this node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.node_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.pause(vm_) Pause the named vm .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.pause <vm name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.reboot(vm_) Reboot a domain via ACPI request .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.reboot <vm name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.reset(vm_) Reset a VM by emulating the reset button on a physical machine .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.reset <vm name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.resume(vm_) Resume the named vm .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.resume <vm name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.setmem(vm_, memory) Changes the amount of memory allocated to VM. .sp Memory is to be specified in MB .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.setmem myvm 768 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.setvcpus(vm_, vcpus) Changes the amount of vcpus allocated to VM. .sp vcpus is an int representing the number to be assigned .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.setvcpus myvm 2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.shutdown(vm_) Send a soft shutdown signal to the named vm .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.shutdown <vm name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.start(config_) Start a defined domain .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.start <path to Xen cfg file> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.stop(vm_) Hard power down the virtual machine, this is equivalent to pulling the power .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.stop <vm name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.vcpu_pin(vm_, vcpu, cpus) Set which CPUs a VCPU can use. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqfoo\(aq virt.vcpu_pin domU\-id 2 1 salt \(aqfoo\(aq virt.vcpu_pin domU\-id 2 2\-6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.vm_cputime(vm_=None) Return cputime used by the vms on this hyper in a list of dicts: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ \(aqyour\-vm\(aq: { \(aqcputime\(aq <int> \(aqcputime_percent\(aq <int> }, ... ] .ft P .fi .UNINDENT .UNINDENT .sp If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.vm_cputime .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.vm_diskstats(vm_=None) Return disk usage counters used by the vms on this hyper in a list of dicts: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ \(aqyour\-vm\(aq: { \(aqio_read_kbs\(aq : 0, \(aqio_write_kbs\(aq : 0 }, ... ] .ft P .fi .UNINDENT .UNINDENT .sp If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.vm_diskstats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.vm_info(vm_=None) Return detailed information about the vms. .sp If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.vm_info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.vm_netstats(vm_=None) Return combined network counters used by the vms on this hyper in a list of dicts: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ \(aqyour\-vm\(aq: { \(aqio_read_kbs\(aq : 0, \(aqio_total_read_kbs\(aq : 0, \(aqio_total_write_kbs\(aq : 0, \(aqio_write_kbs\(aq : 0 }, ... ] .ft P .fi .UNINDENT .UNINDENT .sp If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.vm_netstats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xapi_virt.vm_state(vm_=None) Return list of all the vms and their state. .sp If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq virt.vm_state <vm name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.xbpspkg .sp Package support for XBPS package manager (used by VoidLinux) .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.modules.xbpspkg.add_repo(repo, conffile=\(aq/usr/share/xbps.d/15\-saltstack.conf\(aq) Add an XBPS repository to the system. .INDENT 7.0 .TP .B repo url of repo to add (persistent). .TP .B conffile path to xbps conf file to add this repo default: /usr/share/xbps.d/15\-saltstack.conf .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.add_repo <repo url> [conffile=/path/to/xbps/repo.conf] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xbpspkg.available_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 <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xbpspkg.del_repo(repo, **kwargs) Remove an XBPS repository from the system. .INDENT 7.0 .TP .B repo url of repo to remove (persistent). .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.del_repo <repo url> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xbpspkg.get_repo(repo, **kwargs) Display information about the repo. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.get_repo \(aqrepo\-url\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xbpspkg.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs) Install the passed package .INDENT 7.0 .TP .B name The name of the package to be installed. .TP .B refresh Whether or not to refresh the package database before installing. .TP .B fromrepo Specify a package repository (url) to install from. .UNINDENT .sp Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of packages to install from a software repository. Must be passed as a python list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq,\(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B sources A list of packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sources=\(aq[{\(dqfoo\(dq: \(dqsalt://foo.deb\(dq},{\(dqbar\(dq: \(dqsalt://bar.deb\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Return a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xbpspkg.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 <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xbpspkg.list_pkgs(versions_as_list=False, **kwargs) List the packages currently installed as a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(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.xbpspkg.list_repos(**kwargs) List all repos known by XBPS .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_repos .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xbpspkg.list_upgrades(refresh=True, **kwargs) Check whether or not an upgrade is available for all packages .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xbpspkg.refresh_db(**kwargs) Update list of available packages from installed repos .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.xbpspkg.remove(name=None, pkgs=None, recursive=True, **kwargs) .INDENT 7.0 .TP .B name The name of the package to be deleted. .TP .B recursive Also remove dependent packages (not required elsewhere). Default mode: enabled. .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 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 <package name> [recursive=False] salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> [recursive=False] salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq [recursive=False] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xbpspkg.upgrade(refresh=True, **kwargs) Run a full system upgrade .INDENT 7.0 .TP .B refresh Whether or not to refresh the package database before installing. Default is \fITrue\fP\&. .UNINDENT .sp Returns a dictionary containing the changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xbpspkg.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 <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xbpspkg.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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.xfs .sp Module for managing XFS file systems. .INDENT 0.0 .TP .B salt.modules.xfs.defragment(device) Defragment mounted XFS filesystem. In order to mount a filesystem, device should be properly mounted and writable. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xfs.defragment /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xfs.devices() Get known XFS formatted devices on the system. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xfs.devices .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xfs.dump(device, destination, level=0, label=None, noerase=None) Dump filesystem device to the media (file, tape etc). .sp Required parameters: .INDENT 7.0 .IP \(bu 2 \fBdevice\fP: XFS device, content of which to be dumped. .IP \(bu 2 \fBdestination\fP: Specifies a dump destination. .UNINDENT .sp Valid options are: .INDENT 7.0 .IP \(bu 2 \fBlabel\fP: Label of the dump. Otherwise automatically generated label is used. .IP \(bu 2 \fBlevel\fP: Specifies a dump level of 0 to 9. .IP \(bu 2 \fBnoerase\fP: Pre\-erase media. .UNINDENT .sp Other options are not used in order to let \fBxfsdump\fP use its default values, as they are most optimal. See the \fBxfsdump(8)\fP manpage for a more complete description of these options. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xfs.dump /dev/sda1 /detination/on/the/client salt \(aq*\(aq xfs.dump /dev/sda1 /detination/on/the/client label=\(aqCompany accountancy\(aq salt \(aq*\(aq xfs.dump /dev/sda1 /detination/on/the/client noerase=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xfs.estimate(path) Estimate the space that an XFS filesystem will take. For each directory estimate the space that directory would take if it were copied to an XFS filesystem. Estimation does not cross mount points. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xfs.estimate /path/to/file salt \(aq*\(aq xfs.estimate /path/to/dir/* .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xfs.info(device) Get filesystem geometry information. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xfs.info /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xfs.inventory() Display XFS dump inventory without restoration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xfs.inventory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xfs.mkfs(device, label=None, ssize=None, noforce=None, bso=None, gmo=None, ino=None, lso=None, rso=None, nmo=None, dso=None) Create a file system on the specified device. By default wipes out with force. .sp General options: .INDENT 7.0 .IP \(bu 2 \fBlabel\fP: Specify volume label. .IP \(bu 2 \fBssize\fP: Specify the fundamental sector size of the filesystem. .IP \(bu 2 \fBnoforce\fP: Do not force create filesystem, if disk is already formatted. .UNINDENT .sp Filesystem geometry options: .INDENT 7.0 .IP \(bu 2 \fBbso\fP: Block size options. .IP \(bu 2 \fBgmo\fP: Global metadata options. .IP \(bu 2 .INDENT 2.0 .TP \fBdso\fP: Data section options. These options specify the location, size, and other parameters of the data section of the filesystem. .UNINDENT .IP \(bu 2 \fBino\fP: Inode options to specify the inode size of the filesystem, and other inode allocation parameters. .IP \(bu 2 \fBlso\fP: Log section options. .IP \(bu 2 \fBnmo\fP: Naming options. .IP \(bu 2 \fBrso\fP: Realtime section options. .UNINDENT .sp See the \fBmkfs.xfs(8)\fP manpage for a more complete description of corresponding options description. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xfs.mkfs /dev/sda1 salt \(aq*\(aq xfs.mkfs /dev/sda1 dso=\(aqsu=32k,sw=6\(aq noforce=True salt \(aq*\(aq xfs.mkfs /dev/sda1 dso=\(aqsu=32k,sw=6\(aq lso=\(aqlogdev=/dev/sda2,size=10000b\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xfs.modify(device, label=None, lazy_counting=None, uuid=None) Modify parameters of an XFS filesystem. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xfs.modify /dev/sda1 label=\(aqMy backup\(aq lazy_counting=False salt \(aq*\(aq xfs.modify /dev/sda1 uuid=False salt \(aq*\(aq xfs.modify /dev/sda1 uuid=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xfs.prune_dump(sessionid) Prunes the dump session identified by the given session id. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xfs.prune_dump b74a3586\-e52e\-4a4a\-8775\-c3334fa8ea2c .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.xml .sp XML file manager .sp New in version 3000. .INDENT 0.0 .TP .B salt.modules.xml.get_attribute(file, element) Return the attributes of the matched xpath element. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xml.get_attribute /tmp/test.xml \(dq.//element[@id=\(aq3\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xml.get_value(file, element) Returns the value of the matched xpath element .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xml.get_value /tmp/test.xml \(dq.//element\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xml.set_attribute(file, element, key, value) Set the requested attribute key and value for matched xpath element. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xml.set_attribute /tmp/test.xml \(dq.//element[@id=\(aq3\(aq]\(dq editedby \(dqgal\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xml.set_value(file, element, value) Sets the value of the matched xpath element .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq xml.set_value /tmp/test.xml \(dq.//element\(dq \(dqnew value\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.xmpp .sp Module for Sending Messages via XMPP (a.k.a. Jabber) .sp New in version 2014.1.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 sleekxmpp>=1.3.1 .IP \(bu 2 pyasn1 .IP \(bu 2 pyasn1\-modules .IP \(bu 2 dnspython .UNINDENT .TP .B configuration This module can be used by either passing a jid and password directly to send_message, or by specifying the name of a configuration profile in the minion config, minion pillar, or master config. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my\-xmpp\-login: xmpp.jid: myuser@jabber.example.org/resourcename xmpp.password: verybadpass .ft P .fi .UNINDENT .UNINDENT .sp The resourcename refers to the resource that is using this account. It is user\-definable, and optional. The following configurations are both valid: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my\-xmpp\-login: xmpp.jid: myuser@jabber.example.org/salt xmpp.password: verybadpass my\-xmpp\-login: xmpp.jid: myuser@jabber.example.org xmpp.password: verybadpass .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.xmpp.SendMsgBot(jid, password, recipient, msg) .INDENT 7.0 .TP .B classmethod create_multi(jid, password, msg, recipients=None, rooms=None, nick=\(aqSaltStack Bot\(aq) Alternate constructor that accept multiple recipients and rooms .UNINDENT .INDENT 7.0 .TP .B start(event) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.xmpp.SleekXMPPMUC(name=\(aq\(aq) .INDENT 7.0 .TP .B filter(record) Determine if the specified record is to be logged. .sp Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in\-place. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xmpp.send_msg(recipient, message, jid=None, password=None, profile=None) Send a message to an XMPP recipient. Designed for use in states. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C xmpp.send_msg \(aqadmins@xmpp.example.com\(aq \(aqThis is a salt module test\(aq profile=\(aqmy\-xmpp\-account\(aq xmpp.send_msg \(aqadmins@xmpp.example.com\(aq \(aqThis is a salt module test\(aq jid=\(aqmyuser@xmpp.example.com/salt\(aq password=\(aqverybadpass\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.xmpp.send_msg_multi(message, recipients=None, rooms=None, jid=None, password=None, nick=\(aqSaltStack Bot\(aq, profile=None) Send a message to an XMPP recipient, support send message to multiple recipients or chat room. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C xmpp.send_msg recipients=[\(aqadmins@xmpp.example.com\(aq] rooms=[\(aqsecret@conference.xmpp.example.com\(aq] \(aqThis is a salt module test\(aq profile=\(aqmy\-xmpp\-account\(aq xmpp.send_msg recipients=[\(aqadmins@xmpp.example.com\(aq] rooms=[\(aqsecret@conference.xmpp.example.com\(aq] \(aqThis is a salt module test\(aq jid=\(aqmyuser@xmpp.example.com/salt\(aq password=\(aqverybadpass\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.yaml .sp Yaml helper module for troubleshooting yaml .sp New in version 3005. .INDENT 0.0 .TP .B depends yamllint >= 1.20.0 .UNINDENT .INDENT 0.0 .TP .B salt.modules.yaml.lint(source, saltenv=None, pre_render=None, **kwargs) lint the output after detecting a sucsessful render. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- managed source file .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- the saltenv to use, defaults to minions enviroment or base if not set .IP \(bu 2 \fBpre_render\fP (\fI\%str\fP) \-\- The render options passed to slsutil.renderer other wise file is cached and loaded as stream .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq yaml.lint salt://example/bad_yaml.sls .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.yumpkg .sp Support for YUM/DNF .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 DNF is fully supported as of version 2015.5.10 and 2015.8.4 (partial support for DNF was initially added in 2015.8.0), and DNF is used automatically in place of YUM in Fedora 22 and newer. .UNINDENT .UNINDENT .sp New in version 3003: Support for \fBtdnf\fP on Photon OS. .sp New in version 3007.0: Support for \fBdnf5\(ga\fP on Fedora 39 .INDENT 0.0 .TP .B class salt.modules.yumpkg.AvailablePackages(*args, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.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, and the \fBdisableexcludes\fP option is also supported. .sp New in version 2014.7.0: Support for the \fBdisableexcludes\fP option .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package name> fromrepo=epel\-testing salt \(aq*\(aq pkg.latest_version <package name> disableexcludes=main salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.clean_metadata(**kwargs) New in version 2014.1.0. .sp Cleans local yum metadata. Functionally identical to \fI\%refresh_db()\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.clean_metadata .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.del_repo(repo, basedir=None, **kwargs) Delete a repo from <basedir> (default basedir: all dirs in \fIreposdir\fP yum option). .sp If the .repo file in which the repo exists does not contain any other repo configuration, the file itself will be deleted. .sp Strict parsing of configuration files is the default, this can be disabled using the \fBstrict_config\fP keyword argument set to False .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.del_repo myrepo salt \(aq*\(aq pkg.del_repo myrepo basedir=/path/to/dir strict_config=False salt \(aq*\(aq pkg.del_repo myrepo basedir=/path/to/dir,/path/to/another/dir .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.diff(*paths, **kwargs) Return a formatted diff between current files and original in a package. NOTE: this function includes all files (configuration and not), but does not work on binary content. .INDENT 7.0 .TP .B Parameters \fBpath\fP \-\- Full path to the installed file .TP .B Returns Difference string or raises and exception if examined file is binary. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.diff /etc/apache2/httpd.conf /etc/sudoers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.download(*packages, **kwargs) New in version 2015.5.0. .sp Download packages to the local disk. Requires \fByumdownloader\fP from \fByum\-utils\fP package. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fByum\-utils\fP will already be installed on the minion if the package was installed from the Fedora / EPEL repositories. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.download httpd salt \(aq*\(aq pkg.download httpd postfix .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.file_dict(*packages, **kwargs) New in version 2014.1.0. .sp List the files that belong to a package, grouped by package. Not specifying any packages will return a list of \fIevery\fP file on the system\(aqs rpm 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.yumpkg.file_list(*packages, **kwargs) New in version 2014.1.0. .sp List the files that belong to a package. Not specifying any packages will return a list of \fIevery\fP file on the system\(aqs rpm 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.yumpkg.get_locked_packages(pattern=\(aq[\e\ew+]+(?:[.\-][^\-]+)*\(aq, full=True) This function is an alias of \fBlist_holds\fP\&. .INDENT 7.0 .INDENT 3.5 Changed in version 2015.5.10,2015.8.4,2016.3.0: Function renamed from \fBpkg.get_locked_pkgs\fP to \fBpkg.list_holds\fP\&. .sp List information on locked packages .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Requires the appropriate \fBversionlock\fP plugin package to be installed: .INDENT 0.0 .IP \(bu 2 On RHEL 5: \fByum\-versionlock\fP .IP \(bu 2 On RHEL 6 & 7: \fByum\-plugin\-versionlock\fP .IP \(bu 2 On Fedora: \fBpython\-dnf\-plugins\-extras\-versionlock\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B pattern w+(?:[.\-][^\-]+)* Regular expression used to match the package name .TP .B full True Show the full hold definition including version and epoch. Set to \fBFalse\fP to return just the name of the package(s) being held. .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_holds salt \(aq*\(aq pkg.list_holds full=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.get_repo(repo, basedir=None, **kwargs) Display a repo from <basedir> (default basedir: all dirs in \fBreposdir\fP yum option). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.get_repo myrepo salt \(aq*\(aq pkg.get_repo myrepo basedir=/path/to/dir salt \(aq*\(aq pkg.get_repo myrepo basedir=/path/to/dir,/path/to/another/dir .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.group_diff(name, **kwargs) New in version 2014.1.0. .sp Changed in version 2015.5.10,2015.8.4,2016.3.0: Environment groups are now supported. The key names have been renamed, similar to the changes made in \fI\%pkg.group_info\fP\&. .sp Changed in version 3006.2: Support for \fBfromrepo\fP, \fBenablerepo\fP, and \fBdisablerepo\fP (as used in \fI\%pkg.install\fP) has been added. .sp Lists which of a group\(aqs packages are installed and which are not installed .INDENT 7.0 .TP .B name The name of the group to check .TP .B fromrepo Restrict \fByum groupinfo\fP to the specified repo(s). (e.g., \fByum \-\-disablerepo=\(aq*\(aq \-\-enablerepo=\(aqsomerepo\(aq\fP) .sp New in version 3006.2. .TP .B enablerepo (ignored if \fBfromrepo\fP is specified) Specify a disabled package repository (or repositories) to enable. (e.g., \fByum \-\-enablerepo=\(aqsomerepo\(aq\fP) .sp New in version 3006.2. .TP .B disablerepo (ignored if \fBfromrepo\fP is specified) Specify an enabled package repository (or repositories) to disable. (e.g., \fByum \-\-disablerepo=\(aqsomerepo\(aq\fP) .sp New in version 3006.2. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.group_diff \(aqPerl Support\(aq salt \(aq*\(aq pkg.group_diff \(aqPerl Support\(aq fromrepo=base,updates salt \(aq*\(aq pkg.group_diff \(aqPerl Support\(aq enablerepo=somerepo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.group_info(name, expand=False, ignore_groups=None, **kwargs) New in version 2014.1.0. .sp Changed in version 2015.5.10,2015.8.4,2016.3.0,3001: The return data has changed. A new key \fBtype\fP has been added to distinguish environment groups from package groups. Also, keys for the group name and group ID have been added. The \fBmandatory packages\fP, \fBoptional packages\fP, and \fBdefault packages\fP keys have been renamed to \fBmandatory\fP, \fBoptional\fP, and \fBdefault\fP for accuracy, as environment groups include other groups, and not packages. Finally, this function now properly identifies conditional packages. .sp Changed in version 3006.2: Support for \fBfromrepo\fP, \fBenablerepo\fP, and \fBdisablerepo\fP (as used in \fI\%pkg.install\fP) has been added. .sp Lists packages belonging to a certain group .INDENT 7.0 .TP .B name Name of the group to query .TP .B expand False If the specified group is an environment group, then the group will be expanded and the return data will include package names instead of group names. .sp New in version 2016.3.0. .TP .B ignore_groups None This parameter can be used to pass a list of groups to ignore when expanding subgroups. It is used during recursion in order to prevent expanding the same group multiple times. .sp New in version 3001. .TP .B fromrepo Restrict \fByum groupinfo\fP to the specified repo(s). (e.g., \fByum \-\-disablerepo=\(aq*\(aq \-\-enablerepo=\(aqsomerepo\(aq\fP) .sp New in version 3006.2. .TP .B enablerepo (ignored if \fBfromrepo\fP is specified) Specify a disabled package repository (or repositories) to enable. (e.g., \fByum \-\-enablerepo=\(aqsomerepo\(aq\fP) .sp New in version 3006.2. .TP .B disablerepo (ignored if \fBfromrepo\fP is specified) Specify an enabled package repository (or repositories) to disable. (e.g., \fByum \-\-disablerepo=\(aqsomerepo\(aq\fP) .sp New in version 3006.2. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.group_info \(aqPerl Support\(aq salt \(aq*\(aq pkg.group_info \(aqPerl Support\(aq fromrepo=base,updates salt \(aq*\(aq pkg.group_info \(aqPerl Support\(aq enablerepo=somerepo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.group_install(name, skip=(), include=(), **kwargs) New in version 2014.1.0. .sp Install the passed package group(s). This is basically a wrapper around \fI\%pkg.install\fP, which performs package group resolution for the user. This function is currently considered experimental, and should be expected to undergo changes. .INDENT 7.0 .TP .B name Package group to install. To install more than one group, either use a comma\-separated list or pass the value as a python list. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.group_install \(aqGroup 1\(aq salt \(aq*\(aq pkg.group_install \(aqGroup 1,Group 2\(aq salt \(aq*\(aq pkg.group_install \(aq[\(dqGroup 1\(dq, \(dqGroup 2\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B skip Packages that would normally be installed by the package group (\(dqdefault\(dq packages), which should not be installed. Can be passed either as a comma\-separated list or a python list. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.group_install \(aqMy Group\(aq skip=\(aqfoo,bar\(aq salt \(aq*\(aq pkg.group_install \(aqMy Group\(aq skip=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B include Packages which are included in a group, which would not normally be installed by a \fByum groupinstall\fP (\(dqoptional\(dq packages). Note that this will not enforce group membership; if you include packages which are not members of the specified groups, they will still be installed. Can be passed either as a comma\-separated list or a python list. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.group_install \(aqMy Group\(aq include=\(aqfoo,bar\(aq salt \(aq*\(aq pkg.group_install \(aqMy Group\(aq include=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Because this is essentially a wrapper around pkg.install, any argument which can be passed to pkg.install may also be included here, and it will be passed along wholesale. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.group_list() New in version 2014.1.0. .sp Lists all groups known by yum on this system .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.group_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.groupinstall(name, skip=(), include=(), **kwargs) This function is an alias of \fBgroup_install\fP\&. .INDENT 7.0 .INDENT 3.5 New in version 2014.1.0. .sp Install the passed package group(s). This is basically a wrapper around \fI\%pkg.install\fP, which performs package group resolution for the user. This function is currently considered experimental, and should be expected to undergo changes. .INDENT 0.0 .TP .B name Package group to install. To install more than one group, either use a comma\-separated list or pass the value as a python list. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.group_install \(aqGroup 1\(aq salt \(aq*\(aq pkg.group_install \(aqGroup 1,Group 2\(aq salt \(aq*\(aq pkg.group_install \(aq[\(dqGroup 1\(dq, \(dqGroup 2\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B skip Packages that would normally be installed by the package group (\(dqdefault\(dq packages), which should not be installed. Can be passed either as a comma\-separated list or a python list. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.group_install \(aqMy Group\(aq skip=\(aqfoo,bar\(aq salt \(aq*\(aq pkg.group_install \(aqMy Group\(aq skip=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B include Packages which are included in a group, which would not normally be installed by a \fByum groupinstall\fP (\(dqoptional\(dq packages). Note that this will not enforce group membership; if you include packages which are not members of the specified groups, they will still be installed. Can be passed either as a comma\-separated list or a python list. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.group_install \(aqMy Group\(aq include=\(aqfoo,bar\(aq salt \(aq*\(aq pkg.group_install \(aqMy Group\(aq include=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Because this is essentially a wrapper around pkg.install, any argument which can be passed to pkg.install may also be included here, and it will be passed along wholesale. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.hold(name=None, pkgs=None, sources=None, normalize=True, **kwargs) New in version 2014.7.0. .sp Version\-lock packages .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Requires the appropriate \fBversionlock\fP plugin package to be installed: .INDENT 0.0 .IP \(bu 2 On RHEL 5: \fByum\-versionlock\fP .IP \(bu 2 On RHEL 6 & 7: \fByum\-plugin\-versionlock\fP .IP \(bu 2 On Fedora: \fBpython\-dnf\-plugins\-extras\-versionlock\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the package to be held. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to hold. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .UNINDENT .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.hold <package name> salt \(aq*\(aq pkg.hold pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.info_installed(*names, **kwargs) New in version 2015.8.1. .sp Return the information of the named package(s), installed on the system. .INDENT 7.0 .TP .B Parameters \fBall_versions\fP \-\- Include information for all versions of the packages installed on the minion. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.info_installed <package1> salt \(aq*\(aq pkg.info_installed <package1> <package2> <package3> ... salt \(aq*\(aq pkg.info_installed <package1> <package2> <package3> all_versions=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.install(name=None, refresh=False, skip_verify=False, pkgs=None, sources=None, downloadonly=False, reinstall=False, normalize=True, update_holds=False, saltenv=\(aqbase\(aq, 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 yum/dnf 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Install the passed package(s), add refresh=True to clean the yum database before package is installed. .INDENT 7.0 .TP .B name The name of the package to be installed. Note that this parameter is ignored if either \(dqpkgs\(dq or \(dqsources\(dq 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 \(dqsources\(dq option. .sp 32\-bit packages can be installed on 64\-bit systems by appending the architecture designation (\fB\&.i686\fP, \fB\&.i586\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 <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B refresh Whether or not to update the yum database before executing. .TP .B reinstall Specifying reinstall=True will use \fByum reinstall\fP rather than \fByum install\fP for requested packages that are already installed. .sp If a version is specified with the requested package, then \fByum reinstall\fP will only be used if the installed version matches the requested version. .sp Works with \fBsources\fP when the package header of the source can be matched to the name and version of an installed package. .sp New in version 2014.7.0. .TP .B skip_verify Skip the GPG verification check (e.g., \fB\-\-nogpgcheck\fP) .TP .B downloadonly Only download the packages, do not install. .TP .B version Install a specific version of the package, e.g. 1.2.3\-4.el5. Ignored if \(dqpkgs\(dq or \(dqsources\(dq 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 update_holds False If \fBTrue\fP, and this function would update the package version, any packages held using the yum/dnf \(dqversionlock\(dq plugin will be unheld so that they can be updated. Otherwise, if this function attempts to update a held package, the held package(s) will be skipped and an error will be raised. .sp New in version 2016.11.0. .TP .B setopt A comma\-separated or Python list of key=value options. This list will be expanded and \fB\-\-setopt\fP prepended to each in the yum/dnf command that is run. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install foo setopt=\(aqobsoletes=0,plugins=0\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2019.2.0. .UNINDENT .sp Repository Options: .INDENT 7.0 .TP .B fromrepo Specify a package repository (or repositories) from which to install. (e.g., \fByum \-\-disablerepo=\(aq*\(aq \-\-enablerepo=\(aqsomerepo\(aq\fP) .TP .B enablerepo (ignored if \fBfromrepo\fP is specified) Specify a disabled package repository (or repositories) to enable. (e.g., \fByum \-\-enablerepo=\(aqsomerepo\(aq\fP) .TP .B disablerepo (ignored if \fBfromrepo\fP is specified) Specify an enabled package repository (or repositories) to disable. (e.g., \fByum \-\-disablerepo=\(aqsomerepo\(aq\fP) .TP .B disableexcludes Disable exclude from main, for a repo or for everything. (e.g., \fByum \-\-disableexcludes=\(aqmain\(aq\fP) .sp New in version 2014.7.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. A specific version number can be specified by using a single\-element dict representing the package and its version. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, {\(dqbar\(dq: \(dq1.2.3\-4.el5\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B sources A list of RPM packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sources=\(aq[{\(dqfoo\(dq: \(dqsalt://foo.rpm\(dq}, {\(dqbar\(dq: \(dqsalt://bar.rpm\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B normalize True Normalize the package name by removing the architecture. This is useful for poorly created packages which might include the architecture as an actual part of the name such as kernel modules which match a specific kernel version. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G role:nsd pkg.install gpfs.gplbin\-2.6.32\-279.31.1.el6.x86_64 normalize=False .ft P .fi .UNINDENT .UNINDENT .sp New in version 2014.7.0. .TP .B split_arch True If set to False it prevents package name normalization more strict way than \fBnormalize\fP set to \fBFalse\fP does. .sp New in version 3006.0. .TP .B diff_attr: If a list of package attributes is specified, returned value will contain them, eg.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: { \(aqold\(aq: { \(aqversion\(aq: \(aq<old\-version>\(aq, \(aqarch\(aq: \(aq<old\-arch>\(aq}, \(aqnew\(aq: { \(aqversion\(aq: \(aq<new\-version>\(aq, \(aqarch\(aq: \(aq<new\-arch>\(aq}}} .ft P .fi .UNINDENT .UNINDENT .sp Valid attributes are: \fBepoch\fP, \fBversion\fP, \fBrelease\fP, \fBarch\fP, \fBinstall_date\fP, \fBinstall_date_time_t\fP\&. .sp If \fBall\fP is specified, all valid attributes will be returned. .sp New in version 2018.3.0. .UNINDENT .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp If an attribute list in diff_attr is specified, the dict will also contain any specified attribute, eg.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: { \(aqold\(aq: { \(aqversion\(aq: \(aq<old\-version>\(aq, \(aqarch\(aq: \(aq<old\-arch>\(aq}, \(aqnew\(aq: { \(aqversion\(aq: \(aq<new\-version>\(aq, \(aqarch\(aq: \(aq<new\-arch>\(aq}}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.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, and the \fBdisableexcludes\fP option is also supported. .sp New in version 2014.7.0: Support for the \fBdisableexcludes\fP option .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package name> fromrepo=epel\-testing salt \(aq*\(aq pkg.latest_version <package name> disableexcludes=main salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.list_downloaded(**kwargs) New in version 2017.7.0. .sp List prefetched packages downloaded by Yum in the local disk. .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.yumpkg.list_holds(pattern=\(aq[\e\ew+]+(?:[.\-][^\-]+)*\(aq, full=True) Changed in version 2015.5.10,2015.8.4,2016.3.0: Function renamed from \fBpkg.get_locked_pkgs\fP to \fBpkg.list_holds\fP\&. .sp List information on locked packages .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Requires the appropriate \fBversionlock\fP plugin package to be installed: .INDENT 0.0 .IP \(bu 2 On RHEL 5: \fByum\-versionlock\fP .IP \(bu 2 On RHEL 6 & 7: \fByum\-plugin\-versionlock\fP .IP \(bu 2 On Fedora: \fBpython\-dnf\-plugins\-extras\-versionlock\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B pattern w+(?:[.\-][^\-]+)* Regular expression used to match the package name .TP .B full True Show the full hold definition including version and epoch. Set to \fBFalse\fP to return just the name of the package(s) being held. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_holds salt \(aq*\(aq pkg.list_holds full=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.list_installed_patches(**kwargs) New in version 2017.7.0. .sp List installed advisory patches on the system. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_installed_patches .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.list_patches(refresh=False, **kwargs) New in version 2017.7.0. .sp List all known advisory patches from available repos. .INDENT 7.0 .TP .B refresh force a refresh if set to True. If set to False (default) it depends on yum if a refresh is executed. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_patches .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.list_pkgs(versions_as_list=False, **kwargs) List the packages currently installed as a dict. By default, the dict contains versions as a comma separated string: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>[,<version>...]\(aq} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B versions_as_list: If set to true, the versions are provided as a list .sp {\(aq<package_name>\(aq: [\(aq<version>\(aq, \(aq<version>\(aq]} .TP .B attr: If a list of package attributes is specified, returned value will contain them in addition to version, eg.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: [{\(aqversion\(aq : \(aqversion\(aq, \(aqarch\(aq : \(aqarch\(aq}]} .ft P .fi .UNINDENT .UNINDENT .sp Valid attributes are: \fBepoch\fP, \fBversion\fP, \fBrelease\fP, \fBarch\fP, \fBinstall_date\fP, \fBinstall_date_time_t\fP\&. .sp If \fBall\fP is specified, all valid attributes will be returned. .INDENT 7.0 .INDENT 3.5 New in version 2018.3.0. .UNINDENT .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 attr=version,arch salt \(aq*\(aq pkg.list_pkgs attr=\(aq[\(dqversion\(dq, \(dqarch\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.list_repo_pkgs(*args, **kwargs) New in version 2014.1.0. .sp Changed in version 2014.7.0: All available versions of each package are now returned. This required a slight modification to the structure of the return dict. The return data shown below reflects the updated return dict structure. Note that packages which are version\-locked using \fI\%pkg.hold\fP will only show the currently\-installed version, as locking a package will make other versions appear unavailable to yum/dnf. .sp Changed in version 2017.7.0: By default, the versions for each package are no longer organized by repository. To get results organized by repository, use \fBbyrepo=True\fP\&. .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. This is recommended as it speeds up the function considerably. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Running this function on RHEL/CentOS 6 and earlier will be more resource\-intensive, as the version of yum that ships with older RHEL/CentOS has no yum subcommand for listing packages from a repository. Thus, a \fByum list installed\fP and \fByum list available\fP are run, which generates a lot of output, which must then be analyzed to determine which package information to include in the return data. .UNINDENT .UNINDENT .sp This function can be helpful in discovering the version or repo to specify in a \fI\%pkg.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. If \fBbyrepo\fP is set to \fBTrue\fP, then the return dictionary will contain repository names at the top level, and each repository will map packages to lists of version numbers. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # With byrepo=False (default) { \(aqbash\(aq: [\(aq4.1.2\-15.el6_5.2\(aq, \(aq4.1.2\-15.el6_5.1\(aq, \(aq4.1.2\-15.el6_4\(aq], \(aqkernel\(aq: [\(aq2.6.32\-431.29.2.el6\(aq, \(aq2.6.32\-431.23.3.el6\(aq, \(aq2.6.32\-431.20.5.el6\(aq, \(aq2.6.32\-431.20.3.el6\(aq, \(aq2.6.32\-431.17.1.el6\(aq, \(aq2.6.32\-431.11.2.el6\(aq, \(aq2.6.32\-431.5.1.el6\(aq, \(aq2.6.32\-431.3.1.el6\(aq, \(aq2.6.32\-431.1.2.0.1.el6\(aq, \(aq2.6.32\-431.el6\(aq] } # With byrepo=True { \(aqbase\(aq: { \(aqbash\(aq: [\(aq4.1.2\-15.el6_4\(aq], \(aqkernel\(aq: [\(aq2.6.32\-431.el6\(aq] }, \(aqupdates\(aq: { \(aqbash\(aq: [\(aq4.1.2\-15.el6_5.2\(aq, \(aq4.1.2\-15.el6_5.1\(aq], \(aqkernel\(aq: [\(aq2.6.32\-431.29.2.el6\(aq, \(aq2.6.32\-431.23.3.el6\(aq, \(aq2.6.32\-431.20.5.el6\(aq, \(aq2.6.32\-431.20.3.el6\(aq, \(aq2.6.32\-431.17.1.el6\(aq, \(aq2.6.32\-431.11.2.el6\(aq, \(aq2.6.32\-431.5.1.el6\(aq, \(aq2.6.32\-431.3.1.el6\(aq, \(aq2.6.32\-431.1.2.0.1.el6\(aq] } } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B fromrepo None Only include results from the specified repo(s). Multiple repos can be specified, comma\-separated. .TP .B enablerepo (ignored if \fBfromrepo\fP is specified) Specify a disabled package repository (or repositories) to enable. (e.g., \fByum \-\-enablerepo=\(aqsomerepo\(aq\fP) .sp New in version 2017.7.0. .TP .B disablerepo (ignored if \fBfromrepo\fP is specified) Specify an enabled package repository (or repositories) to disable. (e.g., \fByum \-\-disablerepo=\(aqsomerepo\(aq\fP) .sp New in version 2017.7.0. .TP .B byrepo False When \fBTrue\fP, the return data for each package will be organized by repository. .sp New in version 2017.7.0. .TP .B cacheonly False When \fBTrue\fP, the repo information will be retrieved from the cached repo metadata. This is equivalent to passing the \fB\-C\fP option to yum/dnf. .sp New in version 2017.7.0. .TP .B setopt A comma\-separated or Python list of key=value options. This list will be expanded and \fB\-\-setopt\fP prepended to each in the yum/dnf command that is run. .sp New in version 2019.2.0. .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 salt \(aq*\(aq pkg.list_repo_pkgs \(aqsamba4*\(aq fromrepo=base,updates salt \(aq*\(aq pkg.list_repo_pkgs \(aqpython2\-*\(aq byrepo=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.list_repos(basedir=None, **kwargs) Lists all repos in <basedir> (default: all dirs in \fIreposdir\fP yum option). .sp Strict parsing of configuration files is the default, this can be disabled using the \fBstrict_config\fP keyword argument set to False .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 basedir=/path/to/dir salt \(aq*\(aq pkg.list_repos basedir=/path/to/dir,/path/to/another/dir strict_config=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.list_updates(refresh=True, **kwargs) This function is an alias of \fBlist_upgrades\fP\&. .INDENT 7.0 .INDENT 3.5 Check whether or not an upgrade is available for all packages .sp The \fBfromrepo\fP, \fBenablerepo\fP, and \fBdisablerepo\fP arguments are supported, as used in pkg states, and the \fBdisableexcludes\fP option is also supported. .sp New in version 2014.7.0: Support for the \fBdisableexcludes\fP option .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.list_upgrades(refresh=True, **kwargs) Check whether or not an upgrade is available for all packages .sp The \fBfromrepo\fP, \fBenablerepo\fP, and \fBdisablerepo\fP arguments are supported, as used in pkg states, and the \fBdisableexcludes\fP option is also supported. .sp New in version 2014.7.0: Support for the \fBdisableexcludes\fP option .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.yumpkg.mod_repo(repo, basedir=None, **kwargs) Modify one or more values for a repo. If the repo does not exist, it will be created, so long as the following values are specified: .INDENT 7.0 .TP .B repo name by which the yum refers to the repo .TP .B name a human\-readable name for the repo .TP .B baseurl the URL for yum to reference .TP .B mirrorlist the URL for yum to reference .UNINDENT .sp Key/Value pairs may also be removed from a repo\(aqs configuration by setting a key to a blank value. Bear in mind that a name cannot be deleted, and a baseurl can only be deleted if a mirrorlist is specified (or vice versa). .sp Strict parsing of configuration files is the default, this can be disabled using the \fBstrict_config\fP keyword argument set to False .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.mod_repo reponame enabled=1 gpgcheck=1 salt \(aq*\(aq pkg.mod_repo reponame basedir=/path/to/dir enabled=1 strict_config=False salt \(aq*\(aq pkg.mod_repo reponame baseurl= mirrorlist=http://host.com/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.modified(*packages, **flags) List the modified files that belong to a package. Not specifying any packages will return a list of _all_ modified files on the system\(aqs RPM database. .sp New in version 2015.5.0. .sp Filtering by flags (True or False): .INDENT 7.0 .TP .B size Include only files where size changed. .TP .B mode Include only files which file\(aqs mode has been changed. .TP .B checksum Include only files which MD5 checksum has been changed. .TP .B device Include only files which major and minor numbers has been changed. .TP .B symlink Include only files which are symbolic link contents. .TP .B owner Include only files where owner has been changed. .TP .B group Include only files where group has been changed. .TP .B time Include only files where modification time of the file has been changed. .TP .B capabilities Include only files where capabilities differ or not. Note: supported only on newer RPM versions. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.modified salt \(aq*\(aq pkg.modified httpd salt \(aq*\(aq pkg.modified httpd postfix salt \(aq*\(aq pkg.modified httpd owner=True group=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.normalize_name(name) Strips the architecture from the specified package name, if necessary. Circumstances where this would be done include: .INDENT 7.0 .IP \(bu 2 If the arch is 32 bit and the package name ends in a 32\-bit arch. .IP \(bu 2 If the arch matches the OS arch, or is \fBnoarch\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.normalize_name zsh.x86_64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.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 Examples: .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 /etc/httpd/conf/httpd.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.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.x86_64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.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 yum/dnf 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Package purges are not supported by yum, this function is identical to \fI\%pkg.remove\fP\&. .INDENT 7.0 .TP .B name The name of the package to be purged .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 <package name> salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3> salt \(aq*\(aq pkg.purge pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.refresh_db(**kwargs) Check the yum repos for updated packages .sp Returns: .INDENT 7.0 .IP \(bu 2 \fBTrue\fP: Updates are available .IP \(bu 2 \fBFalse\fP: An error occurred .IP \(bu 2 \fBNone\fP: No updates are available .UNINDENT .INDENT 7.0 .TP .B repo Refresh just the specified repo .TP .B disablerepo Do not refresh the specified repo .TP .B enablerepo Refresh a disabled repo using this option .TP .B branch Add the specified branch when refreshing .TP .B disableexcludes Disable the excludes defined in your config files. Takes one of three options: \- \fBall\fP \- disable all excludes \- \fBmain\fP \- disable excludes defined in [main] in yum.conf \- \fBrepoid\fP \- disable excludes defined for that repo .TP .B setopt A comma\-separated or Python list of key=value options. This list will be expanded and \fB\-\-setopt\fP prepended to each in the yum/dnf command that is run. .sp New in version 2019.2.0. .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.yumpkg.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 yum/dnf 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Remove packages .INDENT 7.0 .TP .B name The name of the package to be removed .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. .INDENT 7.0 .TP .B split_arch True If set to False it prevents package name normalization by removing arch. .sp New in version 3006.0. .UNINDENT .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 <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.services_need_restart(**kwargs) New in version 3003. .sp List services that use files which have been changed by the package manager. It might be needed to restart them. .sp Requires systemd. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.services_need_restart .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.unhold(name=None, pkgs=None, sources=None, **kwargs) New in version 2014.7.0. .sp Remove version locks .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Requires the appropriate \fBversionlock\fP plugin package to be installed: .INDENT 0.0 .IP \(bu 2 On RHEL 5: \fByum\-versionlock\fP .IP \(bu 2 On RHEL 6 & 7: \fByum\-plugin\-versionlock\fP .IP \(bu 2 On Fedora: \fBpython\-dnf\-plugins\-extras\-versionlock\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the package to be unheld .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to unhold. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .UNINDENT .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unhold <package name> salt \(aq*\(aq pkg.unhold pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.update(name=None, pkgs=None, refresh=True, skip_verify=False, normalize=True, minimal=False, obsoletes=False, **kwargs) New in version 2019.2.0. .sp Calls \fI\%pkg.upgrade\fP with \fBobsoletes=False\fP\&. Mirrors the CLI behavior of \fByum update\fP\&. See \fI\%pkg.upgrade\fP for further documentation. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.upgrade(name=None, pkgs=None, refresh=True, skip_verify=False, normalize=True, minimal=False, obsoletes=True, diff_attr=None, **kwargs) Run a full system upgrade (a \fByum upgrade\fP or \fBdnf upgrade\fP), or upgrade specified packages. If the packages aren\(aqt installed, they will not be installed. .sp Changed in version 2014.7.0. .sp 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 yum/dnf 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Changed in version 2019.2.0: Added \fBobsoletes\fP and \fBminimal\fP arguments .sp Returns a dictionary containing the changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade salt \(aq*\(aq pkg.upgrade name=openssl .ft P .fi .UNINDENT .UNINDENT .sp Repository Options: .INDENT 7.0 .TP .B fromrepo Specify a package repository (or repositories) from which to install. (e.g., \fByum \-\-disablerepo=\(aq*\(aq \-\-enablerepo=\(aqsomerepo\(aq\fP) .TP .B enablerepo (ignored if \fBfromrepo\fP is specified) Specify a disabled package repository (or repositories) to enable. (e.g., \fByum \-\-enablerepo=\(aqsomerepo\(aq\fP) .TP .B disablerepo (ignored if \fBfromrepo\fP is specified) Specify an enabled package repository (or repositories) to disable. (e.g., \fByum \-\-disablerepo=\(aqsomerepo\(aq\fP) .TP .B disableexcludes Disable exclude from main, for a repo or for everything. (e.g., \fByum \-\-disableexcludes=\(aqmain\(aq\fP) .sp New in version 2014.7.0. .TP .B name The name of the package to be upgraded. Note that this parameter is ignored if \(dqpkgs\(dq is passed. .sp 32\-bit packages can be upgraded on 64\-bit systems by appending the architecture designation (\fB\&.i686\fP, \fB\&.i586\fP, etc.) to the end of the package name. .sp Warning: if you forget \(aqname=\(aq and run pkg.upgrade openssl, ALL packages are upgraded. This will be addressed in next releases. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade name=openssl .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .TP .B pkgs A list of packages to upgrade from a software repository. Must be passed as a python list. A specific version number can be specified by using a single\-element dict representing the package and its version. If the package was not already installed on the system, it will not be installed. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq salt \(aq*\(aq pkg.upgrade pkgs=\(aq[\(dqfoo\(dq, {\(dqbar\(dq: \(dq1.2.3\-4.el5\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .TP .B normalize True Normalize the package name by removing the architecture. This is useful for poorly created packages which might include the architecture as an actual part of the name such as kernel modules which match a specific kernel version. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G role:nsd pkg.upgrade gpfs.gplbin\-2.6.32\-279.31.1.el6.x86_64 normalize=False .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.3.0. .TP .B minimal False Use upgrade\-minimal instead of upgrade (e.g., \fByum upgrade\-minimal\fP) Goes to the \(aqnewest\(aq package match which fixes a problem that affects your system. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade minimal=True .ft P .fi .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B obsoletes True Controls whether yum/dnf should take obsoletes into account and remove them. If set to \fBFalse\fP yum will use \fBupdate\fP instead of \fBupgrade\fP and dnf will be run with \fB\-\-obsoletes=False\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade obsoletes=False .ft P .fi .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B setopt A comma\-separated or Python list of key=value options. This list will be expanded and \fB\-\-setopt\fP prepended to each in the yum/dnf command that is run. .sp New in version 2019.2.0. .TP .B diff_attr: If a list of package attributes is specified, returned value will contain them, eg.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: { \(aqold\(aq: { \(aqversion\(aq: \(aq<old\-version>\(aq, \(aqarch\(aq: \(aq<old\-arch>\(aq}, \(aqnew\(aq: { \(aqversion\(aq: \(aq<new\-version>\(aq, \(aqarch\(aq: \(aq<new\-arch>\(aq}}} .ft P .fi .UNINDENT .UNINDENT .sp Valid attributes are: \fBepoch\fP, \fBversion\fP, \fBrelease\fP, \fBarch\fP, \fBinstall_date\fP, \fBinstall_date_time_t\fP\&. .sp If \fBall\fP is specified, all valid attributes will be returned. .sp New in version 3006.0. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To add extra arguments to the \fByum upgrade\fP command, pass them as key word arguments. For arguments without assignments, pass \fBTrue\fP .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade security=True exclude=\(aqkernel*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.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 <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.verify(*names, **kwargs) New in version 2014.1.0. .sp Runs an rpm \-Va on a system, and returns the results in a dict .sp Pass options to modify rpm verify behavior using the \fBverify_options\fP keyword argument .sp Files with an attribute of config, doc, ghost, license or readme in the package header can be ignored using the \fBignore_types\fP keyword argument .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.verify salt \(aq*\(aq pkg.verify httpd salt \(aq*\(aq pkg.verify \(aqhttpd postfix\(aq salt \(aq*\(aq pkg.verify \(aqhttpd postfix\(aq ignore_types=[\(aqconfig\(aq,\(aqdoc\(aq] salt \(aq*\(aq pkg.verify \(aqhttpd postfix\(aq verify_options=[\(aqnodeps\(aq,\(aqnosize\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.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 <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.version_cmp(pkg1, pkg2, ignore_epoch=False, **kwargs) New in version 2015.5.4. .sp 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\-001\(aq \(aq0.2.0.1\-002\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.zabbix .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%zabbix Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Support for Zabbix .INDENT 0.0 .TP .B optdepends .INDENT 7.0 .IP \(bu 2 zabbix server .UNINDENT .TP .B configuration This module is not usable until the zabbix user and zabbix password are specified either in a pillar or in the minion\(aqs config file. Zabbix url should be also specified. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C zabbix.user: Admin zabbix.password: mypassword zabbix.url: http://127.0.0.1/zabbix/api_jsonrpc.php .ft P .fi .UNINDENT .UNINDENT .sp Connection arguments from the minion config file can be overridden on the CLI by using arguments with \fB_connection_\fP prefix. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C zabbix.apiinfo_version _connection_user=Admin _connection_password=zabbix _connection_url=http://host/zabbix/ .ft P .fi .UNINDENT .UNINDENT .TP .B codeauthor Jiri Kotlin <\fI\%jiri.kotlin@ultimum.io\fP> .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.apiinfo_version(**connection_args) Retrieve the version of the Zabbix API. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns On success string with Zabbix API version, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.apiinfo_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.compare_params(defined, existing, return_old_value=False) New in version 2017.7.0. .sp Compares Zabbix object definition against existing Zabbix object. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdefined\fP \-\- Zabbix object definition taken from sls file. .IP \(bu 2 \fBexisting\fP \-\- Existing Zabbix object taken from result of an API call. .IP \(bu 2 \fBreturn_old_value\fP \-\- Default False. If True, returns dict(\(dqold\(dq=old_val, \(dqnew\(dq=new_val) for rollback purpose. .UNINDENT .TP .B Returns Params that are different from existing object. Result extended by object ID can be passed directly to Zabbix API update method. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.compare_params new_zabbix_object_dict existing_zabbix_onject_dict .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.configuration_import(config_file, rules=None, file_format=\(aqxml\(aq, **connection_args) New in version 2017.7.0. .sp Imports Zabbix configuration specified in file to Zabbix server. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconfig_file\fP \-\- File with Zabbix config (local or remote) .IP \(bu 2 \fBrules\fP \-\- Optional \- Rules that have to be different from default (defaults are the same as in Zabbix web UI.) .IP \(bu 2 \fBfile_format\fP \-\- Config file format (default: xml) .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.configuration_import salt://zabbix/config/zabbix_templates.xml \(dq{\(aqscreens\(aq: {\(aqcreateMissing\(aq: True, \(aqupdateExisting\(aq: True}}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.get_object_id_by_params(obj, params=None, **connection_args) New in version 2017.7.0. .sp Get ID of single Zabbix object specified by its name. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- Zabbix object type .IP \(bu 2 \fBparams\fP \-\- Parameters by which object is uniquely identified .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns object ID .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.get_object_id_by_params object_type params=zabbix_api_query_parameters_dict .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.get_zabbix_id_mapper() New in version 2017.7.0. .sp Make ZABBIX_ID_MAPPER constant available to state modules. .INDENT 7.0 .TP .B Returns ZABBIX_ID_MAPPER .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.get_zabbix_id_mapper .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.host_create(host, groups, interfaces, **connection_args) New in version 2016.3.0. .sp Create new host .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard host properties: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhost\fP \-\- technical name of the host .IP \(bu 2 \fBgroups\fP \-\- groupids of host groups to add the host to .IP \(bu 2 \fBinterfaces\fP \-\- interfaces to be created for the host .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .IP \(bu 2 \fBvisible_name\fP \-\- string with visible name of the host, use \(aqvisible_name\(aq instead of \(aqname\(aq parameter to not mess with value supplied from Salt sls file. .UNINDENT .UNINDENT .sp return: ID of the created host. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.host_create technicalname 4 interfaces=\(aq{type: 1, main: 1, useip: 1, ip: \(dq192.168.3.1\(dq, dns: \(dq\(dq, port: 10050}\(aq visible_name=\(aqHost Visible Name\(aq inventory_mode=0 inventory=\(aq{\(dqalias\(dq: \(dqsomething\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.host_delete(hostids, **connection_args) Delete hosts. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhostids\fP \-\- Hosts (hostids) to delete. .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns IDs of the deleted hosts. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.host_delete 10106 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.host_exists(host=None, hostid=None, name=None, node=None, nodeids=None, **connection_args) Checks if at least one host that matches the given filter criteria exists. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhost\fP \-\- technical name of the host .IP \(bu 2 \fBhostids\fP \-\- Hosts (hostids) to delete. .IP \(bu 2 \fBname\fP \-\- visible name of the host .IP \(bu 2 \fBnode\fP \-\- name of the node the hosts must belong to (zabbix API < 2.4) .IP \(bu 2 \fBnodeids\fP \-\- IDs of the node the hosts must belong to (zabbix API < 2.4) .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns IDs of the deleted hosts, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.host_exists \(aqZabbix server\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.host_get(host=None, name=None, hostids=None, **connection_args) New in version 2016.3.0. .sp Retrieve hosts according to the given parameters .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all optional host.get parameters: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhost\fP \-\- technical name of the host .IP \(bu 2 \fBname\fP \-\- visible name of the host .IP \(bu 2 \fBhostids\fP \-\- ids of the hosts .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Array with convenient hosts details, False if no host found or on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.host_get \(aqZabbix server\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.host_inventory_get(hostids, **connection_args) Retrieve host inventory according to the given parameters. See: \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/host/object#host_inventory\fP .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhostids\fP \-\- ID of the host to query .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Array with host inventory fields, populated or not, False if host inventory is disabled or on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.host_inventory_get 101054 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.host_inventory_set(hostid, **connection_args) Update host inventory items NOTE: This function accepts all standard host: keyword argument names for inventory see: \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/host/object#host_inventory\fP .sp New in version 2019.2.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhostid\fP \-\- ID of the host to update .IP \(bu 2 \fBclear_old\fP \-\- Set to True in order to remove all existing inventory items before setting the specified items .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns ID of the updated host, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.host_inventory_set 101054 asset_tag=jml3322 type=vm clear_old=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.host_list(**connection_args) Retrieve all hosts. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Array with details about hosts, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.host_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.host_update(hostid, **connection_args) New in version 2016.3.0. .sp Update existing hosts .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard host and host.update properties: keyword argument names differ depending on your zabbix version, see the documentation for \fI\%host objects\fP and the documentation for \fI\%updating hosts\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhostid\fP \-\- ID of the host to update .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .IP \(bu 2 \fBvisible_name\fP \-\- string with visible name of the host, use \(aqvisible_name\(aq instead of \(aqname\(aq parameter to not mess with value supplied from Salt sls file. .UNINDENT .TP .B Returns ID of the updated host. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.host_update 10084 name=\(aqZabbix server2\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.hostgroup_create(name, **connection_args) New in version 2016.3.0. .sp Create a host group .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard host group properties: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- name of the host group .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns ID of the created host group. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.hostgroup_create MyNewGroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.hostgroup_delete(hostgroupids, **connection_args) Delete the host group. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhostgroupids\fP \-\- IDs of the host groups to delete .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns ID of the deleted host groups, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.hostgroup_delete 23 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.hostgroup_exists(name=None, groupid=None, node=None, nodeids=None, **connection_args) Checks if at least one host group that matches the given filter criteria exists. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- names of the host groups .IP \(bu 2 \fBgroupid\fP \-\- host group IDs .IP \(bu 2 \fBnode\fP \-\- name of the node the host groups must belong to (zabbix API < 2.4) .IP \(bu 2 \fBnodeids\fP \-\- IDs of the nodes the host groups must belong to (zabbix API < 2.4) .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns True if at least one host group exists, False if not or on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.hostgroup_exists MyNewGroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.hostgroup_get(name=None, groupids=None, hostids=None, **connection_args) New in version 2016.3.0. .sp Retrieve host groups according to the given parameters .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard hostgroup.get properities: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- names of the host groups .IP \(bu 2 \fBgroupid\fP \-\- host group IDs .IP \(bu 2 \fBnode\fP \-\- name of the node the host groups must belong to .IP \(bu 2 \fBnodeids\fP \-\- IDs of the nodes the host groups must belong to .IP \(bu 2 \fBhostids\fP \-\- return only host groups that contain the given hosts .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Array with host groups details, False if no convenient host group found or on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.hostgroup_get MyNewGroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.hostgroup_list(**connection_args) Retrieve all host groups. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Array with details about host groups, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.hostgroup_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.hostgroup_update(groupid, name=None, **connection_args) New in version 2016.3.0. .sp Update existing hosts group .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard host group properties: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgroupid\fP \-\- ID of the host group to update .IP \(bu 2 \fBname\fP \-\- name of the host group .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns IDs of updated host groups. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.hostgroup_update 24 name=\(aqRenamed Name\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.hostinterface_create(hostid, ip_, dns=\(aq\(aq, main=1, if_type=1, useip=1, port=None, **connection_args) New in version 2016.3.0. .sp Create new host interface .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard host group interface: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhostid\fP \-\- ID of the host the interface belongs to .IP \(bu 2 \fBip\fP \-\- IP address used by the interface .IP \(bu 2 \fBdns\fP \-\- DNS name used by the interface .IP \(bu 2 \fBmain\fP \-\- whether the interface is used as default on the host (0 \- not default, 1 \- default) .IP \(bu 2 \fBport\fP \-\- port number used by the interface .IP \(bu 2 \fBtype\fP \-\- Interface type (1 \- agent; 2 \- SNMP; 3 \- IPMI; 4 \- JMX) .IP \(bu 2 \fBuseip\fP \-\- Whether the connection should be made via IP (0 \- connect using host DNS name; 1 \- connect using host IP address for this host interface) .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns ID of the created host interface, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.hostinterface_create 10105 192.193.194.197 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.hostinterface_delete(interfaceids, **connection_args) Delete host interface .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBinterfaceids\fP \-\- IDs of the host interfaces to delete .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns ID of deleted host interfaces, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.hostinterface_delete 50 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.hostinterface_get(hostids, **connection_args) New in version 2016.3.0. .sp Retrieve host groups according to the given parameters .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard hostinterface.get properities: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhostids\fP \-\- Return only host interfaces used by the given hosts. .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Array with host interfaces details, False if no convenient host interfaces found or on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.hostinterface_get 101054 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.hostinterface_update(interfaceid, **connection_args) New in version 2016.3.0. .sp Update host interface .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard hostinterface: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBinterfaceid\fP \-\- ID of the hostinterface to update .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns ID of the updated host interface, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.hostinterface_update 6 ip_=0.0.0.2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.mediatype_create(name, mediatype, **connection_args) Create new mediatype .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard mediatype properties: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmediatype\fP \-\- media type \- 0: email, 1: script, 2: sms, 3: Jabber, 100: Ez Texting .IP \(bu 2 \fBexec_path\fP \-\- exec path \- Required for script and Ez Texting types, see Zabbix API docs .IP \(bu 2 \fBgsm_modem\fP \-\- exec path \- Required for sms type, see Zabbix API docs .IP \(bu 2 \fBsmtp_email\fP \-\- email address from which notifications will be sent, required for email type .IP \(bu 2 \fBsmtp_helo\fP \-\- SMTP HELO, required for email type .IP \(bu 2 \fBsmtp_server\fP \-\- SMTP server, required for email type .IP \(bu 2 \fBstatus\fP \-\- whether the media type is enabled \- 0: enabled, 1: disabled .IP \(bu 2 \fBusername\fP \-\- authentication user, required for Jabber and Ez Texting types .IP \(bu 2 \fBpasswd\fP \-\- authentication password, required for Jabber and Ez Texting types .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .UNINDENT .sp return: ID of the created mediatype. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.mediatype_create \(aqEmail\(aq 0 smtp_email=\(aqnoreply@example.com\(aq smtp_server=\(aqmailserver.example.com\(aq smtp_helo=\(aqzabbix.example.com\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.mediatype_delete(mediatypeids, **connection_args) Delete mediatype .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBinterfaceids\fP \-\- IDs of the mediatypes to delete .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns ID of deleted mediatype, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.mediatype_delete 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.mediatype_get(name=None, mediatypeids=None, **connection_args) Retrieve mediatypes according to the given parameters. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Name or description of the mediatype .IP \(bu 2 \fBmediatypeids\fP \-\- ids of the mediatypes .IP \(bu 2 \fBconnection_args\fP (\fIoptional\fP) \-\- .sp _connection_user: zabbix user (can also be set in opts or pillar, see module\(aqs docstring) _connection_password: zabbix password (can also be set in opts or pillar, see module\(aqs docstring) _connection_url: url of zabbix frontend (can also be set in opts or pillar, see module\(aqs docstring) .sp all optional mediatype.get parameters: keyword argument names depends on your zabbix version, see: .sp \fI\%https://www.zabbix.com/documentation/2.2/manual/api/reference/mediatype/get\fP .UNINDENT .TP .B Returns Array with mediatype details, False if no mediatype found or on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.mediatype_get name=\(aqEmail\(aq salt \(aq*\(aq zabbix.mediatype_get mediatypeids=\(dq[\(aq1\(aq, \(aq2\(aq, \(aq3\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.mediatype_update(mediatypeid, name=False, mediatype=False, **connection_args) Update existing mediatype .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard mediatype properties: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmediatypeid\fP \-\- ID of the mediatype to update .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns IDs of the updated mediatypes, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usergroup_update 8 name=\(dqEmail update\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.run_query(method, params, **connection_args) Send Zabbix API call .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmethod\fP \-\- actual operation to perform via the API .IP \(bu 2 \fBparams\fP \-\- parameters required for specific method .IP \(bu 2 \fBconnection_args\fP (\fIoptional\fP) \-\- .sp _connection_user: zabbix user (can also be set in opts or pillar, see module\(aqs docstring) _connection_password: zabbix password (can also be set in opts or pillar, see module\(aqs docstring) _connection_url: url of zabbix frontend (can also be set in opts or pillar, see module\(aqs docstring) .sp all optional template.get parameters: keyword argument names depends on your zabbix version, see: .sp \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/\fP .UNINDENT .TP .B Returns Response from Zabbix API .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.run_query proxy.create \(aq{\(dqhost\(dq: \(dqzabbixproxy.domain.com\(dq, \(dqstatus\(dq: \(dq5\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.substitute_params(input_object, extend_params=None, filter_key=\(aqname\(aq, **kwargs) New in version 2017.7.0. .sp Go through Zabbix object params specification and if needed get given object ID from Zabbix API and put it back as a value. Definition of the object is done via dict with keys \(dqquery_object\(dq and \(dqquery_name\(dq. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBinput_object\fP \-\- Zabbix object type specified in state file .IP \(bu 2 \fBextend_params\fP \-\- Specify query with params .IP \(bu 2 \fBfilter_key\fP \-\- Custom filtering key (default: name) .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Params structure with values converted to string for further comparison purposes .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.substitute_params \(aq{\(dqquery_object\(dq: \(dqobject_name\(dq, \(dqquery_name\(dq: \(dqspecific_object_name\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.template_get(name=None, host=None, templateids=None, **connection_args) Retrieve templates according to the given parameters. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhost\fP \-\- technical name of the template .IP \(bu 2 \fBname\fP \-\- visible name of the template .IP \(bu 2 \fBhostids\fP \-\- ids of the templates .IP \(bu 2 \fBconnection_args\fP (\fIoptional\fP) \-\- .sp _connection_user: zabbix user (can also be set in opts or pillar, see module\(aqs docstring) _connection_password: zabbix password (can also be set in opts or pillar, see module\(aqs docstring) _connection_url: url of zabbix frontend (can also be set in opts or pillar, see module\(aqs docstring) .sp all optional template.get parameters: keyword argument names depends on your zabbix version, see: .sp \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/template/get\fP .UNINDENT .TP .B Returns Array with convenient template details, False if no template found or on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.template_get name=\(aqTemplate OS Linux\(aq salt \(aq*\(aq zabbix.template_get templateids=\(dq[\(aq10050\(aq, \(aq10001\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.user_addmedia(userids, active, mediatypeid, period, sendto, severity, **connection_args) Add new media to multiple users. Available only for Zabbix version 3.4 or older. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuserids\fP \-\- ID of the user that uses the media .IP \(bu 2 \fBactive\fP \-\- Whether the media is enabled (0 enabled, 1 disabled) .IP \(bu 2 \fBmediatypeid\fP \-\- ID of the media type used by the media .IP \(bu 2 \fBperiod\fP \-\- Time when the notifications can be sent as a time period .IP \(bu 2 \fBsendto\fP \-\- Address, user name or other identifier of the recipient .IP \(bu 2 \fBseverity\fP \-\- Trigger severities to send notifications about .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns IDs of the created media. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.user_addmedia 4 active=0 mediatypeid=1 period=\(aq1\-7,00:00\-24:00\(aq sendto=\(aqsupport2@example.com\(aq severity=63 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.user_create(alias, passwd, usrgrps, **connection_args) New in version 2016.3.0. .sp Create new zabbix user .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard user properties: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBalias\fP \-\- user alias .IP \(bu 2 \fBpasswd\fP \-\- user\(aqs password .IP \(bu 2 \fBusrgrps\fP \-\- user groups to add the user to .IP \(bu 2 \fB_connection_user\fP \-\- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- url of zabbix frontend (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fBfirstname\fP \-\- string with firstname of the user, use \(aqfirstname\(aq instead of \(aqname\(aq parameter to not mess with value supplied from Salt sls file. .UNINDENT .TP .B Returns On success string with id of the created user. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.user_create james password007 \(aq[7, 12]\(aq firstname=\(aqJames Bond\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.user_delete(users, **connection_args) Delete zabbix users. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBusers\fP \-\- array of users (userids) to delete .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns On success array with userids of deleted users. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.user_delete 15 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.user_deletemedia(mediaids, **connection_args) Delete media by id. Available only for Zabbix version 3.4 or older. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmediaids\fP \-\- IDs of the media to delete .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns IDs of the deleted media, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.user_deletemedia 27 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.user_exists(alias, **connection_args) Checks if user with given alias exists. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBalias\fP \-\- user alias .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns True if user exists, else False. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.user_exists james .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.user_get(alias=None, userids=None, **connection_args) Retrieve users according to the given parameters. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBalias\fP \-\- user alias .IP \(bu 2 \fBuserids\fP \-\- return only users with the given IDs .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Array with details of convenient users, False on failure of if no user found. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.user_get james .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.user_getmedia(userids=None, **connection_args) New in version 2016.3.0. .sp Retrieve media according to the given parameters .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard usermedia.get properties: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuserids\fP \-\- return only media that are used by the given users .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns List of retrieved media, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.user_getmedia .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.user_list(**connection_args) Retrieve all of the configured users. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Array with user details. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.user_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.user_update(userid, **connection_args) New in version 2016.3.0. .sp Update existing users .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard user properties: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuserid\fP \-\- id of the user to update .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Id of the updated user on success. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.user_update 16 visible_name=\(aqJames Brown\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usergroup_create(name, **connection_args) New in version 2016.3.0. .sp Create new user group .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard user group properties: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- name of the user group .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns IDs of the created user groups. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usergroup_create GroupName .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usergroup_delete(usergroupids, **connection_args) New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBusergroupids\fP \-\- IDs of the user groups to delete .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns IDs of the deleted user groups. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usergroup_delete 28 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usergroup_exists(name=None, node=None, nodeids=None, **connection_args) Checks if at least one user group that matches the given filter criteria exists .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- names of the user groups .IP \(bu 2 \fBnode\fP \-\- name of the node the user groups must belong to (This will override the nodeids parameter.) .IP \(bu 2 \fBnodeids\fP \-\- IDs of the nodes the user groups must belong to .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns True if at least one user group that matches the given filter criteria exists, else False. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usergroup_exists Guests .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usergroup_get(name=None, usrgrpids=None, userids=None, **connection_args) New in version 2016.3.0. .sp Retrieve user groups according to the given parameters .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all usergroup_get properties: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- names of the user groups .IP \(bu 2 \fBusrgrpids\fP \-\- return only user groups with the given IDs .IP \(bu 2 \fBuserids\fP \-\- return only user groups that contain the given users .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Array with convenient user groups details, False if no user group found or on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usergroup_get Guests .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usergroup_list(**connection_args) Retrieve all enabled user groups. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Array with enabled user groups details, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usergroup_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usergroup_update(usrgrpid, **connection_args) New in version 2016.3.0. .sp Update existing user group .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function accepts all standard user group properties: keyword argument names differ depending on your zabbix version, see \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBusrgrpid\fP \-\- ID of the user group to update. .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns IDs of the updated user group, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usergroup_update 8 name=guestsRenamed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usermacro_create(macro, value, hostid, **connection_args) Create new host usermacro. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmacro\fP \-\- name of the host usermacro .IP \(bu 2 \fBvalue\fP \-\- value of the host usermacro .IP \(bu 2 \fBhostid\fP \-\- hostid or templateid .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .UNINDENT .sp return: ID of the created host usermacro. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usermacro_create \(aq{$SNMP_COMMUNITY}\(aq \(aqpublic\(aq 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usermacro_createglobal(macro, value, **connection_args) Create new global usermacro. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmacro\fP \-\- name of the global usermacro .IP \(bu 2 \fBvalue\fP \-\- value of the global usermacro .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .UNINDENT .sp return: ID of the created global usermacro. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usermacro_createglobal \(aq{$SNMP_COMMUNITY}\(aq \(aqpublic\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usermacro_delete(macroids, **connection_args) Delete host usermacros. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmacroids\fP \-\- macroids of the host usermacros .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .UNINDENT .sp return: IDs of the deleted host usermacro. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usermacro_delete 21 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usermacro_deleteglobal(macroids, **connection_args) Delete global usermacros. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmacroids\fP \-\- macroids of the global usermacros .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .UNINDENT .sp return: IDs of the deleted global usermacro. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usermacro_deleteglobal 21 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usermacro_get(macro=None, hostids=None, templateids=None, hostmacroids=None, globalmacroids=None, globalmacro=False, **connection_args) Retrieve user macros according to the given parameters. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmacro\fP \-\- name of the usermacro .IP \(bu 2 \fBhostids\fP \-\- Return macros for the given hostids .IP \(bu 2 \fBtemplateids\fP \-\- Return macros for the given templateids .IP \(bu 2 \fBhostmacroids\fP \-\- Return macros with the given hostmacroids .IP \(bu 2 \fBglobalmacroids\fP \-\- Return macros with the given globalmacroids (implies globalmacro=True) .IP \(bu 2 \fBglobalmacro\fP \-\- if True, returns only global macros .IP \(bu 2 \fBconnection_args\fP (\fIoptional\fP) \-\- _connection_user: zabbix user (can also be set in opts or pillar, see module\(aqs docstring) _connection_password: zabbix password (can also be set in opts or pillar, see module\(aqs docstring) _connection_url: url of zabbix frontend (can also be set in opts or pillar, see module\(aqs docstring) .UNINDENT .TP .B Returns Array with usermacro details, False if no usermacro found or on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usermacro_get macro=\(aq{$SNMP_COMMUNITY}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usermacro_update(hostmacroid, value, **connection_args) Update existing host usermacro. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhostmacroid\fP \-\- id of the host usermacro .IP \(bu 2 \fBvalue\fP \-\- new value of the host usermacro .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .UNINDENT .sp return: ID of the update host usermacro. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usermacro_update 1 \(aqpublic\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zabbix.usermacro_updateglobal(globalmacroid, value, **connection_args) Update existing global usermacro. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBglobalmacroid\fP \-\- id of the host usermacro .IP \(bu 2 \fBvalue\fP \-\- new value of the host usermacro .IP \(bu 2 \fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring) .IP \(bu 2 \fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring) .UNINDENT .UNINDENT .sp return: ID of the update global usermacro. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zabbix.usermacro_updateglobal 1 \(aqpublic\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.zcbuildout .sp Management of zc.buildout .sp New in version 2014.1.0. .sp This module is inspired by \fI\%minitage\(aqs buildout maker\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The zc.buildout integration is still in beta; the API is subject to change .UNINDENT .UNINDENT .SS General notes .sp You have those following methods: .INDENT 0.0 .IP \(bu 2 upgrade_bootstrap .IP \(bu 2 bootstrap .IP \(bu 2 run_buildout .IP \(bu 2 buildout .UNINDENT .INDENT 0.0 .TP .B salt.modules.zcbuildout.bootstrap(*a, **kw) Run the buildout bootstrap dance (python bootstrap.py). .INDENT 7.0 .TP .B directory directory to execute in .TP .B config alternative buildout configuration file to use .TP .B runas User used to run buildout as .TP .B env environment variables to set when running .TP .B buildout_ver force a specific buildout version (1 | 2) .TP .B test_release buildout accept test release .TP .B offline are we executing buildout in offline mode .TP .B distribute Forcing use of distribute .TP .B new_st Forcing use of setuptools >= 0.7 .TP .B python path to a python executable to use in place of default (salt one) .TP .B onlyif Only execute cmd if statement on the host return 0 .TP .B unless Do not execute cmd if statement on the host return 0 .TP .B use_vt Use the new salt VT to stream output [experimental] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq buildout.bootstrap /srv/mybuildout .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zcbuildout.buildout(*a, **kw) Run buildout in a directory. .INDENT 7.0 .TP .B directory directory to execute in .TP .B config buildout config to use .TP .B parts specific buildout parts to run .TP .B runas user used to run buildout as .TP .B env environment variables to set when running .TP .B buildout_ver force a specific buildout version (1 | 2) .TP .B test_release buildout accept test release .TP .B new_st Forcing use of setuptools >= 0.7 .TP .B distribute use distribute over setuptools if possible .TP .B offline does buildout run offline .TP .B python python to use .TP .B debug run buildout with \-D debug flag .TP .B onlyif Only execute cmd if statement on the host return 0 .TP .B unless Do not execute cmd if statement on the host return 0 .TP .B newest run buildout in newest mode .TP .B verbose run buildout in verbose mode (\-vvvvv) .TP .B use_vt Use the new salt VT to stream output [experimental] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq buildout.buildout /srv/mybuildout .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zcbuildout.run_buildout(*a, **kw) Run a buildout in a directory. .INDENT 7.0 .TP .B directory directory to execute in .TP .B config alternative buildout configuration file to use .TP .B offline are we executing buildout in offline mode .TP .B runas user used to run buildout as .TP .B env environment variables to set when running .TP .B onlyif Only execute cmd if statement on the host return 0 .TP .B unless Do not execute cmd if statement on the host return 0 .TP .B newest run buildout in newest mode .TP .B force run buildout unconditionally .TP .B verbose run buildout in verbose mode (\-vvvvv) .TP .B use_vt Use the new salt VT to stream output [experimental] .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq buildout.run_buildout /srv/mybuildout .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zcbuildout.upgrade_bootstrap(*a, **kw) Upgrade current bootstrap.py with the last released one. .sp Indeed, when we first run a buildout, a common source of problem is to have a locally stale bootstrap, we just try to grab a new copy .INDENT 7.0 .TP .B directory directory to execute in .TP .B offline are we executing buildout in offline mode .TP .B buildout_ver forcing to use a specific buildout version (1 | 2) .TP .B onlyif Only execute cmd if statement on the host return 0 .TP .B unless Do not execute cmd if statement on the host return 0 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq buildout.upgrade_bootstrap /srv/mybuildout .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.zenoss .sp Module for working with the Zenoss API .sp New in version 2016.3.0. .INDENT 0.0 .TP .B configuration This module requires a \(aqzenoss\(aq entry in the master/minion config. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C zenoss: hostname: https://zenoss.example.com username: admin password: admin123 verify_ssl: True ca_bundle: /etc/ssl/certs/ca\-certificates.crt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zenoss.add_device(device=None, device_class=None, collector=\(aqlocalhost\(aq, prod_state=1000) A function to connect to a zenoss server and add a new device entry. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdevice\fP \-\- (Optional) Will use the grain \(aqfqdn\(aq by default. .IP \(bu 2 \fBdevice_class\fP \-\- (Optional) The device class to use. If none, will determine based on kernel grain. .IP \(bu 2 \fBcollector\fP \-\- (Optional) The collector to use for this device. Defaults to \(aqlocalhost\(aq. .IP \(bu 2 \fBprod_state\fP \-\- (Optional) The prodState to set on the device. If none, defaults to 1000 ( production ) .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zenoss.add_device .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zenoss.device_exists(device=None) Check to see if a device already exists in Zenoss. .INDENT 7.0 .TP .B Parameters \fBdevice\fP \-\- (Optional) Will use the grain \(aqfqdn\(aq by default .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zenoss.device_exists .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zenoss.find_device(device=None) Find a device in Zenoss. If device not found, returns None. .INDENT 7.0 .TP .B Parameters \fBdevice\fP \-\- (Optional) Will use the grain \(aqfqdn\(aq by default .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zenoss.find_device .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zenoss.set_prod_state(prod_state, device=None) A function to set the prod_state in zenoss. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprod_state\fP \-\- (Required) Integer value of the state .IP \(bu 2 \fBdevice\fP \-\- (Optional) Will use the grain \(aqfqdn\(aq by default. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt zenoss.set_prod_state 1000 hostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.zfs .sp Module for running ZFS command .INDENT 0.0 .TP .B codeauthor Nitin Madhok <\fI\%nmadhok@g.clemson.edu\fP>, Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B depends salt.utils.zfs .TP .B platform illumos,freebsd,linux .UNINDENT .sp Changed in version 2018.3.1: Big refactor to remove duplicate code, better type conversions and improved consistency in output. .INDENT 0.0 .TP .B salt.modules.zfs.bookmark(snapshot, bookmark) Creates a bookmark of the given snapshot .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Bookmarks mark the point in time when the snapshot was created, and can be used as the incremental source for a zfs send command. .sp This feature must be enabled to be used. See zpool\-features(5) for details on ZFS feature flags and the bookmarks feature. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B snapshot string name of snapshot to bookmark .TP .B bookmark string name of bookmark .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.bookmark myzpool/mydataset@yesterday myzpool/mydataset#complete .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.clone(name_a, name_b, **kwargs) Creates a clone of the given snapshot. .INDENT 7.0 .TP .B name_a string name of snapshot .TP .B name_b string name of filesystem or volume .TP .B create_parent boolean creates all the non\-existing parent datasets. any property specified on the command line using the \-o option is ignored. .TP .B properties dict additional zfs properties (\-o) .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 ZFS properties can be specified at the time of creation of the filesystem by passing an additional argument called \(dqproperties\(dq and specifying the properties with their respective values in the form of a python dictionary: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C properties=\(dq{\(aqproperty1\(aq: \(aqvalue1\(aq, \(aqproperty2\(aq: \(aqvalue2\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.clone myzpool/mydataset@yesterday myzpool/mydataset_yesterday .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.create(name, **kwargs) Create a ZFS File System. .INDENT 7.0 .TP .B name string name of dataset or volume .TP .B volume_size string if specified, a zvol will be created instead of a dataset .TP .B sparse boolean create sparse volume .TP .B create_parent boolean creates all the non\-existing parent datasets. any property specified on the command line using the \-o option is ignored. .TP .B properties dict additional zfs properties (\-o) .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 ZFS properties can be specified at the time of creation of the filesystem by passing an additional argument called \(dqproperties\(dq and specifying the properties with their respective values in the form of a python dictionary: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C properties=\(dq{\(aqproperty1\(aq: \(aqvalue1\(aq, \(aqproperty2\(aq: \(aqvalue2\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.create myzpool/mydataset [create_parent=True|False] salt \(aq*\(aq zfs.create myzpool/mydataset properties=\(dq{\(aqmountpoint\(aq: \(aq/export/zfs\(aq, \(aqsharenfs\(aq: \(aqon\(aq}\(dq salt \(aq*\(aq zfs.create myzpool/volume volume_size=1G [sparse=True|False]\(ga salt \(aq*\(aq zfs.create myzpool/volume volume_size=1G properties=\(dq{\(aqvolblocksize\(aq: \(aq512\(aq}\(dq [sparse=True|False] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.destroy(name, **kwargs) Destroy a ZFS File System. .INDENT 7.0 .TP .B name string name of dataset, volume, or snapshot .TP .B force boolean force an unmount of any file systems using the unmount \-f command. .TP .B recursive boolean recursively destroy all children. (\-r) .TP .B recursive_all boolean recursively destroy all dependents, including cloned file systems outside the target hierarchy. (\-R) .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 watch out when using recursive and recursive_all .UNINDENT .UNINDENT .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.destroy myzpool/mydataset [force=True|False] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.diff(name_a, name_b=None, **kwargs) Display the difference between a snapshot of a given filesystem and another snapshot of that filesystem from a later time or the current contents of the filesystem. .INDENT 7.0 .TP .B name_a string name of snapshot .TP .B name_b string (optional) name of snapshot or filesystem .TP .B show_changetime boolean display the path\(aqs inode change time as the first column of output. (default = True) .TP .B show_indication boolean display an indication of the type of file. (default = True) .TP .B parsable boolean if true we don\(aqt parse the timestamp to a more readable date (default = True) .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.diff myzpool/mydataset@yesterday myzpool/mydataset .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.exists(name, **kwargs) Check if a ZFS filesystem or volume or snapshot exists. .INDENT 7.0 .TP .B name string name of dataset .TP .B type string also check if dataset is of a certain type, valid choices are: filesystem, snapshot, volume, bookmark, or all. .UNINDENT .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.exists myzpool/mydataset salt \(aq*\(aq zfs.exists myzpool/myvolume type=volume .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.get(*dataset, **kwargs) Displays properties for the given datasets. .INDENT 7.0 .TP .B dataset string name of snapshot(s), filesystem(s), or volume(s) .TP .B properties string comma\-separated list of properties to list, defaults to all .TP .B recursive boolean recursively list children .TP .B depth int recursively list children to depth .TP .B fields string comma\-separated list of fields to include, the name and property field will always be added .TP .B type string comma\-separated list of types to display, where type is one of filesystem, snapshot, volume, bookmark, or all. .sp Changed in version 3004. .sp type is ignored on Solaris 10 and 11 since not a valid parameter on those platforms .TP .B source string comma\-separated list of sources to display. Must be one of the following: local, default, inherited, temporary, and none. The default value is all sources. .TP .B parsable boolean display numbers in parsable (exact) values (default = True) \&.. versionadded:: 2018.3.0 .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no datasets are specified, then the command displays properties for all datasets on the system. .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.get salt \(aq*\(aq zfs.get myzpool/mydataset [recursive=True|False] salt \(aq*\(aq zfs.get myzpool/mydataset properties=\(dqsharenfs,mountpoint\(dq [recursive=True|False] salt \(aq*\(aq zfs.get myzpool/mydataset myzpool/myotherdataset properties=available fields=value depth=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.hold(tag, *snapshot, **kwargs) Adds a single reference, named with the tag argument, to the specified snapshot or snapshots. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Each snapshot has its own tag namespace, and tags must be unique within that space. .sp If a hold exists on a snapshot, attempts to destroy that snapshot by using the zfs destroy command return EBUSY. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B tag string name of tag .TP .B snapshot string name of snapshot(s) .TP .B recursive boolean specifies that a hold with the given tag is applied recursively to the snapshots of all descendent file systems. .UNINDENT .sp New in version 2016.3.0. .sp Changed in version 2018.3.1. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 As of 2018.3.1 the tag parameter no longer accepts a comma\-separated value. It\(aqs is now possible to create a tag that contains a comma, this was impossible before. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.hold mytag myzpool/mydataset@mysnapshot [recursive=True] salt \(aq*\(aq zfs.hold mytag myzpool/mydataset@mysnapshot myzpool/mydataset@myothersnapshot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.holds(snapshot, **kwargs) Lists all existing user references for the given snapshot or snapshots. .INDENT 7.0 .TP .B snapshot string name of snapshot .TP .B recursive boolean lists the holds that are set on the named descendent snapshots also. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.holds myzpool/mydataset@baseline .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.inherit(prop, name, **kwargs) Clears the specified property .INDENT 7.0 .TP .B prop string name of property .TP .B name string name of the filesystem, volume, or snapshot .TP .B recursive boolean recursively inherit the given property for all children. .TP .B revert boolean revert the property to the received value if one exists; otherwise operate as if the \-S option was not specified. .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.inherit canmount myzpool/mydataset [recursive=True|False] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.list_(name=None, **kwargs) Return a list of all datasets or a specified dataset on the system and the values of their used, available, referenced, and mountpoint properties. .INDENT 7.0 .TP .B name string name of dataset, volume, or snapshot .TP .B recursive boolean recursively list children .TP .B depth int limit recursion to depth .TP .B properties string comma\-separated list of properties to list, the name property will always be added .TP .B type string comma\-separated list of types to display, where type is one of filesystem, snapshot, volume, bookmark, or all. .TP .B sort string property to sort on (default = name) .TP .B order string [ascending|descending] sort order (default = ascending) .TP .B parsable boolean display numbers in parsable (exact) values \&.. versionadded:: 2018.3.0 .UNINDENT .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.list salt \(aq*\(aq zfs.list myzpool/mydataset [recursive=True|False] salt \(aq*\(aq zfs.list myzpool/mydataset properties=\(dqsharenfs,mountpoint\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.list_mount() List mounted zfs filesystems .sp New in version 2018.3.1. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.list_mount .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.mount(name=None, **kwargs) Mounts ZFS file systems .INDENT 7.0 .TP .B name string name of the filesystem, having this set to None will mount all filesystems. (this is the default) .TP .B overlay boolean perform an overlay mount. .TP .B options string optional comma\-separated list of mount options to use temporarily for the duration of the mount. .UNINDENT .sp New in version 2016.3.0. .sp Changed in version 2018.3.1. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Passing \(aq\-a\(aq as name is deprecated and will be removed in 3001. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.mount salt \(aq*\(aq zfs.mount myzpool/mydataset salt \(aq*\(aq zfs.mount myzpool/mydataset options=ro .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.promote(name) Promotes a clone file system to no longer be dependent on its \(dqorigin\(dq snapshot. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This makes it possible to destroy the file system that the clone was created from. The clone parent\-child dependency relationship is reversed, so that the origin file system becomes a clone of the specified file system. .sp The snapshot that was cloned, and any snapshots previous to this snapshot, are now owned by the promoted clone. The space they use moves from the origin file system to the promoted clone, so enough space must be available to accommodate these snapshots. No new space is consumed by this operation, but the space accounting is adjusted. The promoted clone must not have any conflicting snapshot names of its own. The rename subcommand can be used to rename any conflicting snapshots. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name string name of clone\-filesystem .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.promote myzpool/myclone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.release(tag, *snapshot, **kwargs) Removes a single reference, named with the tag argument, from the specified snapshot or snapshots. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The tag must already exist for each snapshot. If a hold exists on a snapshot, attempts to destroy that snapshot by using the zfs destroy command return EBUSY. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B tag string name of tag .TP .B snapshot string name of snapshot(s) .TP .B recursive boolean recursively releases a hold with the given tag on the snapshots of all descendent file systems. .UNINDENT .sp New in version 2016.3.0. .sp Changed in version 2018.3.1. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 As of 2018.3.1 the tag parameter no longer accepts a comma\-separated value. It\(aqs is now possible to create a tag that contains a comma, this was impossible before. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.release mytag myzpool/mydataset@mysnapshot [recursive=True] salt \(aq*\(aq zfs.release mytag myzpool/mydataset@mysnapshot myzpool/mydataset@myothersnapshot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.rename(name, new_name, **kwargs) Rename or Relocate a ZFS File System. .INDENT 7.0 .TP .B name string name of dataset, volume, or snapshot .TP .B new_name string new name of dataset, volume, or snapshot .TP .B force boolean force unmount any filesystems that need to be unmounted in the process. .TP .B create_parent boolean creates all the nonexistent parent datasets. Datasets created in this manner are automatically mounted according to the mountpoint property inherited from their parent. .TP .B recursive boolean recursively rename the snapshots of all descendent datasets. snapshots are the only dataset that can be renamed recursively. .UNINDENT .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.rename myzpool/mydataset myzpool/renameddataset .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.rollback(name, **kwargs) Roll back the given dataset to a previous snapshot. .INDENT 7.0 .TP .B name string name of snapshot .TP .B recursive boolean destroy any snapshots and bookmarks more recent than the one specified. .TP .B recursive_all boolean destroy any more recent snapshots and bookmarks, as well as any clones of those snapshots. .TP .B force boolean used with the \-R option to force an unmount of any clone file systems that are to be destroyed. .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 When a dataset is rolled back, all data that has changed since the snapshot is discarded, and the dataset reverts to the state at the time of the snapshot. By default, the command refuses to roll back to a snapshot other than the most recent one. .sp In order to do so, all intermediate snapshots and bookmarks must be destroyed by specifying the \-r option. .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.rollback myzpool/mydataset@yesterday .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.set(*dataset, **kwargs) Sets the property or list of properties to the given value(s) for each dataset. .INDENT 7.0 .TP .B dataset string name of snapshot(s), filesystem(s), or volume(s) .TP .B properties string additional zfs properties pairs .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 properties are passed as key\-value pairs. e.g. .INDENT 0.0 .INDENT 3.5 compression=off .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Only some properties can be edited. .sp See the Properties section for more information on what properties can be set and acceptable values. .sp Numeric values can be specified as exact values, or in a human\-readable form with a suffix of B, K, M, G, T, P, E (for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, or exabytes respectively). .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.set myzpool/mydataset compression=off salt \(aq*\(aq zfs.set myzpool/mydataset myzpool/myotherdataset compression=off salt \(aq*\(aq zfs.set myzpool/mydataset myzpool/myotherdataset compression=lz4 canmount=off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.snapshot(*snapshot, **kwargs) Creates snapshots with the given names. .INDENT 7.0 .TP .B snapshot string name of snapshot(s) .TP .B recursive boolean recursively create snapshots of all descendent datasets. .TP .B properties dict additional zfs properties (\-o) .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 ZFS properties can be specified at the time of creation of the filesystem by passing an additional argument called \(dqproperties\(dq and specifying the properties with their respective values in the form of a python dictionary: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C properties=\(dq{\(aqproperty1\(aq: \(aqvalue1\(aq, \(aqproperty2\(aq: \(aqvalue2\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.snapshot myzpool/mydataset@yesterday [recursive=True] salt \(aq*\(aq zfs.snapshot myzpool/mydataset@yesterday myzpool/myotherdataset@yesterday [recursive=True] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zfs.unmount(name, **kwargs) Unmounts ZFS file systems .INDENT 7.0 .TP .B name string name of the filesystem, you can use None to unmount all mounted filesystems. .TP .B force boolean forcefully unmount the file system, even if it is currently in use. .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Using \fB\-a\fP for the name parameter will probably break your system, unless your rootfs is not on zfs. .UNINDENT .UNINDENT .sp New in version 2016.3.0. .sp Changed in version 2018.3.1. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Passing \(aq\-a\(aq as name is deprecated and will be removed in 3001. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zfs.unmount myzpool/mydataset [force=True|False] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.zk_concurrency .SS Concurrency controls in zookeeper .INDENT 0.0 .TP .B depends kazoo .TP .B configuration See \fI\%salt.modules.zookeeper\fP for setup instructions. .UNINDENT .sp This module allows you to acquire and release a slot. This is primarily useful for ensureing that no more than N hosts take a specific action at once. This can also be used to coordinate between masters. .INDENT 0.0 .TP .B salt.modules.zk_concurrency.lock(path, zk_hosts=None, identifier=None, max_concurrency=1, timeout=None, ephemeral_lease=False, force=False, profile=None, scheme=None, username=None, password=None, default_acl=None) Get lock (with optional timeout) .INDENT 7.0 .TP .B path The path in zookeeper where the lock is .TP .B zk_hosts zookeeper connect string .TP .B identifier Name to identify this minion, if unspecified defaults to the hostname .TP .B max_concurrency Maximum number of lock holders .TP .B timeout timeout to wait for the lock. A None timeout will block forever .TP .B ephemeral_lease Whether the locks in zookeper should be ephemeral .TP .B force Forcibly acquire the lock regardless of available slots .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion zk_concurrency.lock /lock/path host1:1234,host2:1234 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zk_concurrency.lock_holders(path, zk_hosts=None, identifier=None, max_concurrency=1, timeout=None, ephemeral_lease=False, profile=None, scheme=None, username=None, password=None, default_acl=None) Return an un\-ordered list of lock holders .INDENT 7.0 .TP .B path The path in zookeeper where the lock is .TP .B zk_hosts zookeeper connect string .TP .B identifier Name to identify this minion, if unspecified defaults to hostname .TP .B max_concurrency Maximum number of lock holders .TP .B timeout timeout to wait for the lock. A None timeout will block forever .TP .B ephemeral_lease Whether the locks in zookeper should be ephemeral .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion zk_concurrency.lock_holders /lock/path host1:1234,host2:1234 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zk_concurrency.party_members(path, zk_hosts=None, min_nodes=1, blocking=False, profile=None, scheme=None, username=None, password=None, default_acl=None) Get the List of identifiers in a particular party, optionally waiting for the specified minimum number of nodes (min_nodes) to appear .INDENT 7.0 .TP .B path The path in zookeeper where the lock is .TP .B zk_hosts zookeeper connect string .TP .B min_nodes The minimum number of nodes expected to be present in the party .TP .B blocking The boolean indicating if we need to block until min_nodes are available .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion zk_concurrency.party_members /lock/path host1:1234,host2:1234 salt minion zk_concurrency.party_members /lock/path host1:1234,host2:1234 min_nodes=3 blocking=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zk_concurrency.unlock(path, zk_hosts=None, identifier=None, max_concurrency=1, ephemeral_lease=False, scheme=None, profile=None, username=None, password=None, default_acl=None) Remove lease from semaphore .INDENT 7.0 .TP .B path The path in zookeeper where the lock is .TP .B zk_hosts zookeeper connect string .TP .B identifier Name to identify this minion, if unspecified defaults to hostname .TP .B max_concurrency Maximum number of lock holders .TP .B timeout timeout to wait for the lock. A None timeout will block forever .TP .B ephemeral_lease Whether the locks in zookeper should be ephemeral .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion zk_concurrency.unlock /lock/path host1:1234,host2:1234 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.znc .sp znc \- An advanced IRC bouncer .sp New in version 2014.7.0. .sp Provides an interface to basic ZNC functionality .INDENT 0.0 .TP .B salt.modules.znc.buildmod(*modules) Build module using znc\-buildmod .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq znc.buildmod module.cpp [...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.znc.dumpconf() Write the active configuration state to config file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq znc.dumpconf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.znc.rehashconf() Rehash the active configuration state from config file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq znc.rehashconf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.znc.version() Return server version from znc \-\-version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq znc.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.zoneadm .sp Module for Solaris 10\(aqs zoneadm .INDENT 0.0 .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B platform OmniOS,OpenIndiana,SmartOS,OpenSolaris,Solaris 10 .UNINDENT .sp New in version 2017.7.0. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Oracle Solaris 11\(aqs zoneadm is not supported by this module! .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.attach(zone, force=False, brand_opts=None) Attach the specified zone. .INDENT 7.0 .TP .B zone string name of the zone .TP .B force boolean force the zone into the \(dqinstalled\(dq state with no validation .TP .B brand_opts string brand specific options to pass .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.attach lawrence salt \(aq*\(aq zoneadm.attach lawrence True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.boot(zone, single=False, altinit=None, smf_options=None) Boot (or activate) the specified zone. .INDENT 7.0 .TP .B zone string name or uuid of the zone .TP .B single boolean boots only to milestone svc:/milestone/single\-user:default. .TP .B altinit string valid path to an alternative executable to be the primordial process. .TP .B smf_options string include two categories of options to control booting behavior of the service management facility: recovery options and messages options. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.boot clementine salt \(aq*\(aq zoneadm.boot maeve single=True salt \(aq*\(aq zoneadm.boot teddy single=True smf_options=verbose .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.clone(zone, source, snapshot=None) Install a zone by copying an existing installed zone. .INDENT 7.0 .TP .B zone string name of the zone .TP .B source string zone to clone from .TP .B snapshot string optional name of snapshot to use as source .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.clone clementine dolores .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.detach(zone) Detach the specified zone. .INDENT 7.0 .TP .B zone string name or uuid of the zone .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.detach kissy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.halt(zone) Halt the specified zone. .INDENT 7.0 .TP .B zone string name or uuid of the zone .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To cleanly shutdown the zone use the shutdown function. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.halt hector .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.install(zone, nodataset=False, brand_opts=None) Install the specified zone from the system. .INDENT 7.0 .TP .B zone string name of the zone .TP .B nodataset boolean do not create a ZFS file system .TP .B brand_opts string brand specific options to pass .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.install dolores salt \(aq*\(aq zoneadm.install teddy True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.list_zones(verbose=True, installed=False, configured=False, hide_global=True) List all zones .INDENT 7.0 .TP .B verbose boolean display additional zone information .TP .B installed boolean include installed zones in output .TP .B configured boolean include configured zones in output .TP .B hide_global boolean do not include global zone .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.move(zone, zonepath) Move zone to new zonepath. .INDENT 7.0 .TP .B zone string name or uuid of the zone .TP .B zonepath string new zonepath .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.move meave /sweetwater/meave .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.ready(zone) Prepares a zone for running applications. .INDENT 7.0 .TP .B zone string name or uuid of the zone .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.ready clementine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.reboot(zone, single=False, altinit=None, smf_options=None) Restart the zone. This is equivalent to a halt boot sequence. .INDENT 7.0 .TP .B zone string name or uuid of the zone .TP .B single boolean boots only to milestone svc:/milestone/single\-user:default. .TP .B altinit string valid path to an alternative executable to be the primordial process. .TP .B smf_options string include two categories of options to control booting behavior of the service management facility: recovery options and messages options. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.reboot dolores salt \(aq*\(aq zoneadm.reboot teddy single=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.shutdown(zone, reboot=False, single=False, altinit=None, smf_options=None) Gracefully shutdown the specified zone. .INDENT 7.0 .TP .B zone string name or uuid of the zone .TP .B reboot boolean reboot zone after shutdown (equivalent of shutdown \-i6 \-g0 \-y) .TP .B single boolean boots only to milestone svc:/milestone/single\-user:default. .TP .B altinit string valid path to an alternative executable to be the primordial process. .TP .B smf_options string include two categories of options to control booting behavior of the service management facility: recovery options and messages options. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.shutdown peter salt \(aq*\(aq zoneadm.shutdown armistice reboot=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.uninstall(zone) Uninstall the specified zone from the system. .INDENT 7.0 .TP .B zone string name or uuid of the zone .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The \-F flag is always used to avoid the prompts when uninstalling. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.uninstall teddy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zoneadm.verify(zone) Check to make sure the configuration of the specified zone can safely be installed on the machine. .INDENT 7.0 .TP .B zone string name of the zone .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zoneadm.verify dolores .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.zonecfg .sp Module for Solaris 10\(aqs zonecfg .INDENT 0.0 .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B platform OmniOS,OpenIndiana,SmartOS,OpenSolaris,Solaris 10 .TP .B depend salt.modules.file .UNINDENT .sp New in version 2017.7.0. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Oracle Solaris 11\(aqs zonecfg is not supported by this module! .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zonecfg.add_resource(zone, resource_type, **kwargs) Add a resource .INDENT 7.0 .TP .B zone string name of zone .TP .B resource_type string type of resource .TP .B kwargs string|int|... resource properties .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zonecfg.add_resource tallgeese rctl name=zone.max\-locked\-memory value=\(aq(priv=privileged,limit=33554432,action=deny)\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zonecfg.clear_property(zone, key) Clear a property .INDENT 7.0 .TP .B zone string name of zone .TP .B key string name of property .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zonecfg.clear_property deathscythe cpu\-shares .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zonecfg.create(zone, brand, zonepath, force=False) Create an in\-memory configuration for the specified zone. .INDENT 7.0 .TP .B zone string name of zone .TP .B brand string brand name .TP .B zonepath string path of zone .TP .B force boolean overwrite configuration .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zonecfg.create deathscythe ipkg /zones/deathscythe .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zonecfg.create_from_template(zone, template) Create an in\-memory configuration from a template for the specified zone. .INDENT 7.0 .TP .B zone string name of zone .TP .B template string name of template .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 existing config will be overwritten! .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zonecfg.create_from_template leo tallgeese .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zonecfg.delete(zone) Delete the specified configuration from memory and stable storage. .INDENT 7.0 .TP .B zone string name of zone .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zonecfg.delete epyon .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zonecfg.export(zone, path=None) Export the configuration from memory to stable storage. .INDENT 7.0 .TP .B zone string name of zone .TP .B path string path of file to export to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zonecfg.export epyon salt \(aq*\(aq zonecfg.export epyon /zones/epyon.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zonecfg.import_(zone, path) Import the configuration to memory from stable storage. .INDENT 7.0 .TP .B zone string name of zone .TP .B path string path of file to export to .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zonecfg.import epyon /zones/epyon.cfg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zonecfg.info(zone, show_all=False) Display the configuration from memory .INDENT 7.0 .TP .B zone string name of zone .TP .B show_all boolean also include calculated values like capped\-cpu, cpu\-shares, ... .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zonecfg.info tallgeese .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zonecfg.remove_resource(zone, resource_type, resource_key, resource_value) Remove a resource .INDENT 7.0 .TP .B zone string name of zone .TP .B resource_type string type of resource .TP .B resource_key string key for resource selection .TP .B resource_value string value for resource selection .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Set resource_selector to None for resource that do not require one. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zonecfg.remove_resource tallgeese rctl name zone.max\-locked\-memory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zonecfg.set_property(zone, key, value) Set a property .INDENT 7.0 .TP .B zone string name of zone .TP .B key string name of property .TP .B value string value of property .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zonecfg.set_property deathscythe cpu\-shares 100 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zonecfg.update_resource(zone, resource_type, resource_selector, **kwargs) Add a resource .INDENT 7.0 .TP .B zone string name of zone .TP .B resource_type string type of resource .TP .B resource_selector string unique resource identifier .TP .B kwargs string|int|... resource properties .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Set resource_selector to None for resource that do not require one. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zonecfg.update_resource tallgeese rctl name name=zone.max\-locked\-memory value=\(aq(priv=privileged,limit=33554432,action=deny)\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.zookeeper .SS Zookeeper Module .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity new .TP .B platform all .TP .B depends kazoo .UNINDENT .sp New in version 2018.3.0. .SS Configuration .INDENT 0.0 .TP .B configuration This module is not usable until the following are specified either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C zookeeper: hosts: zoo1,zoo2,zoo3 default_acl: \- username: daniel password: test read: true write: true create: true delete: true admin: true username: daniel password: test .ft P .fi .UNINDENT .UNINDENT .sp If configuration for multiple zookeeper environments is required, they can be set up as different configuration profiles. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C zookeeper: prod: hosts: zoo1,zoo2,zoo3 default_acl: \- username: daniel password: test read: true write: true create: true delete: true admin: true username: daniel password: test dev: hosts: \- dev1 \- dev2 \- dev3 default_acl: \- username: daniel password: test read: true write: true create: true delete: true admin: true username: daniel password: test .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zookeeper.create(path, value=\(aq\(aq, acls=None, ephemeral=False, sequence=False, makepath=False, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Create Znode .INDENT 7.0 .TP .B path path of znode to create .TP .B value value to assign to znode (Default: \(aq\(aq) .TP .B acls list of acl dictionaries to be assigned (Default: None) .TP .B ephemeral indicate node is ephemeral (Default: False) .TP .B sequence indicate node is suffixed with a unique index (Default: False) .TP .B makepath Create parent paths if they do not exist (Default: False) .TP .B profile Configured Zookeeper profile to authenticate with (Default: None) .TP .B hosts Lists of Zookeeper Hosts (Default: \(aq127.0.0.1:2181) .TP .B scheme Scheme to authenticate with (Default: \(aqdigest\(aq) .TP .B username Username to authenticate (Default: None) .TP .B password Password to authenticate (Default: None) .TP .B default_acl Default acls to assign if a node is created in this connection (Default: None) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion1 zookeeper.create /test/name daniel profile=prod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zookeeper.delete(path, version=\-1, recursive=False, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Delete znode .INDENT 7.0 .TP .B path path to znode .TP .B version only delete if version matches (Default: \-1 (always matches)) .TP .B profile Configured Zookeeper profile to authenticate with (Default: None) .TP .B hosts Lists of Zookeeper Hosts (Default: \(aq127.0.0.1:2181) .TP .B scheme Scheme to authenticate with (Default: \(aqdigest\(aq) .TP .B username Username to authenticate (Default: None) .TP .B password Password to authenticate (Default: None) .TP .B default_acl Default acls to assign if a node is created in this connection (Default: None) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion1 zookeeper.delete /test/name profile=prod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zookeeper.ensure_path(path, acls=None, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Ensure Znode path exists .INDENT 7.0 .TP .B path Parent path to create .TP .B acls list of acls dictionaries to be assigned (Default: None) .TP .B profile Configured Zookeeper profile to authenticate with (Default: None) .TP .B hosts Lists of Zookeeper Hosts (Default: \(aq127.0.0.1:2181) .TP .B scheme Scheme to authenticate with (Default: \(aqdigest\(aq) .TP .B username Username to authenticate (Default: None) .TP .B password Password to authenticate (Default: None) .TP .B default_acl Default acls to assign if a node is created in this connection (Default: None) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion1 zookeeper.ensure_path /test/name profile=prod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zookeeper.exists(path, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Check if path exists .INDENT 7.0 .TP .B path path to check .TP .B profile Configured Zookeeper profile to authenticate with (Default: None) .TP .B hosts Lists of Zookeeper Hosts (Default: \(aq127.0.0.1:2181) .TP .B scheme Scheme to authenticate with (Default: \(aqdigest\(aq) .TP .B username Username to authenticate (Default: None) .TP .B password Password to authenticate (Default: None) .TP .B default_acl Default acls to assign if a node is created in this connection (Default: None) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion1 zookeeper.exists /test/name profile=prod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zookeeper.get(path, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Get value saved in znode .INDENT 7.0 .TP .B path path to check .TP .B profile Configured Zookeeper profile to authenticate with (Default: None) .TP .B hosts Lists of Zookeeper Hosts (Default: \(aq127.0.0.1:2181) .TP .B scheme Scheme to authenticate with (Default: \(aqdigest\(aq) .TP .B username Username to authenticate (Default: None) .TP .B password Password to authenticate (Default: None) .TP .B default_acl Default acls to assign if a node is created in this connection (Default: None) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion1 zookeeper.get /test/name profile=prod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zookeeper.get_acls(path, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Get acls on a znode .INDENT 7.0 .TP .B path path to znode .TP .B profile Configured Zookeeper profile to authenticate with (Default: None) .TP .B hosts Lists of Zookeeper Hosts (Default: \(aq127.0.0.1:2181) .TP .B scheme Scheme to authenticate with (Default: \(aqdigest\(aq) .TP .B username Username to authenticate (Default: None) .TP .B password Password to authenticate (Default: None) .TP .B default_acl Default acls to assign if a node is created in this connection (Default: None) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion1 zookeeper.get_acls /test/name profile=prod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zookeeper.get_children(path, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Get children in znode path .INDENT 7.0 .TP .B path path to check .TP .B profile Configured Zookeeper profile to authenticate with (Default: None) .TP .B hosts Lists of Zookeeper Hosts (Default: \(aq127.0.0.1:2181) .TP .B scheme Scheme to authenticate with (Default: \(aqdigest\(aq) .TP .B username Username to authenticate (Default: None) .TP .B password Password to authenticate (Default: None) .TP .B default_acl Default acls to assign if a node is created in this connection (Default: None) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion1 zookeeper.get_children /test profile=prod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zookeeper.make_digest_acl(username, password, read=False, write=False, create=False, delete=False, admin=False, allperms=False) Generate acl object .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is heavily used in the zookeeper state and probably is not useful as a cli module .UNINDENT .UNINDENT .INDENT 7.0 .TP .B username username of acl .TP .B password plain text password of acl .TP .B read read acl .TP .B write write acl .TP .B create create acl .TP .B delete delete acl .TP .B admin admin acl .TP .B allperms set all other acls to True .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion1 zookeeper.make_digest_acl username=daniel password=mypass allperms=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zookeeper.set(path, value, version=\-1, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Update znode with new value .INDENT 7.0 .TP .B path znode to update .TP .B value value to set in znode .TP .B version only update znode if version matches (Default: \-1 (always matches)) .TP .B profile Configured Zookeeper profile to authenticate with (Default: None) .TP .B hosts Lists of Zookeeper Hosts (Default: \(aq127.0.0.1:2181) .TP .B scheme Scheme to authenticate with (Default: \(aqdigest\(aq) .TP .B username Username to authenticate (Default: None) .TP .B password Password to authenticate (Default: None) .TP .B default_acl Default acls to assign if a node is created in this connection (Default: None) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion1 zookeeper.set /test/name gtmanfred profile=prod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zookeeper.set_acls(path, acls, version=\-1, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Set acls on a znode .INDENT 7.0 .TP .B path path to znode .TP .B acls list of acl dictionaries to set on the znode .TP .B version only set acls if version matches (Default: \-1 (always matches)) .TP .B profile Configured Zookeeper profile to authenticate with (Default: None) .TP .B hosts Lists of Zookeeper Hosts (Default: \(aq127.0.0.1:2181) .TP .B scheme Scheme to authenticate with (Default: \(aqdigest\(aq) .TP .B username Username to authenticate (Default: None) .TP .B password Password to authenticate (Default: None) .TP .B default_acl Default acls to assign if a node is created in this connection (Default: None) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion1 zookeeper.set_acls /test/name acls=\(aq[{\(dqusername\(dq: \(dqgtmanfred\(dq, \(dqpassword\(dq: \(dqtest\(dq, \(dqall\(dq: True}]\(aq profile=prod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.zpool .sp Module for running ZFS zpool command .INDENT 0.0 .TP .B codeauthor Nitin Madhok <\fI\%nmadhok@g.clemson.edu\fP>, Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B depends salt.utils.zfs .TP .B platform illumos,freebsd,linux .UNINDENT .sp Changed in version 2018.3.1: Big refactor to remove duplicate code, better type conversions and improved consistency in output. .INDENT 0.0 .TP .B salt.modules.zpool.add(zpool, *vdevs, **kwargs) Add the specified vdev\(aqs to the given storage pool .INDENT 7.0 .TP .B zpool string Name of storage pool .TP .B vdevs string One or more devices .TP .B force boolean Forces use of device .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.add myzpool /path/to/vdev1 /path/to/vdev2 [...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.attach(zpool, device, new_device, force=False) Attach specified device to zpool .INDENT 7.0 .TP .B zpool string Name of storage pool .TP .B device string Existing device name too .TP .B new_device string New device name (to be attached to \fBdevice\fP) .TP .B force boolean Forces use of device .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.attach myzpool /path/to/vdev1 /path/to/vdev2 [...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.clear(zpool, device=None) Clears device errors in a pool. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The device must not be part of an active pool configuration. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B zpool string name of storage pool .TP .B device string (optional) specific device to clear .UNINDENT .sp New in version 2018.3.1. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.clear mypool salt \(aq*\(aq zpool.clear mypool /path/to/dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.create(zpool, *vdevs, **kwargs) New in version 2015.5.0. .sp Create a simple zpool, a mirrored zpool, a zpool having nested VDEVs, a hybrid zpool with cache, spare and log drives or a zpool with RAIDZ\-1, RAIDZ\-2 or RAIDZ\-3 .INDENT 7.0 .TP .B zpool string Name of storage pool .TP .B vdevs string One or move devices .TP .B force boolean Forces use of vdevs, even if they appear in use or specify a conflicting replication level. .TP .B mountpoint string Sets the mount point for the root dataset .TP .B altroot string Equivalent to \(dq\-o cachefile=none,altroot=root\(dq .TP .B properties dict Additional pool properties .TP .B filesystem_properties dict Additional filesystem properties .TP .B createboot boolean create a boot partition .sp New in version 2018.3.0. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.create myzpool /path/to/vdev1 [...] [force=True|False] salt \(aq*\(aq zpool.create myzpool mirror /path/to/vdev1 /path/to/vdev2 [...] [force=True|False] salt \(aq*\(aq zpool.create myzpool raidz1 /path/to/vdev1 /path/to/vdev2 raidz2 /path/to/vdev3 /path/to/vdev4 /path/to/vdev5 [...] [force=True|False] salt \(aq*\(aq zpool.create myzpool mirror /path/to/vdev1 [...] mirror /path/to/vdev2 /path/to/vdev3 [...] [force=True|False] salt \(aq*\(aq zpool.create myhybridzpool mirror /tmp/file1 [...] log mirror /path/to/vdev1 [...] cache /path/to/vdev2 [...] spare /path/to/vdev3 [...] [force=True|False] .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Zpool properties can be specified at the time of creation of the pool by passing an additional argument called \(dqproperties\(dq and specifying the properties with their respective values in the form of a python dictionary: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C properties=\(dq{\(aqproperty1\(aq: \(aqvalue1\(aq, \(aqproperty2\(aq: \(aqvalue2\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .sp Filesystem properties can be specified at the time of creation of the pool by passing an additional argument called \(dqfilesystem_properties\(dq and specifying the properties with their respective values in the form of a python dictionary: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C filesystem_properties=\(dq{\(aqproperty1\(aq: \(aqvalue1\(aq, \(aqproperty2\(aq: \(aqvalue2\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.create myzpool /path/to/vdev1 [...] properties=\(dq{\(aqproperty1\(aq: \(aqvalue1\(aq, \(aqproperty2\(aq: \(aqvalue2\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.create myzpool /path/to/vdev1 [...] [force=True|False] salt \(aq*\(aq zpool.create myzpool mirror /path/to/vdev1 /path/to/vdev2 [...] [force=True|False] salt \(aq*\(aq zpool.create myzpool raidz1 /path/to/vdev1 /path/to/vdev2 raidz2 /path/to/vdev3 /path/to/vdev4 /path/to/vdev5 [...] [force=True|False] salt \(aq*\(aq zpool.create myzpool mirror /path/to/vdev1 [...] mirror /path/to/vdev2 /path/to/vdev3 [...] [force=True|False] salt \(aq*\(aq zpool.create myhybridzpool mirror /tmp/file1 [...] log mirror /path/to/vdev1 [...] cache /path/to/vdev2 [...] spare /path/to/vdev3 [...] [force=True|False] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.create_file_vdev(size, *vdevs) Creates file based virtual devices for a zpool .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.create_file_vdev 7G /path/to/vdev1 [/path/to/vdev2] [...] .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Depending on file size, the above command may take a while to return. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.destroy(zpool, force=False) Destroys a storage pool .INDENT 7.0 .TP .B zpool string Name of storage pool .TP .B force boolean Force destroy of pool .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.destroy myzpool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.detach(zpool, device) Detach specified device to zpool .INDENT 7.0 .TP .B zpool string Name of storage pool .TP .B device string Device to detach .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.detach myzpool /path/to/vdev1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.exists(zpool) Check if a ZFS storage pool is active .INDENT 7.0 .TP .B zpool string Name of storage pool .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.exists myzpool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.export(*pools, **kwargs) New in version 2015.5.0. .sp Export storage pools .INDENT 7.0 .TP .B pools string One or more storage pools to export .TP .B force boolean Force export of storage pools .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.export myzpool ... [force=True|False] salt \(aq*\(aq zpool.export myzpool2 myzpool2 ... [force=True|False] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.get(zpool, prop=None, show_source=False, parsable=True) New in version 2016.3.0. .sp Retrieves the given list of properties .INDENT 7.0 .TP .B zpool string Name of storage pool .TP .B prop string Optional name of property to retrieve .TP .B show_source boolean Show source of property .TP .B parsable boolean Display numbers in parsable (exact) values .sp New in version 2018.3.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.get myzpool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.healthy() Check if all zpools are healthy .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.healthy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.history(zpool=None, internal=False, verbose=False) New in version 2016.3.0. .sp Displays the command history of the specified pools, or all pools if no pool is specified .INDENT 7.0 .TP .B zpool string Optional storage pool .TP .B internal boolean Toggle display of internally logged ZFS events .TP .B verbose boolean Toggle display of the user name, the hostname, and the zone in which the operation was performed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.upgrade myzpool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.import_(zpool=None, new_name=None, **kwargs) New in version 2015.5.0. .sp Import storage pools or list pools available for import .INDENT 7.0 .TP .B zpool string Optional name of storage pool .TP .B new_name string Optional new name for the storage pool .TP .B mntopts string Comma\-separated list of mount options to use when mounting datasets within the pool. .TP .B force boolean Forces import, even if the pool appears to be potentially active. .TP .B altroot string Equivalent to \(dq\-o cachefile=none,altroot=root\(dq .TP .B dir string Searches for devices or files in dir, multiple dirs can be specified as follows: \fBdir=\(dqdir1,dir2\(dq\fP .TP .B no_mount boolean Import the pool without mounting any file systems. .TP .B only_destroyed boolean Imports destroyed pools only. This also sets \fBforce=True\fP\&. .TP .B recovery bool|str false: do not try to recovery broken pools true: try to recovery the pool by rolling back the latest transactions test: check if a pool can be recovered, but don\(aqt import it nolog: allow import without log device, recent transactions might be lost .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If feature flags are not support this forced to the default of \(aqfalse\(aq .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 When recovery is set to \(aqtest\(aq the result will be have imported set to True if the pool can be imported. The pool might also be imported if the pool was not broken to begin with. .UNINDENT .UNINDENT .TP .B properties dict Additional pool properties .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Zpool properties can be specified at the time of creation of the pool by passing an additional argument called \(dqproperties\(dq and specifying the properties with their respective values in the form of a python dictionary: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C properties=\(dq{\(aqproperty1\(aq: \(aqvalue1\(aq, \(aqproperty2\(aq: \(aqvalue2\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.import [force=True|False] salt \(aq*\(aq zpool.import myzpool [mynewzpool] [force=True|False] salt \(aq*\(aq zpool.import myzpool dir=\(aq/tmp\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.iostat(zpool=None, sample_time=5, parsable=True) Display I/O statistics for the given pools .INDENT 7.0 .TP .B zpool string optional name of storage pool .TP .B sample_time int seconds to capture data before output default a sample of 5 seconds is used .TP .B parsable boolean display data in pythonc values (True, False, Bytes,...) .UNINDENT .sp New in version 2016.3.0. .sp Changed in version 2018.3.1: Added \fB\(gaparsable\(ga\fP parameter that defaults to True .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.iostat myzpool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.labelclear(device, force=False) New in version 2018.3.0. .sp Removes ZFS label information from the specified device .INDENT 7.0 .TP .B device string Device name; must not be part of an active pool configuration. .TP .B force boolean Treat exported or foreign devices as inactive .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.labelclear /path/to/dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.list_(properties=\(aqsize,alloc,free,cap,frag,health\(aq, zpool=None, parsable=True) New in version 2015.5.0. .sp Return information about (all) storage pools .INDENT 7.0 .TP .B zpool string optional name of storage pool .TP .B properties string comma\-separated list of properties to list .TP .B parsable boolean display numbers in parsable (exact) values .sp New in version 2018.3.0. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fBname\fP property will always be included, while the \fBfrag\fP property will get removed if not available .UNINDENT .UNINDENT .INDENT 7.0 .TP .B zpool string optional zpool .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Multiple storage pool can be provided as a space separated list .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.list salt \(aq*\(aq zpool.list zpool=tank salt \(aq*\(aq zpool.list \(aqsize,free\(aq salt \(aq*\(aq zpool.list \(aqsize,free\(aq tank .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.offline(zpool, *vdevs, **kwargs) New in version 2015.5.0. .sp Ensure that the specified devices are offline .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 By default, the \fBOFFLINE\fP state is persistent. The device remains offline when the system is rebooted. To temporarily take a device offline, use \fBtemporary=True\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B zpool string name of storage pool .TP .B vdevs string One or more devices .TP .B temporary boolean Enable temporarily offline .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.offline myzpool /path/to/vdev1 [...] [temporary=True|False] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.online(zpool, *vdevs, **kwargs) New in version 2015.5.0. .sp Ensure that the specified devices are online .INDENT 7.0 .TP .B zpool string name of storage pool .TP .B vdevs string one or more devices .TP .B expand boolean Expand the device to use all available space. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the device is part of a mirror or raidz then all devices must be expanded before the new space will become available to the pool. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.online myzpool /path/to/vdev1 [...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.reguid(zpool) Generates a new unique identifier for the pool .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 You must ensure that all devices in this pool are online and healthy before performing this action. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B zpool string name of storage pool .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.reguid myzpool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.reopen(zpool) Reopen all the vdevs associated with the pool .INDENT 7.0 .TP .B zpool string name of storage pool .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.reopen myzpool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.replace(zpool, old_device, new_device=None, force=False) Replaces \fBold_device\fP with \fBnew_device\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is equivalent to attaching \fBnew_device\fP, waiting for it to resilver, and then detaching \fBold_device\fP\&. .sp The size of \fBnew_device\fP must be greater than or equal to the minimum size of all the devices in a mirror or raidz configuration. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B zpool string Name of storage pool .TP .B old_device string Old device to replace .TP .B new_device string Optional new device .TP .B force boolean Forces use of new_device, even if its appears to be in use. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.replace myzpool /path/to/vdev1 /path/to/vdev2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.scrub(zpool, stop=False, pause=False) Scrub a storage pool .INDENT 7.0 .TP .B zpool string Name of storage pool .TP .B stop boolean If \fBTrue\fP, cancel ongoing scrub .TP .B pause boolean If \fBTrue\fP, pause ongoing scrub .sp New in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Pause is only available on recent versions of ZFS. .sp If both \fBpause\fP and \fBstop\fP are \fBTrue\fP, then \fBstop\fP will win. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.scrub myzpool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.set(zpool, prop, value) Sets the given property on the specified pool .INDENT 7.0 .TP .B zpool string Name of storage pool .TP .B prop string Name of property to set .TP .B value string Value to set for the specified property .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.set myzpool readonly yes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.split(zpool, newzpool, **kwargs) New in version 2018.3.0. .sp Splits devices off pool creating newpool. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 All vdevs in pool must be mirrors. At the time of the split, \fBnewzpool\fP will be a replica of \fBzpool\fP\&. .sp After splitting, do not forget to import the new pool! .UNINDENT .UNINDENT .INDENT 7.0 .TP .B zpool string Name of storage pool .TP .B newzpool string Name of new storage pool .TP .B mountpoint string Sets the mount point for the root dataset .TP .B altroot string Sets altroot for newzpool .TP .B properties dict Additional pool properties for newzpool .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.split datamirror databackup salt \(aq*\(aq zpool.split datamirror databackup altroot=/backup .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Zpool properties can be specified at the time of creation of the pool by passing an additional argument called \(dqproperties\(dq and specifying the properties with their respective values in the form of a python dictionary: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C properties=\(dq{\(aqproperty1\(aq: \(aqvalue1\(aq, \(aqproperty2\(aq: \(aqvalue2\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.split datamirror databackup properties=\(dq{\(aqreadonly\(aq: \(aqon\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.split datamirror databackup salt \(aq*\(aq zpool.split datamirror databackup altroot=/backup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.status(zpool=None) Return the status of the named zpool .INDENT 7.0 .TP .B zpool string optional name of storage pool .UNINDENT .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.status myzpool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zpool.upgrade(zpool=None, version=None) New in version 2016.3.0. .sp Enables all supported features on the given pool .INDENT 7.0 .TP .B zpool string Optional storage pool, applies to all otherwize .TP .B version int Version to upgrade to, if unspecified upgrade to the highest possible .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Once this is done, the pool will no longer be accessible on systems that do not support feature flags. See zpool\-features(5) for details on compatibility with systems that support feature flags, but do not support all features enabled on the pool. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq zpool.upgrade myzpool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.zypperpkg .sp Package support for openSUSE via the zypper package manager .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 \fBrpm\fP Python module. Install with \fBzypper install rpm\-python\fP .UNINDENT .UNINDENT .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 \fI\%here\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.zypperpkg.Wildcard(zypper) New in version 2017.7.0. .sp Converts string wildcard to a zypper query. \&.. rubric:: Example .sp \(aq1.2.3.4*\(aq is \(aq1.2.3.4.whatever.is.here\(aq and is equal to: \(aq1.2.3.4 >= and < 1.2.3.5\(aq .INDENT 7.0 .TP .B Parameters \fBptn\fP \-\- Pattern .TP .B Returns Query range .UNINDENT .INDENT 7.0 .TP .B Z_OP = [\(aq<\(aq, \(aq<=\(aq, \(aq=\(aq, \(aq>=\(aq, \(aq>\(aq] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.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 dict will be returned for that package. .INDENT 0.0 .TP .B refresh force a refresh if set to True (default). If set to False it depends on zypper if a refresh is executed or not. .TP .B root operate on a different root directory. .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.clean_locks(root=None) Remove unused locks that do not currently (with regard to repositories used) lock any package. .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.clean_locks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.del_repo(repo, root=None) Delete a repo. .INDENT 7.0 .TP .B root operate on a different root directory. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.del_repo alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.diff(*paths, **kwargs) Return a formatted diff between current files and original in a package. NOTE: this function includes all files (configuration and not), but does not work on binary content. .sp The root parameter can also be passed via the keyword argument. .INDENT 7.0 .TP .B Parameters \fBpath\fP \-\- Full path to the installed file .TP .B Returns Difference string or raises and exception if examined file is binary. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.diff /etc/apache2/httpd.conf /etc/sudoers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.download(*packages, **kwargs) Download packages to the local disk. .INDENT 7.0 .TP .B refresh force a refresh if set to True. If set to False (default) it depends on zypper if a refresh is executed. .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.download httpd salt \(aq*\(aq pkg.download httpd postfix .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.file_dict(*packages, **kwargs) List the files that belong to a package, grouped by package. Not specifying any packages will return a list of \fIevery\fP file on the system\(aqs rpm database (not generally recommended). .sp The root parameter can also be passed via the keyword argument. .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.zypperpkg.file_list(*packages, **kwargs) List the files that belong to a package. Not specifying any packages will return a list of \fIevery\fP file on the system\(aqs rpm database (not generally recommended). .sp The root parameter can also be passed via the keyword argument. .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.zypperpkg.get_repo(repo, root=None, **kwargs) Display a repo. .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.get_repo alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.hold(name=None, pkgs=None, root=None, **kwargs) New in version 3003. .sp Add a package hold. Specify one of \fBname\fP and \fBpkgs\fP\&. .INDENT 7.0 .TP .B name A package name to hold, or a comma\-separated list of package names to hold. .TP .B pkgs A list of packages to hold. The \fBname\fP parameter will be ignored if this option is passed. .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.hold <package name> salt \(aq*\(aq pkg.hold <package1>,<package2>,<package3> salt \(aq*\(aq pkg.hold pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.info_available(*names, **kwargs) Return the information of the named package available for the system. .INDENT 7.0 .TP .B refresh force a refresh if set to True (default). If set to False it depends on zypper if a refresh is executed or not. .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.info_available <package1> salt \(aq*\(aq pkg.info_available <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.info_installed(*names, **kwargs) Return the information of the named package(s), installed on the system. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnames\fP \-\- Names of the packages to get information about. .IP \(bu 2 \fBattr\fP \-\- .sp Comma\-separated package attributes. If no \(aqattr\(aq is specified, all available attributes returned. .INDENT 2.0 .TP .B Valid attributes are: version, vendor, release, build_date, build_date_time_t, install_date, install_date_time_t, build_host, group, source_rpm, arch, epoch, size, license, signature, packager, url, summary, description. .UNINDENT .IP \(bu 2 \fBerrors\fP \-\- .sp Handle RPM field errors. If \(aqignore\(aq is chosen, then various mistakes are simply ignored and omitted from the texts or strings. If \(aqreport\(aq is chonen, then a field with a mistake is not returned, instead a \(aqN/A (broken)\(aq (not available, broken) text is placed. .INDENT 2.0 .TP .B Valid attributes are: ignore, report .UNINDENT .IP \(bu 2 \fBall_versions\fP \-\- Include information for all versions of the packages installed on the minion. .IP \(bu 2 \fBroot\fP \-\- Operate on a different root directory. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.info_installed <package1> salt \(aq*\(aq pkg.info_installed <package1> <package2> <package3> ... salt \(aq*\(aq pkg.info_installed <package1> <package2> <package3> all_versions=True salt \(aq*\(aq pkg.info_installed <package1> attr=version,vendor all_versions=True salt \(aq*\(aq pkg.info_installed <package1> <package2> <package3> ... attr=version,vendor salt \(aq*\(aq pkg.info_installed <package1> <package2> <package3> ... attr=version,vendor errors=ignore salt \(aq*\(aq pkg.info_installed <package1> <package2> <package3> ... attr=version,vendor errors=report .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, downloadonly=None, skip_verify=False, version=None, ignore_repo_failure=False, no_recommends=False, root=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 zypper 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Install the passed package(s), add refresh=True to force a \(aqzypper refresh\(aq before package is installed. .INDENT 7.0 .TP .B name The name of the package to be installed. Note that this parameter is ignored if either \fBpkgs\fP or \fBsources\fP 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 \fBsources\fP option. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .UNINDENT .TP .B refresh force a refresh if set to True. If set to False (default) it depends on zypper if a refresh is executed. .TP .B fromrepo Specify a package repository to install from. .TP .B downloadonly Only download the packages, do not install. .TP .B skip_verify Skip the GPG verification check (e.g., \fB\-\-no\-gpg\-checks\fP) .TP .B version Can be either a version number, or the combination of a comparison operator (<, >, <=, >=, =) and a version number (ex. \(aq>1.2.3\-4\(aq). This parameter is ignored if \fBpkgs\fP or \fBsources\fP is passed. .TP .B resolve_capabilities If this option is set to True zypper will take capabilities into account. In this case names which are just provided by a package will get installed. Default is False. .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. A specific version number can be specified by using a single\-element dict representing the package and its version. As with the \fBversion\fP parameter above, comparison operators can be used to target a specific version of a package. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, {\(dqbar\(dq: \(dq1.2.3\-4\(dq}]\(aq salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, {\(dqbar\(dq: \(dq<1.2.3\-4\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B sources A list of RPM packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sources=\(aq[{\(dqfoo\(dq: \(dqsalt://foo.rpm\(dq},{\(dqbar\(dq: \(dqsalt://bar.rpm\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B ignore_repo_failure Zypper returns error code 106 if one of the repositories are not available for various reasons. In case to set strict check, this parameter needs to be set to True. Default: False. .TP .B no_recommends Do not install recommended packages, only required ones. .TP .B root operate on a different root directory. .TP .B diff_attr: If a list of package attributes is specified, returned value will contain them, eg.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: { \(aqold\(aq: { \(aqversion\(aq: \(aq<old\-version>\(aq, \(aqarch\(aq: \(aq<old\-arch>\(aq}, \(aqnew\(aq: { \(aqversion\(aq: \(aq<new\-version>\(aq, \(aqarch\(aq: \(aq<new\-arch>\(aq}}} .ft P .fi .UNINDENT .UNINDENT .sp Valid attributes are: \fBepoch\fP, \fBversion\fP, \fBrelease\fP, \fBarch\fP, \fBinstall_date\fP, \fBinstall_date_time_t\fP\&. .sp If \fBall\fP is specified, all valid attributes will be returned. .sp New in version 2018.3.0. .UNINDENT .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp If an attribute list is specified in \fBdiff_attr\fP, the dict will also contain any specified attribute, eg.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: { \(aqold\(aq: { \(aqversion\(aq: \(aq<old\-version>\(aq, \(aqarch\(aq: \(aq<old\-arch>\(aq}, \(aqnew\(aq: { \(aqversion\(aq: \(aq<new\-version>\(aq, \(aqarch\(aq: \(aq<new\-arch>\(aq}}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.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 dict will be returned for that package. .INDENT 7.0 .TP .B refresh force a refresh if set to True (default). If set to False it depends on zypper if a refresh is executed or not. .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.latest_version <package name> salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_downloaded(root=None, **kwargs) New in version 2017.7.0. .sp List prefetched packages downloaded by Zypper 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.zypperpkg.list_holds(pattern=None, full=True, root=None, **kwargs) New in version 3005. .sp List information on locked packages. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function returns the computed output of \fBlist_locks\fP to show exact locked packages. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B pattern Regular expression used to match the package name .TP .B full True Show the full hold definition including version and epoch. Set to \fBFalse\fP to return just the name of the package(s) being held. .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_holds salt \(aq*\(aq pkg.list_holds full=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_installed_patches(root=None, **kwargs) New in version 2017.7.0. .sp List installed advisory patches on the system. .INDENT 7.0 .TP .B root operate on a different root directory. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_installed_patches .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_installed_patterns(root=None) List installed patterns on the system. .INDENT 7.0 .TP .B root operate on a different root directory. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_installed_patterns .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_locks(root=None) List current package locks. .INDENT 7.0 .TP .B root operate on a different root directory. .UNINDENT .sp Return a dict containing the locked package with attributes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqcase_sensitive\(aq: \(aq<case_sensitive>\(aq, \(aqmatch_type\(aq: \(aq<match_type>\(aq \(aqtype\(aq: \(aq<type>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_locks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_patches(refresh=False, root=None, **kwargs) New in version 2017.7.0. .sp List all known advisory patches from available repos. .INDENT 7.0 .TP .B refresh force a refresh if set to True. If set to False (default) it depends on zypper if a refresh is executed. .TP .B root operate on a different root directory. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_patches .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_patterns(refresh=False, root=None) List all known patterns from available repos. .INDENT 7.0 .TP .B refresh force a refresh if set to True. If set to False (default) it depends on zypper if a refresh is executed. .TP .B root operate on a different root directory. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_patterns .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_pkgs(versions_as_list=False, root=None, includes=None, **kwargs) List the packages currently installed as a dict. By default, the dict contains versions as a comma separated string: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>[,<version>...]\(aq} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B versions_as_list: If set to true, the versions are provided as a list .sp {\(aq<package_name>\(aq: [\(aq<version>\(aq, \(aq<version>\(aq]} .TP .B root: operate on a different root directory. .TP .B includes: List of types of packages to include (package, patch, pattern, product) By default packages are always included .TP .B attr: If a list of package attributes is specified, returned value will contain them in addition to version, eg.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package_name>\(aq: [{\(aqversion\(aq : \(aqversion\(aq, \(aqarch\(aq : \(aqarch\(aq}]} .ft P .fi .UNINDENT .UNINDENT .sp Valid attributes are: \fBepoch\fP, \fBversion\fP, \fBrelease\fP, \fBarch\fP, \fBinstall_date\fP, \fBinstall_date_time_t\fP\&. .sp If \fBall\fP is specified, all valid attributes will be returned. .INDENT 7.0 .INDENT 3.5 New in version 2018.3.0. .UNINDENT .UNINDENT .TP .B removed: not supported .TP .B purge_desired: not supported .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 attr=version,arch salt \(aq*\(aq pkg.list_pkgs attr=\(aq[\(dqversion\(dq, \(dqarch\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_products(all=False, refresh=False, root=None) List all available or installed SUSE products. .INDENT 7.0 .TP .B all List all products available or only installed. Default is False. .TP .B refresh force a refresh if set to True. If set to False (default) it depends on zypper if a refresh is executed. .TP .B root operate on a different root directory. .UNINDENT .sp Includes handling for OEM products, which read the OEM productline file and overwrite the release value. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_products salt \(aq*\(aq pkg.list_products all=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_provides(root=None, **kwargs) New in version 2018.3.0. .sp List package provides of installed packages as a dict. {\(aq<provided_name>\(aq: [\(aq<package_name>\(aq, \(aq<package_name>\(aq, ...]} .INDENT 7.0 .TP .B root operate on a different root directory. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_provides .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_repo_pkgs(*args, **kwargs) New in version 2017.7.5,2018.3.1. .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. This is recommended as it speeds up the function considerably. .sp This function can be helpful in discovering the version or repo to specify in a \fI\%pkg.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. If \fBbyrepo\fP is set to \fBTrue\fP, then the return dictionary will contain repository names at the top level, and each repository will map packages to lists of version numbers. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # With byrepo=False (default) { \(aqbash\(aq: [\(aq4.3\-83.3.1\(aq, \(aq4.3\-82.6\(aq], \(aqvim\(aq: [\(aq7.4.326\-12.1\(aq] } { \(aqOSS\(aq: { \(aqbash\(aq: [\(aq4.3\-82.6\(aq], \(aqvim\(aq: [\(aq7.4.326\-12.1\(aq] }, \(aqOSS Update\(aq: { \(aqbash\(aq: [\(aq4.3\-83.3.1\(aq] } } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B fromrepo None Only include results from the specified repo(s). Multiple repos can be specified, comma\-separated. .TP .B byrepo False When \fBTrue\fP, the return data for each package will be organized by repository. .TP .B root operate on a different root directory. .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 salt \(aq*\(aq pkg.list_repo_pkgs \(aqpython2\-*\(aq byrepo=True salt \(aq*\(aq pkg.list_repo_pkgs \(aqpython2\-*\(aq fromrepo=\(aqOSS Updates\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_repos(root=None, **kwargs) Lists all repos. .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_repos .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_updates(refresh=True, root=None, **kwargs) This function is an alias of \fBlist_upgrades\fP\&. .INDENT 7.0 .INDENT 3.5 List all available package upgrades on this system .INDENT 0.0 .TP .B refresh force a refresh if set to True (default). If set to False it depends on zypper if a refresh is executed. .TP .B root operate on a different root directory. .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.list_upgrades(refresh=True, root=None, **kwargs) List all available package upgrades on this system .INDENT 7.0 .TP .B refresh force a refresh if set to True (default). If set to False it depends on zypper if a refresh is executed. .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_upgrades .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.mod_repo(repo, **kwargs) Modify one or more values for a repo. If the repo does not exist, it will be created, so long as the following values are specified: .INDENT 7.0 .TP .B repo or alias alias by which Zypper refers to the repo .TP .B url, mirrorlist or baseurl the URL for Zypper to reference .TP .B enabled Enable or disable (True or False) repository, but do not remove if disabled. .TP .B name This is used as the descriptive name value in the repo file. .TP .B refresh Enable or disable (True or False) auto\-refresh of the repository. .TP .B cache Enable or disable (True or False) RPM files caching. .TP .B gpgcheck Enable or disable (True or False) GPG check for this repository. .TP .B gpgautoimport False If set to True, automatically trust and import public GPG key for the repository. .TP .B root operate on a different root directory. .UNINDENT .sp Key/Value pairs may also be removed from a repo\(aqs configuration by setting a key to a blank value. Bear in mind that a name cannot be deleted, and a URL can only be deleted if a \fBmirrorlist\fP is specified (or vice versa). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.mod_repo alias alias=new_alias salt \(aq*\(aq pkg.mod_repo alias url= mirrorlist=http://host.com/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.modified(*packages, **flags) List the modified files that belong to a package. Not specifying any packages will return a list of _all_ modified files on the system\(aqs RPM database. .sp New in version 2015.5.0. .sp Filtering by flags (True or False): .INDENT 7.0 .TP .B size Include only files where size changed. .TP .B mode Include only files which file\(aqs mode has been changed. .TP .B checksum Include only files which MD5 checksum has been changed. .TP .B device Include only files which major and minor numbers has been changed. .TP .B symlink Include only files which are symbolic link contents. .TP .B owner Include only files where owner has been changed. .TP .B group Include only files where group has been changed. .TP .B time Include only files where modification time of the file has been changed. .TP .B capabilities Include only files where capabilities differ or not. Note: supported only on newer RPM versions. .TP .B root operate on a different root directory. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.modified salt \(aq*\(aq pkg.modified httpd salt \(aq*\(aq pkg.modified httpd postfix salt \(aq*\(aq pkg.modified httpd owner=True group=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.normalize_name(name) Strips the architecture from the specified package name, if necessary. Circumstances where this would be done include: .INDENT 7.0 .IP \(bu 2 If the arch is 32 bit and the package name ends in a 32\-bit arch. .IP \(bu 2 If the arch matches the OS arch, or is \fBnoarch\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.normalize_name zsh.x86_64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.owner(*paths, **kwargs) Return the name of the package that owns the file. Multiple file paths can be passed. 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 The root parameter can also be passed via the keyword argument. .sp CLI Examples: .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 /etc/httpd/conf/httpd.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.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.x86_64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.purge(name=None, pkgs=None, root=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 zypper 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Recursively remove a package and all dependencies which were installed with it, this will call a \fBzypper \-n remove \-u\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. .TP .B root Operate on a different root directory. .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 <package name> salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3> salt \(aq*\(aq pkg.purge pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.refresh_db(force=None, root=None, gpgautoimport=False, **kwargs) Trigger a repository refresh by calling \fBzypper refresh\fP\&. Refresh will run with \fB\-\-force\fP if the \(dqforce=True\(dq flag is passed on the CLI or \fBrefreshdb_force\fP is set to \fBtrue\fP in the pillar. The CLI option overrides the pillar setting. .sp It will return a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<database name>\(aq: Bool} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B gpgautoimport False If set to True, automatically trust and import public GPG key for the repository. .sp New in version 3007.0. .TP .B repos Refresh just the specified repos .sp New in version 3007.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.refresh_db [force=true|false] .ft P .fi .UNINDENT .UNINDENT .sp Pillar Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C zypper: refreshdb_force: false .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.remove(name=None, pkgs=None, root=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 zypper 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Remove packages with \fBzypper \-n 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. .TP .B root Operate on a different root directory. .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 <package name> salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3> salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3007.0: Can now remove also PTF packages which require a different handling in the backend. .sp Can now remove also PTF packages which require a different handling in the backend. .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.resolve_capabilities(pkgs, refresh=False, root=None, **kwargs) New in version 2018.3.0. .sp Convert name provides in \fBpkgs\fP into real package names if \fBresolve_capabilities\fP parameter is set to True. In case of \fBresolve_capabilities\fP is set to False the package list is returned unchanged. .INDENT 7.0 .TP .B refresh force a refresh if set to True. If set to False (default) it depends on zypper if a refresh is executed. .TP .B root operate on a different root directory. .TP .B resolve_capabilities If this option is set to True the input will be checked if a package with this name exists. If not, this function will search for a package which provides this name. If one is found the output is exchanged with the real package name. In case this option is set to False (Default) the input will be returned unchanged. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.resolve_capabilities resolve_capabilities=True w3m_ssl .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.search(criteria, refresh=False, **kwargs) List known packages, available to the system. .INDENT 7.0 .TP .B refresh force a refresh if set to True. If set to False (default) it depends on zypper if a refresh is executed. .TP .B match (str) One of \fIexact\fP, \fIwords\fP, \fIsubstrings\fP\&. Search for an \fIexact\fP match or for the whole \fIwords\fP only. Default to \fIsubstrings\fP to patch partial words. .TP .B provides (bool) Search for packages which provide the search strings. .TP .B recommends (bool) Search for packages which recommend the search strings. .TP .B requires (bool) Search for packages which require the search strings. .TP .B suggests (bool) Search for packages which suggest the search strings. .TP .B conflicts (bool) Search packages conflicting with search strings. .TP .B obsoletes (bool) Search for packages which obsolete the search strings. .TP .B file_list (bool) Search for a match in the file list of packages. .TP .B search_descriptions (bool) Search also in package summaries and descriptions. .TP .B case_sensitive (bool) Perform case\-sensitive search. .TP .B installed_only (bool) Show only installed packages. .TP .B not_installed_only (bool) Show only packages which are not installed. .TP .B details (bool) Show version and repository .TP .B root operate on a different root directory. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.search <criteria> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.services_need_restart(root=None, **kwargs) New in version 3003. .sp List services that use files which have been changed by the package manager. It might be needed to restart them. .INDENT 7.0 .TP .B root operate on a different root directory. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.services_need_restart .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.unhold(name=None, pkgs=None, root=None, **kwargs) New in version 3003. .sp Remove a package hold. .INDENT 7.0 .TP .B name A package name to unhold, or a comma\-separated list of package names to unhold. .TP .B pkgs A list of packages to unhold. The \fBname\fP parameter will be ignored if this option is passed. .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.unhold <package name> salt \(aq*\(aq pkg.unhold <package1>,<package2>,<package3> salt \(aq*\(aq pkg.unhold pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.upgrade(name=None, pkgs=None, refresh=True, dryrun=False, dist_upgrade=False, fromrepo=None, novendorchange=False, skip_verify=False, no_recommends=False, root=None, diff_attr=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 zypper 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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Run a full system upgrade, a zypper upgrade .INDENT 7.0 .TP .B name The name of the package to be installed. Note that this parameter is ignored if \fBpkgs\fP is passed or if \fBdryrun\fP is set to True. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install name=<package name> .ft P .fi .UNINDENT .UNINDENT .TP .B pkgs A list of packages to install from a software repository. Must be passed as a python list. Note that this parameter is ignored if \fBdryrun\fP is set to True. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B refresh force a refresh if set to True (default). If set to False it depends on zypper if a refresh is executed. .TP .B dryrun If set to True, it creates a debug solver log file and then perform a dry\-run upgrade (no changes are made). Default: False .TP .B dist_upgrade Perform a system dist\-upgrade. Default: False .TP .B fromrepo Specify a list of package repositories to upgrade from. Default: None .TP .B novendorchange If set to True, no allow vendor changes. Default: False .TP .B skip_verify Skip the GPG verification check (e.g., \fB\-\-no\-gpg\-checks\fP) .TP .B no_recommends Do not install recommended packages, only required ones. .TP .B root Operate on a different root directory. .TP .B diff_attr: If a list of package attributes is specified, returned value will contain them, eg.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: { \(aqold\(aq: { \(aqversion\(aq: \(aq<old\-version>\(aq, \(aqarch\(aq: \(aq<old\-arch>\(aq}, \(aqnew\(aq: { \(aqversion\(aq: \(aq<new\-version>\(aq, \(aqarch\(aq: \(aq<new\-arch>\(aq}}} .ft P .fi .UNINDENT .UNINDENT .sp Valid attributes are: \fBepoch\fP, \fBversion\fP, \fBrelease\fP, \fBarch\fP, \fBinstall_date\fP, \fBinstall_date_time_t\fP\&. .sp If \fBall\fP is specified, all valid attributes will be returned. .sp New in version 3006.0. .UNINDENT .sp Returns a dictionary containing the changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp If an attribute list is specified in \fBdiff_attr\fP, the dict will also contain any specified attribute, eg.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \&.. code\-block:: python .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B {\(aq<package>\(aq: { .INDENT 7.0 .TP .B \(aqold\(aq: { \(aqversion\(aq: \(aq<old\-version>\(aq, \(aqarch\(aq: \(aq<old\-arch>\(aq}, .TP .B \(aqnew\(aq: { \(aqversion\(aq: \(aq<new\-version>\(aq, \(aqarch\(aq: \(aq<new\-arch>\(aq}}} .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade salt \(aq*\(aq pkg.upgrade name=mypackage salt \(aq*\(aq pkg.upgrade pkgs=\(aq[\(dqpackage1\(dq, \(dqpackage2\(dq]\(aq salt \(aq*\(aq pkg.upgrade dist_upgrade=True fromrepo=\(aq[\(dqMyRepoName\(dq]\(aq novendorchange=True salt \(aq*\(aq pkg.upgrade dist_upgrade=True dryrun=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.upgrade_available(name, **kwargs) Check whether or not an upgrade is available for a given package .INDENT 7.0 .TP .B refresh force a refresh if set to True (default). If set to False it depends on zypper if a refresh is executed or not. .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.upgrade_available <package name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.verify(*names, **kwargs) Runs an rpm \-Va on a system, and returns the results in a dict .sp Files with an attribute of config, doc, ghost, license or readme in the package header can be ignored using the \fBignore_types\fP keyword argument. .sp The root parameter can also be passed via the keyword argument. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.verify salt \(aq*\(aq pkg.verify httpd salt \(aq*\(aq pkg.verify \(aqhttpd postfix\(aq salt \(aq*\(aq pkg.verify \(aqhttpd postfix\(aq ignore_types=[\(aqconfig\(aq,\(aqdoc\(aq] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.version(*names, **kwargs) Returns a string representing the package version or an empty dict if not installed. If more than one package name is specified, a dict of name/version pairs is returned. .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.version <package name> salt \(aq*\(aq pkg.version <package1> <package2> <package3> ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypperpkg.version_cmp(ver1, ver2, ignore_epoch=False, **kwargs) New in version 2015.5.4. .sp Do a cmp\-style comparison on two packages. Return \-1 if ver1 < ver2, 0 if ver1 == ver2, and 1 if ver1 > ver2. 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\-001\(aq \(aq0.2.0.1\-002\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS executors modules .TS center; |l|l|. _ T{ \fI\%direct_call\fP T} T{ Direct call executor module T} _ T{ \fI\%docker\fP T} T{ T} _ T{ \fI\%splay\fP T} T{ Splay function calls across targeted minions T} _ T{ \fI\%sudo\fP T} T{ Sudo executor module T} _ T{ \fI\%transactional_update\fP T} T{ Transactional executor module T} _ .TE .SS salt.executors.direct_call .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 .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%docker Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Docker executor module .sp New in version 2019.2.0. .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 .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 .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 <sudo_user> 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 salt.executors.transactional_update module .sp Transactional executor module .sp New in version 3004. .INDENT 0.0 .TP .B salt.executors.transactional_update.execute(opts, data, func, args, kwargs) Delegate into transactional_update module .sp The \fBtransactional_update\fP module support the execution of functions inside a transaction, as support apply a state (via \fBapply\fP, \fBsls\fP, \fBsingle\fP or \fBhighstate\fP). .sp This execution module can be used to route some Salt modules and functions to be executed inside the transaction snapshot. .sp Add this executor in the minion configuration file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C module_executors: \- transactional_update \- direct_call .ft P .fi .UNINDENT .UNINDENT .sp Or use the command line parameter: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-module\-executors=\(aq[transactional_update, direct_call]\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp You can also schedule a reboot if needed: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-module\-executors=\(aq[transactional_update]\(aq state.sls stuff activate_transaction=True .ft P .fi .UNINDENT .UNINDENT .sp There are some configuration parameters supported: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Replace the list of default modules that all the functions # are delegated to \(gatransactional_update.call()\(ga delegated_modules: [cmd, pkg] # Replace the list of default functions that are delegated to # \(gatransactional_update.call()\(ga delegated_functions: [pip.install] # Expand the default list of modules add_delegated_modules: [ansible] # Expand the default list of functions add_delegated_functions: [file.copy] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS fileserver modules .TS center; |l|l|. _ T{ \fI\%gitfs\fP T} T{ Git Fileserver Backend T} _ T{ \fI\%hgfs\fP T} T{ Mercurial Fileserver Backend T} _ T{ \fI\%minionfs\fP T} T{ Fileserver backend which serves files pushed to the Master T} _ T{ \fI\%roots\fP T} T{ The default file server backend T} _ T{ \fI\%s3fs\fP T} T{ Amazon S3 Fileserver Backend T} _ T{ \fI\%svnfs\fP T} T{ Subversion Fileserver Backend T} _ .TE .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 \fI\%fileserver_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 (\fI\%gitfs_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 \fI\%GitFS Walkthrough\fP\&. .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 \fI\%here\fP\&. .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 \fI\%fileserver_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 \fI\%fileserver_backend\fP option in the salt master config file. .sp This fileserver has an additional option \fI\%hgfs_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 \fI\%hgfs_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 \fI\%hgfs_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 \fI\%cp.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, \fI\%file_recv\fP needs to be set to \fBTrue\fP in the master config file (otherwise \fI\%cp.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: \fI\%minionfs_whitelist\fP, \fI\%minionfs_blacklist\fP, \fI\%minionfs_mountpoint\fP, and \fI\%minionfs_env\fP\&. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%MinionFS Backend Walkthrough\fP .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 \fI\%fileserver_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 \fI\%fileserver_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 \fI\%file_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 \fI\%fileserver_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://<bucket name>/<environment>/<files> .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This fileserver back\-end will by default sync all buckets on every fileserver update. .sp If you want files to be only populated in the cache when requested, you can disable this in the master config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s3.s3_sync_on_update: False .ft P .fi .UNINDENT .UNINDENT .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 \fI\%fileserver_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 \fI\%svnfs_trunk\fP, \fI\%svnfs_branches\fP, and \fI\%svnfs_tags\fP\&. \fI\%svnfs_mountpoint\fP was also added. Finally, support for per\-remote configuration parameters was added. See the \fI\%documentation\fP for more information. .SS grains modules .TS center; |l|l|. _ T{ \fI\%chronos\fP T} T{ Generate chronos proxy minion grains. T} _ T{ \fI\%cimc\fP T} T{ Generate baseline proxy minion grains for cimc hosts. T} _ T{ \fI\%core\fP T} T{ The static grains, these are the core, or built in grains. T} _ T{ \fI\%disks\fP T} T{ Detect disks T} _ T{ \fI\%esxi\fP T} T{ Generate baseline proxy minion grains for ESXi hosts. T} _ T{ \fI\%extra\fP T} T{ T} _ T{ \fI\%fibre_channel\fP T} T{ Grains for Fibre Channel WWN\(aqs. T} _ T{ \fI\%fx2\fP T} T{ Generate baseline proxy minion grains for Dell FX2 chassis. T} _ T{ \fI\%iscsi\fP T} T{ Grains for iSCSI Qualified Names (IQN). T} _ T{ \fI\%junos\fP T} T{ Grains for junos. T} _ T{ \fI\%lvm\fP T} T{ Detect LVM Volumes T} _ T{ \fI\%marathon\fP T} T{ Generate marathon proxy minion grains. T} _ T{ \fI\%mdadm\fP T} T{ Detect MDADM RAIDs T} _ T{ \fI\%mdata\fP T} T{ SmartOS Metadata grain provider T} _ T{ \fI\%metadata\fP T} T{ Grains from cloud metadata servers at 169.254.169.254 T} _ T{ \fI\%metadata_gce\fP T} T{ Grains from cloud metadata servers at 169.254.169.254 in google compute engine T} _ T{ \fI\%minion_process\fP T} T{ Set grains describing the minion process. T} _ T{ \fI\%napalm\fP T} T{ NAPALM Grains T} _ T{ \fI\%nvme\fP T} T{ Grains for NVMe Qualified Names (NQN). T} _ T{ \fI\%nxos\fP T} T{ Grains for Cisco NX\-OS minions T} _ T{ \fI\%opts\fP T} T{ Simple grain to merge the opts into the grains directly if the grain_opts configuration value is set. T} _ T{ \fI\%package\fP T} T{ Grains for detecting what type of package Salt is using T} _ T{ \fI\%panos\fP T} T{ Generate baseline proxy minion grains for panos hosts. T} _ T{ \fI\%pending_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{ \fI\%philips_hue\fP T} T{ Static grains for the Philips HUE lamps T} _ T{ \fI\%rest_sample\fP T} T{ Generate baseline proxy minion grains T} _ T{ \fI\%smartos\fP T} T{ SmartOS grain provider T} _ T{ \fI\%ssh_sample\fP T} T{ Generate baseline proxy minion grains T} _ T{ \fI\%zfs\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 <ip>\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 \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be deprecated in a future release of Salt. VMware strongly recommends using the \fI\%VMware Salt extensions\fP instead of the ESXi module. Because the Salt extensions are newer and actively supported by VMware, they are more compatible with current versions of ESXi and they work well with the latest features in the VMware product line. .UNINDENT .UNINDENT .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 .INDENT 0.0 .TP .B salt.grains.extra.transactional() Determine if the system is transactional. .UNINDENT .INDENT 0.0 .TP .B salt.grains.extra.uefi() Populate UEFI grains. .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 2017.7.0. .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.metadata_gce .sp Grains from cloud metadata servers at 169.254.169.254 in google compute engine .sp New in version 3005. .INDENT 0.0 .TP .B depends requests .UNINDENT .sp To enable these grains that pull from the \fI\%http://169.254.169.254/computeMetadata/v1/\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_gce.metadata() Takes no arguments, returns a dictionary of metadata values from Google. .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: \fI\%NAPALM 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: .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.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 \(dqshut\(dq .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 New in version 2016.11.0. .sp For documentation on setting up the nxos proxy minion look in the documentation for \fI\%salt.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.package .sp Grains for detecting what type of package Salt is using .sp New in version 3007.0. .INDENT 0.0 .TP .B salt.grains.package.package() Function to determine if the user is currently using onedir, pip or system level package of Salt. .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.module.cmdmod .TP .B platform SmartOS .UNINDENT .sp New in version 2017.7.0. .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 netapi modules .TS center; |l|l|. _ T{ \fI\%rest_cherrypy\fP T} T{ A script to start the CherryPy WSGI server T} _ T{ \fI\%rest_tornado\fP T} T{ T} _ T{ \fI\%rest_wsgi\fP T} T{ A minimalist REST API for Salt T} _ .TE .SS rest_cherrypy .INDENT 0.0 .IP \(bu 2 \fI\%A REST API for Salt\fP .INDENT 2.0 .IP \(bu 2 \fI\%Authentication\fP .IP \(bu 2 \fI\%Usage\fP .IP \(bu 2 \fI\%Content negotiation\fP .UNINDENT .IP \(bu 2 \fI\%Performance Expectations and Recommended Usage\fP .INDENT 2.0 .IP \(bu 2 \fI\%Long\-Running HTTP Connections\fP .IP \(bu 2 \fI\%Timeouts\fP .IP \(bu 2 \fI\%Best Practices\fP .IP \(bu 2 \fI\%Performance Tuning\fP .IP \(bu 2 \fI\%Future Plans\fP .UNINDENT .IP \(bu 2 \fI\%Deployment\fP .INDENT 2.0 .IP \(bu 2 \fI\%salt\-api using the CherryPy server\fP .IP \(bu 2 \fI\%Using a WSGI\-compliant web server\fP .UNINDENT .UNINDENT .sp A script to start the CherryPy WSGI server .sp This is run by \fBsalt\-api\fP and started in a multiprocess. .SS A REST API for Salt .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This module is Experimental on Windows platforms and supports limited configurations: .INDENT 0.0 .IP \(bu 2 doesn\(aqt support PAM authentication (i.e. external_auth: auto) .IP \(bu 2 doesn\(aqt support SSL (i.e. disable_ssl: True) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 CherryPy Python module. .sp Note: there is a \fI\%known SSL traceback for CherryPy versions 3.2.5 through 3.7.x\fP\&. Please use version 3.2.3 or the latest 10.x version instead. .UNINDENT .TP .B optdepends .INDENT 7.0 .IP \(bu 2 ws4py Python module for websockets support. .UNINDENT .TP .B client_libraries .INDENT 7.0 .IP \(bu 2 Java: \fI\%https://github.com/SUSE/salt\-netapi\-client\fP .IP \(bu 2 Python: \fI\%https://github.com/saltstack/pepper\fP .UNINDENT .TP .B setup All steps below are performed on the machine running the Salt Master daemon. Configuration goes into the Master configuration file. .INDENT 7.0 .IP 1. 3 Install \fBsalt\-api\fP\&. (This step varies between OS and Linux distros. Some package systems have a split package, others include salt\-api in the main Salt package. Ensure the \fBsalt\-api \-\-version\fP output matches the \fBsalt \-\-version\fP output.) .IP 2. 3 Install CherryPy. (Read the version caveat in the section above.) .IP 3. 3 Optional: generate self\-signed SSL certificates. .sp Using a secure HTTPS connection is strongly recommended since Salt eauth authentication credentials will be sent over the wire. .INDENT 3.0 .IP 1. 3 Install the PyOpenSSL package. .IP 2. 3 Generate a self\-signed certificate using the \fI\%create_self_signed_cert()\fP execution function. .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local tls.create_self_signed_cert .ft P .fi .UNINDENT .UNINDENT .UNINDENT .IP 4. 3 Edit the master config to create at least one external auth user or group following the \fI\%full external auth instructions\fP\&. .IP 5. 3 Edit the master config with the following production\-ready example to enable the \fBrest_cherrypy\fP module. (Adjust cert paths as needed, or disable SSL (not recommended!).) .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C rest_cherrypy: port: 8000 ssl_crt: /etc/pki/tls/certs/localhost.crt ssl_key: /etc/pki/tls/certs/localhost.key .ft P .fi .UNINDENT .UNINDENT .IP 6. 3 Restart the \fBsalt\-master\fP daemon. .IP 7. 3 Start the \fBsalt\-api\fP daemon. .UNINDENT .TP .B configuration All available configuration options are detailed below. These settings configure the CherryPy HTTP server and do not apply when using an external server such as Apache or Nginx. .INDENT 7.0 .TP .B port \fBRequired\fP .sp The port for the webserver to listen on. .TP .B host \fB0.0.0.0\fP The socket interface for the HTTP server to listen on. .TP .B debug \fBFalse\fP Starts the web server in development mode. It will reload itself when the underlying code is changed and will output more debugging info. .TP .B log_access_file Path to a file to write HTTP access logs. .sp New in version 2016.11.0. .TP .B log_error_file Path to a file to write HTTP error logs. .sp New in version 2016.11.0. .TP .B ssl_crt The path to a SSL certificate. (See below) .TP .B ssl_key The path to the private key for your SSL certificate. (See below) .TP .B ssl_chain (Optional when using PyOpenSSL) the certificate chain to pass to \fBContext.load_verify_locations\fP\&. .TP .B disable_ssl A flag to disable SSL. Warning: your Salt authentication credentials will be sent in the clear! .TP .B webhook_disable_auth False The \fI\%Webhook\fP URL requires authentication by default but external services cannot always be configured to send authentication. See the Webhook documentation for suggestions on securing this interface. .TP .B webhook_url /hook Configure the URL endpoint for the \fI\%Webhook\fP entry point. .TP .B thread_pool \fB100\fP The number of worker threads to start up in the pool. .TP .B socket_queue_size \fB30\fP Specify the maximum number of HTTP connections to queue. .TP .B expire_responses True Whether to check for and kill HTTP responses that have exceeded the default timeout. .sp Deprecated since version 2016.11.9,2017.7.3,2018.3.0: The \(dqexpire_responses\(dq configuration setting, which corresponds to the \fBtimeout_monitor\fP setting in CherryPy, is no longer supported in CherryPy versions >= 12.0.0. .TP .B max_request_body_size \fB1048576\fP Maximum size for the HTTP request body. .TP .B collect_stats False Collect and report statistics about the CherryPy server .sp Reports are available via the \fI\%Stats\fP URL. .TP .B stats_disable_auth False Do not require authentication to access the \fB/stats\fP endpoint. .sp New in version 2018.3.0. .TP .B static A filesystem path to static HTML/JavaScript/CSS/image assets. .TP .B static_path \fB/static\fP The URL prefix to use when serving static assets out of the directory specified in the \fBstatic\fP setting. .TP .B enable_sessions \fBTrue\fP Enable or disable all endpoints that rely on session cookies. This can be useful to enforce only header\-based authentication. .sp New in version 2017.7.0. .TP .B app \fBindex.html\fP A filesystem path to an HTML file that will be served as a static file. This is useful for bootstrapping a single\-page JavaScript app. .sp Warning! If you set this option to a custom web application, anything that uses cookie\-based authentication is vulnerable to XSRF attacks. Send the custom \fBX\-Auth\-Token\fP header instead and consider disabling the \fBenable_sessions\fP setting. .sp Changed in version 2017.7.0: Add a proof\-of\-concept JavaScript single\-page app. .TP .B app_path \fB/app\fP The URL prefix to use for serving the HTML file specified in the \fBapp\fP setting. This should be a simple name containing no slashes. .sp Any path information after the specified path is ignored; this is useful for apps that utilize the HTML5 history API. .TP .B root_prefix \fB/\fP A URL path to the main entry point for the application. This is useful for serving multiple applications from the same URL. .UNINDENT .UNINDENT .SS Authentication .sp Authentication is performed by passing a session token with each request. Tokens are generated via the \fI\%Login\fP URL. .sp The token may be sent in one of two ways: as a custom header or as a session cookie. The latter is far more convenient for clients that support cookies. .INDENT 0.0 .IP \(bu 2 Include a custom header named \fIX\-Auth\-Token\fP\&. .sp For example, using curl: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C curl \-sSk https://localhost:8000/login \e \-H \(aqAccept: application/x\-yaml\(aq \e \-d username=saltdev \e \-d password=saltdev \e \-d eauth=pam .ft P .fi .UNINDENT .UNINDENT .sp Copy the \fBtoken\fP value from the output and include it in subsequent requests: .INDENT 2.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 \-d client=local \e \-d tgt=\(aq*\(aq \e \-d fun=test.ping .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Sent via a cookie. This option is a convenience for HTTP clients that automatically handle cookie support (such as browsers). .sp For example, using curl: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C # Write the cookie file: curl \-sSk https://localhost:8000/login \e \-c ~/cookies.txt \e \-H \(aqAccept: application/x\-yaml\(aq \e \-d username=saltdev \e \-d password=saltdev \e \-d eauth=auto # Read the cookie file: curl \-sSk https://localhost:8000 \e \-b ~/cookies.txt \e \-H \(aqAccept: application/x\-yaml\(aq \e \-d client=local \e \-d tgt=\(aq*\(aq \e \-d fun=test.ping .ft P .fi .UNINDENT .UNINDENT .sp Another example using the \fBrequests\fP library in Python: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C >>> import requests >>> session = requests.Session() >>> session.post(\(aqhttp://localhost:8000/login\(aq, json={ \(aqusername\(aq: \(aqsaltdev\(aq, \(aqpassword\(aq: \(aqsaltdev\(aq, \(aqeauth\(aq: \(aqauto\(aq, }) <Response [200]> >>> resp = session.post(\(aqhttp://localhost:8000\(aq, json=[{ \(aqclient\(aq: \(aqlocal\(aq, \(aqtgt\(aq: \(aq*\(aq, \(aqfun\(aq: \(aqtest.arg\(aq, \(aqarg\(aq: [\(aqfoo\(aq, \(aqbar\(aq], \(aqkwarg\(aq: {\(aqbaz\(aq: \(aqBaz!\(aq}, }]) >>> resp.json() {u\(aqreturn\(aq: [{ ...snip... }]} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 You can bypass the session handling via the \fI\%Run\fP URL. .UNINDENT .UNINDENT .SS Usage .sp This interface directly exposes Salt\(aqs \fI\%Python API\fP\&. Everything possible at the CLI is possible through the Python API. Commands are executed on the Salt Master. .sp The root URL (\fB/\fP) is RPC\-like in that it accepts instructions in the request body for what Salt functions to execute, and the response contains the result of those function calls. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl \-sSi https://localhost:8000 \-H \(aqContent\-type: application/json\(aq \-d \(aq[{ \(dqclient\(dq: \(dqlocal\(dq, \(dqtgt\(dq: \(dq*\(dq, \(dqfun\(dq: \(dqtest.ping\(dq }]\(aq HTTP/1.1 200 OK Content\-Type: application/json [...snip...] {\(dqreturn\(dq: [{\(dqjerry\(dq: true}]} .ft P .fi .UNINDENT .UNINDENT .sp The request body must be an array of commands. Use this workflow to build a command: .INDENT 0.0 .IP 1. 3 Choose a client interface. .IP 2. 3 Choose a function. .IP 3. 3 Fill out the remaining parameters needed for the chosen client. .UNINDENT .sp The \fBclient\fP field is a reference to the main Python classes used in Salt\(aqs Python API. Read the full \fI\%Client APIs\fP documentation, but in short: .INDENT 0.0 .IP \(bu 2 \(dqlocal\(dq uses \fI\%LocalClient\fP which sends commands to Minions. Equivalent to the \fBsalt\fP CLI command. .IP \(bu 2 \(dqrunner\(dq uses \fI\%RunnerClient\fP which invokes runner modules on the Master. Equivalent to the \fBsalt\-run\fP CLI command. .IP \(bu 2 \(dqwheel\(dq uses \fI\%WheelClient\fP which invokes wheel modules on the Master. Wheel modules do not have a direct CLI equivalent but they typically manage Master\-side resources such as state files, pillar files, the Salt config files, and the \fI\%key wheel module\fP exposes similar functionality as the \fBsalt\-key\fP CLI command. .UNINDENT .sp Most clients have variants like synchronous or asynchronous execution as well as others like batch execution. See the \fI\%full list of client interfaces\fP\&. .sp Each client requires different arguments and sometimes has different syntax. For example, \fBLocalClient\fP requires the \fBtgt\fP argument because it forwards the command to Minions and the other client interfaces do not. \fBLocalClient\fP also takes \fBarg\fP (array) and \fBkwarg\fP (dictionary) arguments because these values are sent to the Minions and used to execute the requested function there. \fBRunnerClient\fP and \fBWheelClient\fP are executed directly on the Master and thus do not need or accept those arguments. .sp Read the method signatures in the client documentation linked above, but hopefully an example will help illustrate the concept. This example causes Salt to execute two functions \-\- the \fI\%test.arg execution function\fP using \fBLocalClient\fP and the \fI\%test.arg runner function\fP using \fBRunnerClient\fP; note the different structure for each command. The results for both are combined and returned as one response. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl \-b ~/cookies.txt \-sSi localhost:8000 \-H \(aqContent\-type: application/json\(aq \-d \(aq [ { \(dqclient\(dq: \(dqlocal\(dq, \(dqtgt\(dq: \(dq*\(dq, \(dqfun\(dq: \(dqtest.arg\(dq, \(dqarg\(dq: [\(dqpositional arg one\(dq, \(dqpositional arg two\(dq], \(dqkwarg\(dq: { \(dqkeyword arg one\(dq: \(dqHello from a minion\(dq, \(dqkeyword arg two\(dq: \(dqHello again from a minion\(dq } }, { \(dqclient\(dq: \(dqrunner\(dq, \(dqfun\(dq: \(dqtest.arg\(dq, \(dqkeyword arg one\(dq: \(dqHello from a master\(dq, \(dqkeyword arg two\(dq: \(dqRunners do not support positional args\(dq } ] \(aq HTTP/1.1 200 OK [...snip...] { \(dqreturn\(dq: [ { \(dqjerry\(dq: { \(dqargs\(dq: [ \(dqpositional arg one\(dq, \(dqpositional arg two\(dq ], \(dqkwargs\(dq: { \(dqkeyword arg one\(dq: \(dqHello from a minion\(dq, \(dqkeyword arg two\(dq: \(dqHello again from a minion\(dq, [...snip...] } }, [...snip; other minion returns here...] }, { \(dqargs\(dq: [], \(dqkwargs\(dq: { \(dqkeyword arg two\(dq: \(dqRunners do not support positional args\(dq, \(dqkeyword arg one\(dq: \(dqHello from a master\(dq } } ] } .ft P .fi .UNINDENT .UNINDENT .sp One more example, this time with more commonly used functions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-b /tmp/cookies.txt \-sSi localhost:8000 \-H \(aqContent\-type: application/json\(aq \-d \(aq [ { \(dqclient\(dq: \(dqlocal\(dq, \(dqtgt\(dq: \(dq*\(dq, \(dqfun\(dq: \(dqstate.sls\(dq, \(dqkwarg\(dq: { \(dqmods\(dq: \(dqapache\(dq, \(dqpillar\(dq: { \(dqlookup\(dq: { \(dqwwwdir\(dq: \(dq/srv/httpd/htdocs\(dq } } } }, { \(dqclient\(dq: \(dqrunner\(dq, \(dqfun\(dq: \(dqcloud.create\(dq, \(dqprovider\(dq: \(dqmy\-ec2\-provider\(dq, \(dqinstances\(dq: \(dqmy\-centos\-6\(dq, \(dqimage\(dq: \(dqami\-1624987f\(dq, \(dqdelvol_on_destroy\(dq, true } ] \(aq HTTP/1.1 200 OK [...snip...] { \(dqreturn\(dq: [ { \(dqjerry\(dq: { \(dqpkg_|\-install_apache_|\-httpd_|\-installed\(dq: { [...snip full state return here...] } } [...snip other minion returns here...] }, { [...snip full salt\-cloud output here...] } ] } .ft P .fi .UNINDENT .UNINDENT .SS Content negotiation .sp This REST interface is flexible in what data formats it will accept as well as what formats it will return (e.g., JSON, YAML, urlencoded). .INDENT 0.0 .IP \(bu 2 Specify the format of data in the request body by including the \fIContent\-Type\fP header. .IP \(bu 2 Specify the desired data format for the response body with the \fIAccept\fP header. .UNINDENT .sp We recommend the JSON format for most HTTP requests. urlencoded data is simple and cannot express complex data structures \-\- and that is often required for some Salt commands, such as starting a state run that uses Pillar data. Salt\(aqs CLI tool can reformat strings passed in at the CLI into complex data structures, and that behavior also works via salt\-api, but that can be brittle and since salt\-api can accept JSON it is best just to send JSON. .sp Here is an example of sending urlencoded data: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-sSik https://localhost:8000 \e \-b ~/cookies.txt \e \-d client=runner \e \-d fun=\(aqjobs.lookup_jid\(aq \e \-d jid=\(aq20150129182456704682\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .IP "urlencoded data caveats" .INDENT 0.0 .IP \(bu 2 Only a single command may be sent per HTTP request. .IP \(bu 2 Repeating the \fBarg\fP parameter multiple times will cause those parameters to be combined into a single list. .sp Note, some popular frameworks and languages (notably jQuery, PHP, and Ruby on Rails) will automatically append empty brackets onto repeated query string parameters. E.g., \fB?foo[]=fooone&foo[]=footwo\fP\&. This is \fBnot\fP supported; send \fB?foo=fooone&foo=footwo\fP instead, or send JSON or YAML. .UNINDENT .sp A note about \fBcurl\fP .sp The \fB\-d\fP flag to curl does \fInot\fP automatically urlencode data which can affect passwords and other data that contains characters that must be encoded. Use the \fB\-\-data\-urlencode\fP flag instead. E.g.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-ksi http://localhost:8000/login \e \-H \(dqAccept: application/json\(dq \e \-d username=\(aqmyapiuser\(aq \e \-\-data\-urlencode password=\(aq1234+\(aq \e \-d eauth=\(aqpam\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Performance Expectations and Recommended Usage .sp This module provides a thin wrapper around \fI\%Salt\(aqs Python API\fP\&. Executing a Salt command via rest_cherrypy is directly analogous to executing a Salt command via Salt\(aqs CLI (which also uses the Python API) \-\- they share the same semantics, performance characteristics, and 98% of the same code. As a rule\-of\-thumb: if you wouldn\(aqt do it at the CLI don\(aqt do it via this API. .SS Long\-Running HTTP Connections .sp The CherryPy server is a production\-ready, threading HTTP server written in Python. Because it makes use of a thread pool to process HTTP requests it is not ideally suited to maintaining large numbers of concurrent, synchronous connections. On moderate hardware with default settings it should top\-out at around 30 to 50 concurrent connections. .sp That number of long\-running, synchronous Salt processes is also not ideal. Like at the CLI, each Salt command run will start a process that instantiates its own \fBLocalClient\fP, which instantiates its own listener to the Salt event bus, and sends out its own periodic \fBsaltutil.find_job\fP queries to determine if a Minion is still running the command. Not exactly a lightweight operation. .SS Timeouts .sp In addition to the above resource overhead for long\-running connections, there are the usual HTTP timeout semantics for the CherryPy server, any HTTP client being used, as well as any hardware in between such as proxies, gateways, or load balancers. rest_cherrypy can be configured not to time\-out long responses via the \fBexpire_responses\fP setting, and both \fI\%LocalClient\fP and \fI\%RunnerClient\fP have their own timeout parameters that may be passed as top\-level keywords: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-b /tmp/cookies.txt \-sSi localhost:8000 \-H \(aqContent\-type: application/json\(aq \-d \(aq [ { \(dqclient\(dq: \(dqlocal\(dq, \(dqtgt\(dq: \(dq*\(dq, \(dqfun\(dq: \(dqtest.sleep\(dq, \(dqkwarg\(dq: {\(dqlength\(dq: 30}, \(dqtimeout\(dq: 60 }, { \(dqclient\(dq: \(dqrunner\(dq, \(dqfun\(dq: \(dqtest.sleep\(dq, \(dqkwarg\(dq: {\(dqs_time\(dq: 30}, \(dqtimeout\(dq: 60 } ] \(aq .ft P .fi .UNINDENT .UNINDENT .SS Best Practices .sp Given the performance overhead and HTTP timeouts for long\-running operations described above, the most effective and most scalable way to use both Salt and salt\-api is to run commands asynchronously using the \fBlocal_async\fP, \fBrunner_async\fP, and \fBwheel_async\fP clients. .sp Running asynchronous jobs results in being able to process 3x more commands per second for \fBLocalClient\fP and 17x more commands per second for \fBRunnerClient\fP, in addition to much less network traffic and memory requirements. Job returns can be fetched from Salt\(aqs job cache via the \fB/jobs/<jid>\fP endpoint, or they can be collected into a data store using Salt\(aqs \fI\%Returner system\fP\&. .sp The \fB/events\fP endpoint is specifically designed to handle long\-running HTTP connections and it exposes Salt\(aqs event bus which includes job returns. Watching this endpoint first, then executing asynchronous Salt commands second, is the most lightweight and scalable way to use \fBrest_cherrypy\fP while still receiving job returns in real\-time. But this requires clients that can properly handle the inherent asynchronicity of that workflow. .SS Performance Tuning .sp The \fBthread_pool\fP and \fBsocket_queue_size\fP settings can be used to increase the capacity of rest_cherrypy to handle incoming requests. Keep an eye on RAM usage as well as available file handles while testing changes to these settings. As salt\-api is a thin wrapper around Salt\(aqs Python API, also keep an eye on the performance of Salt when testing. .SS Future Plans .sp Now that Salt uses the Tornado concurrency library internally, we plan to improve performance in the API by taking advantage of existing processes and event listeners and to use lightweight coroutines to facilitate more simultaneous HTTP connections and better support for synchronous operations. That effort can be tracked in \fI\%issue 26505\fP, but until that issue is closed rest_cherrypy will remain the officially recommended REST API. .SS Deployment .sp The \fBrest_cherrypy\fP netapi module is a standard Python WSGI app. It can be deployed one of two ways. .SS \fBsalt\-api\fP using the CherryPy server .sp The default configuration is to run this module using \fBsalt\-api\fP to start the Python\-based CherryPy server. This server is lightweight, multi\-threaded, encrypted with SSL, and should be considered production\-ready. See the section above for performance expectations. .SS Using a WSGI\-compliant web server .sp This module may be deployed on any WSGI\-compliant server such as Apache with mod_wsgi or Nginx with FastCGI, to name just two (there are many). .sp Note, external WSGI servers handle URLs, paths, and SSL certs directly. The \fBrest_cherrypy\fP configuration options are ignored and the \fBsalt\-api\fP daemon does not need to be running at all. Remember Salt authentication credentials are sent in the clear unless SSL is being enforced! .sp An example Apache virtual host configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C <VirtualHost *:80> ServerName example.com ServerAlias *.example.com ServerAdmin webmaster@example.com LogLevel warn ErrorLog /var/www/example.com/logs/error.log CustomLog /var/www/example.com/logs/access.log combined DocumentRoot /var/www/example.com/htdocs WSGIScriptAlias / /path/to/salt/netapi/rest_cherrypy/wsgi.py </VirtualHost> .ft P .fi .UNINDENT .UNINDENT .SS REST URI Reference .SS \fB/\fP .INDENT 0.0 .TP .B class salt.netapi.rest_cherrypy.app.LowDataAdapter The primary entry point to Salt\(aqs REST API .INDENT 7.0 .TP .B GET() An explanation of the API with links of where to go next .INDENT 7.0 .TP .B GET / .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-i localhost:8000 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET / HTTP/1.1 Host: localhost:8000 Accept: application/json .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Type: application/json .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B POST(**kwargs) Send one or more Salt commands in the request body .INDENT 7.0 .TP .B POST / .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fIX\-Auth\-Token\fP \-\- a session token from \fI\%Login\fP\&. .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .IP \(bu 2 \fI\%Content\-Type\fP \-\- the format of the request body. .UNINDENT .TP .B Response Headers .INDENT 7.0 .IP \(bu 2 \fI\%Content\-Type\fP \-\- the format of the response body; depends on the \fIAccept\fP request header. .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%400 Bad Request\fP \-\- bad or malformed request .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .sp \fI\%lowstate\fP data describing Salt commands must be sent in the request body. .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-sSik https://localhost:8000 \e \-b ~/cookies.txt \e \-H \(dqAccept: application/x\-yaml\(dq \e \-H \(dqContent\-type: application/json\(dq \e \-d \(aq[{\(dqclient\(dq: \(dqlocal\(dq, \(dqtgt\(dq: \(dq*\(dq, \(dqfun\(dq: \(dqtest.ping\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C POST / HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml X\-Auth\-Token: d40d1e1e Content\-Type: application/json [{\(dqclient\(dq: \(dqlocal\(dq, \(dqtgt\(dq: \(dq*\(dq, \(dqfun\(dq: \(dqtest.ping\(dq}] .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 200 Allow: GET, HEAD, POST Content\-Type: application/x\-yaml return: \- ms\-0: true ms\-1: true ms\-2: true ms\-3: true ms\-4: true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/login\fP .INDENT 0.0 .TP .B class salt.netapi.rest_cherrypy.app.Login(*args, **kwargs) Log in to receive a session token .sp \fI\%Authentication information\fP\&. .INDENT 7.0 .TP .B GET() Present the login interface .INDENT 7.0 .TP .B GET /login An explanation of how to log in. .INDENT 7.0 .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-i localhost:8000/login .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /login HTTP/1.1 Host: localhost:8000 Accept: text/html .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Type: text/html .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B POST(**kwargs) \fI\%Authenticate\fP against Salt\(aqs eauth system .INDENT 7.0 .TP .B POST /login .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fIX\-Auth\-Token\fP \-\- a session token from \fI\%Login\fP\&. .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .IP \(bu 2 \fI\%Content\-Type\fP \-\- the format of the request body. .UNINDENT .TP .B Form Parameters .INDENT 7.0 .IP \(bu 2 \fBeauth\fP \-\- the eauth backend configured for the user .IP \(bu 2 \fBusername\fP \-\- username .IP \(bu 2 \fBpassword\fP \-\- password .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-si localhost:8000/login \e \-c ~/cookies.txt \e \-H \(dqAccept: application/json\(dq \e \-H \(dqContent\-type: application/json\(dq \e \-d \(aq{ \(dqusername\(dq: \(dqsaltuser\(dq, \(dqpassword\(dq: \(dqsaltuser\(dq, \(dqeauth\(dq: \(dqauto\(dq }\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C POST / HTTP/1.1 Host: localhost:8000 Content\-Length: 42 Content\-Type: application/json Accept: application/json {\(dqusername\(dq: \(dqsaltuser\(dq, \(dqpassword\(dq: \(dqsaltuser\(dq, \(dqeauth\(dq: \(dqauto\(dq} .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Type: application/json Content\-Length: 206 X\-Auth\-Token: 6d1b722e Set\-Cookie: session_id=6d1b722e; expires=Sat, 17 Nov 2012 03:23:52 GMT; Path=/ {\(dqreturn\(dq: { \(dqtoken\(dq: \(dq6d1b722e\(dq, \(dqstart\(dq: 1363805943.776223, \(dqexpire\(dq: 1363849143.776224, \(dquser\(dq: \(dqsaltuser\(dq, \(dqeauth\(dq: \(dqpam\(dq, \(dqperms\(dq: [ \(dqgrains.*\(dq, \(dqstatus.*\(dq, \(dqsys.*\(dq, \(dqtest.*\(dq ] }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/logout\fP .INDENT 0.0 .TP .B class salt.netapi.rest_cherrypy.app.Logout Class to remove or invalidate sessions .INDENT 7.0 .TP .B POST() Destroy the currently active session and expire the session cookie .UNINDENT .UNINDENT .SS \fB/minions\fP .INDENT 0.0 .TP .B class salt.netapi.rest_cherrypy.app.Minions Convenience URLs for working with minions .INDENT 7.0 .TP .B GET(mid=None) A convenience URL for getting lists of minions or getting minion details .INDENT 7.0 .TP .B GET /minions/(mid) .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fIX\-Auth\-Token\fP \-\- a session token from \fI\%Login\fP\&. .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-i localhost:8000/minions/ms\-3 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /minions/ms\-3 HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 129005 Content\-Type: application/x\-yaml return: \- ms\-3: grains.items: ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B POST(**kwargs) Start an execution command and immediately return the job id .INDENT 7.0 .TP .B POST /minions .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fIX\-Auth\-Token\fP \-\- a session token from \fI\%Login\fP\&. .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .IP \(bu 2 \fI\%Content\-Type\fP \-\- the format of the request body. .UNINDENT .TP .B Response Headers .INDENT 7.0 .IP \(bu 2 \fI\%Content\-Type\fP \-\- the format of the response body; depends on the \fIAccept\fP request header. .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%400 Bad Request\fP \-\- bad or malformed request .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .sp Lowstate data describing Salt commands must be sent in the request body. The \fBclient\fP option will be set to \fBlocal_async()\fP\&. .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-sSi localhost:8000/minions \e \-b ~/cookies.txt \e \-H \(dqAccept: application/x\-yaml\(dq \e \-d \(aq[{\(dqtgt\(dq: \(dq*\(dq, \(dqfun\(dq: \(dqstatus.diskusage\(dq}]\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C POST /minions HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml Content\-Type: application/x\-www\-form\-urlencoded tgt=*&fun=status.diskusage .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 202 Accepted Content\-Length: 86 Content\-Type: application/x\-yaml return: \- jid: \(aq20130603122505459265\(aq minions: [ms\-4, ms\-3, ms\-2, ms\-1, ms\-0] _links: jobs: \- href: /jobs/20130603122505459265 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/jobs\fP .INDENT 0.0 .TP .B class salt.netapi.rest_cherrypy.app.Jobs .INDENT 7.0 .TP .B GET(jid=None, timeout=\(aq\(aq) A convenience URL for getting lists of previously run jobs or getting the return from a single job .INDENT 7.0 .TP .B GET /jobs/(jid) List jobs or show a single job from the job cache. .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fIX\-Auth\-Token\fP \-\- a session token from \fI\%Login\fP\&. .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-i localhost:8000/jobs .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /jobs HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 165 Content\-Type: application/x\-yaml return: \- \(aq20121130104633606931\(aq: Arguments: \- \(aq3\(aq Function: test.fib Start Time: 2012, Nov 30 10:46:33.606931 Target: jerry Target\-type: glob .ft P .fi .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-i localhost:8000/jobs/20121130104633606931 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /jobs/20121130104633606931 HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 73 Content\-Type: application/x\-yaml info: \- Arguments: \- \(aq3\(aq Function: test.fib Minions: \- jerry Start Time: 2012, Nov 30 10:46:33.606931 Target: \(aq*\(aq Target\-type: glob User: saltdev jid: \(aq20121130104633606931\(aq return: \- jerry: \- \- 0 \- 1 \- 1 \- 2 \- 6.9141387939453125e\-06 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/run\fP .INDENT 0.0 .TP .B class salt.netapi.rest_cherrypy.app.Run Run commands bypassing the \fI\%normal session handling\fP\&. .sp salt\-api does not enforce authorization, Salt\(aqs eauth system does that. Local/Runner/WheelClient all accept \fBusername\fP/\fBpassword\fP/\fBeauth\fP \fBor\fP \fBtoken\fP kwargs that are then checked by the eauth system. The session mechanism in \fBrest_cherrypy\fP simply pairs a session with a Salt eauth token and then passes the \fBtoken\fP kwarg in automatically. .sp If you already have a Salt eauth token, perhaps generated by the \fI\%mk_token\fP function in the Auth Runner module, then there is no reason to use sessions. .sp This endpoint accepts either a \fBusername\fP, \fBpassword\fP, \fBeauth\fP trio, \fBor\fP a \fBtoken\fP kwarg and does not make use of sessions at all. .INDENT 7.0 .TP .B POST(**kwargs) Run commands bypassing the \fI\%normal session handling\fP\&. Otherwise, this URL is identical to the \fI\%root URL (/)\fP\&. .INDENT 7.0 .TP .B POST /run An array of lowstate data describing Salt commands must be sent in the request body. .INDENT 7.0 .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%400 Bad Request\fP \-\- bad or malformed request .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-sS localhost:8000/run \e \-H \(aqAccept: application/x\-yaml\(aq \e \-H \(aqContent\-type: application/json\(aq \e \-d \(aq[{ \(dqclient\(dq: \(dqlocal\(dq, \(dqtgt\(dq: \(dq*\(dq, \(dqfun\(dq: \(dqtest.ping\(dq, \(dqusername\(dq: \(dqsaltdev\(dq, \(dqpassword\(dq: \(dqsaltdev\(dq, \(dqeauth\(dq: \(dqauto\(dq }]\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBOr\fP using a Salt Eauth token: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-sS localhost:8000/run \e \-H \(aqAccept: application/x\-yaml\(aq \e \-H \(aqContent\-type: application/json\(aq \e \-d \(aq[{ \(dqclient\(dq: \(dqlocal\(dq, \(dqtgt\(dq: \(dq*\(dq, \(dqfun\(dq: \(dqtest.ping\(dq, \(dqtoken\(dq: \(dq<salt eauth token here>\(dq }]\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C POST /run HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml Content\-Length: 75 Content\-Type: application/json [{\(dqclient\(dq: \(dqlocal\(dq, \(dqtgt\(dq: \(dq*\(dq, \(dqfun\(dq: \(dqtest.ping\(dq, \(dqusername\(dq: \(dqsaltdev\(dq, \(dqpassword\(dq: \(dqsaltdev\(dq, \(dqeauth\(dq: \(dqauto\(dq}] .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 73 Content\-Type: application/x\-yaml return: \- ms\-0: true ms\-1: true ms\-2: true ms\-3: true ms\-4: true .ft P .fi .UNINDENT .UNINDENT .sp The /run endpoint can also be used to issue commands using the salt\-ssh subsystem. When using salt\-ssh, eauth credentials must also be supplied, and are subject to \fI\%eauth access\-control lists\fP\&. .sp All SSH client requests are synchronous. .sp \fBExample SSH client request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-sS localhost:8000/run \e \-H \(aqAccept: application/x\-yaml\(aq \e \-d client=\(aqssh\(aq \e \-d tgt=\(aq*\(aq \e \-d username=\(aqsaltdev\(aq \e \-d password=\(aqsaltdev\(aq \e \-d eauth=\(aqauto\(aq \e \-d fun=\(aqtest.ping\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C POST /run HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml Content\-Length: 75 Content\-Type: application/x\-www\-form\-urlencoded .ft P .fi .UNINDENT .UNINDENT .sp \fBExample SSH response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C return: \- silver: _stamp: \(aq2020\-09\-08T23:04:28.912609\(aq fun: test.ping fun_args: [] id: silver jid: \(aq20200908230427905565\(aq retcode: 0 return: true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/events\fP .INDENT 0.0 .TP .B class salt.netapi.rest_cherrypy.app.Events Expose the Salt event bus .sp The event bus on the Salt master exposes a large variety of things, notably when executions are started on the master and also when minions ultimately return their results. This URL provides a real\-time window into a running Salt infrastructure. .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 \fI\%Events & Reactor\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B GET(token=None, salt_token=None) An HTTP stream of the Salt master event bus .sp This stream is formatted per the Server Sent Events (SSE) spec. Each event is formatted as JSON. .INDENT 7.0 .TP .B GET /events .INDENT 7.0 .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .TP .B Query Parameters .INDENT 7.0 .IP \(bu 2 \fBtoken\fP \-\- \fBoptional\fP parameter containing the token ordinarily supplied via the X\-Auth\-Token header in order to allow cross\-domain requests in browsers that do not include CORS support in the EventSource API. E.g., \fBcurl \-NsS localhost:8000/events?token=308650d\fP .IP \(bu 2 \fBsalt_token\fP \-\- \fBoptional\fP parameter containing a raw Salt \fIeauth token\fP (not to be confused with the token returned from the /login URL). E.g., \fBcurl \-NsS localhost:8000/events?salt_token=30742765\fP .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-NsS localhost:8000/events .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /events HTTP/1.1 Host: localhost:8000 .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .sp Note, the \fBtag\fP field is not part of the spec. SSE compliant clients should ignore unknown fields. This addition allows non\-compliant clients to only watch for certain tags without having to deserialze the JSON object each time. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Connection: keep\-alive Cache\-Control: no\-cache Content\-Type: text/event\-stream;charset=utf\-8 retry: 400 tag: salt/job/20130802115730568475/new data: {\(aqtag\(aq: \(aqsalt/job/20130802115730568475/new\(aq, \(aqdata\(aq: {\(aqminions\(aq: [\(aqms\-4\(aq, \(aqms\-3\(aq, \(aqms\-2\(aq, \(aqms\-1\(aq, \(aqms\-0\(aq]}} tag: salt/job/20130802115730568475/ret/jerry data: {\(aqtag\(aq: \(aqsalt/job/20130802115730568475/ret/jerry\(aq, \(aqdata\(aq: {\(aqjid\(aq: \(aq20130802115730568475\(aq, \(aqreturn\(aq: True, \(aqretcode\(aq: 0, \(aqsuccess\(aq: True, \(aqcmd\(aq: \(aq_return\(aq, \(aqfun\(aq: \(aqtest.ping\(aq, \(aqid\(aq: \(aqms\-1\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp The event stream can be easily consumed via JavaScript: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C var source = new EventSource(\(aq/events\(aq); source.onopen = function() { console.info(\(aqListening ...\(aq) }; source.onerror = function(err) { console.error(err) }; source.onmessage = function(message) { var saltEvent = JSON.parse(message.data); console.log(saltEvent.tag, saltEvent.data); }; .ft P .fi .UNINDENT .UNINDENT .sp Note, the SSE stream is fast and completely asynchronous and Salt is very fast. If a job is created using a regular POST request, it is possible that the job return will be available on the SSE stream before the response for the POST request arrives. It is important to take that asynchronicity into account when designing an application. Below are some general guidelines. .INDENT 7.0 .IP \(bu 2 Subscribe to the SSE stream _before_ creating any events. .IP \(bu 2 Process SSE events directly as they arrive and don\(aqt wait for any other process to \(dqcomplete\(dq first (like an ajax request). .IP \(bu 2 Keep a buffer of events if the event stream must be used for synchronous lookups. .IP \(bu 2 Be cautious in writing Salt\(aqs event stream directly to the DOM. It is very busy and can quickly overwhelm the memory allocated to a browser tab. .UNINDENT .sp A full, working proof\-of\-concept JavaScript application is available \fI\%adjacent to this file\fP\&. It can be viewed by pointing a browser at the \fB/app\fP endpoint in a running \fBrest_cherrypy\fP instance. .sp Or using CORS: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C var source = new EventSource(\(aq/events?token=ecd589e4e01912cf3c4035afad73426dbb8dba75\(aq, {withCredentials: true}); .ft P .fi .UNINDENT .UNINDENT .sp It is also possible to consume the stream via the shell. .sp Records are separated by blank lines; the \fBdata:\fP and \fBtag:\fP prefixes will need to be removed manually before attempting to unserialize the JSON. .sp curl\(aqs \fB\-N\fP flag turns off input buffering which is required to process the stream incrementally. .sp Here is a basic example of printing each event as it comes in: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-NsS localhost:8000/events |\e while IFS= read \-r line ; do echo $line done .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of using awk to filter events based on tag: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-NsS localhost:8000/events |\e awk \(aq BEGIN { RS=\(dq\(dq; FS=\(dq\e\en\(dq } $1 ~ /^tag: salt\e/job\e/[0\-9]+\e/new$/ { print $0 } \(aq tag: salt/job/20140112010149808995/new data: {\(dqtag\(dq: \(dqsalt/job/20140112010149808995/new\(dq, \(dqdata\(dq: {\(dqtgt_type\(dq: \(dqglob\(dq, \(dqjid\(dq: \(dq20140112010149808995\(dq, \(dqtgt\(dq: \(dqjerry\(dq, \(dq_stamp\(dq: \(dq2014\-01\-12_01:01:49.809617\(dq, \(dquser\(dq: \(dqshouse\(dq, \(dqarg\(dq: [], \(dqfun\(dq: \(dqtest.ping\(dq, \(dqminions\(dq: [\(dqjerry\(dq]}} tag: 20140112010149808995 data: {\(dqtag\(dq: \(dq20140112010149808995\(dq, \(dqdata\(dq: {\(dqfun_args\(dq: [], \(dqjid\(dq: \(dq20140112010149808995\(dq, \(dqreturn\(dq: true, \(dqretcode\(dq: 0, \(dqsuccess\(dq: true, \(dqcmd\(dq: \(dq_return\(dq, \(dq_stamp\(dq: \(dq2014\-01\-12_01:01:49.819316\(dq, \(dqfun\(dq: \(dqtest.ping\(dq, \(dqid\(dq: \(dqjerry\(dq}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/hook\fP .INDENT 0.0 .TP .B class salt.netapi.rest_cherrypy.app.Webhook A generic web hook entry point that fires an event on Salt\(aqs event bus .sp External services can POST data to this URL to trigger an event in Salt. For example, Amazon SNS, Jenkins\-CI or Travis\-CI, or GitHub web hooks. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Be mindful of security .sp Salt\(aqs Reactor can run any code. A Reactor SLS that responds to a hook event is responsible for validating that the event came from a trusted source and contains valid data. .sp \fBThis is a generic interface and securing it is up to you!\fP .sp This URL requires authentication however not all external services can be configured to authenticate. For this reason authentication can be selectively disabled for this URL. Follow best practices \-\- always use SSL, pass a secret key, configure the firewall to only allow traffic from a known source, etc. .UNINDENT .UNINDENT .sp The event data is taken from the request body. The \fIContent\-Type\fP header is respected for the payload. .sp The event tag is prefixed with \fBsalt/netapi/hook\fP and the URL path is appended to the end. For example, a \fBPOST\fP request sent to \fB/hook/mycompany/myapp/mydata\fP will produce a Salt event with the tag \fBsalt/netapi/hook/mycompany/myapp/mydata\fP\&. .sp The following is an example \fB\&.travis.yml\fP file to send notifications to Salt of successful test runs: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C language: python script: python \-m unittest tests after_success: \- | curl \-sSk https://saltapi\-url.example.com:8000/hook/travis/build/success \-d branch=\(dq${TRAVIS_BRANCH}\(dq \-d commit=\(dq${TRAVIS_COMMIT}\(dq .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 \fI\%Events & Reactor\fP, \fI\%reactor\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B POST(*args, **kwargs) Fire an event in Salt with a custom event tag and data .INDENT 7.0 .TP .B POST /hook .INDENT 7.0 .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .IP \(bu 2 \fI\%413 Request Entity Too Large\fP \-\- request body is too large .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-sS localhost:8000/hook \e \-H \(aqContent\-type: application/json\(aq \e \-d \(aq{\(dqfoo\(dq: \(dqFoo!\(dq, \(dqbar\(dq: \(dqBar!\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C POST /hook HTTP/1.1 Host: localhost:8000 Content\-Length: 16 Content\-Type: application/json {\(dqfoo\(dq: \(dqFoo!\(dq, \(dqbar\(dq: \(dqBar!\(dq} .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 14 Content\-Type: application/json {\(dqsuccess\(dq: true} .ft P .fi .UNINDENT .UNINDENT .sp As a practical example, an internal continuous\-integration build server could send an HTTP POST request to the URL \fBhttps://localhost:8000/hook/mycompany/build/success\fP which contains the result of a build and the SHA of the version that was built as JSON. That would then produce the following event in Salt that could be used to kick off a deployment via Salt\(aqs Reactor: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Event fired at Fri Feb 14 17:40:11 2014 ************************* Tag: salt/netapi/hook/mycompany/build/success Data: {\(aq_stamp\(aq: \(aq2014\-02\-14_17:40:11.440996\(aq, \(aqheaders\(aq: { \(aqX\-My\-Secret\-Key\(aq: \(aqF0fAgoQjIT@W\(aq, \(aqContent\-Length\(aq: \(aq37\(aq, \(aqContent\-Type\(aq: \(aqapplication/json\(aq, \(aqHost\(aq: \(aqlocalhost:8000\(aq, \(aqRemote\-Addr\(aq: \(aq127.0.0.1\(aq}, \(aqpost\(aq: {\(aqrevision\(aq: \(aqaa22a3c4b2e7\(aq, \(aqresult\(aq: True}} .ft P .fi .UNINDENT .UNINDENT .sp Salt\(aqs Reactor could listen for the event: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C reactor: \- \(aqsalt/netapi/hook/mycompany/build/*\(aq: \- /srv/reactor/react_ci_builds.sls .ft P .fi .UNINDENT .UNINDENT .sp And finally deploy the new build: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set secret_key = data.get(\(aqheaders\(aq, {}).get(\(aqX\-My\-Secret\-Key\(aq) %} {% set build = data.get(\(aqpost\(aq, {}) %} {% if secret_key == \(aqF0fAgoQjIT@W\(aq and build.result == True %} deploy_my_app: cmd.state.sls: \- tgt: \(aqapplication*\(aq \- arg: \- myapp.deploy \- kwarg: pillar: revision: {{ revision }} {% endif %} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/keys\fP .INDENT 0.0 .TP .B class salt.netapi.rest_cherrypy.app.Keys Convenience URLs for working with minion keys .sp New in version 2014.7.0. .sp These URLs wrap the functionality provided by the \fI\%key wheel module\fP functions. .INDENT 7.0 .TP .B GET(mid=None) Show the list of minion keys or detail on a specific key .sp New in version 2014.7.0. .INDENT 7.0 .TP .B GET /keys/(mid) List all keys or show a specific key .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fIX\-Auth\-Token\fP \-\- a session token from \fI\%Login\fP\&. .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-i localhost:8000/keys .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /keys HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 165 Content\-Type: application/x\-yaml return: local: \- master.pem \- master.pub minions: \- jerry minions_pre: [] minions_rejected: [] .ft P .fi .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-i localhost:8000/keys/jerry .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /keys/jerry HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 73 Content\-Type: application/x\-yaml return: minions: jerry: 51:93:b3:d0:9f:3a:6d:e5:28:67:c2:4b:27:d6:cd:2b .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B POST(**kwargs) Easily generate keys for a minion and auto\-accept the new key .sp Accepts all the same parameters as the \fI\%key.gen_accept\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A note about \fBcurl\fP Avoid using the \fB\-i\fP flag or HTTP headers will be written and produce an invalid tar file. .UNINDENT .UNINDENT .sp Example partial kickstart script to bootstrap a new minion: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C %post mkdir \-p /etc/salt/pki/minion curl \-sSk https://localhost:8000/keys \e \-d mid=jerry \e \-d username=kickstart \e \-d password=kickstart \e \-d eauth=pam \e | tar \-C /etc/salt/pki/minion \-xf \- mkdir \-p /etc/salt/minion.d printf \(aqmaster: 10.0.0.5\enid: jerry\(aq > /etc/salt/minion.d/id.conf %end .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B POST /keys Generate a public and private key and return both as a tarball .sp Authentication credentials must be passed in the request. .INDENT 7.0 .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-sSk https://localhost:8000/keys \e \-d mid=jerry \e \-d username=kickstart \e \-d password=kickstart \e \-d eauth=pam \e \-o jerry\-salt\-keys.tar .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C POST /keys HTTP/1.1 Host: localhost:8000 .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 10240 Content\-Disposition: attachment; filename=\(dqsaltkeys\-jerry.tar\(dq Content\-Type: application/x\-tar jerry.pub0000644000000000000000000000070300000000000010730 0ustar 00000000000000 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/ws\fP .INDENT 0.0 .TP .B class salt.netapi.rest_cherrypy.app.WebsocketEndpoint Open a WebSocket connection to Salt\(aqs event bus .sp The event bus on the Salt master exposes a large variety of things, notably when executions are started on the master and also when minions ultimately return their results. This URL provides a real\-time window into a running Salt infrastructure. Uses websocket as the transport mechanism. .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 \fI\%Events & Reactor\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B GET(token=None, **kwargs) Return a websocket connection of Salt\(aqs event stream .INDENT 7.0 .TP .B GET /ws/(token) .UNINDENT .INDENT 7.0 .TP .B Query format_events The event stream will undergo server\-side formatting if the \fBformat_events\fP URL parameter is included in the request. This can be useful to avoid formatting on the client\-side: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-NsS <...snip...> localhost:8000/ws?format_events .ft P .fi .UNINDENT .UNINDENT .TP .B Reqheader X\-Auth\-Token an authentication token from \fI\%Login\fP\&. .TP .B Status 101 switching to the websockets protocol .TP .B Status 401 authentication required .TP .B Status 406 requested Content\-Type not available .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-NsSk \e \-H \(aqX\-Auth\-Token: ffedf49d\(aq \e \-H \(aqHost: localhost:8000\(aq \e \-H \(aqConnection: Upgrade\(aq \e \-H \(aqUpgrade: websocket\(aq \e \-H \(aqOrigin: https://localhost:8000\(aq \e \-H \(aqSec\-WebSocket\-Version: 13\(aq \e \-H \(aqSec\-WebSocket\-Key: \(aq\(dq$(echo \-n $RANDOM | base64)\(dq \e localhost:8000/ws .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /ws HTTP/1.1 Connection: Upgrade Upgrade: websocket Host: localhost:8000 Origin: https://localhost:8000 Sec\-WebSocket\-Version: 13 Sec\-WebSocket\-Key: s65VsgHigh7v/Jcf4nXHnA== X\-Auth\-Token: ffedf49d .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec\-WebSocket\-Accept: mWZjBV9FCglzn1rIKJAxrTFlnJE= Sec\-WebSocket\-Version: 13 .ft P .fi .UNINDENT .UNINDENT .sp An authentication token \fBmay optionally\fP be passed as part of the URL for browsers that cannot be configured to send the authentication header or cookie: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-NsS <...snip...> localhost:8000/ws/ffedf49d .ft P .fi .UNINDENT .UNINDENT .sp The event stream can be easily consumed via JavaScript: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C // Note, you must be authenticated! var source = new Websocket(\(aqws://localhost:8000/ws/d0ce6c1a\(aq); source.onerror = function(e) { console.debug(\(aqerror!\(aq, e); }; source.onmessage = function(e) { console.debug(e.data); }; source.send(\(aqwebsocket client ready\(aq) source.close(); .ft P .fi .UNINDENT .UNINDENT .sp Or via Python, using the Python module \fI\%websocket\-client\fP for example. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Note, you must be authenticated! from websocket import create_connection ws = create_connection(\(aqws://localhost:8000/ws/d0ce6c1a\(aq) ws.send(\(aqwebsocket client ready\(aq) # Look at https://pypi.python.org/pypi/websocket\-client/ for more # examples. while listening_to_events: print ws.recv() ws.close() .ft P .fi .UNINDENT .UNINDENT .sp Above examples show how to establish a websocket connection to Salt and activating real time updates from Salt\(aqs event stream by signaling \fBwebsocket client ready\fP\&. .UNINDENT .UNINDENT .SS \fB/stats\fP .INDENT 0.0 .TP .B class salt.netapi.rest_cherrypy.app.Stats Expose statistics on the running CherryPy server .INDENT 7.0 .TP .B GET() Return a dump of statistics collected from the CherryPy server .INDENT 7.0 .TP .B GET /stats .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fIX\-Auth\-Token\fP \-\- a session token from \fI\%Login\fP\&. .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .UNINDENT .TP .B Response Headers .INDENT 7.0 .IP \(bu 2 \fI\%Content\-Type\fP \-\- the format of the response body; depends on the \fIAccept\fP request header. .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS rest_tornado .SS A non\-blocking REST API for Salt .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 tornado Python module .UNINDENT .TP .B configuration All authentication is done through Salt\(aqs \fI\%external auth\fP system which requires additional configuration not described here. .UNINDENT .sp In order to run rest_tornado with the salt\-master add the following to the Salt master config file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rest_tornado: # can be any port port: 8000 # address to bind to (defaults to 0.0.0.0) address: 0.0.0.0 # socket backlog backlog: 128 ssl_crt: /etc/pki/api/certs/server.crt # no need to specify ssl_key if cert and key # are in one single file ssl_key: /etc/pki/api/certs/server.key debug: False disable_ssl: False webhook_disable_auth: False cors_origin: null .ft P .fi .UNINDENT .UNINDENT .SS Authentication .sp Authentication is performed by passing a session token with each request. Tokens are generated via the \fI\%SaltAuthHandler\fP URL. .sp The token may be sent in one of two ways: .INDENT 0.0 .IP \(bu 2 Include a custom header named \fIX\-Auth\-Token\fP\&. .IP \(bu 2 Sent via a cookie. This option is a convenience for HTTP clients that automatically handle cookie support (such as browsers). .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 You can bypass the session handling via the \fI\%RunSaltAPIHandler\fP URL. .UNINDENT .UNINDENT .SS CORS .sp rest_tornado supports Cross\-site HTTP requests out of the box. It is by default deactivated and controlled by the \fIcors_origin\fP config key. .sp You can allow all origins by settings \fIcors_origin\fP to \fI*\fP\&. .sp You can allow only one origin with this configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rest_tornado: cors_origin: http://salt.yourcompany.com .ft P .fi .UNINDENT .UNINDENT .sp You can also be more specific and select only a few allowed origins by using a list. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rest_tornado: cors_origin: \- http://salt.yourcompany.com \- http://salt\-preprod.yourcampany.com .ft P .fi .UNINDENT .UNINDENT .sp The format for origin are full URL, with both scheme and port if not standard. .sp In this case, rest_tornado will check if the Origin header is in the allowed list if it\(aqs the case allow the origin. Else it will returns nothing, effectively preventing the origin to make request. .sp For reference, CORS is a mechanism used by browser to allow (or disallow) requests made from browser from a different origin than salt\-api. It\(aqs complementary to Authentication and mandatory only if you plan to use a salt client developed as a Javascript browser application. .SS Usage .sp Commands are sent to a running Salt master via this module by sending HTTP requests to the URLs detailed below. .INDENT 0.0 .INDENT 3.5 .IP "Content negotiation" .sp This REST interface is flexible in what data formats it will accept as well as what formats it will return (e.g., JSON, YAML, x\-www\-form\-urlencoded). .INDENT 0.0 .IP \(bu 2 Specify the format of data in the request body by including the \fIContent\-Type\fP header. .IP \(bu 2 Specify the desired data format for the response body with the \fIAccept\fP header. .UNINDENT .UNINDENT .UNINDENT .sp Data sent in \fI\%POST\fP and \fI\%PUT\fP requests must be in the format of a list of lowstate dictionaries. This allows multiple commands to be executed in a single HTTP request. .INDENT 0.0 .TP .B lowstate A dictionary containing various keys that instruct Salt which command to run, where that command lives, any parameters for that command, any authentication credentials, what returner to use, etc. .sp Salt uses the lowstate data format internally in many places to pass command data between functions. Salt also uses lowstate for the \fI\%LocalClient()\fP Python API interface. .UNINDENT .sp The following example (in JSON format) causes Salt to execute two commands: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [{ \(dqclient\(dq: \(dqlocal\(dq, \(dqtgt\(dq: \(dq*\(dq, \(dqfun\(dq: \(dqtest.fib\(dq, \(dqarg\(dq: [\(dq10\(dq] }, { \(dqclient\(dq: \(dqrunner\(dq, \(dqfun\(dq: \(dqjobs.lookup_jid\(dq, \(dqjid\(dq: \(dq20130603122505459265\(dq }] .ft P .fi .UNINDENT .UNINDENT .sp Multiple commands in a Salt API request will be executed in serial and makes no guarantees that all commands will run. Meaning that if test.fib (from the example above) had an exception, the API would still execute \(dqjobs.lookup_jid\(dq. .sp Responses to these lowstates are an in\-order list of dicts containing the return data, a yaml response could look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- ms\-1: true ms\-2: true \- ms\-1: foo ms\-2: bar .ft P .fi .UNINDENT .UNINDENT .sp In the event of an exception while executing a command the return for that lowstate will be a string, for example if no minions matched the first lowstate we would get a return like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- No minions matched the target. No command was sent, no jid was assigned. \- ms\-1: true ms\-2: true .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .IP "x\-www\-form\-urlencoded" .sp Sending JSON or YAML in the request body is simple and most flexible, however sending data in urlencoded format is also supported with the caveats below. It is the default format for HTML forms, many JavaScript libraries, and the \fBcurl\fP command. .sp For example, the equivalent to running \fBsalt \(aq*\(aq test.ping\fP is sending \fBfun=test.ping&arg&client=local&tgt=*\fP in the HTTP request body. .sp Caveats: .INDENT 0.0 .IP \(bu 2 Only a single command may be sent per HTTP request. .IP \(bu 2 Repeating the \fBarg\fP parameter multiple times will cause those parameters to be combined into a single list. .sp Note, some popular frameworks and languages (notably jQuery, PHP, and Ruby on Rails) will automatically append empty brackets onto repeated parameters. E.g., \fBarg=one\fP, \fBarg=two\fP will be sent as \fBarg[]=one\fP, \fBarg[]=two\fP\&. This is not supported; send JSON or YAML instead. .UNINDENT .UNINDENT .UNINDENT .SS A Websockets add\-on to saltnado .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 tornado Python module .UNINDENT .UNINDENT .sp In order to enable saltnado_websockets you must add websockets: True to your saltnado config block. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rest_tornado: # can be any port port: 8000 ssl_crt: /etc/pki/api/certs/server.crt # no need to specify ssl_key if cert and key # are in one single file ssl_key: /etc/pki/api/certs/server.key debug: False disable_ssl: False websockets: True .ft P .fi .UNINDENT .UNINDENT .SS All Events .sp Exposes \fBall\fP \(dqreal\-time\(dq events from Salt\(aqs event bus on a websocket connection. It should be noted that \(dqReal\-time\(dq here means these events are made available to the server as soon as any salt related action (changes to minions, new jobs etc) happens. Clients are however assumed to be able to tolerate any network transport related latencies. Functionality provided by this endpoint is similar to the \fB/events\fP end point. .sp The event bus on the Salt master exposes a large variety of things, notably when executions are started on the master and also when minions ultimately return their results. This URL provides a real\-time window into a running Salt infrastructure. Uses websocket as the transport mechanism. .sp Exposes GET method to return websocket connections. All requests should include an auth token. A way to obtain obtain authentication tokens is shown below. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl \-si localhost:8000/login \e \-H \(dqAccept: application/json\(dq \e \-d username=\(aqsalt\(aq \e \-d password=\(aqsalt\(aq \e \-d eauth=\(aqpam\(aq .ft P .fi .UNINDENT .UNINDENT .sp Which results in the response .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { \(dqreturn\(dq: [{ \(dqperms\(dq: [\(dq.*\(dq, \(dq@runner\(dq, \(dq@wheel\(dq], \(dqstart\(dq: 1400556492.277421, \(dqtoken\(dq: \(dqd0ce6c1a37e99dcc0374392f272fe19c0090cca7\(dq, \(dqexpire\(dq: 1400599692.277422, \(dquser\(dq: \(dqsalt\(dq, \(dqeauth\(dq: \(dqpam\(dq }] } .ft P .fi .UNINDENT .UNINDENT .sp In this example the \fBtoken\fP returned is \fBd0ce6c1a37e99dcc0374392f272fe19c0090cca7\fP and can be included in subsequent websocket requests (as part of the URL). .sp The event stream can be easily consumed via JavaScript: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // Note, you must be authenticated! // Get the Websocket connection to Salt var source = new Websocket(\(aqwss://localhost:8000/all_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7\(aq); // Get Salt\(aqs \(dqreal time\(dq event stream. source.onopen = function() { source.send(\(aqwebsocket client ready\(aq); }; // Other handlers source.onerror = function(e) { console.debug(\(aqerror!\(aq, e); }; // e.data represents Salt\(aqs \(dqreal time\(dq event data as serialized JSON. source.onmessage = function(e) { console.debug(e.data); }; // Terminates websocket connection and Salt\(aqs \(dqreal time\(dq event stream on the server. source.close(); .ft P .fi .UNINDENT .UNINDENT .sp Or via Python, using the Python module \fI\%websocket\-client\fP for example. Or the tornado \fI\%client\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note, you must be authenticated! from websocket import create_connection # Get the Websocket connection to Salt ws = create_connection(\(aqwss://localhost:8000/all_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7\(aq) # Get Salt\(aqs \(dqreal time\(dq event stream. ws.send(\(aqwebsocket client ready\(aq) # Simple listener to print results of Salt\(aqs \(dqreal time\(dq event stream. # Look at https://pypi.python.org/pypi/websocket\-client/ for more examples. while listening_to_events: print ws.recv() # Salt\(aqs \(dqreal time\(dq event data as serialized JSON. # Terminates websocket connection and Salt\(aqs \(dqreal time\(dq event stream on the server. ws.close() # Please refer to https://github.com/liris/websocket\-client/issues/81 when using a self signed cert .ft P .fi .UNINDENT .UNINDENT .sp Above examples show how to establish a websocket connection to Salt and activating real time updates from Salt\(aqs event stream by signaling \fBwebsocket client ready\fP\&. .SS Formatted Events .sp Exposes \fBformatted\fP \(dqreal\-time\(dq events from Salt\(aqs event bus on a websocket connection. It should be noted that \(dqReal\-time\(dq here means these events are made available to the server as soon as any salt related action (changes to minions, new jobs etc) happens. Clients are however assumed to be able to tolerate any network transport related latencies. Functionality provided by this endpoint is similar to the \fB/events\fP end point. .sp The event bus on the Salt master exposes a large variety of things, notably when executions are started on the master and also when minions ultimately return their results. This URL provides a real\-time window into a running Salt infrastructure. Uses websocket as the transport mechanism. .sp Formatted events parses the raw \(dqreal time\(dq event stream and maintains a current view of the following: .INDENT 0.0 .IP \(bu 2 minions .IP \(bu 2 jobs .UNINDENT .sp A change to the minions (such as addition, removal of keys or connection drops) or jobs is processed and clients are updated. Since we use salt\(aqs presence events to track minions, please enable \fBpresence_events\fP and set a small value for the \fBloop_interval\fP in the salt master config file. .sp Exposes GET method to return websocket connections. All requests should include an auth token. A way to obtain obtain authentication tokens is shown below. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % curl \-si localhost:8000/login \e \-H \(dqAccept: application/json\(dq \e \-d username=\(aqsalt\(aq \e \-d password=\(aqsalt\(aq \e \-d eauth=\(aqpam\(aq .ft P .fi .UNINDENT .UNINDENT .sp Which results in the response .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { \(dqreturn\(dq: [{ \(dqperms\(dq: [\(dq.*\(dq, \(dq@runner\(dq, \(dq@wheel\(dq], \(dqstart\(dq: 1400556492.277421, \(dqtoken\(dq: \(dqd0ce6c1a37e99dcc0374392f272fe19c0090cca7\(dq, \(dqexpire\(dq: 1400599692.277422, \(dquser\(dq: \(dqsalt\(dq, \(dqeauth\(dq: \(dqpam\(dq }] } .ft P .fi .UNINDENT .UNINDENT .sp In this example the \fBtoken\fP returned is \fBd0ce6c1a37e99dcc0374392f272fe19c0090cca7\fP and can be included in subsequent websocket requests (as part of the URL). .sp The event stream can be easily consumed via JavaScript: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // Note, you must be authenticated! // Get the Websocket connection to Salt var source = new Websocket(\(aqwss://localhost:8000/formatted_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7\(aq); // Get Salt\(aqs \(dqreal time\(dq event stream. source.onopen = function() { source.send(\(aqwebsocket client ready\(aq); }; // Other handlers source.onerror = function(e) { console.debug(\(aqerror!\(aq, e); }; // e.data represents Salt\(aqs \(dqreal time\(dq event data as serialized JSON. source.onmessage = function(e) { console.debug(e.data); }; // Terminates websocket connection and Salt\(aqs \(dqreal time\(dq event stream on the server. source.close(); .ft P .fi .UNINDENT .UNINDENT .sp Or via Python, using the Python module \fI\%websocket\-client\fP for example. Or the tornado \fI\%client\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note, you must be authenticated! from websocket import create_connection # Get the Websocket connection to Salt ws = create_connection(\(aqwss://localhost:8000/formatted_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7\(aq) # Get Salt\(aqs \(dqreal time\(dq event stream. ws.send(\(aqwebsocket client ready\(aq) # Simple listener to print results of Salt\(aqs \(dqreal time\(dq event stream. # Look at https://pypi.python.org/pypi/websocket\-client/ for more examples. while listening_to_events: print ws.recv() # Salt\(aqs \(dqreal time\(dq event data as serialized JSON. # Terminates websocket connection and Salt\(aqs \(dqreal time\(dq event stream on the server. ws.close() # Please refer to https://github.com/liris/websocket\-client/issues/81 when using a self signed cert .ft P .fi .UNINDENT .UNINDENT .sp Above examples show how to establish a websocket connection to Salt and activating real time updates from Salt\(aqs event stream by signaling \fBwebsocket client ready\fP\&. .SS Example responses .sp \fBMinion information\fP is a dictionary keyed by each connected minion\(aqs \fBid\fP (\fBmid\fP), grains information for each minion is also included. .sp Minion information is sent in response to the following minion events: .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B connection drops .INDENT 7.0 .IP \(bu 2 requires running \fBmanage.present\fP periodically every \fBloop_interval\fP seconds .UNINDENT .UNINDENT .IP \(bu 2 minion addition .IP \(bu 2 minion removal .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Not all grains are shown data: { \(dqminions\(dq: { \(dqminion1\(dq: { \(dqid\(dq: \(dqminion1\(dq, \(dqgrains\(dq: { \(dqkernel\(dq: \(dqDarwin\(dq, \(dqdomain\(dq: \(dqlocal\(dq, \(dqzmqversion\(dq: \(dq4.0.3\(dq, \(dqkernelrelease\(dq: \(dq13.2.0\(dq } } } } .ft P .fi .UNINDENT .UNINDENT .sp \fBJob information\fP is also tracked and delivered. .sp Job information is also a dictionary in which each job\(aqs information is keyed by salt\(aqs \fBjid\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C data: { \(dqjobs\(dq: { \(dq20140609153646699137\(dq: { \(dqtgt_type\(dq: \(dqglob\(dq, \(dqjid\(dq: \(dq20140609153646699137\(dq, \(dqtgt\(dq: \(dq*\(dq, \(dqstart_time\(dq: \(dq2014\-06\-09T15:36:46.700315\(dq, \(dqstate\(dq: \(dqcomplete\(dq, \(dqfun\(dq: \(dqtest.ping\(dq, \(dqminions\(dq: { \(dqminion1\(dq: { \(dqreturn\(dq: true, \(dqretcode\(dq: 0, \(dqsuccess\(dq: true } } } } } .ft P .fi .UNINDENT .UNINDENT .SS Setup .SS REST URI Reference .INDENT 0.0 .IP \(bu 2 \fI\%/\fP .IP \(bu 2 \fI\%/login\fP .IP \(bu 2 \fI\%/minions\fP .IP \(bu 2 \fI\%/jobs\fP .IP \(bu 2 \fI\%/run\fP .IP \(bu 2 \fI\%/events\fP .IP \(bu 2 \fI\%/hook\fP .UNINDENT .SS \fB/\fP .INDENT 0.0 .TP .B class salt.netapi.rest_tornado.saltnado.SaltAPIHandler(*args, **kwargs) Main API handler for base \(dq/\(dq .INDENT 7.0 .TP .B disbatch() Disbatch all lowstates to the appropriate clients .UNINDENT .INDENT 7.0 .TP .B get() An endpoint to determine salt\-api capabilities .INDENT 7.0 .TP .B GET / .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-i localhost:8000 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET / HTTP/1.1 Host: localhost:8000 Accept: application/json .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Type: application/json Content\-Legnth: 83 {\(dqclients\(dq: [\(dqlocal\(dq, \(dqlocal_async\(dq, \(dqrunner\(dq, \(dqrunner_async\(dq], \(dqreturn\(dq: \(dqWelcome\(dq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B post() Send one or more Salt commands (lowstates) in the request body .INDENT 7.0 .TP .B POST / .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fIX\-Auth\-Token\fP \-\- a session token from \fI\%SaltAuthHandler\fP\&. .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .IP \(bu 2 \fI\%Content\-Type\fP \-\- the format of the request body. .UNINDENT .TP .B Response Headers .INDENT 7.0 .IP \(bu 2 \fI\%Content\-Type\fP \-\- the format of the response body; depends on the \fIAccept\fP request header. .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .sp \fI\%lowstate\fP data describing Salt commands must be sent in the request body. .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-si https://localhost:8000 \e \-H \(dqAccept: application/x\-yaml\(dq \e \-H \(dqX\-Auth\-Token: d40d1e1e\(dq \e \-d client=local \e \-d tgt=\(aq*\(aq \e \-d fun=\(aqtest.ping\(aq \e \-d arg .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C POST / HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml X\-Auth\-Token: d40d1e1e Content\-Length: 36 Content\-Type: application/x\-www\-form\-urlencoded fun=test.ping&arg&client=local&tgt=* .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .sp Responses are an in\-order list of the lowstate\(aqs return data. In the event of an exception running a command the return will be a string instead of a mapping. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 200 Allow: GET, HEAD, POST Content\-Type: application/x\-yaml return: \- ms\-0: true ms\-1: true ms\-2: true ms\-3: true ms\-4: true .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .IP "multiple commands" .sp Note that if multiple \fI\%lowstate\fP structures are sent, the Salt API will execute them in serial, and will not stop execution upon failure of a previous job. If you need to have commands executed in order and stop on failure please use compound\-command\-execution. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/login\fP .INDENT 0.0 .TP .B class salt.netapi.rest_tornado.saltnado.SaltAuthHandler(*args, **kwargs) Handler for login requests .INDENT 7.0 .TP .B get() All logins are done over post, this is a parked endpoint .INDENT 7.0 .TP .B GET /login .INDENT 7.0 .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-i localhost:8000/login .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /login HTTP/1.1 Host: localhost:8000 Accept: application/json .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 401 Unauthorized Content\-Type: application/json Content\-Length: 58 {\(dqstatus\(dq: \(dq401 Unauthorized\(dq, \(dqreturn\(dq: \(dqPlease log in\(dq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B post() \fI\%Authenticate\fP against Salt\(aqs eauth system .INDENT 7.0 .TP .B POST /login .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fIX\-Auth\-Token\fP \-\- a session token from \fI\%SaltAuthHandler\fP\&. .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .IP \(bu 2 \fI\%Content\-Type\fP \-\- the format of the request body. .UNINDENT .TP .B Form Parameters .INDENT 7.0 .IP \(bu 2 \fBeauth\fP \-\- the eauth backend configured for the user .IP \(bu 2 \fBusername\fP \-\- username .IP \(bu 2 \fBpassword\fP \-\- password .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%400 Bad Request\fP \-\- bad request .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .IP \(bu 2 \fI\%500 Internal Server Error\fP \-\- internal server error .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-si localhost:8000/login \e \-H \(dqAccept: application/json\(dq \e \-d username=\(aqsaltuser\(aq \e \-d password=\(aqsaltpass\(aq \e \-d eauth=\(aqpam\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C POST / HTTP/1.1 Host: localhost:8000 Content\-Length: 42 Content\-Type: application/x\-www\-form\-urlencoded Accept: application/json username=saltuser&password=saltpass&eauth=pam .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Type: application/json Content\-Length: 206 X\-Auth\-Token: 6d1b722e Set\-Cookie: session_id=6d1b722e; expires=Sat, 17 Nov 2012 03:23:52 GMT; Path=/ {\(dqreturn\(dq: { \(dqtoken\(dq: \(dq6d1b722e\(dq, \(dqstart\(dq: 1363805943.776223, \(dqexpire\(dq: 1363849143.776224, \(dquser\(dq: \(dqsaltuser\(dq, \(dqeauth\(dq: \(dqpam\(dq, \(dqperms\(dq: [ \(dqgrains.*\(dq, \(dqstatus.*\(dq, \(dqsys.*\(dq, \(dqtest.*\(dq ] }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/minions\fP .INDENT 0.0 .TP .B class salt.netapi.rest_tornado.saltnado.MinionSaltAPIHandler(*args, **kwargs) A convenience endpoint for minion related functions .INDENT 7.0 .TP .B get(mid=None) A convenience URL for getting lists of minions or getting minion details .INDENT 7.0 .TP .B GET /minions/(mid) .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fIX\-Auth\-Token\fP \-\- a session token from \fI\%SaltAuthHandler\fP\&. .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-i localhost:8000/minions/ms\-3 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /minions/ms\-3 HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 129005 Content\-Type: application/x\-yaml return: \- ms\-3: grains.items: ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B post() Start an execution command and immediately return the job id .INDENT 7.0 .TP .B POST /minions .INDENT 7.0 .TP .B Request Headers .INDENT 7.0 .IP \(bu 2 \fIX\-Auth\-Token\fP \-\- a session token from \fI\%SaltAuthHandler\fP\&. .IP \(bu 2 \fI\%Accept\fP \-\- the desired response format. .IP \(bu 2 \fI\%Content\-Type\fP \-\- the format of the request body. .UNINDENT .TP .B Response Headers .INDENT 7.0 .IP \(bu 2 \fI\%Content\-Type\fP \-\- the format of the response body; depends on the \fIAccept\fP request header. .UNINDENT .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .sp \fI\%lowstate\fP data describing Salt commands must be sent in the request body. The \fBclient\fP option will be set to \fBlocal_async()\fP\&. .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-sSi localhost:8000/minions \e \-H \(dqAccept: application/x\-yaml\(dq \e \-d tgt=\(aq*\(aq \e \-d fun=\(aqstatus.diskusage\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C POST /minions HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml Content\-Length: 26 Content\-Type: application/x\-www\-form\-urlencoded tgt=*&fun=status.diskusage .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 202 Accepted Content\-Length: 86 Content\-Type: application/x\-yaml return: \- jid: \(aq20130603122505459265\(aq minions: [ms\-4, ms\-3, ms\-2, ms\-1, ms\-0] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/jobs\fP .INDENT 0.0 .TP .B class salt.netapi.rest_tornado.saltnado.JobsSaltAPIHandler(*args, **kwargs) A convenience endpoint for job cache data .INDENT 7.0 .TP .B get(jid=None) A convenience URL for getting lists of previously run jobs or getting the return from a single job .INDENT 7.0 .TP .B GET /jobs/(jid) List jobs or show a single job from the job cache. .INDENT 7.0 .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-i localhost:8000/jobs .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /jobs HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 165 Content\-Type: application/x\-yaml return: \- \(aq20121130104633606931\(aq: Arguments: \- \(aq3\(aq Function: test.fib Start Time: 2012, Nov 30 10:46:33.606931 Target: jerry Target\-type: glob .ft P .fi .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-i localhost:8000/jobs/20121130104633606931 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /jobs/20121130104633606931 HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 73 Content\-Type: application/x\-yaml info: \- Arguments: \- \(aq3\(aq Function: test.fib Minions: \- jerry Start Time: 2012, Nov 30 10:46:33.606931 Target: \(aq*\(aq Target\-type: glob User: saltdev jid: \(aq20121130104633606931\(aq return: \- jerry: \- \- 0 \- 1 \- 1 \- 2 \- 6.9141387939453125e\-06 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/run\fP .INDENT 0.0 .TP .B class salt.netapi.rest_tornado.saltnado.RunSaltAPIHandler(*args, **kwargs) Endpoint to run commands without normal session handling .INDENT 7.0 .TP .B post() Run commands bypassing the \fI\%normal session handling\fP .INDENT 7.0 .TP .B POST /run This entry point is primarily for \(dqone\-off\(dq commands. Each request must pass full Salt authentication credentials. Otherwise this URL is identical to the \fBroot URL (/)\fP\&. .sp \fI\%lowstate\fP data describing Salt commands must be sent in the request body. .INDENT 7.0 .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-sS localhost:8000/run \e \-H \(aqAccept: application/x\-yaml\(aq \e \-d client=\(aqlocal\(aq \e \-d tgt=\(aq*\(aq \e \-d fun=\(aqtest.ping\(aq \e \-d username=\(aqsaltdev\(aq \e \-d password=\(aqsaltdev\(aq \e \-d eauth=\(aqpam\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C POST /run HTTP/1.1 Host: localhost:8000 Accept: application/x\-yaml Content\-Length: 75 Content\-Type: application/x\-www\-form\-urlencoded client=local&tgt=*&fun=test.ping&username=saltdev&password=saltdev&eauth=pam .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 73 Content\-Type: application/x\-yaml return: \- ms\-0: true ms\-1: true ms\-2: true ms\-3: true ms\-4: true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/events\fP .INDENT 0.0 .TP .B class salt.netapi.rest_tornado.saltnado.EventsSaltAPIHandler(*args, **kwargs) Expose the Salt event bus .sp The event bus on the Salt master exposes a large variety of things, notably when executions are started on the master and also when minions ultimately return their results. This URL provides a real\-time window into a running Salt infrastructure. .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 \fI\%Events & Reactor\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get() An HTTP stream of the Salt master event bus .sp This stream is formatted per the Server Sent Events (SSE) spec. Each event is formatted as JSON. .INDENT 7.0 .TP .B GET /events .INDENT 7.0 .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-NsS localhost:8000/events .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C GET /events HTTP/1.1 Host: localhost:8000 .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Connection: keep\-alive Cache\-Control: no\-cache Content\-Type: text/event\-stream;charset=utf\-8 retry: 400 data: {\(aqtag\(aq: \(aq\(aq, \(aqdata\(aq: {\(aqminions\(aq: [\(aqms\-4\(aq, \(aqms\-3\(aq, \(aqms\-2\(aq, \(aqms\-1\(aq, \(aqms\-0\(aq]}} data: {\(aqtag\(aq: \(aq20130802115730568475\(aq, \(aqdata\(aq: {\(aqjid\(aq: \(aq20130802115730568475\(aq, \(aqreturn\(aq: True, \(aqretcode\(aq: 0, \(aqsuccess\(aq: True, \(aqcmd\(aq: \(aq_return\(aq, \(aqfun\(aq: \(aqtest.ping\(aq, \(aqid\(aq: \(aqms\-1\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp The event stream can be easily consumed via JavaScript: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C <!\-\- Note, you must be authenticated! \-\-> var source = new EventSource(\(aq/events\(aq); source.onopen = function() { console.debug(\(aqopening\(aq) }; source.onerror = function(e) { console.debug(\(aqerror!\(aq, e) }; source.onmessage = function(e) { console.debug(e.data) }; .ft P .fi .UNINDENT .UNINDENT .sp Or using CORS: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C var source = new EventSource(\(aq/events\(aq, {withCredentials: true}); .ft P .fi .UNINDENT .UNINDENT .sp Some browser clients lack CORS support for the \fBEventSource()\fP API. Such clients may instead pass the \fIX\-Auth\-Token\fP value as an URL parameter: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-NsS localhost:8000/events/6d1b722e .ft P .fi .UNINDENT .UNINDENT .sp It is also possible to consume the stream via the shell. .sp Records are separated by blank lines; the \fBdata:\fP and \fBtag:\fP prefixes will need to be removed manually before attempting to unserialize the JSON. .sp curl\(aqs \fB\-N\fP flag turns off input buffering which is required to process the stream incrementally. .sp Here is a basic example of printing each event as it comes in: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-NsS localhost:8000/events |\e while IFS= read \-r line ; do echo $line done .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of using awk to filter events based on tag: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-NsS localhost:8000/events |\e awk \(aq BEGIN { RS=\(dq\(dq; FS=\(dq\e\en\(dq } $1 ~ /^tag: salt\e/job\e/[0\-9]+\e/new$/ { print $0 } \(aq tag: salt/job/20140112010149808995/new data: {\(dqtag\(dq: \(dqsalt/job/20140112010149808995/new\(dq, \(dqdata\(dq: {\(dqtgt_type\(dq: \(dqglob\(dq, \(dqjid\(dq: \(dq20140112010149808995\(dq, \(dqtgt\(dq: \(dqjerry\(dq, \(dq_stamp\(dq: \(dq2014\-01\-12_01:01:49.809617\(dq, \(dquser\(dq: \(dqshouse\(dq, \(dqarg\(dq: [], \(dqfun\(dq: \(dqtest.ping\(dq, \(dqminions\(dq: [\(dqjerry\(dq]}} tag: 20140112010149808995 data: {\(dqtag\(dq: \(dq20140112010149808995\(dq, \(dqdata\(dq: {\(dqfun_args\(dq: [], \(dqjid\(dq: \(dq20140112010149808995\(dq, \(dqreturn\(dq: true, \(dqretcode\(dq: 0, \(dqsuccess\(dq: true, \(dqcmd\(dq: \(dq_return\(dq, \(dq_stamp\(dq: \(dq2014\-01\-12_01:01:49.819316\(dq, \(dqfun\(dq: \(dqtest.ping\(dq, \(dqid\(dq: \(dqjerry\(dq}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fB/hook\fP .INDENT 0.0 .TP .B class salt.netapi.rest_tornado.saltnado.WebhookSaltAPIHandler(*args, **kwargs) A generic web hook entry point that fires an event on Salt\(aqs event bus .sp External services can POST data to this URL to trigger an event in Salt. For example, Amazon SNS, Jenkins\-CI or Travis\-CI, or GitHub web hooks. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Be mindful of security .sp Salt\(aqs Reactor can run any code. A Reactor SLS that responds to a hook event is responsible for validating that the event came from a trusted source and contains valid data. .sp \fBThis is a generic interface and securing it is up to you!\fP .sp This URL requires authentication however not all external services can be configured to authenticate. For this reason authentication can be selectively disabled for this URL. Follow best practices \-\- always use SSL, pass a secret key, configure the firewall to only allow traffic from a known source, etc. .UNINDENT .UNINDENT .sp The event data is taken from the request body. The \fIContent\-Type\fP header is respected for the payload. .sp The event tag is prefixed with \fBsalt/netapi/hook\fP and the URL path is appended to the end. For example, a \fBPOST\fP request sent to \fB/hook/mycompany/myapp/mydata\fP will produce a Salt event with the tag \fBsalt/netapi/hook/mycompany/myapp/mydata\fP\&. .sp The following is an example \fB\&.travis.yml\fP file to send notifications to Salt of successful test runs: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C language: python script: python \-m unittest tests after_success: \- \(aqcurl \-sS http://saltapi\-url.example.com:8000/hook/travis/build/success \-d branch=\(dq${TRAVIS_BRANCH}\(dq \-d commit=\(dq${TRAVIS_COMMIT}\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 \fI\%Events\fP, \fI\%Reactor\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B post(tag_suffix=None) Fire an event in Salt with a custom event tag and data .INDENT 7.0 .TP .B POST /hook .INDENT 7.0 .TP .B Status Codes .INDENT 7.0 .IP \(bu 2 \fI\%200 OK\fP \-\- success .IP \(bu 2 \fI\%401 Unauthorized\fP \-\- authentication required .IP \(bu 2 \fI\%406 Not Acceptable\fP \-\- requested Content\-Type not available .IP \(bu 2 \fI\%413 Request Entity Too Large\fP \-\- request body is too large .UNINDENT .UNINDENT .UNINDENT .sp \fBExample request:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C curl \-sS localhost:8000/hook \-d foo=\(aqFoo!\(aq \-d bar=\(aqBar!\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C POST /hook HTTP/1.1 Host: localhost:8000 Content\-Length: 16 Content\-Type: application/x\-www\-form\-urlencoded foo=Foo&bar=Bar! .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.1 200 OK Content\-Length: 14 Content\-Type: application/json {\(dqsuccess\(dq: true} .ft P .fi .UNINDENT .UNINDENT .sp As a practical example, an internal continuous\-integration build server could send an HTTP POST request to the URL \fBhttp://localhost:8000/hook/mycompany/build/success\fP which contains the result of a build and the SHA of the version that was built as JSON. That would then produce the following event in Salt that could be used to kick off a deployment via Salt\(aqs Reactor: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Event fired at Fri Feb 14 17:40:11 2014 ************************* Tag: salt/netapi/hook/mycompany/build/success Data: {\(aq_stamp\(aq: \(aq2014\-02\-14_17:40:11.440996\(aq, \(aqheaders\(aq: { \(aqX\-My\-Secret\-Key\(aq: \(aqF0fAgoQjIT@W\(aq, \(aqContent\-Length\(aq: \(aq37\(aq, \(aqContent\-Type\(aq: \(aqapplication/json\(aq, \(aqHost\(aq: \(aqlocalhost:8000\(aq, \(aqRemote\-Addr\(aq: \(aq127.0.0.1\(aq}, \(aqpost\(aq: {\(aqrevision\(aq: \(aqaa22a3c4b2e7\(aq, \(aqresult\(aq: True}} .ft P .fi .UNINDENT .UNINDENT .sp Salt\(aqs Reactor could listen for the event: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C reactor: \- \(aqsalt/netapi/hook/mycompany/build/*\(aq: \- /srv/reactor/react_ci_builds.sls .ft P .fi .UNINDENT .UNINDENT .sp And finally deploy the new build: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set secret_key = data.get(\(aqheaders\(aq, {}).get(\(aqX\-My\-Secret\-Key\(aq) %} {% set build = data.get(\(aqpost\(aq, {}) %} {% if secret_key == \(aqF0fAgoQjIT@W\(aq and build.result == True %} deploy_my_app: cmd.state.sls: \- tgt: \(aqapplication*\(aq \- arg: \- myapp.deploy \- kwarg: pillar: revision: {{ revision }} {% endif %} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS rest_wsgi .SS A minimalist REST API for Salt .sp This \fBrest_wsgi\fP module provides a no\-frills REST interface for sending commands to the Salt master. There are no dependencies. .sp Extra care must be taken when deploying this module into production. Please read this documentation in entirety. .sp All authentication is done through Salt\(aqs \fI\%external auth\fP system. .SS Usage .INDENT 0.0 .IP \(bu 2 All requests must be sent to the root URL (\fB/\fP). .IP \(bu 2 All requests must be sent as a POST request with JSON content in the request body. .IP \(bu 2 All responses are in JSON. .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%rest_cherrypy\fP .sp The \fI\%rest_cherrypy\fP module is more full\-featured, production\-ready, and has builtin security features. .UNINDENT .UNINDENT .SS Deployment .sp The \fBrest_wsgi\fP netapi module is a standard Python WSGI app. It can be deployed one of two ways. .SS Using a WSGI\-compliant web server .sp This module may be run via any WSGI\-compliant production server such as Apache with mod_wsgi or Nginx with FastCGI. .sp It is strongly recommended that this app be used with a server that supports HTTPS encryption since raw Salt authentication credentials must be sent with every request. Any apps that access Salt through this interface will need to manually manage authentication credentials (either username and password or a Salt token). Tread carefully. .SS \fBsalt\-api\fP using a development\-only server .sp If run directly via the salt\-api daemon it uses the \fI\%wsgiref.simple_server()\fP that ships in the Python standard library. This is a single\-threaded server that is intended for testing and development. \fBThis server does not use encryption\fP; please note that raw Salt authentication credentials must be sent with every HTTP request. .sp \fBRunning this module via salt\-api is not recommended!\fP .sp In order to start this module via the \fBsalt\-api\fP daemon the following must be put into the Salt master config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rest_wsgi: port: 8001 .ft P .fi .UNINDENT .UNINDENT .SS Usage examples .INDENT 0.0 .TP .B POST / \fBExample request\fP for a basic \fBtest.ping\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C % curl \-sS \-i \e \-H \(aqContent\-Type: application/json\(aq \e \-d \(aq[{\(dqeauth\(dq:\(dqpam\(dq,\(dqusername\(dq:\(dqsaltdev\(dq,\(dqpassword\(dq:\(dqsaltdev\(dq,\(dqclient\(dq:\(dqlocal\(dq,\(dqtgt\(dq:\(dq*\(dq,\(dqfun\(dq:\(dqtest.ping\(dq}]\(aq localhost:8001 .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.0 200 OK Content\-Length: 89 Content\-Type: application/json {\(dqreturn\(dq: [{\(dqms\-\-4\(dq: true, \(dqms\-\-3\(dq: true, \(dqms\-\-2\(dq: true, \(dqms\-\-1\(dq: true, \(dqms\-\-0\(dq: true}]} .ft P .fi .UNINDENT .UNINDENT .sp \fBExample request\fP for an asynchronous \fBtest.ping\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C % curl \-sS \-i \e \-H \(aqContent\-Type: application/json\(aq \e \-d \(aq[{\(dqeauth\(dq:\(dqpam\(dq,\(dqusername\(dq:\(dqsaltdev\(dq,\(dqpassword\(dq:\(dqsaltdev\(dq,\(dqclient\(dq:\(dqlocal_async\(dq,\(dqtgt\(dq:\(dq*\(dq,\(dqfun\(dq:\(dqtest.ping\(dq}]\(aq localhost:8001 .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.0 200 OK Content\-Length: 103 Content\-Type: application/json {\(dqreturn\(dq: [{\(dqjid\(dq: \(dq20130412192112593739\(dq, \(dqminions\(dq: [\(dqms\-\-4\(dq, \(dqms\-\-3\(dq, \(dqms\-\-2\(dq, \(dqms\-\-1\(dq, \(dqms\-\-0\(dq]}]} .ft P .fi .UNINDENT .UNINDENT .sp \fBExample request\fP for looking up a job ID: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C % curl \-sS \-i \e \-H \(aqContent\-Type: application/json\(aq \e \-d \(aq[{\(dqeauth\(dq:\(dqpam\(dq,\(dqusername\(dq:\(dqsaltdev\(dq,\(dqpassword\(dq:\(dqsaltdev\(dq,\(dqclient\(dq:\(dqrunner\(dq,\(dqfun\(dq:\(dqjobs.lookup_jid\(dq,\(dqjid\(dq:\(dq20130412192112593739\(dq}]\(aq localhost:8001 .ft P .fi .UNINDENT .UNINDENT .sp \fBExample response\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HTTP/1.0 200 OK Content\-Length: 89 Content\-Type: application/json {\(dqreturn\(dq: [{\(dqms\-\-4\(dq: true, \(dqms\-\-3\(dq: true, \(dqms\-\-2\(dq: true, \(dqms\-\-1\(dq: true, \(dqms\-\-0\(dq: true}]} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B form lowstate A list of lowstate data appropriate for the \fI\%client\fP interface you are calling. .TP .B status 200 success .TP .B status 401 authentication required .UNINDENT .SS output modules .sp Follow one of the below links for further information and examples .TS center; |l|l|. _ T{ \fI\%dson\fP T} T{ Display return data in DSON format T} _ T{ \fI\%highstate\fP T} T{ Outputter for displaying results of state runs T} _ T{ \fI\%json_out\fP T} T{ Display return data in JSON format T} _ T{ \fI\%key\fP T} T{ Display salt\-key output T} _ T{ \fI\%nested\fP T} T{ Recursively display nested data T} _ T{ \fI\%newline_values_only\fP T} T{ Display values only, separated by newlines T} _ T{ \fI\%no_out_quiet\fP T} T{ Display no output T} _ T{ \fI\%no_return\fP T} T{ Display output for minions that did not return T} _ T{ \fI\%overstatestage\fP T} T{ Display clean output of an overstate stage T} _ T{ \fI\%pony\fP T} T{ Display Pony output data structure T} _ T{ \fI\%pprint_out\fP T} T{ Python pretty\-print (pprint) T} _ T{ \fI\%profile\fP T} T{ Display profiling data in a table format T} _ T{ \fI\%progress\fP T} T{ Display return data as a progress bar T} _ T{ \fI\%raw\fP T} T{ Display raw output data structure T} _ T{ \fI\%table_out\fP T} T{ Display output in a table format T} _ T{ \fI\%txt\fP T} T{ Simple text outputter T} _ T{ \fI\%virt_query\fP T} T{ virt.query outputter T} _ T{ \fI\%yaml_out\fP T} T{ Display return data in YAML format T} _ .TE .SS salt.output.dson .SS Display return data in DSON format .sp This outputter is intended for demonstration purposes. Information on the DSON spec can be found \fI\%here\fP\&. .sp This outputter requires \fI\%Dogeon\fP (installable via pip) .INDENT 0.0 .TP .B salt.output.dson.output(data, **kwargs) Print the output data in JSON .UNINDENT .SS salt.output.highstate .SS Outputter for displaying results of state runs .sp The return data from the Highstate command is a standard data structure which is parsed by the highstate outputter to deliver a clean and readable set of information about the HighState run on minions. .sp Two configurations can be set to modify the highstate outputter. These values can be set in the master config to change the output of the \fBsalt\fP command or set in the minion config to change the output of the \fBsalt\-call\fP command. .INDENT 0.0 .TP .B state_verbose: By default \fIstate_verbose\fP is set to \fITrue\fP, setting this to \fIFalse\fP will instruct the highstate outputter to omit displaying anything in green, this means that nothing with a result of True and no changes will not be printed .TP .B state_output: The highstate outputter has six output modes, \fBfull\fP, \fBterse\fP, \fBmixed\fP, \fBchanges\fP and \fBfilter\fP .INDENT 7.0 .IP \(bu 2 The default is set to \fBfull\fP, which will display many lines of detailed information for each executed chunk. .IP \(bu 2 If \fBterse\fP is used, then the output is greatly simplified and shown in only one line. .IP \(bu 2 If \fBmixed\fP is used, then terse output will be used unless a state failed, in which case full output will be used. .IP \(bu 2 If \fBchanges\fP is used, then terse output will be used if there was no error and no changes, otherwise full output will be used. .IP \(bu 2 If \fBfilter\fP is used, then either or both of two different filters can be used: \fBexclude\fP or \fBterse\fP\&. .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 for \fBexclude\fP, state.highstate expects a list of states to be excluded (or \fBNone\fP) followed by \fBTrue\fP for terse output or \fBFalse\fP for regular output. Because of parsing nuances, if only one of these is used, it must still contain a comma. For instance: \fIexclude=True,\fP\&. .IP \(bu 2 for \fBterse\fP, state.highstate expects simply \fBTrue\fP or \fBFalse\fP\&. .UNINDENT .UNINDENT .UNINDENT .sp These can be set as such from the command line, or in the Salt config as \fIstate_output_exclude\fP or \fIstate_output_terse\fP, respectively. .UNINDENT .sp The output modes have one modifier: .sp \fBfull_id\fP, \fBterse_id\fP, \fBmixed_id\fP, \fBchanges_id\fP and \fBfilter_id\fP If \fB_id\fP is used, then the corresponding form will be used, but the value for \fBname\fP will be drawn from the state ID. This is useful for cases where the name value might be very long and hard to read. .TP .B state_tabular: If \fIstate_output\fP uses the terse output, set this to \fITrue\fP for an aligned output format. If you wish to use a custom format, this can be set to a string. .TP .B state_output_pct: Set \fIstate_output_pct\fP to \fITrue\fP in order to add \(dqSuccess %\(dq and \(dqFailure %\(dq to the \(dqSummary\(dq section at the end of the highstate output. .TP .B state_compress_ids: Set \fIstate_compress_ids\fP to \fITrue\fP to aggregate information about states which have multiple \(dqnames\(dq under the same state ID in the highstate output. This is useful in combination with the \fIterse_id\fP value set in the \fIstate_output\fP option when states are using the \fInames\fP state parameter. .UNINDENT .sp Example usage: .sp If \fBstate_output: filter\fP is set in the configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.highstate exclude=None,True .ft P .fi .UNINDENT .UNINDENT .sp means to exclude no states from the highstate and turn on terse output. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt twd state.highstate exclude=problemstate1,problemstate2,False .ft P .fi .UNINDENT .UNINDENT .sp means to exclude states \fBproblemstate1\fP and \fBproblemstate2\fP from the highstate, and use regular output. .sp Example output for the above highstate call when \fBtop.sls\fP defines only one other state to apply to minion \fBtwd\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C twd: Summary for twd \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 1 (changed=1) Failed: 0 \-\-\-\-\-\-\-\-\-\-\-\- Total states run: 1 .ft P .fi .UNINDENT .UNINDENT .sp Example output with no special settings in configuration files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myminion: \-\-\-\-\-\-\-\-\-\- ID: test.ping Function: module.run Result: True Comment: Module function test.ping executed Changes: \-\-\-\-\-\-\-\-\-\- ret: True Summary for myminion \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 1 Failed: 0 \-\-\-\-\-\-\-\-\-\-\-\- Total: 0 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.highstate.output(data, **kwargs) The HighState Outputter is only meant to be used with the state.highstate function, or a function that returns highstate return data. .UNINDENT .SS salt.output.json_out .SS Display return data in JSON format .INDENT 0.0 .TP .B configuration The output format can be configured in two ways: Using the \fB\-\-out\-indent\fP CLI flag and specifying a positive integer or a negative integer to group JSON from each minion to a single line. .sp Or setting the \fBoutput_indent\fP setting in the Master or Minion configuration file with one of the following values: .INDENT 7.0 .IP \(bu 2 \fBNull\fP: put each minion return on a single line. .IP \(bu 2 \fBpretty\fP: use four\-space indents and sort the keys. .IP \(bu 2 An integer: specify the indentation level. .UNINDENT .UNINDENT .sp Salt\(aqs outputters operate on a per\-minion basis. Each minion return will be output as a single JSON object once it comes in to the master. .sp Some JSON parsers can guess when an object ends and a new one begins but many can not. A good way to differentiate between each minion return is to use the single\-line output format and to parse each line individually. Example output (truncated): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {\(dqdave\(dq: {\(dqen0\(dq: {\(dqhwaddr\(dq: \(dq02:b0:26:32:4c:69\(dq, ...}}} {\(dqjerry\(dq: {\(dqen0\(dq: {\(dqhwaddr\(dq: \(dq02:26:ab:0d:b9:0d\(dq, ...}}} {\(dqkevin\(dq: {\(dqen0\(dq: {\(dqhwaddr\(dq: \(dq02:6d:7f:ce:9f:ee\(dq, ...}}} {\(dqmike\(dq: {\(dqen0\(dq: {\(dqhwaddr\(dq: \(dq02:48:a2:4b:70:a0\(dq, ...}}} {\(dqphill\(dq: {\(dqen0\(dq: {\(dqhwaddr\(dq: \(dq02:1d:cc:a2:33:55\(dq, ...}}} {\(dqstuart\(dq: {\(dqen0\(dq: {\(dqhwaddr\(dq: \(dq02:9a:e0:ea:9e:3c\(dq, ...}}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq foo.bar \-\-out=json .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.json_out.output(data, **kwargs) Print the output data in JSON .UNINDENT .SS salt.output.key .SS Display salt\-key output .sp The \fBsalt\-key\fP command makes use of this outputter to format its output. .INDENT 0.0 .TP .B salt.output.key.output(data, **kwargs) Read in the dict structure generated by the salt key API methods and print the structure. .UNINDENT .SS salt.output.nested .SS Recursively display nested data .sp This is the default outputter for most execution functions. .sp Example output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myminion: \-\-\-\-\-\-\-\-\-\- foo: \-\-\-\-\-\-\-\-\-\- bar: baz dictionary: \-\-\-\-\-\-\-\-\-\- abc: 123 def: 456 list: \- Hello \- World .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.output.nested.NestDisplay(retcode=0) Manage the nested display contents .INDENT 7.0 .TP .B display(ret, indent, prefix, out) Recursively iterate down through data structures to determine output .UNINDENT .INDENT 7.0 .TP .B ustring(indent, color, msg, prefix=\(aq\(aq, suffix=\(aq\(aq, endc=None) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.nested.output(ret, **kwargs) Display ret data .UNINDENT .SS salt.output.newline_values_only .SS Display values only, separated by newlines .sp New in version 2015.5.0. .sp This outputter is designed for Salt CLI return data. It will do the following to the return dict: .INDENT 0.0 .IP 1. 3 Get just the values (ignoring the minion IDs). .IP 2. 3 Each value, if it is iterable, is split a separate line. .IP 3. 3 Each minion\(aqs values are separated by newlines. .UNINDENT .sp This results in a single string of return data containing all the values from the various minions. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 As noted above, this outputter will discard the minion ID. If the minion ID is important, then an outputter that returns the full return dictionary in a parsable format (such as \fBjson\fP, \fBpprint,\fP, or \fByaml\fP) may be more suitable. .UNINDENT .UNINDENT .SS Example 1 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq foo.bar \-\-out=newline_values_only .ft P .fi .UNINDENT .UNINDENT .SS Input .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { \(aqmyminion\(aq: [\(aq127.0.0.1\(aq, \(aq10.0.0.1\(aq], \(aqsecond\-minion\(aq: [\(aq127.0.0.1\(aq, \(aq10.0.0.2\(aq] } .ft P .fi .UNINDENT .UNINDENT .SS Output .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 127.0.0.1 10.0.0.1 127.0.0.1 10.0.0.2 .ft P .fi .UNINDENT .UNINDENT .SS Example 2 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq foo.bar \-\-out=newline_values_only .ft P .fi .UNINDENT .UNINDENT .SS Input .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { \(aqmyminion\(aq: 8, \(aqsecond\-minion\(aq: 10 } .ft P .fi .UNINDENT .UNINDENT .SS Output .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 8 10 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.newline_values_only.output(data, **kwargs) Display modified ret data .UNINDENT .SS salt.output.no_out_quiet .SS Display no output .sp No output is produced when this outputter is selected .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq foo.bar \-\-out=quiet .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.no_out_quiet.output(ret, **kwargs) Don\(aqt display data. Used when you only are interested in the return. .UNINDENT .SS salt.output.no_return .SS Display output for minions that did not return .sp This outputter is used to display notices about which minions failed to return when a salt function is run with \fB\-v\fP or \fB\-\-verbose\fP\&. It should not be called directly from the CLI. .sp Example output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virtucentos: Minion did not return .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.output.no_return.NestDisplay Create generator for nested output .INDENT 7.0 .TP .B display(ret, indent, prefix, out) Recursively iterate down through data structures to determine output .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.no_return.output(ret, **kwargs) Display ret data .UNINDENT .SS salt.output.overstatestage .SS Display clean output of an overstate stage .sp This outputter is used to display \fI\%Orchestrate Runner\fP stages, and should not be called directly. .INDENT 0.0 .TP .B salt.output.overstatestage.output(data, **kwargs) Format the data for printing stage information from the overstate system .UNINDENT .SS salt.output.pony .SS Display Pony output data structure .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 ponysay CLI program .UNINDENT .UNINDENT .sp Display output from a pony. Ponies are better than cows because everybody wants a pony. .sp Example output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C < {\(aqlocal\(aq: True} > \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \e \e \e ▄▄▄▄▄▄▄ ▀▄▄████▄▄ ▄▄▄█████▄█▄█▄█▄▄▄ ██████▄▄▄█▄▄█████▄▄ ▀▄▀ █████▄▄█▄▄█████ ▄▄▄███████████▄▄▄ ████▄▄▄▄▄▄███▄▄██ ▄▄▄▄▄▄▄ ████▄████▄██▄▄███ ▄▄▄▄██▄▄▄▄▄▄ █▄███▄▄█▄███▄▄██▄▀ ▄▄███████▄▄███▄▄ ▀▄██████████████▄▄ ▄▄█▄▀▀▀▄▄█████▄▄██ ▀▀▀▀▀█████▄█▄█▄▄▄▄▄▄▄█ ▀▄████▄████ ████▄███▄▄▄▄▄▄▄▄▄ ▄▄█████▄███ ▀▄█▄█▄▄▄██▄▄▄▄▄██ ▄▄██▄██████ ▀▄████████████▄▀ ▄▄█▄██████▄▀ ██▄██▄▄▄▄█▄███▄ ███▄▄▄▄▄██▄▀ ██████ ▀▄▄█████ ▀████████ ▄▄▄▄███ ███████ ██████▄█▄▄ ███████ ████████▀▄▀███▄▄█▄▄ ▄██▄▄████ ████████ ▀▄██▀▄▄▀ █▄▄██████ █▄▄██████ █▄▄▄▄█ █▄▄▄▄█ .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq foo.bar \-\-out=pony .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.pony.output(data, **kwargs) Mane function .UNINDENT .SS salt.output.pprint_out .SS Python pretty\-print (pprint) .sp The python pretty\-print system was once the default outputter. It simply passes the return data through to \fBpprint.pformat\fP and prints the results. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq foo.bar \-\-out=pprint .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {\(aqsaltmine\(aq: {\(aqfoo\(aq: {\(aqbar\(aq: \(aqbaz\(aq, \(aqdictionary\(aq: {\(aqabc\(aq: 123, \(aqdef\(aq: 456}, \(aqlist\(aq: [\(aqHello\(aq, \(aqWorld\(aq]}}} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.pprint_out.output(data, **kwargs) Print out via pretty print .UNINDENT .SS salt.output.profile .SS Display profiling data in a table format .sp Show profile data for returners that would normally show a highstate output. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply something \-\-out=profile .ft P .fi .UNINDENT .UNINDENT .sp Attempt to output the returns of state.sls and state.highstate as a table of names, modules and durations that looks somewhat like the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C name mod.fun duration (ms) \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- I\-fail\-unless\-stmt other.function \-1.0000 old\-minion\-config grains.list_present 1.1200 salt\-data group.present 48.3800 /etc/salt/minion file.managed 63.1450 .ft P .fi .UNINDENT .UNINDENT .sp To get the above appearance, use settings something like these: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C out.table.separate_rows: False out.table.justify: left out.table.delim: \(aq \(aq out.table.prefix: \(aq\(aq out.table.suffix: \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.profile.output(data, **kwargs) Display the profiling data in a table format. .UNINDENT .SS salt.output.progress .sp Display return data as a progress bar .INDENT 0.0 .TP .B salt.output.progress.output(ret, bar, **kwargs) Update the progress bar .UNINDENT .INDENT 0.0 .TP .B salt.output.progress.progress_iter(progress) Initialize and return a progress bar iter .UNINDENT .SS salt.output.raw .SS Display raw output data structure .sp This outputter simply displays the output as a python data structure, by printing a string representation of it. It is similar to the \fBpprint\fP outputter, only the data is not nicely formatted/indented. .sp This was the original outputter used by Salt before the outputter system was developed. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq foo.bar \-\-out=raw .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq foo.bar \-\-out=raw {\(aqmyminion\(aq: {\(aqfoo\(aq: {\(aqlist\(aq: [\(aqHello\(aq, \(aqWorld\(aq], \(aqbar\(aq: \(aqbaz\(aq, \(aqdictionary\(aq: {\(aqabc\(aq: 123, \(aqdef\(aq: 456}}}} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.raw.output(data, **kwargs) Rather basic.... .UNINDENT .SS salt.output.table_out .SS Display output in a table format .sp New in version 2017.7.0. .sp The \fBtable\fP outputter displays a sequence of rows as table. .sp Example output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C edge01.bjm01: \-\-\-\-\-\-\-\-\-\- comment: \-\-\-\-\-\-\-\-\-\- out: \-\-\-\-\-\-\-\-\-\- ______________________________________________________________________________ | Active | Interface | Last Move | Mac | Moves | Static | Vlan | ______________________________________________________________________________ | True | ae1.900 | 0.0 | 40:A6:77:5A:50:01 | 0 | False | 111 | ______________________________________________________________________________ | True | ae1.111 | 0.0 | 64:16:8D:32:26:58 | 0 | False | 111 | ______________________________________________________________________________ | True | ae1.111 | 0.0 | 8C:60:4F:73:2D:57 | 0 | False | 111 | ______________________________________________________________________________ | True | ae1.111 | 0.0 | 8C:60:4F:73:2D:7C | 0 | False | 111 | ______________________________________________________________________________ | True | ae1.222 | 0.0 | 8C:60:4F:73:2D:57 | 0 | False | 222 | ______________________________________________________________________________ | True | ae1.222 | 0.0 | F4:0F:1B:76:9D:97 | 0 | False | 222 | ______________________________________________________________________________ result: \-\-\-\-\-\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq foo.bar \-\-out=table .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.output.table_out.TableDisplay(has_header=True, row_delimiter=\(aq\-\(aq, delim=\(aq | \(aq, justify=\(aqcenter\(aq, separate_rows=True, prefix=\(aq| \(aq, suffix=\(aq |\(aq, width=50, wrapfunc=None) Manage the table display content. .INDENT 7.0 .TP .B display(ret, indent, out, rows_key=None, labels_key=None) Display table(s). .UNINDENT .INDENT 7.0 .TP .B display_rows(rows, labels, indent) Prepares row content and displays. .UNINDENT .INDENT 7.0 .TP .B prepare_rows(rows, indent, has_header) Prepare rows content to be displayed. .UNINDENT .INDENT 7.0 .TP .B ustring(indent, color, msg, prefix=\(aq\(aq, suffix=\(aq\(aq, endc=None) Build the unicode string to be displayed. .UNINDENT .INDENT 7.0 .TP .B wrap_onspace(text) When the text inside the column is longer then the width, will split by space and continue on the next line. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.table_out.output(ret, **kwargs) Display the output as table. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnested_indent\fP (\fI*\fP) \-\- integer, specify the left alignment. .IP \(bu 2 \fBhas_header\fP (\fI*\fP) \-\- boolean specifying if header should be displayed. Default: True. .IP \(bu 2 \fBrow_delimiter\fP (\fI*\fP) \-\- character to separate rows. Default: \fB_\fP\&. .IP \(bu 2 \fBdelim\fP (\fI*\fP) \-\- character to separate columns. Default: \fB\(dq | \(dq\fP\&. .IP \(bu 2 \fBjustify\fP (\fI*\fP) \-\- text alignment. Default: \fBcenter\fP\&. .IP \(bu 2 \fBseparate_rows\fP (\fI*\fP) \-\- boolean specifying if row separator will be displayed between consecutive rows. Default: True. .IP \(bu 2 \fBprefix\fP (\fI*\fP) \-\- character at the beginning of the row. Default: \fB\(dq| \(dq\fP\&. .IP \(bu 2 \fBsuffix\fP (\fI*\fP) \-\- character at the end of the row. Default: \fB\(dq |\(dq\fP\&. .IP \(bu 2 \fBwidth\fP (\fI*\fP) \-\- column max width. Default: \fB50\fP\&. .IP \(bu 2 \fBrows_key\fP (\fI*\fP) \-\- display the rows under a specific key. .IP \(bu 2 \fBlabels_key\fP (\fI*\fP) \-\- use the labels under a certain key. Otherwise will try to use the dictionary keys (if any). .IP \(bu 2 \fBtitle\fP (\fI*\fP) \-\- display title when only one table is selected (using the \fBrows_key\fP argument). .UNINDENT .UNINDENT .UNINDENT .SS salt.output.txt .SS Simple text outputter .sp The \fBtxt\fP outputter has been developed to make the output from shell commands on minions appear as they do when the command is executed on the minion. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq foo.bar \-\-out=txt .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.txt.output(data, **kwargs) Output the data in lines, very nice for running commands .UNINDENT .SS salt.output.virt_query .SS virt.query outputter .sp Used to display the output from the \fI\%virt.query\fP runner. .INDENT 0.0 .TP .B salt.output.virt_query.output(data, **kwargs) Display output for the salt\-run virt.query function .UNINDENT .SS salt.output.yaml_out .SS Display return data in YAML format .sp This outputter defaults to printing in YAML block mode for better readability. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq foo.bar \-\-out=yaml .ft P .fi .UNINDENT .UNINDENT .sp Example output: .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C saltmine: foo: bar: baz dictionary: abc: 123 def: 456 list: \- Hello \- World .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.output.yaml_out.output(data, **kwargs) Print out YAML using the block mode .UNINDENT .SS pillar modules .TS center; |l|l|. _ T{ \fI\%cmd_json\fP T} T{ Execute a command and read the output as JSON. T} _ T{ \fI\%cmd_yaml\fP T} T{ Execute a command and read the output as YAML. T} _ T{ \fI\%cmd_yamlex\fP T} T{ Execute a command and read the output as YAMLEX. T} _ T{ \fI\%cobbler\fP T} T{ A module to pull data from Cobbler via its API into the Pillar dictionary T} _ T{ \fI\%confidant\fP T} T{ An external pillar module for getting credentials from confidant. T} _ T{ \fI\%consul_pillar\fP T} T{ Use Consul K/V as a Pillar source with values parsed as YAML T} _ T{ \fI\%csvpillar\fP T} T{ Store key/value pairs in a CSV file T} _ T{ \fI\%digicert\fP T} T{ Digicert Pillar Certificates T} _ T{ \fI\%django_orm\fP T} T{ Generate Pillar data from Django models through the Django ORM T} _ T{ \fI\%ec2_pillar\fP T} T{ Retrieve EC2 instance data for minions for ec2_tags and ec2_tags_list T} _ T{ \fI\%etcd_pillar\fP T} T{ Use etcd data as a Pillar source T} _ T{ \fI\%extra_minion_data_in_pillar\fP T} T{ Add all extra minion data to the pillar. T} _ T{ \fI\%file_tree\fP T} T{ The \fBfile_tree\fP external pillar allows values from all files in a directory tree to be imported as Pillar data. T} _ T{ \fI\%foreman\fP T} T{ A module to pull data from Foreman via its API into the Pillar dictionary T} _ T{ \fI\%git_pillar\fP T} T{ Use a git repository as a Pillar source T} _ T{ \fI\%gpg\fP T} T{ Decrypt pillar data through the builtin GPG renderer T} _ T{ \fI\%hg_pillar\fP T} T{ Use remote Mercurial repository as a Pillar source. T} _ T{ \fI\%hiera\fP T} T{ Use hiera data as a Pillar source T} _ T{ \fI\%http_json\fP T} T{ A module that adds data to the Pillar structure retrieved by an http request T} _ T{ \fI\%http_yaml\fP T} T{ A module that adds data to the Pillar structure retrieved by an http request T} _ T{ \fI\%libvirt\fP T} T{ Load up the libvirt keys into Pillar for a given minion if said keys have been generated using the libvirt key runner T} _ T{ \fI\%makostack\fP T} T{ Simple and flexible YAML ext_pillar which can read pillar from within pillar. T} _ T{ \fI\%mongo\fP T} T{ Read Pillar data from a mongodb collection T} _ T{ \fI\%mysql\fP T} T{ Retrieve Pillar data by doing a MySQL query T} _ T{ \fI\%nacl\fP T} T{ Decrypt pillar data through the builtin NACL renderer T} _ T{ \fI\%netbox\fP T} T{ A module that adds data to the Pillar structure from a NetBox API. T} _ T{ \fI\%neutron\fP T} T{ Use Openstack Neutron data as a Pillar source. T} _ T{ \fI\%nodegroups\fP T} T{ Nodegroups Pillar T} _ T{ \fI\%pepa\fP T} T{ Pepa T} _ T{ \fI\%pillar_ldap\fP T} T{ Use LDAP data as a Pillar source T} _ T{ \fI\%postgres\fP T} T{ Retrieve Pillar data by doing a postgres query T} _ T{ \fI\%puppet\fP T} T{ Execute an unmodified puppet_node_classifier and read the output as YAML. T} _ T{ \fI\%reclass_adapter\fP T} T{ Use the \(dqreclass\(dq database as a Pillar source T} _ T{ \fI\%redismod\fP T} T{ Read pillar data from a Redis backend T} _ T{ \fI\%rethinkdb_pillar\fP T} T{ Provide external pillar data from RethinkDB T} _ T{ \fI\%s3\fP T} T{ Copy pillar data from a bucket in Amazon S3 T} _ T{ \fI\%saltclass\fP T} T{ SaltClass Pillar Module T} _ T{ \fI\%sql_base\fP T} T{ Retrieve Pillar data by doing a SQL query T} _ T{ \fI\%sqlcipher\fP T} T{ Retrieve Pillar data by running a SQLCipher query T} _ T{ \fI\%sqlite3\fP T} T{ Retrieve Pillar data by doing a SQLite3 query T} _ T{ \fI\%stack\fP T} T{ Simple and flexible YAML ext_pillar which can read pillar from within pillar. T} _ T{ \fI\%svn_pillar\fP T} T{ Clone a remote SVN repository and use the filesystem as a Pillar source T} _ T{ \fI\%varstack_pillar\fP T} T{ Use \fI\%Varstack\fP data as a Pillar source T} _ T{ \fI\%vault\fP T} T{ Vault Pillar Module T} _ T{ \fI\%venafi\fP T} T{ Venafi Pillar Certificates T} _ T{ \fI\%virtkey\fP T} T{ Accept a key from a hypervisor if the virt runner has already submitted an authorization request T} _ T{ \fI\%vmware_pillar\fP T} T{ Pillar data from vCenter or an ESXi host T} _ .TE .SS salt.pillar.cmd_json .sp Execute a command and read the output as JSON. The JSON data is then directly overlaid onto the minion\(aqs Pillar data. .SS Configuring the CMD_JSON ext_pillar .sp Set the following Salt config to setup cmd json result as external pillar source: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- cmd_json: \(aqecho {\(dqarg\(dq:\(dqvalue\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp This will run the command \fBecho {arg: value}\fP on the master. .SS Module Documentation .INDENT 0.0 .TP .B salt.pillar.cmd_json.ext_pillar(minion_id, pillar, command) Execute a command and read the output as JSON .UNINDENT .SS salt.pillar.cmd_yaml .sp Execute a command and read the output as YAML. The YAML data is then directly overlaid onto the minion\(aqs Pillar data .INDENT 0.0 .TP .B salt.pillar.cmd_yaml.ext_pillar(minion_id, pillar, command) Execute a command and read the output as YAML .UNINDENT .SS salt.pillar.cmd_yamlex .sp Execute a command and read the output as YAMLEX. .sp The YAMLEX data is then directly overlaid onto the minion\(aqs Pillar data .INDENT 0.0 .TP .B salt.pillar.cmd_yamlex.ext_pillar(minion_id, pillar, command) Execute a command and read the output as YAMLEX .UNINDENT .SS salt.pillar.cobbler .sp A module to pull data from Cobbler via its API into the Pillar dictionary .SS Configuring the Cobbler ext_pillar .sp The same cobbler.* parameters are used for both the Cobbler tops and Cobbler pillar modules. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- cobbler: key: cobbler # Nest results within this key. By default, values are not nested. only: [parameters] # Add only these keys to pillar. cobbler.url: https://example.com/cobbler_api #default is http://localhost/cobbler_api cobbler.user: username # default is no username cobbler.password: password # default is no password .ft P .fi .UNINDENT .UNINDENT .SS Module Documentation .INDENT 0.0 .TP .B salt.pillar.cobbler.ext_pillar(minion_id, pillar, key=None, only=()) Read pillar data from Cobbler via its API. .UNINDENT .SS salt.pillar.confidant .sp An external pillar module for getting credentials from confidant. .SS Configuring the Confidant module .sp The module can be configured via ext_pillar in the minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B ext_pillar: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B confidant: .INDENT 7.0 .TP .B profile: # The URL of the confidant web service url: \(aq\fI\%https://confidant\-production.example.com\fP\(aq # The context to use for KMS authentication auth_context: from: example\-production\-iad to: confidant\-production\-iad user_type: service # The KMS master key to use for authentication auth_key: \(dqalias/authnz\(dq # Cache file for KMS auth token token_cache_file: /run/confidant/confidant_token # The duration of the validity of a token, in minutes token_duration: 60 # key, keyid and region can be defined in the profile, but it\(aqs # generally best to use IAM roles or environment variables for AWS # auth. keyid: 98nh9h9h908h09kjjk key: jhf908gyeghehe0he0g8h9u0j0n0n09hj09h0 region: us\-east\-1 .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends confidant\-common, confidant\-client .UNINDENT .SS Module Documentation .INDENT 0.0 .TP .B salt.pillar.confidant.ext_pillar(minion_id, pillar, profile=None) Read pillar data from Confidant via its API. .UNINDENT .SS salt.pillar.consul_pillar .sp Use Consul K/V as a Pillar source with values parsed as YAML .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 python\-consul .UNINDENT .UNINDENT .sp In order to use an consul server, a profile must be created in the master configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_consul_config: consul.host: 127.0.0.1 consul.port: 8500 consul.token: b6376760\-a8bb\-edd5\-fcda\-33bc13bfc556 consul.scheme: http consul.consistency: default consul.dc: dev consul.verify: True .ft P .fi .UNINDENT .UNINDENT .sp All parameters are optional. .sp The \fBconsul.token\fP requires python\-consul >= 0.4.7. .sp If you have a multi\-datacenter Consul cluster you can map your \fBpillarenv\fP entries to your data centers by providing a dictionary of mappings in \fBconsul.dc\fP field: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_consul_config: consul.dc: dev: us\-east\-1 prod: us\-west\-1 .ft P .fi .UNINDENT .UNINDENT .sp In the example above we specifying static mapping between Pillar environments and data centers: the data for \fBdev\fP and \fBprod\fP Pillar environments will be fetched from \fBus\-east\-1\fP and \fBus\-west\-1\fP datacenter respectively. .sp In fact when \fBconsul.dc\fP is set to dictionary keys are processed as regular expressions (that can capture named parameters) and values are processed as string templates as per PEP 3101. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_consul_config: consul.dc: ^dev\-.*$: dev\-datacenter ^(?P<region>.*)\-prod$: prod\-datacenter\-{region} .ft P .fi .UNINDENT .UNINDENT .sp This example maps all Pillar environments starting with \fBdev\-\fP to \fBdev\-datacenter\fP whereas Pillar environment like \fBeu\-prod\fP will be mapped to \fBprod\-datacenter\-eu\fP\&. .sp Before evaluation patterns are sorted by length in descending order. .sp If Pillar environment names correspond to data center names a single pattern can be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_consul_config: consul.dc: ^(?P<env>.*)$: \(aq{env}\(aq .ft P .fi .UNINDENT .UNINDENT .sp After the profile is created, configure the external pillar system to use it. Optionally, a root may be specified. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- consul: my_consul_config ext_pillar: \- consul: my_consul_config root=salt .ft P .fi .UNINDENT .UNINDENT .sp Using these configuration profiles, multiple consul sources may also be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- consul: my_consul_config \- consul: my_other_consul_config .ft P .fi .UNINDENT .UNINDENT .sp Either the \fBminion_id\fP, or the \fBrole\fP, or the \fBenvironment\fP grain may be used in the \fBroot\fP path to expose minion\-specific information stored in consul. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- consul: my_consul_config root=salt/%(minion_id)s \- consul: my_consul_config root=salt/%(role)s \- consul: my_consul_config root=salt/%(environment)s .ft P .fi .UNINDENT .UNINDENT .sp Minion\-specific values may override shared values when the minion\-specific root appears after the shared root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- consul: my_consul_config root=salt\-shared \- consul: my_other_consul_config root=salt\-private/%(minion_id)s .ft P .fi .UNINDENT .UNINDENT .sp If using the \fBrole\fP or \fBenvironment\fP grain in the consul key path, be sure to define it using \fI/etc/salt/grains\fP, or similar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C role: my\-minion\-role environment: dev .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs possible to lock down where the pillar values are shared through minion targeting. Note that double quotes \fB\(dq\fP are required around the target value and cannot be used inside the matching statement. See the section on Compound Matchers for more examples. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- consul: my_consul_config root=salt target=\(dqL@salt.example.com and G@osarch:x86_64\(dq .ft P .fi .UNINDENT .UNINDENT .sp The data from Consul can be merged into a nested key in Pillar. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- consul: my_consul_config pillar_root=consul_data .ft P .fi .UNINDENT .UNINDENT .sp By default, keys containing YAML data will be deserialized before being merged into Pillar. This behavior can be disabled by setting \fBexpand_keys\fP to \fBfalse\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- consul: my_consul_config expand_keys=false .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.consul_pillar.consul_fetch(client, path) Query consul for all keys/values within base path .UNINDENT .INDENT 0.0 .TP .B salt.pillar.consul_pillar.ext_pillar(minion_id, pillar, conf) Check consul for all data .UNINDENT .INDENT 0.0 .TP .B salt.pillar.consul_pillar.fetch_tree(client, path, expand_keys) Grab data from consul, trim base path and remove any keys which are folders. Take the remaining data and send it to be formatted in such a way as to be used as pillar data. .UNINDENT .INDENT 0.0 .TP .B salt.pillar.consul_pillar.get_conn(opts, profile) Return a client object for accessing consul .UNINDENT .INDENT 0.0 .TP .B salt.pillar.consul_pillar.pillar_format(ret, keys, value, expand_keys) Perform data formatting to be used as pillar data and merge it with the current pillar data .UNINDENT .SS salt.pillar.csvpillar .sp Store key/value pairs in a CSV file .sp New in version 2016.11.0. .sp Example configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- csv: /path/to/file.csv # or ext_pillar: \- csv: path: /path/to/file.csv namespace: \(aqsubkey\(aq fieldnames: \- col1 \- col2 \- col2 .ft P .fi .UNINDENT .UNINDENT .sp The first column must be minion IDs and the first row must be dictionary keys. E.g.: .TS center; |l|l|l|. _ T{ id T} T{ role T} T{ env T} _ T{ jerry T} T{ web T} T{ prod T} _ T{ stuart T} T{ web T} T{ stage T} _ T{ dave T} T{ web T} T{ qa T} _ T{ phil T} T{ db T} T{ prod T} _ T{ kevin T} T{ db T} T{ stage T} _ T{ mike T} T{ db T} T{ qa T} _ .TE .sp Will produce the following Pillar values for a minion named \(dqjerry\(dq: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { \(aqrole\(aq: \(aqweb\(aq, \(aqenv\(aq: \(aqprod\(aq, } .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.csvpillar.ext_pillar(mid, pillar, path, idkey=\(aqid\(aq, namespace=None, fieldnames=None, restkey=None, restval=None, dialect=\(aqexcel\(aq) Read a CSV into Pillar .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- Absolute path to a CSV file. .IP \(bu 2 \fBidkey\fP (\fI\%str\fP) \-\- (Optional) The column name of minion IDs. .IP \(bu 2 \fBnamespace\fP (\fI\%str\fP) \-\- (Optional) A pillar key to namespace the values under. .IP \(bu 2 \fBfieldnames\fP (\fI\%list\fP) \-\- (Optional) if the first row of the CSV is not column names they may be specified here instead. .UNINDENT .UNINDENT .UNINDENT .SS salt.pillar.digicert .sp Digicert Pillar Certificates .sp This module will only return pillar data if the \fBdigicert\fP runner module has already been used to create certificates. .sp To configure this module, set \fBdigicert\fP to \fBTrue\fP in the \fBext_pillar\fP section of your \fBmaster\fP configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- digicert: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.digicert.ext_pillar(minion_id, pillar, conf) Return an existing set of certificates .UNINDENT .SS salt.pillar.django_orm .sp Generate Pillar data from Django models through the Django ORM .INDENT 0.0 .TP .B maintainer Micah Hausler <\fI\%micah.hausler@gmail.com\fP> .TP .B maturity new .UNINDENT .SS Configuring the django_orm ext_pillar .sp To use this module, your Django project must be on the salt master server with database access. This assumes you are using virtualenv with all the project\(aqs requirements installed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- django_orm: pillar_name: my_application project_path: /path/to/project/ settings_module: my_application.settings env_file: /path/to/env/file.sh # Optional: If your project is not using the system python, # add your virtualenv path below. env: /path/to/virtualenv/ django_app: # Required: the app that is included in INSTALLED_APPS my_application.clients: # Required: the model name Client: # Required: model field to use as the key in the rendered # Pillar. Must be unique; must also be included in the # \(ga\(gafields\(ga\(ga list below. name: shortname # Optional: # See Django\(aqs QuerySet documentation for how to use .filter() filter: {\(aqkw\(aq: \(aqargs\(aq} # Required: a list of field names # List items will be used as arguments to the .values() method. # See Django\(aqs QuerySet documentation for how to use .values() fields: \- field_1 \- field_2 .ft P .fi .UNINDENT .UNINDENT .sp This would return pillar data that would look like .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_application: my_application.clients: Client: client_1: field_1: data_from_field_1 field_2: data_from_field_2 client_2: field_1: data_from_field_1 field_2: data_from_field_2 .ft P .fi .UNINDENT .UNINDENT .sp As another example, data from multiple database tables can be fetched using Django\(aqs regular lookup syntax. Note, using ManyToManyFields will not currently work since the return from values() changes if a ManyToMany is present. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- django_orm: pillar_name: djangotutorial project_path: /path/to/mysite settings_module: mysite.settings django_app: mysite.polls: Choices: name: poll__question fields: \- poll__question \- poll__id \- choice_text \- votes .ft P .fi .UNINDENT .UNINDENT .SS Module Documentation .INDENT 0.0 .TP .B salt.pillar.django_orm.ext_pillar(minion_id, pillar, pillar_name, project_path, settings_module, django_app, env=None, env_file=None, *args, **kwargs) Connect to a Django database through the ORM and retrieve model fields .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpillar_name\fP (\fI\%str\fP) \-\- The name of the pillar to be returned .IP \(bu 2 \fBproject_path\fP (\fI\%str\fP) \-\- The full path to your Django project (the directory manage.py is in) .IP \(bu 2 \fBsettings_module\fP (\fI\%str\fP) \-\- The settings module for your project. This can be found in your manage.py file .IP \(bu 2 \fBdjango_app\fP (\fI\%str\fP) \-\- A dictionary containing your apps, models, and fields .IP \(bu 2 \fBenv\fP (\fI\%str\fP) \-\- The full path to the virtualenv for your Django project .IP \(bu 2 \fBenv_file\fP (\fI\%str\fP) \-\- An optional bash file that sets up your environment. The file is run in a subprocess and the changed variables are then added .UNINDENT .UNINDENT .UNINDENT .SS salt.pillar.ec2_pillar .sp Retrieve EC2 instance data for minions for ec2_tags and ec2_tags_list .sp The minion id must be the AWS instance\-id or value in \fBtag_match_key\fP\&. For example set \fBtag_match_key\fP to \fBName\fP to have the minion\-id matched against the tag \(aqName\(aq. The tag contents must be unique. The value of \fBtag_match_value\fP can be \(aquqdn\(aq or \(aqasis\(aq. if \(aquqdn\(aq, then the domain will be stripped before comparison. .sp Additionally, the \fBuse_grain\fP option can be set to \fBTrue\fP\&. This allows the use of an instance\-id grain instead of the minion\-id. Since this is a potential security risk, the configuration can be further expanded to include a list of minions that are trusted to only allow the alternate id of the instances to specific hosts. There is no glob matching at this time. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you are using \fBuse_grain: True\fP in the configuration for this external pillar module, the minion must have \fI\%metadata_server_grains\fP enabled in the minion config file (see also \fI\%here\fP). .sp It is important to also note that enabling the \fBuse_grain\fP option allows the minion to manipulate the pillar data returned, as described above. .UNINDENT .UNINDENT .sp The optional \fBtag_list_key\fP indicates which keys should be added to \fBec2_tags_list\fP and be split by \fBtag_list_sep\fP (by default \fB;\fP). If a tag key is included in \fBtag_list_key\fP it is removed from ec2_tags. If a tag does not exist it is still included as an empty list. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As with any master configuration change, restart the salt\-master daemon for changes to take effect. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- ec2_pillar: tag_match_key: \(aqName\(aq tag_match_value: \(aqasis\(aq tag_list_key: \- Role tag_list_sep: \(aq;\(aq use_grain: True minion_ids: \- trusted\-minion\-1 \- trusted\-minion\-2 \- trusted\-minion\-3 .ft P .fi .UNINDENT .UNINDENT .sp This is a very simple pillar configuration that simply retrieves the instance data from AWS. Currently the only portion implemented are EC2 tags, which returns a list of key/value pairs for all of the EC2 tags assigned to the instance. .INDENT 0.0 .TP .B salt.pillar.ec2_pillar.ext_pillar(minion_id, pillar, use_grain=False, minion_ids=None, tag_match_key=None, tag_match_value=\(aqasis\(aq, tag_list_key=None, tag_list_sep=\(aq;\(aq) Execute a command and read the output as YAML .UNINDENT .SS salt.pillar.etcd_pillar .sp Use etcd data as a Pillar source .sp New in version 2014.7.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 python\-etcd or etcd3\-py .UNINDENT .UNINDENT .sp In order to use an etcd server, a profile must be created in the master configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_etcd_config: etcd.host: 127.0.0.1 etcd.port: 4001 .ft P .fi .UNINDENT .UNINDENT .sp In order to choose whether to use etcd API v2 or v3, you can put the following configuration option in the same place as your etcd configuration. This option defaults to true, meaning you will use v2 unless you specify otherwise. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.require_v2: True .ft P .fi .UNINDENT .UNINDENT .sp When using API v3, there are some specific options available to be configured within your etcd profile. They are defaulted to the following... .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.encode_keys: False etcd.encode_values: True etcd.raw_keys: False etcd.raw_values: False etcd.unicode_errors: \(dqsurrogateescape\(dq .ft P .fi .UNINDENT .UNINDENT .sp \fBetcd.encode_keys\fP indicates whether you want to pre\-encode keys using msgpack before adding them to etcd. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you set \fBetcd.encode_keys\fP to \fBTrue\fP, all recursive functionality will no longer work. This includes \fBtree\fP and \fBls\fP and all other methods if you set \fBrecurse\fP/\fBrecursive\fP to \fBTrue\fP\&. This is due to the fact that when encoding with msgpack, keys like \fB/salt\fP and \fB/salt/stack\fP will have differing byte prefixes, and etcd v3 searches recursively using prefixes. .UNINDENT .UNINDENT .sp \fBetcd.encode_values\fP indicates whether you want to pre\-encode values using msgpack before adding them to etcd. This defaults to \fBTrue\fP to avoid data loss on non\-string values wherever possible. .sp \fBetcd.raw_keys\fP determines whether you want the raw key or a string returned. .sp \fBetcd.raw_values\fP determines whether you want the raw value or a string returned. .sp \fBetcd.unicode_errors\fP determines what you policy to follow when there are encoding/decoding errors. .sp After the profile is created, configure the external pillar system to use it. Optionally, a root may be specified. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- etcd: my_etcd_config ext_pillar: \- etcd: my_etcd_config root=/salt .ft P .fi .UNINDENT .UNINDENT .sp Using these configuration profiles, multiple etcd sources may also be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- etcd: my_etcd_config \- etcd: my_other_etcd_config .ft P .fi .UNINDENT .UNINDENT .sp The \fBminion_id\fP may be used in the \fBroot\fP path to expose minion\-specific information stored in etcd. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- etcd: my_etcd_config root=/salt/%(minion_id)s .ft P .fi .UNINDENT .UNINDENT .sp Minion\-specific values may override shared values when the minion\-specific root appears after the shared root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- etcd: my_etcd_config root=/salt\-shared \- etcd: my_other_etcd_config root=/salt\-private/%(minion_id)s .ft P .fi .UNINDENT .UNINDENT .sp Using the configuration above, the following commands could be used to share a key with all minions but override its value for a specific minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcdctl set /salt\-shared/mykey my_value etcdctl set /salt\-private/special_minion_id/mykey my_other_value .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.etcd_pillar.ext_pillar(minion_id, pillar, conf) Check etcd for all data .UNINDENT .SS salt.pillar.extra_minion_data_in_pillar .sp Add all extra minion data to the pillar. .INDENT 0.0 .TP .B codeauthor \fI\%Alexandru.Bleotu@morganstanley.ms.com\fP .UNINDENT .sp One can filter on the keys to include in the pillar by using the \fBinclude\fP parameter. For subkeys the \(aq:\(aq notation is supported (i.e. \(aqkey:subkey\(aq) The keyword \fB<all>\fP includes all keys. .SS Complete example in etc/salt/master .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- extra_minion_data_in_pillar: include: * ext_pillar: \- extra_minion_data_in_pillar: include: \- key1 \- key2:subkey2 ext_pillar: \- extra_minion_data_in_pillar: include: <all> .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.extra_minion_data_in_pillar.ext_pillar(minion_id, pillar, include, extra_minion_data=None) .UNINDENT .SS salt.pillar.file_tree .sp The \fBfile_tree\fP external pillar allows values from all files in a directory tree to be imported as Pillar data. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is an external pillar and is subject to the \fI\%rules and constraints\fP governing external pillars. .UNINDENT .UNINDENT .sp New in version 2015.5.0. .sp In this pillar, data is organized by either Minion ID or Nodegroup name. To setup pillar data for a specific Minion, place it in \fB<root_dir>/hosts/<minion_id>\fP\&. To setup pillar data for an entire Nodegroup, place it in \fB<root_dir>/nodegroups/<node_group>\fP where \fB<node_group>\fP is the Nodegroup\(aqs name. .SS Example \fBfile_tree\fP Pillar .SS Master Configuration .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- file_tree: root_dir: /srv/ext_pillar follow_dir_links: False keep_newline: True .ft P .fi .UNINDENT .UNINDENT .sp The \fBroot_dir\fP parameter is required and points to the directory where files for each host are stored. The \fBfollow_dir_links\fP parameter is optional and defaults to False. If \fBfollow_dir_links\fP is set to True, this external pillar will follow symbolic links to other directories. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Be careful when using \fBfollow_dir_links\fP, as a recursive symlink chain will result in unexpected results. .UNINDENT .UNINDENT .sp Changed in version 2018.3.0: If \fBroot_dir\fP is a relative path, it will be treated as relative to the \fI\%pillar_roots\fP of the environment specified by \fI\%pillarenv\fP\&. If an environment specifies multiple roots, this module will search for files relative to all of them, in order, merging the results. .sp If \fBkeep_newline\fP is set to \fBTrue\fP, then the pillar values for files ending in newlines will keep that newline. The default behavior is to remove the end\-of\-file newline. \fBkeep_newline\fP should be turned on if the pillar data is intended to be used to deploy a file using \fBcontents_pillar\fP with a \fI\%file.managed\fP state. .sp Changed in version 2015.8.4: The \fBraw_data\fP parameter has been renamed to \fBkeep_newline\fP\&. In earlier releases, \fBraw_data\fP must be used. Also, this parameter can now be a list of globs, allowing for more granular control over which pillar values keep their end\-of\-file newline. The globs match paths relative to the directories named for minion IDs and nodegroups underneath the \fBroot_dir\fP (see the layout examples in the below sections). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- file_tree: root_dir: /path/to/root/directory keep_newline: \- files/testdir/* .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In earlier releases, this documentation incorrectly stated that binary files would not affected by the \fBkeep_newline\fP configuration. However, this module does not actually distinguish between binary and text files. .UNINDENT .UNINDENT .sp Changed in version 2017.7.0: Templating/rendering has been added. You can now specify a default render pipeline and a black\- and whitelist of (dis)allowed renderers. .sp \fBtemplate\fP must be set to \fBTrue\fP for templating to happen. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- file_tree: root_dir: /path/to/root/directory render_default: jinja|yaml renderer_blacklist: \- gpg renderer_whitelist: \- jinja \- yaml template: True .ft P .fi .UNINDENT .UNINDENT .SS Assigning Pillar Data to Individual Hosts .sp To configure pillar data for each host, this external pillar will recursively iterate over \fBroot_dir\fP/hosts/\fBid\fP (where \fBid\fP is a minion ID), and compile pillar data with each subdirectory as a dictionary key and each file as a value. .sp For example, the following \fBroot_dir\fP tree: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./hosts/ \&./hosts/test\-host/ \&./hosts/test\-host/files/ \&./hosts/test\-host/files/testdir/ \&./hosts/test\-host/files/testdir/file1.txt \&./hosts/test\-host/files/testdir/file2.txt \&./hosts/test\-host/files/another\-testdir/ \&./hosts/test\-host/files/another\-testdir/symlink\-to\-file1.txt .ft P .fi .UNINDENT .UNINDENT .sp will result in the following pillar tree for minion with ID \fBtest\-host\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C test\-host: \-\-\-\-\-\-\-\-\-\- apache: \-\-\-\-\-\-\-\-\-\- config.d: \-\-\-\-\-\-\-\-\-\- 00_important.conf: <important_config important_setting=\(dqyes\(dq /> 20_bob_extra.conf: <bob_specific_cfg has_freeze_ray=\(dqyes\(dq /> corporate_app: \-\-\-\-\-\-\-\-\-\- settings: \-\-\-\-\-\-\-\-\-\- common_settings: // This is the main settings file for the corporate // internal web app main_setting: probably bob_settings: role: bob .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The leaf data in the example shown is the contents of the pillar files. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.file_tree.ext_pillar(minion_id, pillar, root_dir=None, follow_dir_links=False, debug=False, keep_newline=False, render_default=None, renderer_blacklist=None, renderer_whitelist=None, template=False) Compile pillar data from the given \fBroot_dir\fP specific to Nodegroup names and Minion IDs. .sp If a Minion\(aqs ID is not found at \fB<root_dir>/host/<minion_id>\fP or if it is not included in any Nodegroups named at \fB<root_dir>/nodegroups/<node_group>\fP, no pillar data provided by this pillar module will be available for that Minion. .sp Changed in version 2017.7.0: Templating/rendering has been added. You can now specify a default render pipeline and a black\- and whitelist of (dis)allowed renderers. .sp \fBtemplate\fP must be set to \fBTrue\fP for templating to happen. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- file_tree: root_dir: /path/to/root/directory render_default: jinja|yaml renderer_blacklist: \- gpg renderer_whitelist: \- jinja \- yaml template: True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBminion_id\fP \-\- The ID of the Minion whose pillar data is to be collected .IP \(bu 2 \fBpillar\fP \-\- Unused by the \fBfile_tree\fP pillar module .IP \(bu 2 \fBroot_dir\fP \-\- .sp Filesystem directory used as the root for pillar data (e.g. \fB/srv/ext_pillar\fP) .sp Changed in version 2018.3.0: If \fBroot_dir\fP is a relative path, it will be treated as relative to the \fI\%pillar_roots\fP of the environment specified by \fI\%pillarenv\fP\&. If an environment specifies multiple roots, this module will search for files relative to all of them, in order, merging the results. .IP \(bu 2 \fBfollow_dir_links\fP \-\- .sp Follow symbolic links to directories while collecting pillar files. Defaults to \fBFalse\fP\&. .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 Care should be exercised when enabling this option as it will follow links that point outside of \fBroot_dir\fP\&. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 Symbolic links that lead to infinite recursion are not filtered. .UNINDENT .UNINDENT .IP \(bu 2 \fBdebug\fP \-\- Enable debug information at log level \fBdebug\fP\&. Defaults to \fBFalse\fP\&. This option may be useful to help debug errors when setting up the \fBfile_tree\fP pillar module. .IP \(bu 2 \fBkeep_newline\fP \-\- .sp Preserve the end\-of\-file newline in files. Defaults to \fBFalse\fP\&. This option may either be a boolean or a list of file globs (as defined by the \fI\%Python fnmatch package\fP) for which end\-of\-file newlines are to be kept. .sp \fBkeep_newline\fP should be turned on if the pillar data is intended to be used to deploy a file using \fBcontents_pillar\fP with a \fI\%file.managed\fP state. .sp Changed in version 2015.8.4: The \fBraw_data\fP parameter has been renamed to \fBkeep_newline\fP\&. In earlier releases, \fBraw_data\fP must be used. Also, this parameter can now be a list of globs, allowing for more granular control over which pillar values keep their end\-of\-file newline. The globs match paths relative to the directories named for Minion IDs and Nodegroup namess underneath the \fBroot_dir\fP\&. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- file_tree: root_dir: /srv/ext_pillar keep_newline: \- apache/config.d/* \- corporate_app/settings/* .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 In earlier releases, this documentation incorrectly stated that binary files would not affected by the \fBkeep_newline\fP\&. However, this module does not actually distinguish between binary and text files. .UNINDENT .UNINDENT .IP \(bu 2 \fBrender_default\fP \-\- .sp Override Salt\(aqs \fI\%default global renderer\fP for the \fBfile_tree\fP pillar. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C render_default: jinja .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBrenderer_blacklist\fP \-\- .sp Disallow renderers for pillar files. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C renderer_blacklist: \- json .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBrenderer_whitelist\fP \-\- .sp Allow renderers for pillar files. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C renderer_whitelist: \- yaml \- jinja .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBtemplate\fP \-\- Enable templating of pillar files. Defaults to \fBFalse\fP\&. .UNINDENT .UNINDENT .UNINDENT .SS salt.pillar.foreman .sp A module to pull data from Foreman via its API into the Pillar dictionary .SS Configuring the Foreman ext_pillar .sp Set the following Salt config to setup Foreman as external pillar source: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- foreman: key: foreman # Nest results within this key only: [\(aqhostgroup_name\(aq, \(aqparameters\(aq] # Add only these keys to pillar foreman.url: https://example.com/foreman_api foreman.user: username # default is admin foreman.password: password # default is changeme .ft P .fi .UNINDENT .UNINDENT .sp The following options are optional: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foreman.api: apiversion # default is 2 (1 is not supported yet) foreman.verifyssl: False # default is True foreman.certfile: /etc/ssl/certs/mycert.pem # default is None foreman.keyfile: /etc/ssl/private/mykey.pem # default is None foreman.cafile: /etc/ssl/certs/mycert.ca.pem # default is None foreman.lookup_parameters: True # default is True .ft P .fi .UNINDENT .UNINDENT .sp An alternative would be to use the Foreman modules integrating Salt features in the Smart Proxy and the webinterface. .sp Further information can be found on \fI\%GitHub\fP\&. .SS Module Documentation .INDENT 0.0 .TP .B salt.pillar.foreman.ext_pillar(minion_id, pillar, key=None, only=()) Read pillar data from Foreman via its API. .UNINDENT .SS salt.pillar.git_pillar .SS Use a git repository as a Pillar source .sp This external pillar allows for a Pillar top file and Pillar SLS files to be sourced from a git repository. .sp However, since git_pillar does not have an equivalent to the \fI\%pillar_roots\fP parameter, configuration is slightly different. A Pillar top file is required to be in the git repository and must still contain the relevant environment, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- foo .ft P .fi .UNINDENT .UNINDENT .sp The branch/tag which maps to that environment must then be specified along with the repo\(aqs URL. Configuration details can be found below. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 Each branch/tag used for git_pillar must have its own top file. This is different from how the top file works when configuring \fI\%States\fP\&. The reason for this is that each git_pillar branch/tag is processed separately from the rest. Therefore, if the \fBqa\fP branch is to be used for git_pillar, it would need to have its own top file, with the \fBqa\fP environment defined within it, like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C qa: \(aqdev\-*\(aq: \- bar .ft P .fi .UNINDENT .UNINDENT .sp Additionally, while git_pillar allows for the branch/tag to be overridden (see \fI\%here\fP), keep in mind that the top file must reference the actual environment name. It is common practice to make the environment in a git_pillar top file match the branch/tag name, but when remapping, the environment of course no longer matches the branch/tag, and the top file needs to be adjusted accordingly. When expected Pillar values configured in git_pillar are missing, this is a common misconfiguration that may be to blame, and is a good first step in troubleshooting. .UNINDENT .UNINDENT .SS Configuring git_pillar for Salt .sp Beginning with Salt version 2015.8.0, \fI\%pygit2\fP is now supported in addition to \fI\%GitPython\fP\&. The requirements for \fI\%GitPython\fP and \fI\%pygit2\fP are the same as for GitFS, as described \fI\%here\fP\&. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 git_pillar has its own set of global configuration parameters. While it may seem intuitive to use the global gitfs configuration parameters (\fI\%gitfs_base\fP, etc.) to manage git_pillar, this will not work. The main difference for this is the fact that the different components which use Salt\(aqs git backend code do not all function identically. For instance, in git_pillar it is necessary to specify which branch/tag to be used for git_pillar remotes. This is the reverse behavior from gitfs, where branches/tags make up your environments. .sp See \fI\%here\fP for documentation on the git_pillar configuration options and their usage. .UNINDENT .UNINDENT .sp Here is an example git_pillar configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- git: # Use \(aqprod\(aq instead of the branch name \(aqproduction\(aq as the environment \- production https://gitserver/git\-pillar.git: \- env: prod # Use \(aqdev\(aq instead of the branch name \(aqdevelop\(aq as the environment \- develop https://gitserver/git\-pillar.git: \- env: dev # No per\-remote config parameters (and no trailing colon), \(aqqa\(aq will # be used as the environment \- qa https://gitserver/git\-pillar.git # SSH key authentication \- master git@other\-git\-server:pillardata\-ssh.git: # Pillar SLS files will be read from the \(aqpillar\(aq subdirectory in # this repository \- root: pillar \- privkey: /path/to/key \- pubkey: /path/to/key.pub \- passphrase: CorrectHorseBatteryStaple # HTTPS authentication \- master https://other\-git\-server/pillardata\-https.git: \- user: git \- password: CorrectHorseBatteryStaple .ft P .fi .UNINDENT .UNINDENT .sp The main difference between this and the old way of configuring git_pillar is that multiple remotes can be configured under one \fBgit\fP section under \fI\%ext_pillar\fP\&. More than one \fBgit\fP section can be used, but it is not necessary. Remotes will be evaluated sequentially. .sp Per\-remote configuration parameters are supported (similar to \fI\%gitfs\fP), and global versions of the git_pillar configuration parameters can also be set. .sp To remap a specific branch to a specific Pillar environment, use the \fBenv\fP per\-remote parameter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- git: \- production https://gitserver/git\-pillar.git: \- env: prod .ft P .fi .UNINDENT .UNINDENT .sp If \fB__env__\fP is specified as the branch name, then git_pillar will decide which branch to use based on the following criteria: .INDENT 0.0 .IP \(bu 2 If the minion has a \fI\%pillarenv\fP configured, it will use that pillar environment. (2016.11.2 and later) .IP \(bu 2 Otherwise, if the minion has an \fBenvironment\fP configured, it will use that environment. .IP \(bu 2 Otherwise, the master\(aqs \fI\%git_pillar_base\fP will be used. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The use of \fI\%environment\fP to choose the pillar environment dates from a time before the \fI\%pillarenv\fP parameter was added. In a future release, it will be ignored and either the minion\(aqs \fI\%pillarenv\fP or the master\(aqs \fI\%git_pillar_base\fP will be used. .UNINDENT .UNINDENT .sp Here\(aqs an example of using \fB__env__\fP as the git_pillar environment: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- git: \- __env__ https://gitserver/git\-pillar.git: \- root: pillar .ft P .fi .UNINDENT .UNINDENT .sp The corresponding Pillar top file would look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(dq{{saltenv}}\(dq: \(aq*\(aq: \- bar .ft P .fi .UNINDENT .UNINDENT .sp With the addition of \fI\%pygit2\fP support, git_pillar can now interact with authenticated remotes. Authentication works just like in gitfs (as outlined in the \fI\%Git Fileserver Backend Walkthrough\fP), only with the global authentication parameter names prefixed with \fBgit_pillar\fP instead of \fBgitfs\fP (e.g. \fI\%git_pillar_pubkey\fP, \fI\%git_pillar_privkey\fP, \fI\%git_pillar_passphrase\fP, etc.). .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBname\fP parameter can be used to further differentiate between two remotes with the same URL and branch. When using two remotes with the same URL, the \fBname\fP option is required. .UNINDENT .UNINDENT .SS How Multiple Remotes Are Handled .sp As noted above, multiple remotes can be included in the same \fBgit\fP ext_pillar configuration. Consider the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_etcd_config: etcd.host: 127.0.0.1 etcd.port: 4001 ext_pillar: \- etcd: my_etcd_config \- git: \- master https://mydomain.tld/foo.git: \- root: pillar \- master https://mydomain.tld/bar.git \- master https://mydomain.tld/baz.git \- dev https://mydomain.tld/qux.git \- git: \- master https://mydomain.tld/abc.git \- dev https://mydomain.tld/123.git .ft P .fi .UNINDENT .UNINDENT .sp To understand how pillar data from these repos will be compiled, it\(aqs important to know how Salt will process them. The following points should be kept in mind: .INDENT 0.0 .IP 1. 3 Each ext_pillar is called separately from the others. So, in the above example, the \fBetcd\fP ext_pillar will be evaluated first, with the first group of git_pillar remotes evaluated next (and merged into the etcd pillar data). Lastly, the second group of git_pillar remotes will be evaluated, and then merged into the ext_pillar data evaluated before it. .IP 2. 3 Within a single group of git_pillar remotes, each remote will be evaluated in order, with results merged together as each remote is evaluated. .sp \fBNOTE:\fP .INDENT 3.0 .INDENT 3.5 Prior to the 2017.7.0 release, remotes would be evaluated in a non\-deterministic order. .UNINDENT .UNINDENT .IP 3. 3 By default, when a repo is evaluated, other remotes\(aq which share its pillar environment will have their files made available to the remote being processed. .UNINDENT .sp The first point should be straightforward enough, but the second and third could use some additional clarification. .sp First, point #2. In the first group of git_pillar remotes, the top file and pillar SLS files in the \fBfoo\fP remote will be evaluated first. The \fBbar\fP remote will be evaluated next, and its results will be merged into the pillar data compiled when the \fBfoo\fP remote was evaluated. As the subsequent remotes are evaluated, their data will be merged in the same fashion. .sp But wait, don\(aqt these repositories belong to more than one pillar environments? Well, yes. The default method of generating pillar data compiles pillar data from all environments. This behavior can be overridden using a \fBpillarenv\fP\&. Setting a \fI\%pillarenv\fP in the minion config file will make that minion tell the master to ignore any pillar data from environments which don\(aqt match that pillarenv. A pillarenv can also be specified for a given minion or set of minions when \fI\%running states\fP, by using the \fBpillarenv\fP argument. The CLI pillarenv will override one set in the minion config file. So, assuming that a pillarenv of \fBbase\fP was set for a minion, it would not get any of the pillar variables configured in the \fBqux\fP remote, since that remote is assigned to the \fBdev\fP environment. The only way to get its pillar data would be to specify a pillarenv of \fBdev\fP, which would mean that it would then ignore any items from the \fBbase\fP pillarenv. A more detailed explanation of pillar environments can be found \fI\%here\fP\&. .sp Moving on to point #3, and looking at the example ext_pillar configuration, as the \fBfoo\fP remote is evaluated, it will also have access to the files from the \fBbar\fP and \fBbaz\fP remotes, since all three are assigned to the \fBbase\fP pillar environment. So, if an SLS file referenced by the \fBfoo\fP remotes\(aqs top file does not exist in the \fBfoo\fP remote, it will be searched for in the \fBbar\fP remote, followed by the \fBbaz\fP remote. When it comes time to evaluate the \fBbar\fP remote, SLS files referenced by the \fBbar\fP remote\(aqs top file will first be looked for in the \fBbar\fP remote, followed by \fBfoo\fP, and \fBbaz\fP, and when the \fBbaz\fP remote is processed, SLS files will be looked for in \fBbaz\fP, followed by \fBfoo\fP and \fBbar\fP\&. This \(dqfailover\(dq logic is called a \fI\%directory overlay\fP, and it is also used by \fI\%file_roots\fP and :conf_minion\(gapillar_roots\(ga. The ordering of which remote is checked for SLS files is determined by the order they are listed. First the remote being processed is checked, then the others that share the same environment are checked. However, before the 2017.7.0 release, since evaluation was unordered, the remote being processed would be checked, followed in no specific order by the other repos which share the same environment. .sp Beginning with the 2017.7.0 release, this behavior of git_pillar remotes having access to files in other repos which share the same environment can be disabled by setting \fI\%git_pillar_includes\fP to \fBFalse\fP\&. If this is done, then all git_pillar remotes will only have access to their own SLS files. Another way of ensuring that a git_pillar remote will not have access to SLS files from other git_pillar remotes which share the same pillar environment is to put them in a separate \fBgit\fP section under \fBext_pillar\fP\&. Look again at the example configuration above. In the second group of git_pillar remotes, the \fBabc\fP remote would not have access to the SLS files from the \fBfoo\fP, \fBbar\fP, and \fBbaz\fP remotes, and vice\-versa. .SS Mountpoints .sp New in version 2017.7.0. .sp Assume the following pillar top file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqweb*\(aq: \- common \- web.server.nginx \- web.server.appdata .ft P .fi .UNINDENT .UNINDENT .sp Now, assume that you would like to configure the \fBweb.server.nginx\fP and \fBweb.server.appdata\fP SLS files in separate repos. This could be done using the following ext_pillar configuration (assuming that \fI\%git_pillar_includes\fP has not been set to \fBFalse\fP): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- git: \- master https://mydomain.tld/pillar\-common.git \- master https://mydomain.tld/pillar\-nginx.git \- master https://mydomain.tld/pillar\-appdata.git .ft P .fi .UNINDENT .UNINDENT .sp However, in order to get the files in the second and third git_pillar remotes to work, you would need to first create the directory structure underneath it (i.e. place them underneath \fBweb/server/\fP in the repository). This also makes it tedious to reorganize the configuration, as changing \fBweb.server.nginx\fP to \fBweb.nginx\fP in the top file would require you to also move the SLS files in the \fBpillar\-nginx\fP up a directory level. .sp For these reasons, much like gitfs, git_pillar now supports a \(dqmountpoint\(dq feature. Using the following ext_pillar configuration, the SLS files in the second and third git_pillar remotes can be placed in the root of the git repository: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- git: \- master https://mydomain.tld/pillar\-common.git \- master https://mydomain.tld/pillar\-nginx.git: \- mountpoint: web/server/ \- master https://mydomain.tld/pillar\-appdata.git: \- mountpoint: web/server/ .ft P .fi .UNINDENT .UNINDENT .sp Now, if the top file changed the SLS target from \fBweb.server.nginx\fP, instead of reorganizing the git repository, you would just need to adjust the mountpoint to \fBweb/\fP (and restart the \fBsalt\-master\fP daemon). .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Leading and trailing slashes on the mountpoints are optional. .IP \(bu 2 Use of the \fBmountpoint\fP feature requires that \fI\%git_pillar_includes\fP is not disabled. .IP \(bu 2 Content from mounted git_pillar repos can only be referenced by a top file in the same pillar environment. .IP \(bu 2 Salt versions prior to 2018.3.4 ignore the \fBroot\fP parameter when \fBmountpoint\fP is set. .UNINDENT .UNINDENT .UNINDENT .SS all_saltenvs .sp New in version 2018.3.4. .sp When \fB__env__\fP is specified as the branch name, \fBall_saltenvs\fP per\-remote configuration parameter overrides the logic Salt uses to map branches/tags to pillar environments (i.e. pillarenvs). This allows a single branch/tag to appear in all saltenvs. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- git: \- __env__ https://mydomain.tld/top.git \- all_saltenvs: master \- __env__ https://mydomain.tld/pillar\-nginx.git: \- mountpoint: web/server/ \- __env__ https://mydomain.tld/pillar\-appdata.git: \- mountpoint: web/server/ .ft P .fi .UNINDENT .UNINDENT .SS git_pillar_update_interval .sp New in version 3000. .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 fallback .sp New in version 3001. .sp Setting \fBfallback\fP per\-remote or global configuration parameter will map non\-existing environments to a default branch. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- git: \- __env__ https://mydomain.tld/top.git \- all_saltenvs: master \- __env__ https://mydomain.tld/pillar\-nginx.git: \- mountpoint: web/server/ \- fallback: master \- __env__ https://mydomain.tld/pillar\-appdata.git: \- mountpoint: web/server/ \- fallback: master .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.git_pillar.ext_pillar(minion_id, pillar, *repos) Checkout the ext_pillar sources and compile the resulting pillar SLS .UNINDENT .SS salt.pillar.gpg .sp Decrypt pillar data through the builtin GPG renderer .sp In most cases, you\(aqll want to make this the last external pillar used. For example, to pair with the builtin stack pillar you could do something like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- stack: /path/to/stack.cfg \- gpg: {} .ft P .fi .UNINDENT .UNINDENT .sp Set \fBgpg_keydir\fP in your config to adjust the homedir the renderer uses. .INDENT 0.0 .TP .B salt.pillar.gpg.ext_pillar(minion_id, pillar, *args, **kwargs) .UNINDENT .SS salt.pillar.hg_pillar .sp Use remote Mercurial repository as a Pillar source. .sp New in version 2015.8.0. .sp The module depends on the \fBhglib\fP python module being available. This is the same requirement as for hgfs_ so should not pose any extra hurdles. .sp This external Pillar source can be configured in the master config file as such: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- hg: ssh://hg@example.co/user/repo .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.pillar.hg_pillar.Repo(repo_uri) Deal with remote hg (mercurial) repository for Pillar .INDENT 7.0 .TP .B close() Cleanup mercurial command server .UNINDENT .INDENT 7.0 .TP .B pull() .UNINDENT .INDENT 7.0 .TP .B update(branch=\(aqdefault\(aq) Ensure we are using the latest revision in the hg repository .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.hg_pillar.ext_pillar(minion_id, pillar, repo, branch=\(aqdefault\(aq, root=None) Extract pillar from an hg repository .UNINDENT .INDENT 0.0 .TP .B salt.pillar.hg_pillar.update(repo_uri) Execute an hg pull on all the repos .UNINDENT .SS salt.pillar.hiera .sp Use hiera data as a Pillar source .INDENT 0.0 .TP .B salt.pillar.hiera.ext_pillar(minion_id, pillar, conf) Execute hiera and return the data .UNINDENT .SS salt.pillar.http_json .sp A module that adds data to the Pillar structure retrieved by an http request .SS Configuring the HTTP_JSON ext_pillar .sp Set the following Salt config to setup http json result as external pillar source: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- http_json: url: http://example.com/api/minion_id namespace: \(aqsubkey\(aq username: username password: password header_dict: None auth: None .ft P .fi .UNINDENT .UNINDENT .sp You can pass additional parameters, they will be added to the http.query call \fI\%utils.http.query function\fP: .sp Changed in version 3006.0: If namespace is defined, the data will be added under the specified subkeys in the Pillar structure. .sp If the with_grains parameter is set, grain keys wrapped in can be provided (wrapped in <> brackets) in the url in order to populate pillar data based on the grain value. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- http_json: url: http://example.com/api/<nodename> with_grains: True .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2018.3.0: If %s is present in the url, it will be automatically replaced by the minion_id: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- http_json: url: http://example.com/api/%s .ft P .fi .UNINDENT .UNINDENT .SS Module Documentation .INDENT 0.0 .TP .B salt.pillar.http_json.ext_pillar(minion_id, pillar, url, with_grains=False, header_dict=None, auth=None, username=None, password=None, namespace=None) Read pillar data from HTTP response. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBurl\fP (\fI\%str\fP) \-\- Url to request. .IP \(bu 2 \fBwith_grains\fP (\fI\%bool\fP) \-\- Whether to substitute strings in the url with their grain values. .IP \(bu 2 \fBheader_dict\fP (\fI\%dict\fP) \-\- Extra headers to send .IP \(bu 2 \fBauth\fP \-\- special auth if needed .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- username for auth .IP \(bu 2 \fBpasword\fP (\fI\%str\fP) \-\- password for auth .IP \(bu 2 \fBnamespace\fP (\fI\%str\fP) \-\- (Optional) A pillar key to namespace the values under. \&.. versionadded:: 3006.0 .UNINDENT .TP .B Returns A dictionary of the pillar data to add. .TP .B Return type \fI\%dict\fP .UNINDENT .UNINDENT .SS salt.pillar.http_yaml .sp A module that adds data to the Pillar structure retrieved by an http request .SS Configuring the HTTP_YAML ext_pillar .sp Set the following Salt config to setup an http endpoint as the external pillar source: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- http_yaml: url: http://example.com/api/minion_id username: username password: password header_dict: None auth: None .ft P .fi .UNINDENT .UNINDENT .sp You can pass additional parameters, they will be added to the http.query call \fI\%utils.http.query function\fP: .sp If the with_grains parameter is set, grain keys wrapped in can be provided (wrapped in <> brackets) in the url in order to populate pillar data based on the grain value. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- http_yaml: url: http://example.com/api/<nodename> with_grains: True .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2018.3.0: If %s is present in the url, it will be automatically replaced by the minion_id: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- http_json: url: http://example.com/api/%s .ft P .fi .UNINDENT .UNINDENT .SS Module Documentation .INDENT 0.0 .TP .B salt.pillar.http_yaml.ext_pillar(minion_id, pillar, url, with_grains=False, header_dict=None, auth=None, username=None, password=None) Read pillar data from HTTP response. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBurl\fP (\fI\%str\fP) \-\- Url to request. .IP \(bu 2 \fBwith_grains\fP (\fI\%bool\fP) \-\- Whether to substitute strings in the url with their grain values. .IP \(bu 2 \fBheader_dict\fP (\fI\%dict\fP) \-\- Extra headers to send .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- username for auth .IP \(bu 2 \fBpasword\fP (\fI\%str\fP) \-\- password for auth .IP \(bu 2 \fBauth\fP \-\- special auth if needed .UNINDENT .TP .B Returns A dictionary of the pillar data to add. .TP .B Return type \fI\%dict\fP .UNINDENT .UNINDENT .SS salt.pillar.libvirt .sp Load up the libvirt keys into Pillar for a given minion if said keys have been generated using the libvirt key runner .INDENT 0.0 .TP .B depends certtool .UNINDENT .INDENT 0.0 .TP .B salt.pillar.libvirt.ext_pillar(minion_id, pillar, command) Read in the generated libvirt keys .UNINDENT .INDENT 0.0 .TP .B salt.pillar.libvirt.gen_hyper_keys(minion_id, country=\(aqUS\(aq, state=\(aqUtah\(aq, locality=\(aqSalt Lake City\(aq, organization=\(aqSalted\(aq, expiration_days=\(aq365\(aq) Generate the keys to be used by libvirt hypervisors, this routine gens the keys and applies them to the pillar for the hypervisor minions .UNINDENT .SS salt.pillar.makostack .sp Simple and flexible YAML ext_pillar which can read pillar from within pillar. .sp New in version 2016.3.0. .sp This custom saltstack \fBext_pillar\fP is a direct ripoff of the \(aqstack\(aq ext_pillar, simply ported to use mako instead of jinja2 for templating. .sp It supports the following features: .INDENT 0.0 .IP \(bu 2 multiple config files that are mako templates with support for \fBpillar\fP, \fB__grains__\fP, \fB__salt__\fP, \fB__opts__\fP objects. .IP \(bu 2 a config file renders as an ordered list of files. Unless absolute, the paths of these files are relative to the current config file \- if absolute, they will be treated literally. .IP \(bu 2 this list of files are read in order as mako templates with support for \fBstack\fP, \fBpillar\fP, \fB__grains__\fP, \fB__salt__\fP, \fB__opts__\fP objects. .IP \(bu 2 all these rendered files are then parsed as \fByaml\fP\&. .IP \(bu 2 then all yaml dicts are merged in order, with support for the following. merging strategies: \fBmerge\-first\fP, \fBmerge\-last\fP, \fBremove\fP, and \fBoverwrite\fP\&. .IP \(bu 2 stack config files can be matched based on \fBpillar\fP, \fBgrains\fP, or \fBopts\fP values, which make it possible to support kind of self\-contained environments. .UNINDENT .SS Configuration in Salt .sp Like any other external pillar, its configuration takes place through the \fBext_pillar\fP key in the master config file. .sp However, you can configure MakoStack in 3 different ways: .SS Single config file .sp This is the simplest option, you just need to set the path to your single MakoStack config file like below: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- makostack: /path/to/stack.cfg .ft P .fi .UNINDENT .UNINDENT .SS List of config files .sp You can also provide a list of config files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- makostack: \- /path/to/stack1.cfg \- /path/to/stack2.cfg .ft P .fi .UNINDENT .UNINDENT .SS Select config files through grains|pillar|opts matching .sp You can also opt for a much more flexible configuration: MakoStack allows one to select the config files for the current minion based on matching values from either grains, or pillar, or opts objects. .sp Here is an example of such a configuration, which should speak by itself: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- makostack: pillar:environment: dev: /path/to/dev/stack.cfg prod: /path/to/prod/stack.cfg grains:custom:grain: value: \- /path/to/stack1.cfg \- /path/to/stack2.cfg opts:custom:opt: value: /path/to/stack0.cfg .ft P .fi .UNINDENT .UNINDENT .SS Grafting data from files to arbitrary namespaces .sp An extended syntax for config files permits defining \(dqgraft points\(dq on a per\-config\-file basis. As an example, if the file foo.cfg would produce the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo: \- bar \- baz .ft P .fi .UNINDENT .UNINDENT .sp and you specified the cfg file as /path/to/foo.cfg:yummy:fur, the following would actually end up in pillar after all merging was complete: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yummy: fur: foo: \- bar \- baz .ft P .fi .UNINDENT .UNINDENT .SS MakoStack configuration files .sp The config files that are referenced in the above \fBext_pillar\fP configuration are mako templates which must render as a simple ordered list of \fByaml\fP files that will then be merged to build pillar data. .sp Unless an absolute path name is specified, the path of these \fByaml\fP files is assumed to be relative to the directory containing the MakoStack config file. If a path begins with \(aq/\(aq, however, it will be treated literally and can be anywhere on the filesystem. .sp The following variables are available in mako templating of makostack configuration files: .INDENT 0.0 .IP \(bu 2 \fBpillar\fP: the pillar data (as passed by Salt to our \fBext_pillar\fP function) .IP \(bu 2 \fBminion_id\fP: the minion id ;\-) .IP \(bu 2 \fB__opts__\fP: a dictionary of mostly Salt configuration options .IP \(bu 2 \fB__grains__\fP: a dictionary of the grains of the minion making this pillar call .IP \(bu 2 \fB__salt__\fP: a dictionary of Salt module functions, useful so you don\(aqt have to duplicate functions that already exist (note: runs on the master) .UNINDENT .sp So you can use all the power of mako to build your list of \fByaml\fP files that will be merged in pillar data. .sp For example, you could have a MakoStack config file which looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ cat /path/to/stack/config.cfg core.yml osarchs/%{ __grains__[\(aqosarch\(aq] }}.yml oscodenames/%{ __grains__[\(aqoscodename\(aq] }.yml % for role in pillar.get(\(aqroles\(aq, []): roles/%{ role }.yml % endfor minions/%{ minion_id }.yml .ft P .fi .UNINDENT .UNINDENT .sp And the whole directory structure could look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ tree /path/to/stack/ /path/to/stack/ ├── config.cfg ├── core.yml ├── osarchs/ │\ \ ├── amd64.yml │\ \ └── armhf.yml ├── oscodenames/ │\ \ ├── wheezy.yml │\ \ └── jessie.yml ├── roles/ │\ \ ├── web.yml │\ \ └── db.yml └── minions/ ├── test\-1\-dev.yml └── test\-2\-dev.yml .ft P .fi .UNINDENT .UNINDENT .SS Overall process .sp In the above MakoStack configuration, given that test\-1\-dev minion is an amd64 platform running Debian Jessie, and which pillar \fBroles\fP is \fB[\(dqdb\(dq]\fP, the following \fByaml\fP files would be merged in order: .INDENT 0.0 .IP \(bu 2 \fBcore.yml\fP .IP \(bu 2 \fBosarchs/amd64.yml\fP .IP \(bu 2 \fBoscodenames/jessie.yml\fP .IP \(bu 2 \fBroles/db.yml\fP .IP \(bu 2 \fBminions/test\-1\-dev.yml\fP .UNINDENT .sp Before merging, every files above will be preprocessed as mako templates. The following variables are available in mako templating of \fByaml\fP files: .INDENT 0.0 .IP \(bu 2 \fBstack\fP: the MakoStack pillar data object that has currently been merged (data from previous \fByaml\fP files in MakoStack configuration) .IP \(bu 2 \fBpillar\fP: the pillar data (as passed by Salt to our \fBext_pillar\fP function) .IP \(bu 2 \fBminion_id\fP: the minion id ;\-) .IP \(bu 2 \fB__opts__\fP: a dictionary of mostly Salt configuration options .IP \(bu 2 \fB__grains__\fP: a dictionary of the grains of the minion making this pillar call .IP \(bu 2 \fB__salt__\fP: a dictionary of Salt module functions, useful so you don\(aqt have to duplicate functions that already exist (note: runs on the master) .UNINDENT .sp So you can use all the power of mako to build your pillar data, and even use other pillar values that has already been merged by MakoStack (from previous \fByaml\fP files in MakoStack configuration) through the \fBstack\fP variable. .sp Once a \fByaml\fP file has been preprocessed by mako, we obtain a Python dict \- let\(aqs call it \fByml_data\fP \- then, MakoStack will merge this \fByml_data\fP dict in the main \fBstack\fP dict (which contains already merged MakoStack pillar data). By default, MakoStack will deeply merge \fByml_data\fP in \fBstack\fP (similarly to the \fBrecurse\fP salt \fBpillar_source_merging_strategy\fP), but 3 merging strategies are currently available for you to choose (see next section). .sp Once every \fByaml\fP files have been processed, the \fBstack\fP dict will contain your whole own pillar data, merged in order by MakoStack. So MakoStack \fBext_pillar\fP returns the \fBstack\fP dict, the contents of which Salt takes care to merge in with all of the other pillars and finally return the whole pillar to the minion. .SS Merging strategies .sp The way the data from a new \fByaml_data\fP dict is merged with the existing \fBstack\fP data can be controlled by specifying a merging strategy. Right now this strategy can either be \fBmerge\-last\fP (the default), \fBmerge\-first\fP, \fBremove\fP, or \fBoverwrite\fP\&. .sp Note that scalar values like strings, integers, booleans, etc. are always evaluated using the \fBoverwrite\fP strategy (other strategies don\(aqt make sense in that case). .sp The merging strategy can be set by including a dict in the form of: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __: <merging strategy> .ft P .fi .UNINDENT .UNINDENT .sp as the first item of the dict or list. This allows fine grained control over the merging process. .SS \fBmerge\-last\fP (default) strategy .sp If the \fBmerge\-last\fP strategy is selected (the default), then content of dict or list variables is merged recursively with previous definitions of this variable (similarly to the \fBrecurse\fP salt \fBpillar_source_merging_strategy\fP). This allows for extending previously defined data. .SS \fBmerge\-first\fP strategy .sp If the \fBmerge\-first\fP strategy is selected, then the content of dict or list variables are swapped between the \fByaml_data\fP and \fBstack\fP objects before being merged recursively with the \fBmerge\-last\fP previous strategy. .SS \fBremove\fP strategy .sp If the \fBremove\fP strategy is selected, then content of dict or list variables in \fBstack\fP are removed only if the corresponding item is present in the \fByaml_data\fP dict. This allows for removing items from previously defined data. .SS \fBoverwrite\fP strategy .sp If the \fBoverwrite\fP strategy is selected, then the content of dict or list variables in \fBstack\fP is overwritten by the content of \fByaml_data\fP dict. So this allows one to overwrite variables from previous definitions. .SS Merging examples .sp Let\(aqs go through small examples that should clarify what\(aqs going on when a \fByaml_data\fP dict is merged in the \fBstack\fP dict. .sp When you don\(aqt specify any strategy, the default \fBmerge\-last\fP strategy is selected: .TS center; |l|l|l|. _ T{ \fBstack\fP T} T{ \fByaml_data\fP T} T{ \fBstack\fP (after merge) T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 500 roles: \- sysadmin root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 1000 roles: \- developer mat: uid: 1001 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 1000 roles: \- sysadmin \- developer mat: uid: 1001 root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} _ .TE .sp Then you can select a custom merging strategy using the \fB__\fP key in a dict: .TS center; |l|l|l|. _ T{ \fBstack\fP T} T{ \fByaml_data\fP T} T{ \fBstack\fP (after merge) T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 500 roles: \- sysadmin root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: __: merge\-last tom: uid: 1000 roles: \- developer mat: uid: 1001 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 1000 roles: \- sysadmin \- developer mat: uid: 1001 root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 500 roles: \- sysadmin root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: __: merge\-first tom: uid: 1000 roles: \- developer mat: uid: 1001 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 500 roles: \- developer \- sysadmin mat: uid: 1001 root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 500 roles: \- sysadmin root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: __: remove tom: mat: .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 500 roles: \- sysadmin root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: __: overwrite tom: uid: 1000 roles: \- developer mat: uid: 1001 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 1000 roles: \- developer mat: uid: 1001 .ft P .fi .UNINDENT .UNINDENT T} _ .TE .sp You can also select a custom merging strategy using a \fB__\fP object in a list: .TS center; |l|l|l|. _ T{ \fBstack\fP T} T{ \fByaml_data\fP T} T{ \fBstack\fP (after merge) T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- tom \- root .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- __: merge\-last \- mat .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- tom \- root \- mat .ft P .fi .UNINDENT .UNINDENT T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- tom \- root .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- __: merge\-first \- mat .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- mat \- tom \- root .ft P .fi .UNINDENT .UNINDENT T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- tom \- root .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- __: remove \- mat \- tom .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- root .ft P .fi .UNINDENT .UNINDENT T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- tom \- root .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- __: overwrite \- mat .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- mat .ft P .fi .UNINDENT .UNINDENT T} _ .TE .INDENT 0.0 .TP .B salt.pillar.makostack.ext_pillar(minion_id, pillar, *args, **kwargs) .UNINDENT .SS salt.pillar.mongo .sp Read Pillar data from a mongodb collection .INDENT 0.0 .TP .B depends pymongo (for salt\-master) .UNINDENT .sp This module will load a node\-specific pillar dictionary from a mongo collection. It uses the node\(aqs id for lookups and can load either the whole document, or just a specific field from that document as the pillar dictionary. .SS Salt Master Mongo Configuration .sp The module shares the same base mongo connection variables as \fI\%salt.returners.mongo_future_return\fP\&. These variables go in your master config file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo.db: <database name> mongo.host: <server ip address> mongo.user: <MongoDB username> mongo.password: <MongoDB user 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 .SS Configuring the Mongo ext_pillar .sp The Mongo ext_pillar takes advantage of the fact that the Salt Master configuration file is yaml. It uses a sub\-dictionary of values to adjust specific features of the pillar. This is the explicit single\-line dictionary notation for yaml. One may be able to get the easier\-to\-read multi\-line dict to work correctly with some experimentation. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- mongo: {collection: vm, id_field: name, re_pattern: \e.example\e.com, fields: [customer_id, software, apache_vhosts]} .ft P .fi .UNINDENT .UNINDENT .sp In the example above, we\(aqve decided to use the \fBvm\fP collection in the database to store the data. Minion ids are stored in the \fBname\fP field on documents in that collection. And, since minion ids are FQDNs in most cases, we\(aqll need to trim the domain name in order to find the minion by hostname in the collection. When we find a minion, return only the \fBcustomer_id\fP, \fBsoftware\fP, and \fBapache_vhosts\fP fields, as that will contain the data we want for a given node. They will be available directly inside the \fBpillar\fP dict in your SLS templates. .SS Module Documentation .INDENT 0.0 .TP .B salt.pillar.mongo.ext_pillar(minion_id, pillar, collection=\(aqpillar\(aq, id_field=\(aq_id\(aq, re_pattern=None, re_replace=\(aq\(aq, fields=None) Connect to a mongo database and read per\-node pillar information. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcollection\fP (\fI*\fP) \-\- The mongodb collection to read data from. Defaults to \fB\(aqpillar\(aq\fP\&. .IP \(bu 2 \fBid_field\fP (\fI*\fP) \-\- The field in the collection that represents an individual minion id. Defaults to \fB\(aq_id\(aq\fP\&. .IP \(bu 2 \fBre_pattern\fP (\fI*\fP) \-\- If your naming convention in the collection is shorter than the minion id, you can use this to trim the name. \fIre_pattern\fP will be used to match the name, and \fIre_replace\fP will be used to replace it. Backrefs are supported as they are in the Python standard library. If \fBNone\fP, no mangling of the name will be performed \- the collection will be searched with the entire minion id. Defaults to \fBNone\fP\&. .IP \(bu 2 \fBre_replace\fP (\fI*\fP) \-\- Use as the replacement value in node ids matched with \fIre_pattern\fP\&. Defaults to \(aq\(aq. Feel free to use backreferences here. .IP \(bu 2 \fBfields\fP (\fI*\fP) \-\- The specific fields in the document to use for the pillar data. If \fBNone\fP, will use the entire document. If using the entire document, the \fB_id\fP field will be converted to string. Be careful with other fields in the document as they must be string serializable. Defaults to \fBNone\fP\&. .UNINDENT .UNINDENT .UNINDENT .SS salt.pillar.mysql .sp Retrieve Pillar data by doing a MySQL query .sp MariaDB provides Python support through the MySQL Python package. Therefore, you may use this module with both MySQL or MariaDB. .sp This module is a concrete implementation of the sql_base ext_pillar for MySQL. .INDENT 0.0 .TP .B maturity new .TP .B depends python\-mysqldb .TP .B platform all .UNINDENT .SS Configuring the mysql ext_pillar .sp Use the \(aqmysql\(aq key under ext_pillar for configuration of queries. .sp MySQL configuration of the MySQL returner is being used (mysql.db, mysql.user, mysql.pass, mysql.port, mysql.host) for database connection info. .sp Required python modules: MySQLdb .SS Complete example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql: user: \(aqsalt\(aq pass: \(aqsuper_secret_password\(aq db: \(aqsalt_db\(aq port: 3306 ssl: cert: /etc/mysql/client\-cert.pem key: /etc/mysql/client\-key.pem ext_pillar: \- mysql: fromdb: query: \(aqSELECT col1,col2,col3,col4,col5,col6,col7 FROM some_random_table WHERE minion_pattern LIKE %s\(aq depth: 5 as_list: True with_lists: [1,3] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.pillar.mysql.MySQLExtPillar This class receives and processes the database rows from MySQL. .INDENT 7.0 .TP .B extract_queries(args, kwargs) This function normalizes the config block into a set of queries we can use. The return is a list of consistently laid out dicts. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.mysql.ext_pillar(minion_id, pillar, *args, **kwargs) Execute queries against MySQL, merge and return as a dict .UNINDENT .SS salt.pillar.nacl .sp Decrypt pillar data through the builtin NACL renderer .sp In most cases, you\(aqll want to make this the last external pillar used. For example, to pair with the builtin stack pillar you could do something like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nacl.config: keyfile: /root/.nacl ext_pillar: \- stack: /path/to/stack.cfg \- nacl: {} .ft P .fi .UNINDENT .UNINDENT .sp Set \fBnacl.config\fP in your config. .INDENT 0.0 .TP .B salt.pillar.nacl.ext_pillar(minion_id, pillar, *args, **kwargs) .UNINDENT .SS salt.pillar.netbox .sp A module that adds data to the Pillar structure from a NetBox API. .sp New in version 2019.2.0. .SS Configuring the NetBox ext_pillar .sp To use this pillar, you must first create a token in your NetBox instance at \fI\%http://netbox.example.com/user/api\-tokens/\fP (substituting the hostname of your NetBox instance) .sp The NetBox api_url and api_token must be set in the master config. .sp For example \fB/etc/salt/master.d/netbox.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- netbox: api_url: http://netbox.example.com/api/ api_token: 123abc .ft P .fi .UNINDENT .UNINDENT .sp The following options are optional, and determine whether or not the module will attempt to configure the \fBproxy\fP pillar data for use with the napalm proxy\-minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy_return: True proxy_username: admin .ft P .fi .UNINDENT .UNINDENT .sp By default, this module will query the NetBox API for the platform associated with the device, and use the \(aqNAPALM driver\(aq field to set the napalm proxy\-minion driver. (Currently only \(aqnapalm\(aq is supported for drivertype.) .sp This module currently only supports the napalm proxy minion and assumes you will use SSH keys to authenticate to the network device. If password authentication is desired, it is recommended to create another \fBproxy\fP key in pillar_roots (or git_pillar) with just the \fBpasswd\fP key and use \fI\%salt.renderers.gpg\fP to encrypt the value. .sp If you use more than one username for your devices, leave proxy_username unset, and set the \fBusername\fP key in your pillar as well. If any additional options for the proxy setup are needed, they should also be configured in pillar_roots. .sp Other available configuration options: .INDENT 0.0 .TP .B site_details: \fBTrue\fP Whether should retrieve details of the site the device belongs to. .TP .B site_prefixes: \fBTrue\fP Whether should retrieve the prefixes of the site the device belongs to. .TP .B devices: \fBTrue\fP New in version 3004. .sp Whether should retrieve physical devices. .TP .B virtual_machines: \fBFalse\fP New in version 3004. .sp Whether should retrieve virtual machines. .TP .B interfaces: \fBFalse\fP New in version 3004. .sp Whether should retrieve the interfaces of the device. .TP .B interface_ips: \fBFalse\fP New in version 3004. .sp Whether should retrieve the IP addresses for interfaces of the device. (interfaces must be set to True as well) .TP .B api_query_result_limit: \fBUse NetBox default\fP New in version 3004. .sp An integer specifying how many results should be returned for each query to the NetBox API. Leaving this unset will use NetBox\(aqs default value. .TP .B connected_devices: \fBFalse\fP New in version 3006.0. .sp Whether connected_devices key should be populated with device objects. If set to True it will force \fIinterfaces\fP to also be true as a dependency .UNINDENT .sp Note that each option you enable can have a detrimental impact on pillar performance, so use them with caution. .sp After configuring the pillar, you must restart the Salt master for the changes to take effect. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl restart salt\-master .ft P .fi .UNINDENT .UNINDENT .sp To query perform a quick test of the pillar, you should refresh the pillar on the minion with the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt minion1 saltutil.refresh_pillar .ft P .fi .UNINDENT .UNINDENT .sp And then query the pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt minion1 pillar.items \(aqnetbox\(aq .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minion1: netbox: \-\-\-\-\-\-\-\-\-\- id: 511 url: https://netbox.example.com/api/dcim/devices/511/ name: minion1 node_type: device display_name: minion1 device_type: \-\-\-\-\-\-\-\-\-\- id: 4 url: https://netbox.example.com/api/dcim/device\-types/4/ manufacturer: \-\-\-\-\-\-\-\-\-\- id: 1 url: https://netbox.example.com/api/dcim/manufacturers/1/ name: Cisco slug: cisco model: ISR2901 slug: isr2901 display_name: Cisco ISR2901 device_role: \-\-\-\-\-\-\-\-\-\- id: 45 url: https://netbox.example.com/api/dcim/device\-roles/45/ name: Network slug: network interfaces: |_ \-\-\-\-\-\-\-\-\-\- id: 8158 ip_addresses: |_ \-\-\-\-\-\-\-\-\-\- id: 1146 url: https://netbox.example.com/api/ipam/ip\-addresses/1146/ family: \-\-\-\-\-\-\-\-\-\- value: 4 label: IPv4 address: 192.0.2.1/24 vrf: None tenant: None status: \-\-\-\-\-\-\-\-\-\- value: active label: Active role: None nat_inside: None nat_outside: None dns_name: description: tags: custom_fields: created: 2021\-02\-19 last_updated: 2021\-02\-19T06:12:04.153386Z url: https://netbox.example.com/api/dcim/interfaces/8158/ name: GigabitEthernet0/0 label: type: \-\-\-\-\-\-\-\-\-\- value: 1000base\-t label: 1000BASE\-T (1GE) enabled: True lag: None mtu: None mac_address: None mgmt_only: False description: mode: None untagged_vlan: None tagged_vlans: cable: None cable_peer: None cable_peer_type: None connected_endpoint: None connected_endpoint_type: None connected_endpoint_reachable: None tags: count_ipaddresses: 1 |_ \-\-\-\-\-\-\-\-\-\- id: 8159 ip_addresses: |_ \-\-\-\-\-\-\-\-\-\- id: 1147 url: https://netbox.example.com/api/ipam/ip\-addresses/1147/ family: \-\-\-\-\-\-\-\-\-\- value: 4 label: IPv4 address: 198.51.100.1/24 vrf: None tenant: None status: \-\-\-\-\-\-\-\-\-\- value: active label: Active role: None nat_inside: None nat_outside: None dns_name: description: tags: custom_fields: created: 2021\-02\-19 last_updated: 2021\-02\-19T06:12:40.508154Z url: https://netbox.example.com/api/dcim/interfaces/8159/ name: GigabitEthernet0/1 label: type: \-\-\-\-\-\-\-\-\-\- value: 1000base\-t label: 1000BASE\-T (1GE) enabled: True lag: None mtu: None mac_address: None mgmt_only: False description: mode: None untagged_vlan: None tagged_vlans: cable: None cable_peer: None cable_peer_type: None connected_endpoint: None connected_endpoint_type: None connected_endpoint_reachable: None tags: count_ipaddresses: 1 tenant: None platform: \-\-\-\-\-\-\-\-\-\- id: 1 url: https://netbox.example.com/api/dcim/platforms/1/ name: Cisco IOS slug: ios serial: asset_tag: None site: \-\-\-\-\-\-\-\-\-\- id: 18 url: https://netbox.example.com/api/dcim/sites/18/ name: Site 1 slug: site1 status: \-\-\-\-\-\-\-\-\-\- value: active label: Active region: None tenant: None facility: asn: None time_zone: None description: physical_address: shipping_address: latitude: None longitude: None contact_name: contact_phone: contact_email: comments: tags: custom_fields: created: 2021\-02\-25 last_updated: 2021\-02\-25T14:21:07.898957Z circuit_count: 0 device_count: 1 prefix_count: 2 rack_count: 0 virtualmachine_count: 1 vlan_count: 0 prefixes: |_ \-\-\-\-\-\-\-\-\-\- id: 284 url: https://netbox.example.com/api/ipam/prefixes/284/ family: \-\-\-\-\-\-\-\-\-\- value: 4 label: IPv4 prefix: 192.0.2.0/24 vrf: None tenant: None vlan: None \-\-\-\-\-\-\-\-\-\- value: active label: Active role: None is_pool: False description: tags: custom_fields: created: 2021\-02\-25 last_updated: 2021\-02\-25T15:08:27.136305Z |_ \-\-\-\-\-\-\-\-\-\- id: 285 url: https://netbox.example.com/api/ipam/prefixes/285/ family: \-\-\-\-\-\-\-\-\-\- value: 4 label: IPv4 prefix: 198.51.100.0/24 vrf: None tenant: None vlan: None status: \-\-\-\-\-\-\-\-\-\- value: active label: Active role: None is_pool: False description: tags: custom_fields: created: 2021\-02\-25 last_updated: 2021\-02\-25T15:08:59.880440Z rack: None position: None face: None parent_device: None status: \-\-\-\-\-\-\-\-\-\- value: active label: Active primary_ip: \-\-\-\-\-\-\-\-\-\- id: 1146 url: https://netbox.example.com/api/ipam/ip\-addresses/1146/ family: 4 address: 192.0.2.1/24 primary_ip4: \-\-\-\-\-\-\-\-\-\- id: 1146 url: https://netbox.example.com/api/ipam/ip\-addresses/1146/ family: 4 address: 192.0.2.1/24 primary_ip6: None cluster: None virtual_chassis: None vc_position: None vc_priority: None comments: local_context_data: None tags: custom_fields: config_context: connected_devices: \-\-\-\-\-\-\-\-\-\- 512: \-\-\-\-\-\-\-\-\-\- airflow: None asset_tag: 001 cluster: None comments: config_context: created: 2022\-03\-10T00:00:00Z custom_fields: device_role: \-\-\-\-\-\-\-\-\-\- display: Network switch id: 512 name: Network switch slug: network_switch url: https://netbox.example.com/api/dcim/device\-roles/5/ device_type: \-\-\-\-\-\-\-\-\-\- display: Nexus 3048 id: 40 manufacturer: \-\-\-\-\-\-\-\-\-\- display: Cisco id: 1 name: Cisco slug: cisco url: https://netbox.example.com/api/dcim/manufacturers/1/ model: Nexus 3048 slug: n3k\-c3048tp\-1ge url: https://netbox.example.com/api/dcim/device\-types/40/ display: another device (001) face: \-\-\-\-\-\-\-\-\-\- label: Front value: front id: 1533 last_updated: 2022\-08\-22T13:50:15.923868Z local_context_data: None location: \-\-\-\-\-\-\-\-\-\- _depth: 2 display: Location Name id: 2 name: Location Name slug: location\-name url: https://netbox.example.com/api/dcim/locations/2 name: another device parent_device: None platform: None position: 18.0 primary_ip: \-\-\-\-\-\-\-\-\-\- address: 192.168.1.1/24 display: 192.168.1.1/24 family: 4 id: 1234 url: https://netbox.example.com/api/ipam/ip\-addresses/1234/ primary_ip4: \-\-\-\-\-\-\-\-\-\- address: 192.168.1.1/24 display: 192.168.1.1/24 family: 4 id: 1234 url: https://netbox.example.com/api/ipam/ip\-addresses/1234/ primary_ip6: None rack: \-\-\-\-\-\-\-\-\-\- display: RackName id: 139 name: RackName url: https://netbox.example.com/api/dcim/racks/139/ serial: ABCD12345 site: \-\-\-\-\-\-\-\-\-\- display: SiteName id: 2 name: SiteName slug: sitename url: https://netbox.example.com/api/dcim/sites/2/ status: \-\-\-\-\-\-\-\-\-\- label: Active value: active tags: tenant: None url: https://netbox.example.com/api/dcim/devices/1533/ vc_position: None vc_priority: None virtual_chassis: None created: 2021\-02\-19 last_updated: 2021\-02\-19T06:12:04.171105Z .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.netbox.ext_pillar(minion_id, pillar, *args, **kwargs) Query NetBox API for minion data .UNINDENT .SS salt.pillar.neutron .sp Use Openstack Neutron data as a Pillar source. Will list all networks listed inside of Neutron, to all minions. .sp New in version 2015.5.1. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 python\-neutronclient .UNINDENT .UNINDENT .sp A keystone profile must be used for the pillar to work (no generic keystone configuration here). For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my openstack_config: keystone.user: \(aqadmin\(aq keystone.password: \(aqpassword\(aq keystone.tenant: \(aqadmin\(aq keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq keystone.region_name: \(aqRegionOne\(aq keystone.service_type: \(aqnetwork\(aq .ft P .fi .UNINDENT .UNINDENT .sp After the profile is created, configure the external pillar system to use it. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- neutron: my_openstack_config .ft P .fi .UNINDENT .UNINDENT .sp Using these configuration profiles, multiple neutron sources may also be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- neutron: my_openstack_config \- neutron: my_other_openstack_config .ft P .fi .UNINDENT .UNINDENT .sp By default, these networks will be returned as a pillar item called \fBnetworks\fP\&. In order to have them returned under a different name, add the name after the Keystone profile name: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B ext_pillar: .INDENT 7.0 .IP \(bu 2 neutron: my_openstack_config neutron_networks .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.neutron.ext_pillar(minion_id, pillar, conf) Check neutron for all data .UNINDENT .SS salt.pillar.nodegroups .SS Nodegroups Pillar .sp Introspection: to which nodegroups does my minion belong? Provides a pillar with the default name of \fInodegroups\fP which contains a list of nodegroups which match for a given minion. .sp New in version 2016.11.0. .SS Command Line .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call pillar.get nodegroups local: \- class_infra \- colo_sj \- state_active \- country_US \- type_saltmaster .ft P .fi .UNINDENT .UNINDENT .SS Configuring Nodegroups Pillar .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C extension_modules: /srv/salt/ext ext_pillar: \- nodegroups: pillar_name: \(aqnodegroups\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.nodegroups.ext_pillar(minion_id, pillar, pillar_name=None) A salt external pillar which provides the list of nodegroups of which the minion is a member. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBminion_id\fP \-\- used for compound matching nodegroups .IP \(bu 2 \fBpillar\fP \-\- provided by salt, but not used by nodegroups ext_pillar .IP \(bu 2 \fBpillar_name\fP \-\- optional name to use for the pillar, defaults to \(aqnodegroups\(aq .UNINDENT .TP .B Returns a dictionary which is included by the salt master in the pillars returned to the minion .UNINDENT .UNINDENT .SS salt.pillar.pepa .SS Pepa .sp Configuration templating for SaltStack using Hierarchical substitution and Jinja. .SS Configuring Pepa .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C extension_modules: /srv/salt/ext ext_pillar: \- pepa: resource: host # Name of resource directory and sub\-key in pillars sequence: # Sequence used for hierarchical substitution \- hostname: # Name of key name: input # Alias used for template directory base_only: True # Only use templates from Base environment, i.e. no staging \- default: \- environment: \- location..region: name: region \- location..country: name: country \- location..datacenter: name: datacenter \- roles: \- osfinger: name: os \- hostname: name: override base_only: True subkey: True # Create a sub\-key in pillars, named after the resource in this case [host] subkey_only: True # Only create a sub\-key, and leave the top level untouched pepa_roots: # Base directory for each environment base: /srv/pepa/base # Path for base environment dev: /srv/pepa/base # Associate dev with base qa: /srv/pepa/qa prod: /srv/pepa/prod # Use a different delimiter for nested dictionaries, defaults to \(aq..\(aq since some keys may use \(aq.\(aq in the name #pepa_delimiter: .. # Supply Grains for Pepa, this should **ONLY** be used for testing or validation #pepa_grains: # environment: dev # Supply Pillar for Pepa, this should **ONLY** be used for testing or validation #pepa_pillars: # saltversion: 0.17.4 # Enable debug for Pepa, and keep Salt on warning #log_level: debug #log_granular_levels: # salt: warning # salt.loaded.ext.pillar.pepa: debug .ft P .fi .UNINDENT .UNINDENT .sp Pepa can also be used in Master\-less SaltStack setup. .SS Command line .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C usage: pepa.py [\-h] [\-c CONFIG] [\-d] [\-g GRAINS] [\-p PILLAR] [\-n] [\-v] hostname positional arguments: hostname Hostname optional arguments: \-h, \-\-help show this help message and exit \-c CONFIG, \-\-config CONFIG Configuration file \-d, \-\-debug Print debug info \-g GRAINS, \-\-grains GRAINS Input Grains as YAML \-p PILLAR, \-\-pillar PILLAR Input Pillar as YAML \-n, \-\-no\-color No color output \-v, \-\-validate Validate output .ft P .fi .UNINDENT .UNINDENT .SS Templates .sp Templates is configuration for a host or software, that can use information from Grains or Pillars. These can then be used for hierarchically substitution. .sp \fBExample File:\fP host/input/test_example_com.yaml .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C location..region: emea location..country: nl location..datacenter: foobar environment: dev roles: \- salt.master network..gateway: 10.0.0.254 network..interfaces..eth0..hwaddr: 00:20:26:a1:12:12 network..interfaces..eth0..dhcp: False network..interfaces..eth0..ipv4: 10.0.0.3 network..interfaces..eth0..netmask: 255.255.255.0 network..interfaces..eth0..fqdn: {{ hostname }} cobbler..profile: fedora\-19\-x86_64 .ft P .fi .UNINDENT .UNINDENT .sp As you see in this example you can use Jinja directly inside the template. .sp \fBExample File:\fP host/region/amer.yaml .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C network..dns..servers: \- 10.0.0.1 \- 10.0.0.2 time..ntp..servers: \- ntp1.amer.example.com \- ntp2.amer.example.com \- ntp3.amer.example.com time..timezone: America/Chihuahua yum..mirror: yum.amer.example.com .ft P .fi .UNINDENT .UNINDENT .sp Each template is named after the value of the key using lowercase and all extended characters are replaced with underscore. .sp \fBExample:\fP .sp osfinger: Fedora\-19 .sp \fBWould become:\fP .sp fedora_19.yaml .SS Nested dictionaries .sp In order to create nested dictionaries as output you can use double dot \fB\(dq..\(dq\fP as a delimiter. You can change this using \(dqpepa_delimiter\(dq we choose double dot since single dot is already used by key names in some modules, and using \(dq:\(dq requires quoting in the YAML. .sp \fBExample:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C network..dns..servers: \- 10.0.0.1 \- 10.0.0.2 network..dns..options: \- timeout:2 \- attempts:1 \- ndots:1 network..dns..search: \- example.com .ft P .fi .UNINDENT .UNINDENT .sp \fBWould become:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C network: dns: servers: \- 10.0.0.1 \- 10.0.0.2 options: \- timeout:2 \- attempts:1 \- ndots:1 search: \- example.com .ft P .fi .UNINDENT .UNINDENT .SS Operators .sp Operators can be used to merge/unset a list/hash or set the key as immutable, so it can\(aqt be changed. .TS center; |l|l|. _ T{ Operator T} T{ Description T} _ T{ merge() T} T{ Merge list or hash T} _ T{ unset() T} T{ Unset key T} _ T{ immutable() T} T{ Set the key as immutable, so it can\(aqt be changed T} _ T{ imerge() T} T{ Set immutable and merge T} _ T{ iunset() T} T{ Set immutable and unset T} _ .TE .sp \fBExample:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C network..dns..search..merge(): \- foobar.com \- dummy.nl owner..immutable(): Operations host..printers..unset(): .ft P .fi .UNINDENT .UNINDENT .SS Validation .sp Since it\(aqs very hard to test Jinja as is, the best approach is to run all the permutations of input and validate the output, i.e. Unit Testing. .sp To facilitate this in Pepa we use YAML, Jinja and Cerberus <\fI\%https://github.com/nicolaiarocci/cerberus\fP>. .SS Schema .sp So this is a validation schema for network configuration, as you see it can be customized with Jinja just as Pepa templates. .sp This was designed to be run as a build job in Jenkins or similar tool. You can provide Grains/Pillar input using either the config file or command line arguments. .sp \fBFile Example: host/validation/network.yaml\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C network..dns..search: type: list allowed: \- example.com network..dns..options: type: list allowed: [\(aqtimeout:2\(aq, \(aqattempts:1\(aq, \(aqndots:1\(aq] network..dns..servers: type: list schema: regex: ^([0\-9]{1,3}\e.){3}[0\-9]{1,3}$ network..gateway: type: string regex: ^([0\-9]{1,3}\e.){3}[0\-9]{1,3}$ {% if network.interfaces is defined %} {% for interface in network.interfaces %} network..interfaces..{{ interface }}..dhcp: type: boolean network..interfaces..{{ interface }}..fqdn: type: string regex: ^([a\-z0\-9]([a\-z0\-9\-]{0,61}[a\-z0\-9])?\e.)+[a\-zA\-Z]{2,6}$ network..interfaces..{{ interface }}..hwaddr: type: string regex: ^([0\-9a\-f]{1,2}\e:){5}[0\-9a\-f]{1,2}$ network..interfaces..{{ interface }}..ipv4: type: string regex: ^([0\-9]{1,3}\e.){3}[0\-9]{1,3}$ network..interfaces..{{ interface }}..netmask: type: string regex: ^([0\-9]{1,3}\e.){3}[0\-9]{1,3}$ {% endfor %} {% endif %} .ft P .fi .UNINDENT .UNINDENT .SS Links .sp For more examples and information see <\fI\%https://github.com/mickep76/pepa\fP>. .INDENT 0.0 .TP .B salt.pillar.pepa.ext_pillar(minion_id, pillar, resource, sequence, subkey=False, subkey_only=False) Evaluate Pepa templates .UNINDENT .INDENT 0.0 .TP .B salt.pillar.pepa.key_value_to_tree(data) Convert key/value to tree .UNINDENT .INDENT 0.0 .TP .B salt.pillar.pepa.validate(output, resource) Validate Pepa templates .UNINDENT .SS salt.pillar.pillar_ldap .sp Use LDAP data as a Pillar source .sp This pillar module executes a series of LDAP searches. Data returned by these searches are aggregated, whereby data returned by later searches override data by previous searches with the same key. .sp The final result is merged with existing pillar data. .sp The configuration of this external pillar module is done via an external file which provides the actual configuration for the LDAP searches. .SS Configuring the LDAP ext_pillar .sp The basic configuration is part of the \fI\%master configuration\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- pillar_ldap: /etc/salt/master.d/pillar_ldap.yaml .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When placing the file in the \fBmaster.d\fP directory, make sure its name doesn\(aqt end in \fB\&.conf\fP, otherwise the salt\-master process will attempt to parse its content. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Make sure this file has very restrictive permissions, as it will contain possibly sensitive LDAP credentials! .UNINDENT .UNINDENT .sp The only required key in the master configuration is \fBpillar_ldap\fP pointing to a file containing the actual configuration. .SS Configuring the LDAP searches .sp The file is processed using \fISalt\(aqs Renderers <renderers>\fP which makes it possible to reference grains within the configuration. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 When using Jinja in this file, make sure to do it in a way which prevents leaking sensitive information. A rogue minion could send arbitrary grains to trick the master into returning secret data. Use only the \(aqid\(aq grain which is verified through the minion\(aqs key/cert. .UNINDENT .UNINDENT .SS Map Mode .sp The \fBit\-admins\fP configuration below returns the Pillar \fBit\-admins\fP by: .INDENT 0.0 .IP \(bu 2 filtering for: \- members of the group \fBit\-admins\fP \- objects with \fBobjectclass=user\fP .IP \(bu 2 returning the data of users, where each user is a dictionary containing the configured string or list attributes. .UNINDENT .SS Configuration .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-users: server: ldap.company.tld port: 389 tls: true dn: \(aqdc=company,dc=tld\(aq binddn: \(aqcn=salt\-pillars,ou=users,dc=company,dc=tld\(aq bindpw: bi7ieBai5Ano referrals: false anonymous: false mode: map dn: \(aqou=users,dc=company,dc=tld\(aq filter: \(aq(&(memberof=cn=it\-admins,ou=groups,dc=company,dc=tld)(objectclass=user))\(aq attrs: \- cn \- displayName \- givenName \- sn lists: \- memberOf search_order: \- salt\-users .ft P .fi .UNINDENT .UNINDENT .SS Result .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { \(aqsalt\-users\(aq: [ { \(aqcn\(aq: \(aqcn=johndoe,ou=users,dc=company,dc=tld\(aq, \(aqdisplayName\(aq: \(aqJohn Doe\(aq \(aqgivenName\(aq: \(aqJohn\(aq \(aqsn\(aq: \(aqDoe\(aq \(aqmemberOf\(aq: [ \(aqcn=it\-admins,ou=groups,dc=company,dc=tld\(aq, \(aqcn=team01,ou=groups,dc=company\(aq ] }, { \(aqcn\(aq: \(aqcn=janedoe,ou=users,dc=company,dc=tld\(aq, \(aqdisplayName\(aq: \(aqJane Doe\(aq, \(aqgivenName\(aq: \(aqJane\(aq, \(aqsn\(aq: \(aqDoe\(aq, \(aqmemberOf\(aq: [ \(aqcn=it\-admins,ou=groups,dc=company,dc=tld\(aq, \(aqcn=team02,ou=groups,dc=company\(aq ] } ] } .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.pillar_ldap.ext_pillar(minion_id, pillar, config_file) Execute LDAP searches and return the aggregated data .UNINDENT .SS salt.pillar.postgres .sp Retrieve Pillar data by doing a postgres query .sp New in version 2017.7.0. .INDENT 0.0 .TP .B maturity new .TP .B depends psycopg2 .TP .B platform all .UNINDENT .SS Complete Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C postgres: user: \(aqsalt\(aq pass: \(aqsuper_secret_password\(aq db: \(aqsalt_db\(aq ext_pillar: \- postgres: fromdb: query: \(aqSELECT col1,col2,col3,col4,col5,col6,col7 FROM some_random_table WHERE minion_pattern LIKE %s\(aq depth: 5 as_list: True with_lists: [1,3] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.pillar.postgres.POSTGRESExtPillar This class receives and processes the database rows from POSTGRES. .INDENT 7.0 .TP .B extract_queries(args, kwargs) This function normalizes the config block into a set of queries we can use. The return is a list of consistently laid out dicts. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.postgres.ext_pillar(minion_id, pillar, *args, **kwargs) Execute queries against POSTGRES, merge and return as a dict .UNINDENT .SS salt.pillar.puppet .sp Execute an unmodified puppet_node_classifier and read the output as YAML. The YAML data is then directly overlaid onto the minion\(aqs Pillar data. .INDENT 0.0 .TP .B salt.pillar.puppet.ext_pillar(minion_id, pillar, command) Execute an unmodified puppet_node_classifier and read the output as YAML .UNINDENT .SS salt.pillar.reclass_adapter .sp Use the \(dqreclass\(dq database as a Pillar source .sp This \fBext_pillar\fP plugin provides access to the \fBreclass\fP database, such that Pillar data for a specific minion are fetched using \fBreclass\fP\&. .sp You can find more information about \fBreclass\fP at \fI\%http://reclass.pantsfullofunix.net\fP\&. .sp To use the plugin, add it to the \fBext_pillar\fP list in the Salt master config and tell \fBreclass\fP by way of a few options how and where to find the inventory: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- reclass: storage_type: yaml_fs inventory_base_uri: /srv/salt .ft P .fi .UNINDENT .UNINDENT .sp This would cause \fBreclass\fP to read the inventory from YAML files in \fB/srv/salt/nodes\fP and \fB/srv/salt/classes\fP\&. .sp If you are also using \fBreclass\fP as \fBmaster_tops\fP plugin, and you want to avoid having to specify the same information for both, use YAML anchors (take note of the differing data types for \fBext_pillar\fP and \fBmaster_tops\fP): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reclass: &reclass storage_type: yaml_fs inventory_base_uri: /srv/salt reclass_source_path: ~/code/reclass ext_pillar: \- reclass: *reclass master_tops: reclass: *reclass .ft P .fi .UNINDENT .UNINDENT .sp If you want to run reclass from source, rather than installing it, you can either let the master know via the \fBPYTHONPATH\fP environment variable, or by setting the configuration option, like in the example above. .INDENT 0.0 .TP .B salt.pillar.reclass_adapter.ext_pillar(minion_id, pillar, **kwargs) Obtain the Pillar data from \fBreclass\fP for the given \fBminion_id\fP\&. .UNINDENT .SS salt.pillar.redismod .SS Read pillar data from a Redis backend .sp New in version 2014.7.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 redis Python module (on master) .UNINDENT .UNINDENT .SS Salt Master Redis Configuration .sp The module shares the same base Redis connection variables as \fI\%salt.returners.redis_return\fP\&. These variables go in your master config file. .INDENT 0.0 .IP \(bu 2 \fBredis.db\fP \- The Redis database to use. Defaults to \fB0\fP\&. .IP \(bu 2 \fBredis.host\fP \- The Redis host to connect to. Defaults to \fB\(aqsalt\(aq\fP\&. .IP \(bu 2 \fBredis.port\fP \- The port that the Redis database is listening on. Defaults to \fB6379\fP\&. .IP \(bu 2 \fBredis.password\fP \- The password for authenticating with Redis. Only required if you are using master auth. Defaults to \fBNone\fP\&. .UNINDENT .SS Configuring the Redis ext_pillar .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- redis: {function: key_value} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.redismod.ext_pillar(minion_id, pillar, function, **kwargs) Grabs external pillar data based on configured function .UNINDENT .INDENT 0.0 .TP .B salt.pillar.redismod.key_json(minion_id, pillar, pillar_key=None) Pulls a string from redis and deserializes it from json. Deserialized dictionary data loaded directly into top level if pillar_key is not set. .INDENT 7.0 .TP .B pillar_key Pillar key to return data into .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.redismod.key_value(minion_id, pillar, pillar_key=\(aqredis_pillar\(aq) Looks for key in redis matching minion_id, returns a structure based on the data type of the redis key. String for string type, dict for hash type and lists for lists, sets and sorted sets. .INDENT 7.0 .TP .B pillar_key Pillar key to return data into .UNINDENT .UNINDENT .SS salt.pillar.rethinkdb_pillar .sp Provide external pillar data from RethinkDB .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends rethinkdb (on the salt\-master) .UNINDENT .SS salt master rethinkdb configuration .INDENT 0.0 .TP .B These variables must be configured in your master configuration file. .INDENT 7.0 .IP \(bu 2 \fBrethinkdb.host\fP \- The RethinkDB server. Defaults to \fB\(aqsalt\(aq\fP .IP \(bu 2 \fBrethinkdb.port\fP \- The port the RethinkDB server listens on. Defaults to \fB\(aq28015\(aq\fP .IP \(bu 2 \fBrethinkdb.database\fP \- The database to connect to. Defaults to \fB\(aqsalt\(aq\fP .IP \(bu 2 \fBrethinkdb.username\fP \- The username for connecting to RethinkDB. Defaults to \fB\(aq\(aq\fP .IP \(bu 2 \fBrethinkdb.password\fP \- The password for connecting to RethinkDB. Defaults to \fB\(aq\(aq\fP .UNINDENT .UNINDENT .SS salt\-master ext_pillar configuration .sp The ext_pillar function arguments are given in single line dictionary notation. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- rethinkdb: {table: ext_pillar, id_field: minion_id, field: pillar_root, pillar_key: external_pillar} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B In the example above the following happens. .INDENT 7.0 .IP \(bu 2 The salt\-master will look for external pillars in the \(aqext_pillar\(aq table on the RethinkDB host .IP \(bu 2 The minion id will be matched against the \(aqminion_id\(aq field .IP \(bu 2 Pillars will be retrieved from the nested field \(aqpillar_root\(aq .IP \(bu 2 Found pillars will be merged inside a key called \(aqexternal_pillar\(aq .UNINDENT .UNINDENT .SS Module Documentation .INDENT 0.0 .TP .B salt.pillar.rethinkdb_pillar.ext_pillar(minion_id, pillar, table=\(aqpillar\(aq, id_field=None, field=None, pillar_key=None) Collect minion external pillars from a RethinkDB database .sp Arguments: .INDENT 7.0 .IP \(bu 2 \fItable\fP: The RethinkDB table containing external pillar information. Defaults to \fB\(aqpillar\(aq\fP .IP \(bu 2 \fIid_field\fP: Field in document containing the minion id. If blank then we assume the table index matches minion ids .IP \(bu 2 \fIfield\fP: Specific field in the document used for pillar data, if blank then the entire document will be used .IP \(bu 2 \fIpillar_key\fP: The salt\-master will nest found external pillars under this key before merging into the minion pillars. If blank, external pillars will be merged at top level .UNINDENT .UNINDENT .SS salt.pillar.s3 .sp Copy pillar data from a bucket in Amazon S3 .sp The S3 pillar can be configured in the master config file with the following options .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- s3: bucket: my.fancy.pillar.bucket keyid: KASKFJWAKJASJKDAJKSD key: ksladfDLKDALSFKSD93q032sdDasdfasdflsadkf multiple_env: False environment: base prefix: somewhere/overthere verify_ssl: True service_url: s3.amazonaws.com kms_keyid: 01234567\-89ab\-cdef\-0123\-4567890abcde s3_cache_expire: 30 s3_sync_on_update: True path_style: False https_enable: True .ft P .fi .UNINDENT .UNINDENT .sp The \fBbucket\fP parameter specifies the target S3 bucket. It is required. .sp The \fBkeyid\fP parameter specifies the key id to use when access the S3 bucket. If it is not provided, an attempt to fetch it from EC2 instance meta\-data will be made. .sp The \fBkey\fP parameter specifies the key to use when access the S3 bucket. If it is not provided, an attempt to fetch it from EC2 instance meta\-data will be made. .sp The \fBmultiple_env\fP defaults to False. It specifies whether the pillar should interpret top level folders as pillar environments (see mode section below). .sp The \fBenvironment\fP defaults to \(aqbase\(aq. It specifies which environment the bucket represents when in single environments mode (see mode section below). It is ignored if multiple_env is True. .sp The \fBprefix\fP defaults to \(aq\(aq. It specifies a key prefix to use when searching for data in the bucket for the pillar. It works when multiple_env is True or False. Essentially it tells ext_pillar to look for your pillar data in a \(aqsubdirectory\(aq of your S3 bucket .sp The \fBverify_ssl\fP parameter defaults to True. It specifies whether to check for valid S3 SSL certificates. \fINOTE\fP If you use bucket names with periods, this must be set to False else an invalid certificate error will be thrown (issue #12200). .sp The \fBservice_url\fP parameter defaults to \(aqs3.amazonaws.com\(aq. It specifies the base url to use for accessing S3. .sp The \fBkms_keyid\fP parameter is optional. It specifies the ID of the Key Management Service (KMS) master key that was used to encrypt the object. .sp The \fBs3_cache_expire\fP parameter defaults to 30s. It specifies expiration time of S3 metadata cache file. .sp The \fBs3_sync_on_update\fP parameter defaults to True. It specifies if cache is synced on update rather than jit. .sp The \fBpath_style\fP parameter defaults to False. It specifies whether to use path style requests or dns style requests .sp The \fBhttps_enable\fP parameter defaults to True. It specifies whether to use https protocol or http protocol .sp This pillar can operate in two modes, single environment per bucket or multiple environments per bucket. .sp Single environment mode must have this bucket structure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s3://<bucket name>/<prefix>/<files> .ft P .fi .UNINDENT .UNINDENT .sp Multiple environment mode must have this bucket structure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s3://<bucket name>/<prefix>/<environment>/<files> .ft P .fi .UNINDENT .UNINDENT .sp If you wish to define your pillar data entirely within S3 it\(aqs recommended that you use the \fIprefix=\fP parameter and specify one entry in ext_pillar for each environment rather than specifying multiple_env. This is due to issue #22471 (\fI\%https://github.com/saltstack/salt/issues/22471\fP) .INDENT 0.0 .TP .B class salt.pillar.s3.S3Credentials(key, keyid, bucket, service_url, verify_ssl=True, kms_keyid=None, location=None, path_style=False, https_enable=True) .UNINDENT .INDENT 0.0 .TP .B salt.pillar.s3.ext_pillar(minion_id, pillar, bucket, key=None, keyid=None, verify_ssl=True, location=None, multiple_env=False, environment=\(aqbase\(aq, prefix=\(aq\(aq, service_url=None, kms_keyid=None, s3_cache_expire=30, s3_sync_on_update=True, path_style=False, https_enable=True) Execute a command and read the output as YAML .UNINDENT .SS salt.pillar.saltclass .SS SaltClass Pillar Module .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- saltclass: \- path: /srv/saltclass .ft P .fi .UNINDENT .UNINDENT .sp For additional configuration instructions, see the \fI\%saltclass\fP module .INDENT 0.0 .TP .B salt.pillar.saltclass.ext_pillar(minion_id, pillar, *args, **kwargs) Compile pillar data .UNINDENT .SS salt.pillar.sql_base .sp Retrieve Pillar data by doing a SQL query .sp This module is not meant to be used directly as an ext_pillar. It is a place to put code common to PEP 249 compliant SQL database adapters. It exposes a python ABC that can be subclassed for new database providers. .INDENT 0.0 .TP .B maturity new .TP .B platform all .UNINDENT .SS Theory of sql_base ext_pillar .sp Ok, here\(aqs the theory for how this works... .INDENT 0.0 .IP \(bu 2 First, any non\-keyword args are processed in order. .IP \(bu 2 Then, remaining keywords are processed. .UNINDENT .sp We do this so that it\(aqs backward compatible with older configs. Keyword arguments are sorted before being appended, so that they\(aqre predictable, but they will always be applied last so overall it\(aqs moot. .sp For each of those items we process, it depends on the object type: .INDENT 0.0 .IP \(bu 2 Strings are executed as is and the pillar depth is determined by the number of fields returned. .IP \(bu 2 A list has the first entry used as the query, the second as the pillar depth. .IP \(bu 2 A mapping uses the keys \(dqquery\(dq and \(dqdepth\(dq as the tuple .UNINDENT .sp You can retrieve as many fields as you like, how they get used depends on the exact settings. .SS Configuring a sql_base ext_pillar .sp The sql_base ext_pillar cannot be used directly, but shares query configuration with its implementations. These examples use a fake \(aqsql_base\(aq adapter, which should be replaced with the name of the adapter you are using. .sp A list of queries can be passed in .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- sql_base: \- \(dqSELECT pillar,value FROM pillars WHERE minion_id = %s\(dq \- \(dqSELECT pillar,value FROM more_pillars WHERE minion_id = %s\(dq .ft P .fi .UNINDENT .UNINDENT .sp Or you can pass in a mapping .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- sql_base: main: \(dqSELECT pillar,value FROM pillars WHERE minion_id = %s\(dq extras: \(dqSELECT pillar,value FROM more_pillars WHERE minion_id = %s\(dq .ft P .fi .UNINDENT .UNINDENT .sp The query can be provided as a string as we have just shown, but they can be provided as lists .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- sql_base: \- \(dqSELECT pillar,value FROM pillars WHERE minion_id = %s\(dq 2 .ft P .fi .UNINDENT .UNINDENT .sp Or as a mapping .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- sql_base: \- query: \(dqSELECT pillar,value FROM pillars WHERE minion_id = %s\(dq depth: 2 .ft P .fi .UNINDENT .UNINDENT .sp The depth defines how the dicts are constructed. Essentially if you query for fields a,b,c,d for each row you\(aqll get: .INDENT 0.0 .IP \(bu 2 With depth 1: {a: {\(dqb\(dq: b, \(dqc\(dq: c, \(dqd\(dq: d}} .IP \(bu 2 With depth 2: {a: {b: {\(dqc\(dq: c, \(dqd\(dq: d}}} .IP \(bu 2 With depth 3: {a: {b: {c: d}}} .UNINDENT .sp Depth greater than 3 wouldn\(aqt be different from 3 itself. Depth of 0 translates to the largest depth needed, so 3 in this case. (max depth == key count \- 1) .sp Then they are merged in a similar way to plain pillar data, in the order returned by the SQL database. .sp Thus subsequent results overwrite previous ones when they collide. .sp The ignore_null option can be used to change the overwrite behavior so that only non\-NULL values in subsequent results will overwrite. This can be used to selectively overwrite default values. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- sql_base: \- query: \(dqSELECT pillar,value FROM pillars WHERE minion_id = \(aqdefault\(aq and minion_id != %s\(dq depth: 2 \- query: \(dqSELECT pillar,value FROM pillars WHERE minion_id = %s\(dq depth: 2 ignore_null: True .ft P .fi .UNINDENT .UNINDENT .sp If you specify \fIas_list: True\fP in the mapping expression it will convert collisions to lists. .sp If you specify \fIwith_lists: \(aq...\(aq\fP in the mapping expression it will convert the specified depths to list. The string provided is a sequence numbers that are comma separated. The string \(aq1,3\(aq will result in: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C a,b,c,d,e,1 # field 1 same, field 3 differs a,b,c,f,g,2 # ^^^^ a,z,h,y,j,3 # field 1 same, field 3 same a,z,h,y,k,4 # ^^^^ ^ ^ .ft P .fi .UNINDENT .UNINDENT .sp These columns define list grouping .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {a: [ {c: [ {e: 1}, {g: 2} ] }, {h: [ {j: 3, k: 4 } ] } ]} .ft P .fi .UNINDENT .UNINDENT .sp The range for with_lists is 1 to number_of_fields, inclusive. Numbers outside this range are ignored. .sp If you specify \fIas_json: True\fP in the mapping expression and query only for single value, returned data are considered in JSON format and will be merged directly. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- sql_base: \- query: \(dqSELECT json_pillar FROM pillars WHERE minion_id = %s\(dq as_json: True .ft P .fi .UNINDENT .UNINDENT .sp The processed JSON entries are recursively merged in a single dictionary. Additionnaly if \fIas_list\fP is set to \fITrue\fP the lists will be merged in case of collision. .sp For instance the following rows: .INDENT 0.0 .INDENT 3.5 {\(dqa\(dq: {\(dqb\(dq: [1, 2]}, \(dqc\(dq: 3} {\(dqa\(dq: {\(dqb\(dq: [1, 3]}, \(dqd\(dq: 4} .UNINDENT .UNINDENT .sp will result in the following pillar with \fIas_list=False\fP .INDENT 0.0 .INDENT 3.5 {\(dqa\(dq: {\(dqb\(dq: [1, 3], \(dqc\(dq: 3, \(dqd\(dq: 4} .UNINDENT .UNINDENT .sp and in with \fIas_list=True\fP .INDENT 0.0 .INDENT 3.5 {\(dqa\(dq: {\(dqb\(dq: [1, 2, 3], \(dqc\(dq: 3, \(dqd\(dq: 4} .UNINDENT .UNINDENT .sp Finally, if you pass the queries in via a mapping, the key will be the first level name where as passing them in as a list will place them in the root. This isolates the query results into their own subtrees. This may be a help or hindrance to your aims and can be used as such. .sp You can basically use any SELECT query that gets you the information, you could even do joins or subqueries in case your minion_id is stored elsewhere. It is capable of handling single rows or multiple rows per minion. .sp Configuration of the connection depends on the adapter in use. .sp New in version 3005: The \fIas_json\fP parameter. .SS More complete example for MySQL (to also show configuration) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql: user: \(aqsalt\(aq pass: \(aqsuper_secret_password\(aq db: \(aqsalt_db\(aq ext_pillar: \- mysql: fromdb: query: \(aqSELECT col1,col2,col3,col4,col5,col6,col7 FROM some_random_table WHERE minion_pattern LIKE %s\(aq depth: 5 as_list: True with_lists: [1,3] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.pillar.sql_base.SqlBaseExtPillar This class receives and processes the database rows in a database agnostic way. .INDENT 7.0 .TP .B as_json = False .UNINDENT .INDENT 7.0 .TP .B as_list = False .UNINDENT .INDENT 7.0 .TP .B depth = 0 .UNINDENT .INDENT 7.0 .TP .B enter_root(root) Set self.focus for kwarg queries .UNINDENT .INDENT 7.0 .TP .B extract_queries(args, kwargs) This function normalizes the config block into a set of queries we can use. The return is a list of consistently laid out dicts. .UNINDENT .INDENT 7.0 .TP .B fetch(minion_id, pillar, *args, **kwargs) Execute queries, merge and return as a dict. .UNINDENT .INDENT 7.0 .TP .B field_names = None .UNINDENT .INDENT 7.0 .TP .B focus = None .UNINDENT .INDENT 7.0 .TP .B ignore_null = False .UNINDENT .INDENT 7.0 .TP .B num_fields = 0 .UNINDENT .INDENT 7.0 .TP .B process_fields(field_names, depth) The primary purpose of this function is to store the sql field list and the depth to which we process. .UNINDENT .INDENT 7.0 .TP .B process_results(rows) This function takes a list of database results and iterates over, merging them into a dict form. .UNINDENT .INDENT 7.0 .TP .B result = None .UNINDENT .INDENT 7.0 .TP .B with_lists = None .UNINDENT .UNINDENT .SS salt.pillar.sqlcipher .sp Retrieve Pillar data by running a SQLCipher query .sp New in version 2016.3.0. .sp Python SQLCipher support is provided by the pysqlcipher Python package. You need this module installed to query Pillar data from a SQLCipher database. .sp This module is a concrete implementation of the sql_base ext_pillar for SQLCipher. .INDENT 0.0 .TP .B maturity new .TP .B depends pysqlcipher (for py2) or pysqlcipher3 (for py3) .TP .B platform all .UNINDENT .SS Configuring the sqlcipher ext_pillar .sp Use the \(aqsqlcipher\(aq key under ext_pillar for configuration of queries. .sp SQLCipher database connection configuration requires the following values configured in the master config: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBsqlcipher.database\fP \- The SQLCipher database to connect to. Defaults to \fB\(aq/var/lib/salt/pillar\-sqlcipher.db\(aq\fP\&. .IP \(bu 2 \fBsqlcipher.pass\fP \- The SQLCipher database decryption password. .IP \(bu 2 \fBsqlcipher.timeout\fP \- The connection timeout in seconds. .UNINDENT .UNINDENT .UNINDENT .sp Example configuration .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sqlcipher: database: /var/lib/salt/pillar\-sqlcipher.db pass: strong_pass_phrase timeout: 5.0 .ft P .fi .UNINDENT .UNINDENT .SS Complete Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sqlcipher: database: \(aq/var/lib/salt/pillar\-sqlcipher.db\(aq pass: strong_pass_phrase timeout: 5.0 ext_pillar: \- sqlcipher: fromdb: query: \(aqSELECT col1,col2,col3,col4,col5,col6,col7 FROM some_random_table WHERE minion_pattern LIKE ?\(aq depth: 5 as_list: True with_lists: [1,3] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.pillar.sqlcipher.SQLCipherExtPillar This class receives and processes the database rows from SQLCipher. .UNINDENT .INDENT 0.0 .TP .B salt.pillar.sqlcipher.ext_pillar(minion_id, pillar, *args, **kwargs) Execute queries against SQLCipher, merge and return as a dict .UNINDENT .SS salt.pillar.sqlite3 .sp Retrieve Pillar data by doing a SQLite3 query .sp New in version 2015.8.0. .sp \fBsqlite3\fP is included in the stdlib since Python 2.5. .sp This module is a concrete implementation of the sql_base ext_pillar for SQLite3. .INDENT 0.0 .TP .B platform all .UNINDENT .SS Configuring the sqlite3 ext_pillar .sp Use the \(aqsqlite3\(aq key under ext_pillar for configuration of queries. .sp SQLite3 database connection configuration requires the following values configured in the master config: .sp Note, timeout is in seconds. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sqlite3.database: /var/lib/salt/pillar.db sqlite3.timeout: 5.0 .ft P .fi .UNINDENT .UNINDENT .SS Complete Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sqlite3: database: \(aq/var/lib/salt/pillar.db\(aq timeout: 5.0 ext_pillar: \- sqlite3: fromdb: query: \(aqSELECT col1,col2,col3,col4,col5,col6,col7 FROM some_random_table WHERE minion_pattern LIKE ?\(aq depth: 5 as_list: True with_lists: [1,3] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.pillar.sqlite3.SQLite3ExtPillar This class receives and processes the database rows from SQLite3. .UNINDENT .INDENT 0.0 .TP .B salt.pillar.sqlite3.ext_pillar(minion_id, pillar, *args, **kwargs) Execute queries against SQLite3, merge and return as a dict .UNINDENT .SS salt.pillar.stack .sp Simple and flexible YAML ext_pillar which can read pillar from within pillar. .sp New in version 2016.3.0. .sp \fI\%PillarStack\fP is a custom saltstack \fBext_pillar\fP which was inspired by \fI\%varstack\fP but is heavily based on Jinja2 for maximum flexibility. .sp It supports the following features: .INDENT 0.0 .IP \(bu 2 multiple config files that are jinja2 templates with support for \fBpillar\fP, \fB__grains__\fP, \fB__salt__\fP, \fB__opts__\fP objects and \fBpillarenv\fP .IP \(bu 2 a config file renders as an ordered list of files (paths of these files are relative to the current config file) .IP \(bu 2 this list of files are read in ordered as jinja2 templates with support for \fBstack\fP, \fBpillar\fP, \fB__grains__\fP, \fB__salt__\fP, \fB__opts__\fP objects and \fBpillarenv\fP .IP \(bu 2 all these rendered files are then parsed as \fByaml\fP .IP \(bu 2 then all yaml dicts are merged in order with support for the following merging strategies: \fBmerge\-first\fP, \fBmerge\-last\fP, \fBremove\fP, and \fBoverwrite\fP .IP \(bu 2 stack config files can be matched based on \fBpillar\fP, \fBgrains\fP, or \fBopts\fP values, which make it possible to support kind of self\-contained environments .UNINDENT .SS Installation .sp PillarStack is already bundled with Salt since 2016.3.0 version so there is nothing to install from version 2016.3.0. .sp If you use an older Salt version or you want to override PillarStack with a more recent one, follow the installation procedure below. .sp Installing the PillarStack \fBext_pillar\fP is as simple as dropping the \fBstack.py\fP file in the \fB<extension_modules>/pillar\fP directory (no external python module required), given that \fBextension_modules\fP is set in your salt\-master configuration, see: \fI\%https://docs.saltproject.io/en/latest/ref/configuration/master.html#extension\-modules\fP .SS Configuration in Salt .sp Like any other external pillar, its configuration takes place through the \fBext_pillar\fP key in the master config file. .sp However, you can configure PillarStack in 3 different ways: .SS Single config file .sp This is the simplest option, you just need to set the path to your single PillarStack config file like below: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- stack: /path/to/stack.cfg .ft P .fi .UNINDENT .UNINDENT .SS List of config files .sp You can also provide a list of config files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- stack: \- /path/to/stack1.cfg \- /path/to/stack2.cfg .ft P .fi .UNINDENT .UNINDENT .SS Select config files through grains|pillar|opts matching .sp You can also opt for a much more flexible configuration: PillarStack allows one to select the config files for the current minion based on matching values from either grains, or pillar, or opts objects. .sp Here is an example of such a configuration, which should speak by itself: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- stack: pillar:something: bar: /path/to/bar/stack.cfg foo: /path/to/foo/stack.cfg grains:custom:grain: value: \- /path/to/stack1.cfg \- /path/to/stack2.cfg opts:custom:opt: value: /path/to/stack0.cfg opts:saltenv: dev: /path/to/dev/stack.cfg __env__: /path/to/__env__/stack.cfg .ft P .fi .UNINDENT .UNINDENT .SS PillarStack configuration files .sp The config files that are referenced in the above \fBext_pillar\fP configuration are jinja2 templates which must render as a simple ordered list of \fByaml\fP files that will then be merged to build pillar data. .sp The path of these \fByaml\fP files must be relative to the directory of the PillarStack config file. These paths support unix style pathname pattern expansion through the \fIPython glob module <https://docs.python.org/2/library/glob.html>\fP\&. .sp The following variables are available in jinja2 templating of PillarStack configuration files: .INDENT 0.0 .IP \(bu 2 \fBpillar\fP: the pillar data (as passed by Salt to our \fBext_pillar\fP function) .IP \(bu 2 \fBminion_id\fP: the minion id ;\-) .IP \(bu 2 \fB__opts__\fP: a dictionary of mostly Salt configuration options .IP \(bu 2 \fB__grains__\fP: a dictionary of the grains of the minion making this pillar call .IP \(bu 2 \fB__salt__\fP: a dictionary of Salt module functions, useful so you don\(aqt have to duplicate functions that already exist (note: runs on the master) .UNINDENT .sp So you can use all the power of jinja2 to build your list of \fByaml\fP files that will be merged in pillar data. .sp For example, you could have a PillarStack config file which looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ cat /path/to/stack/config.cfg core.yml common/*.yml osarchs/{{ __grains__[\(aqosarch\(aq] }}.yml oscodenames/{{ __grains__[\(aqoscodename\(aq] }}.yml {%\- for role in pillar.get(\(aqroles\(aq, []) %} roles/{{ role }}.yml {%\- endfor %} minions/{{ minion_id }}.yml .ft P .fi .UNINDENT .UNINDENT .sp And the whole directory structure could look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ tree /path/to/stack/ /path/to/stack/ ├── config.cfg ├── core.yml ├── common/ │\ \ ├── xxx.yml │\ \ └── yyy.yml ├── osarchs/ │\ \ ├── amd64.yml │\ \ └── armhf.yml ├── oscodenames/ │\ \ ├── wheezy.yml │\ \ └── jessie.yml ├── roles/ │\ \ ├── web.yml │\ \ └── db.yml └── minions/ ├── test\-1\-dev.yml └── test\-2\-dev.yml .ft P .fi .UNINDENT .UNINDENT .SS Overall process .sp In the above PillarStack configuration, given that test\-1\-dev minion is an amd64 platform running Debian Jessie, and which pillar \fBroles\fP is \fB[\(dqdb\(dq]\fP, the following \fByaml\fP files would be merged in order: .INDENT 0.0 .IP \(bu 2 \fBcore.yml\fP .IP \(bu 2 \fBcommon/xxx.yml\fP .IP \(bu 2 \fBcommon/yyy.yml\fP .IP \(bu 2 \fBosarchs/amd64.yml\fP .IP \(bu 2 \fBoscodenames/jessie.yml\fP .IP \(bu 2 \fBroles/db.yml\fP .IP \(bu 2 \fBminions/test\-1\-dev.yml\fP .UNINDENT .sp Before merging, every files above will be preprocessed as Jinja2 templates. The following variables are available in Jinja2 templating of \fByaml\fP files: .INDENT 0.0 .IP \(bu 2 \fBstack\fP: the PillarStack pillar data object that has currently been merged (data from previous \fByaml\fP files in PillarStack configuration) .IP \(bu 2 \fBpillar\fP: the pillar data (as passed by Salt to our \fBext_pillar\fP function) .IP \(bu 2 \fBminion_id\fP: the minion id ;\-) .IP \(bu 2 \fB__opts__\fP: a dictionary of mostly Salt configuration options .IP \(bu 2 \fB__grains__\fP: a dictionary of the grains of the minion making this pillar call .IP \(bu 2 \fB__salt__\fP: a dictionary of Salt module functions, useful so you don\(aqt have to duplicate functions that already exist (note: runs on the master) .UNINDENT .sp So you can use all the power of jinja2 to build your pillar data, and even use other pillar values that has already been merged by PillarStack (from previous \fByaml\fP files in PillarStack configuration) through the \fBstack\fP variable. .sp Once a \fByaml\fP file has been preprocessed by Jinja2, we obtain a Python dict \- let\(aqs call it \fByml_data\fP \- then, PillarStack will merge this \fByml_data\fP dict in the main \fBstack\fP dict (which contains already merged PillarStack pillar data). By default, PillarStack will deeply merge \fByml_data\fP in \fBstack\fP (similarly to the \fBrecurse\fP salt \fBpillar_source_merging_strategy\fP), but 3 merging strategies are currently available for you to choose (see next section). .sp Once every \fByaml\fP files have been processed, the \fBstack\fP dict will contain your whole own pillar data, merged in order by PillarStack. So PillarStack \fBext_pillar\fP returns the \fBstack\fP dict, the contents of which Salt takes care to merge in with all of the other pillars and finally return the whole pillar to the minion. .SS Merging strategies .sp The way the data from a new \fByaml_data\fP dict is merged with the existing \fBstack\fP data can be controlled by specifying a merging strategy. Right now this strategy can either be \fBmerge\-last\fP (the default), \fBmerge\-first\fP, \fBremove\fP, or \fBoverwrite\fP\&. .sp Note that scalar values like strings, integers, booleans, etc. are always evaluated using the \fBoverwrite\fP strategy (other strategies don\(aqt make sense in that case). .sp The merging strategy can be set by including a dict in the form of: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __: <merging strategy> .ft P .fi .UNINDENT .UNINDENT .sp as the first item of the dict or list. This allows fine grained control over the merging process. .SS \fBmerge\-last\fP (default) strategy .sp If the \fBmerge\-last\fP strategy is selected (the default), then content of dict or list variables is merged recursively with previous definitions of this variable (similarly to the \fBrecurse\fP salt \fBpillar_source_merging_strategy\fP). This allows for extending previously defined data. .SS \fBmerge\-first\fP strategy .sp If the \fBmerge\-first\fP strategy is selected, then the content of dict or list variables are swapped between the \fByaml_data\fP and \fBstack\fP objects before being merged recursively with the \fBmerge\-last\fP previous strategy. .SS \fBremove\fP strategy .sp If the \fBremove\fP strategy is selected, then content of dict or list variables in \fBstack\fP are removed only if the corresponding item is present in the \fByaml_data\fP dict. This allows for removing items from previously defined data. .SS \fBoverwrite\fP strategy .sp If the \fBoverwrite\fP strategy is selected, then the content of dict or list variables in \fBstack\fP is overwritten by the content of \fByaml_data\fP dict. So this allows one to overwrite variables from previous definitions. .SS Merging examples .sp Let\(aqs go through small examples that should clarify what\(aqs going on when a \fByaml_data\fP dict is merged in the \fBstack\fP dict. .sp When you don\(aqt specify any strategy, the default \fBmerge\-last\fP strategy is selected: .TS center; |l|l|l|. _ T{ \fBstack\fP T} T{ \fByaml_data\fP T} T{ \fBstack\fP (after merge) T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 500 roles: \- sysadmin root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 1000 roles: \- developer mat: uid: 1001 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 1000 roles: \- sysadmin \- developer mat: uid: 1001 root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} _ .TE .sp Then you can select a custom merging strategy using the \fB__\fP key in a dict: .TS center; |l|l|l|. _ T{ \fBstack\fP T} T{ \fByaml_data\fP T} T{ \fBstack\fP (after merge) T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 500 roles: \- sysadmin root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: __: merge\-last tom: uid: 1000 roles: \- developer mat: uid: 1001 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 1000 roles: \- sysadmin \- developer mat: uid: 1001 root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 500 roles: \- sysadmin root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: __: merge\-first tom: uid: 1000 roles: \- developer mat: uid: 1001 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 500 roles: \- developer \- sysadmin mat: uid: 1001 root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 500 roles: \- sysadmin root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: __: remove tom: mat: .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 500 roles: \- sysadmin root: uid: 0 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: __: overwrite tom: uid: 1000 roles: \- developer mat: uid: 1001 .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: tom: uid: 1000 roles: \- developer mat: uid: 1001 .ft P .fi .UNINDENT .UNINDENT T} _ .TE .sp You can also select a custom merging strategy using a \fB__\fP object in a list: .TS center; |l|l|l|. _ T{ \fBstack\fP T} T{ \fByaml_data\fP T} T{ \fBstack\fP (after merge) T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- tom \- root .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- __: merge\-last \- mat .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- tom \- root \- mat .ft P .fi .UNINDENT .UNINDENT T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- tom \- root .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- __: merge\-first \- mat .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- mat \- tom \- root .ft P .fi .UNINDENT .UNINDENT T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- tom \- root .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- __: remove \- mat \- tom .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- root .ft P .fi .UNINDENT .UNINDENT T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- tom \- root .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- __: overwrite \- mat .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: \- mat .ft P .fi .UNINDENT .UNINDENT T} _ .TE .INDENT 0.0 .TP .B salt.pillar.stack.ext_pillar(minion_id, pillar, *args, **kwargs) Builds stacked pillar from yaml files listed in file(s). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBminion_id\fP (\fI\%str\fP) \-\- Minion ID .IP \(bu 2 \fBpillar\fP (\fI\%dict\fP) \-\- pillar .IP \(bu 2 \fBargs\fP (\fI\%list\fP) \-\- (Optional) file(s) that list yaml files .IP \(bu 2 \fBkwargs\fP (\fI\%dict\fP) \-\- (Optional) conditional file(s) that list yaml files .UNINDENT .UNINDENT .UNINDENT .SS salt.pillar.svn_pillar .sp Clone a remote SVN repository and use the filesystem as a Pillar source .sp This external Pillar source can be configured in the master config file like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- svn: trunk svn://svnserver/repo root=subdirectory .ft P .fi .UNINDENT .UNINDENT .sp The \fIroot=\fP parameter is optional and used to set the subdirectory from where to look for Pillar files (such as \fBtop.sls\fP). .sp Changed in version 2014.7.0: The optional \fBroot\fP parameter will be added. .sp Note that this is not the same thing as configuring pillar data using the \fI\%pillar_roots\fP parameter. The branch referenced in the \fI\%ext_pillar\fP entry above (\fBmaster\fP), would evaluate to the \fBbase\fP environment, so this branch needs to contain a \fBtop.sls\fP with a \fBbase\fP section in it, like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- foo .ft P .fi .UNINDENT .UNINDENT .sp To use other environments from the same SVN repo as svn_pillar sources, just add additional lines, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- svn: trunk svn://svnserver/repo \- svn: dev svn://svnserver/repo .ft P .fi .UNINDENT .UNINDENT .sp In this case, the \fBdev\fP branch would need its own \fBtop.sls\fP with a \fBdev\fP section in it, like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C dev: \(aq*\(aq: \- bar .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.pillar.svn_pillar.SvnPillar(branch, repo_location, root, opts) Deal with the remote SVN repository for Pillar .INDENT 7.0 .TP .B pillar_dir() Returns the directory of the pillars (repo cache + branch + root) .UNINDENT .INDENT 7.0 .TP .B update() .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.svn_pillar.ext_pillar(minion_id, pillar, repo_string) Execute a command and read the output as YAML .UNINDENT .SS salt.pillar.varstack_pillar .sp Use \fI\%Varstack\fP data as a Pillar source .SS Configuring Varstack .sp Using varstack in Salt is fairly simple. Just put the following into the config file of your master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- varstack: /etc/varstack.yaml .ft P .fi .UNINDENT .UNINDENT .sp Varstack will then use /etc/varstack.yaml to determine which configuration data to return as pillar information. From there you can take a look at the \fI\%README\fP of varstack on how this file is evaluated. .INDENT 0.0 .TP .B salt.pillar.varstack_pillar.ext_pillar(minion_id, pillar, conf) Parse varstack data and return the result .UNINDENT .SS salt.pillar.vault .sp Vault Pillar Module .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity New .TP .B platform all .UNINDENT .sp New in version 2016.11.0. .sp This module allows pillar data to be stored in Hashicorp Vault. .sp Base configuration instructions are documented in the \fI\%execution module docs\fP\&. Below are noted extra configuration required for the pillar module, but the base configuration must also be completed. .sp After the base Vault configuration is created, add the configuration below to the ext_pillar section in the Salt master configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- vault: path=secret/salt .ft P .fi .UNINDENT .UNINDENT .sp Each key needs to have all the key\-value pairs with the names you require. Avoid naming every key \(aqpassword\(aq as they will collide. .sp If you want to nest results under a nesting_key name use the following format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- vault: conf: path=secret/salt nesting_key: vault_key_name .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ vault write secret/salt auth=my_password master=127.0.0.1 .ft P .fi .UNINDENT .UNINDENT .sp The above will result in two pillars being available, \fBauth\fP and \fBmaster\fP\&. .sp You can then use normal pillar requests to get each key pair directly from pillar root. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-ssh \(aq*\(aq pillar.get auth .ft P .fi .UNINDENT .UNINDENT .sp Multiple Vault sources may also be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- vault: path=secret/salt \- vault: path=secret/root \- vault: path=secret/minions/{minion}/pass \- vault: path=secret/roles/{pillar[roles]}/pass .ft P .fi .UNINDENT .UNINDENT .sp You can also use nesting here as well. Identical nesting keys will get merged. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- vault: conf: path=secret/salt nesting_key: keyname1 \- vault: conf: path=secret/root nesting_key: keyname1 \- vault: conf: path=secret/minions/{minion}/pass nesting_key: keyname2 .ft P .fi .UNINDENT .UNINDENT .sp The difference between the return with and without the nesting key is shown below. This example takes the key value pairs returned from vault as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C path=secret/salt Key Value \-\-\- \-\-\-\-\- salt\-passwd badpasswd1 path=secret/root Key Value \-\-\- \-\-\-\-\- root\-passwd rootbadpasswd1 path=secret/minions/{minion}/pass Key Value \-\-\- \-\-\-\-\- minion\-passwd minionbadpasswd1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #Nesting Key not defined local: \-\-\-\-\-\-\-\-\-\- salt\-passwd: badpasswd1 root\-passwd: rootbadpasswd1 minion\-passwd: minionbadpasswd1 #Nesting Key defined local: \-\-\-\-\-\-\-\-\-\- keyname1: \-\-\-\-\-\-\-\-\-\- salt\-passwd: badpasswd1 root\-passwd: rootbadpasswd1 keyname2: \-\-\-\-\-\-\-\-\-\- minion\-passwd: minionbadpasswd1 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3006.0: Pillar values from previously rendered pillars can be used to template vault ext_pillar paths. .sp Using pillar values to template vault pillar paths requires them to be defined before the vault ext_pillar is called. Especially consider the significancy of \fI\%ext_pillar_first\fP master config setting. You cannot use pillar values sourced from Vault in pillar\-templated policies. .sp If a pillar pattern matches multiple paths, the results are merged according to the master configuration values \fI\%pillar_source_merging_strategy\fP and \fI\%pillar_merge_lists\fP by default. .sp If the optional nesting_key was defined, the merged result will be nested below. There is currently no way to nest multiple results under different keys. .sp You can override the merging behavior per defined ext_pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- vault: conf: path=secret/roles/{pillar[roles]} merge_strategy: smart merge_lists: false .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.vault.ext_pillar(minion_id, pillar, conf, nesting_key=None, merge_strategy=None, merge_lists=None, extra_minion_data=None) Get pillar data from Vault for the configuration \fBconf\fP\&. .UNINDENT .SS salt.pillar.venafi .sp Venafi Pillar Certificates .sp This module will only return pillar data if the \fBvenafi\fP runner module has already been used to create certificates. .sp To configure this module, set \fBvenafi\fP to \fBTrue\fP in the \fBext_pillar\fP section of your \fBmaster\fP configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- venafi: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.venafi.ext_pillar(minion_id, pillar, conf) Return an existing set of certificates .UNINDENT .SS salt.pillar.virtkey .sp Accept a key from a hypervisor if the virt runner has already submitted an authorization request .INDENT 0.0 .TP .B salt.pillar.virtkey.ext_pillar(hyper_id, pillar, name, key) Accept the key for the VM on the hyper, if authorized. .UNINDENT .SS salt.pillar.vmware_pillar .sp Pillar data from vCenter or an ESXi host .sp New in version 2017.7.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 pyVmomi .UNINDENT .UNINDENT .sp This external pillar can pull attributes from objects in vCenter or an ESXi host and provide those attributes as pillar data to minions. This can allow for pillar based targeting of minions on ESXi host, Datastore, VM configuration, etc. This setup requires only the salt master have access to the vCenter server/ESXi hosts. .sp The pillar will return an empty dict if the \(aqos\(aq or \(aqvirtual\(aq grain are not \(aqVMWare\(aq, \(aqESXi\(aq, or \(aqVMWare ESXi\(aq. .SS Defaults .INDENT 0.0 .IP \(bu 2 The external pillar will search for Virtual Machines with the VM name matching the minion id. .IP \(bu 2 Data will be returned into the \(aqvmware\(aq pillar key. .IP \(bu 2 The external pillar has a default set of properties to return for both VirtualMachine and HostSystem types. .UNINDENT .SS Configuring the VMWare pillar .sp The required minimal configuration in the salt master ext_pillar setup: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- vmware: host: <vcenter/esx host> username: <user to connect with> password: <password> .ft P .fi .UNINDENT .UNINDENT .sp Optionally, the following keyword arguments can be passed to the ext_pillar for customized configuration: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B pillar_key Optionally set the pillar key to return the data into. Default is \fBvmware\fP\&. .TP .B protocol Optionally set to alternate protocol if the vCenter server or ESX/ESXi host is not using the default protocol. Default protocol is \fBhttps\fP\&. .TP .B port Optionally set to alternate port if the vCenter server or ESX/ESXi host is not using the default port. Default port is \fB443\fP\&. .TP .B property_name Property name to match the minion id against. Defaults to \fBname\fP\&. .TP .B property_types Optionally specify a list of pyVmomi vim types to search for the minion id in \(aqproperty_name\(aq. Default is \fB[\(aqVirtualMachine\(aq]\fP\&. .sp For example, to search both vim.VirtualMachine and vim.HostSystem object types: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- vmware: host: myesx username: root password: complex_password property_types: \- VirtualMachine \- HostSystem .ft P .fi .UNINDENT .UNINDENT .sp Additionally, the list of property types can be dicts, the item of the dict being a list specifying the attribute to return for that vim object type. .sp The pillar will attempt to recurse the attribute and return all child attributes. .sp To explicitly specify deeper attributes without attempting to recurse an attribute, convert the list item to a dict with the item of the dict being the child attributes to return. Follow this pattern to return attributes as deep within the object as necessary. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Be careful when specifying custom attributes! Many attributes have objects as attributes which have the parent object as an attribute and which will cause the pillar to fail due to the attempt to convert all sub\-objects recursively (i.e. infinite attribute loops). Specifying only the sub\-attributes you would like returned will keep the infinite recursion from occurring. .sp A maximum recursion exception will occur in this case and the pillar will not return as desired. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- vmware: host: myvcenter username: my_user password: my_pass replace_default_attributes: True property_types: \- VirtualMachine: \- config: \- bootOptions: \- bootDelay \- bootRetryDelay \- HostSystem: \- datastore: \- name .ft P .fi .UNINDENT .UNINDENT .sp The above ext_pillar example would return a pillar like the following for a VirtualMachine object that\(aqs name matched the minion id: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C vmware: config: bootOptions: bootDelay: 1000 bootRetryDelay: 1000 .ft P .fi .UNINDENT .UNINDENT .sp If you were to retrieve these virtual machine attributes via pyVmomi directly, this would be the same as .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C vmObject.config.bootOptions.bootDelay vmObject.config.bootOptionis.bootRetryDelay .ft P .fi .UNINDENT .UNINDENT .sp The above ext_pillar example would return a pillar like the following for a HostySystem object that\(aqs name matched the minion id: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C vmware: datastore: \- name: Datastore1 \- name: Datastore2 .ft P .fi .UNINDENT .UNINDENT .sp The \(aqdatastore\(aq property of a HostSystem object is a list of datastores, thus a list is returned. .TP .B replace_default_attributes If custom attributes are specified by the property_types parameter, replace_default_attributes determines if those will be added to default attributes (False) or replace the default attributes completely (True). The default setting is \(aqFalse\(aq. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 vCenter \(dqCustom Attributes\(dq (i.e. Annotations) will always be returned if it exists on the object as part of the pillar regardless of this setting. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.pillar.vmware_pillar.ext_pillar(minion_id, pillar, **kwargs) Check vmware/vcenter for all data .UNINDENT .SS proxy modules .TS center; |l|l|. _ T{ \fI\%arista_pyeapi\fP T} T{ Arista pyeapi T} _ T{ \fI\%chronos\fP T} T{ Chronos T} _ T{ \fI\%cimc\fP T} T{ Proxy Minion interface module for managing Cisco Integrated Management Controller devices T} _ T{ \fI\%cisconso\fP T} T{ Proxy Minion interface module for managing (practically) any network device with Cisco Network Services Orchestrator (Cisco NSO). T} _ T{ \fI\%deltaproxy\fP T} T{ This is the \(dqmaster\(dq deltaproxy minion, known better as the \fIcontrol proxy\fP because it controls all the deltaproxies underneath it. T} _ T{ \fI\%docker\fP T} T{ T} _ T{ \fI\%dummy\fP T} T{ This is the a dummy proxy\-minion designed for testing the proxy minion subsystem. T} _ T{ \fI\%esxcluster\fP T} T{ Proxy Minion interface module for managing VMWare ESXi clusters. T} _ T{ \fI\%esxdatacenter\fP T} T{ Proxy Minion interface module for managing VMWare ESXi clusters. T} _ T{ \fI\%esxi\fP T} T{ Proxy Minion interface module for managing VMware ESXi hosts. T} _ T{ \fI\%esxvm\fP T} T{ Proxy Minion interface module for managing VMWare ESXi virtual machines. T} _ T{ \fI\%fx2\fP T} T{ Dell FX2 chassis T} _ T{ \fI\%junos\fP T} T{ Interface with a Junos device via proxy\-minion. T} _ T{ \fI\%marathon\fP T} T{ Marathon T} _ T{ \fI\%napalm\fP T} T{ NAPALM: Network Automation and Programmability Abstraction Layer with Multivendor support T} _ T{ \fI\%netmiko_px\fP T} T{ Netmiko T} _ T{ \fI\%nxos\fP T} T{ Proxy Minion for Cisco NX\-OS Switches T} _ T{ \fI\%nxos_api\fP T} T{ Proxy Minion to manage Cisco Nexus Switches (NX\-OS) over the NX\-API T} _ T{ \fI\%panos\fP T} T{ Proxy Minion interface module for managing Palo Alto firewall devices T} _ T{ \fI\%philips_hue\fP T} T{ Philips HUE lamps module for proxy. T} _ T{ \fI\%rest_sample\fP T} T{ This is a simple proxy\-minion designed to connect to and communicate with the bottle\-based web service contained in \fI\%https://github.com/saltstack/salt\-contrib/tree/master/proxyminion_rest_example\fP T} _ T{ \fI\%restconf\fP T} T{ Proxy Minion to manage RESTCONF Devices T} _ T{ \fI\%ssh_sample\fP T} T{ This is a simple proxy\-minion designed to connect to and communicate with a server that exposes functionality via SSH. T} _ T{ \fI\%vcenter\fP T} T{ Proxy Minion interface module for managing VMWare vCenters. T} _ .TE .SS salt.proxy.arista_pyeapi .SS Arista pyeapi .sp New in version 2019.2.0. .sp Proxy module for managing Arista switches via the eAPI using the \fI\%pyeapi\fP library. .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 Proxy module requires pyeapi to be installed: \fBpip install pyeapi\fP\&. .SS Pillar .sp The \fBpyeapi\fP proxy configuration requires the following parameters in order to connect to the network device: .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 All the arguments may be optional, depending on your setup. .SS Proxy Pillar Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: pyeapi host: router1.example.com username: example password: example .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.arista_pyeapi.call(method, *args, **kwargs) Calls an arbitrary pyeapi method. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.arista_pyeapi.conn() Return the connection object. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.arista_pyeapi.init(opts) Open the connection to the Arista switch over the eAPI. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.arista_pyeapi.initialized() Connection finished initializing? .UNINDENT .INDENT 0.0 .TP .B salt.proxy.arista_pyeapi.ping() Connection open successfully? .UNINDENT .INDENT 0.0 .TP .B salt.proxy.arista_pyeapi.shutdown(opts) Closes connection with the device. .UNINDENT .SS salt.proxy.chronos .SS Chronos .sp Proxy minion for managing a Chronos cluster. .SS Dependencies .INDENT 0.0 .IP \(bu 2 \fI\%chronos execution module (salt.modules.chronos)\fP .UNINDENT .SS Pillar .sp The chronos proxy configuration requires a \(aqbase_url\(aq property that points to the chronos endpoint: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: chronos base_url: http://my\-chronos\-master.mydomain.com:4400 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.2. .INDENT 0.0 .TP .B salt.proxy.chronos.init(opts) Perform any needed setup. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.chronos.ping() Is the chronos api responding? .UNINDENT .INDENT 0.0 .TP .B salt.proxy.chronos.shutdown(opts) For this proxy shutdown is a no\-op .UNINDENT .SS salt.proxy.cimc .SS Proxy Minion interface module for managing Cisco Integrated Management Controller devices .sp New in version 2018.3.0. .INDENT 0.0 .TP .B codeauthor \fBSpencer Ervin <spencer_ervin@hotmail.com>\fP .TP .B maturity new .TP .B depends none .TP .B platform unix .UNINDENT .sp This proxy minion enables Cisco Integrated Management Controller devices (hereafter referred to as simply \(aqcimc\(aq devices to be treated individually like a Salt Minion. .sp The cimc proxy leverages the XML API functionality on the Cisco Integrated Management Controller. The Salt proxy must have access to the cimc on HTTPS (tcp/443). .sp More in\-depth conceptual reading on Proxy Minions can be found in the \fI\%Proxy Minion\fP section of Salt\(aqs documentation. .SS Configuration .sp To use this integration proxy module, please configure the following: .SS Pillar .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 ID. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: cimc host: <ip or dns name of cimc host> username: <cimc username> password: <cimc password> verify_ssl: True .ft P .fi .UNINDENT .UNINDENT .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 cimc Proxy Module, set this to \fBcimc\fP\&. .SS host .sp The location, or ip/dns, of the cimc host. Required. .SS username .sp The username used to login to the cimc host. Required. .SS password .sp The password used to login to the cimc host. Required. .INDENT 0.0 .TP .B salt.proxy.cimc.get_config_resolver_class(cid=None, hierarchical=False) The configResolveClass method returns requested managed object in a given class. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cimc.grains() Get the grains from the proxied device .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cimc.grains_refresh() Refresh the grains from the proxied device .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cimc.init(opts) This function gets called when the proxy starts up. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cimc.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 .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cimc.logon() Logs into the cimc device and returns the session cookie. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cimc.logout(cookie=None) Closes the session with the device. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cimc.ping() Returns true if the device is reachable, else false. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cimc.prepare_return(x) Converts the etree to dict .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cimc.set_config_modify(dn=None, inconfig=None, hierarchical=False) The configConfMo method configures the specified managed object in a single subtree (for example, DN). .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cimc.shutdown() Shutdown the connection to the proxy device. For this proxy, shutdown is a no\-op. .UNINDENT .SS salt.proxy.cisconso .sp Proxy Minion interface module for managing (practically) any network device with Cisco Network Services Orchestrator (Cisco NSO). Cisco NSO uses a series of remote polling agents, APIs and SSH commands to fetch network configuration and represent it in a data model. PyNSO, the Python module used by this proxy minion does the task of converting native Python dictionaries into NETCONF/YANG syntax that the REST API for Cisco NSO can then use to set the configuration of the target network device. .INDENT 0.0 .TP .B Supported devices: .INDENT 7.0 .IP \(bu 2 A10 AX Series .IP \(bu 2 Arista 7150 Series .IP \(bu 2 Ciena 3000, 5000, ESM .IP \(bu 2 H3c S5800 Series .IP \(bu 2 Overture 1400, 2200, 5000, 5100, 6000 .IP \(bu 2 Accedian MetroNID .IP \(bu 2 Avaya ERS 4000, SR8000, VSP 9000 .IP \(bu 2 .INDENT 2.0 .TP .B Cisco: APIC\-DC, ASA, IOS, IOS XE, IOS XR, er, ME\-4600, NX OS, Prime Network Registrar, Quantum, StarOS, UCS ManagWSA .UNINDENT .IP \(bu 2 Huawei: NE40E, quidway series, Enterprise Network Simulation Framework .IP \(bu 2 PaloAlto PA\-2000, PA\-3000, Virtualized Firewalls .IP \(bu 2 Adtran 900 Series .IP \(bu 2 Brocade ADX, MLX, Netiron, Vyatta .IP \(bu 2 Dell Force 10 Networking S\-Series .IP \(bu 2 Infinera DTN\-X Multi\-Terabit Packet Optical Network Platform .IP \(bu 2 Pulsecom SuperG .IP \(bu 2 Adva 150CC Series .IP \(bu 2 CableLabs Converged Cable Access Platform .IP \(bu 2 Ericsson EFN324 Series, SE family .IP \(bu 2 Juniper: Contrail, EX, M, MX, QFX, SRX, Virtual SRX .IP \(bu 2 Quagga Routing Software .IP \(bu 2 Affirmed Networks .IP \(bu 2 Citrix Netscaler .IP \(bu 2 F5 BIG\-IP .IP \(bu 2 NEC iPasolink .IP \(bu 2 Riverbed Steelhead Series .IP \(bu 2 Alcatel\-Lucent 7XXX, SAM .IP \(bu 2 Clavister .IP \(bu 2 Fortinet .IP \(bu 2 Nominum DCS .IP \(bu 2 Sonus SBC 5000 Series .IP \(bu 2 Allied Telesys .IP \(bu 2 Open vSwitch .UNINDENT .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B codeauthor \fIAnthony Shaw <anthony.shaw@dimensiondata.com>\fP .UNINDENT .sp This proxy minion enables a consistent interface to fetch, control and maintain the configuration of network devices via a NETCONF\-compliant control plane. Cisco Network Services Orchestrator. .sp More in\-depth conceptual reading on Proxy Minions can be found in the \fI\%Proxy Minion\fP section of Salt\(aqs documentation. .SS Dependencies .INDENT 0.0 .IP \(bu 2 pynso Python module .UNINDENT .SS PyNSO .sp PyNSO can be installed via pip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install pynso .ft P .fi .UNINDENT .UNINDENT .SS Configuration .sp To use this integration proxy module, please configure the following: .SS Pillar .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 ID. At a minimum for communication with the NSO host, the pillar should look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: cisconso host: <ip or dns name of host> port: 8080 use_ssl: false username: <username> password: password .ft P .fi .UNINDENT .UNINDENT .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 Cisco NSO Proxy Module, set this to \fBcisconso\fP\&. .SS host .sp The location, or IP/dns, of the Cisco NSO API host. Required. .SS username .sp The username used to login to the Cisco NSO host, such as \fBadmin\fP\&. Required. .SS passwords .sp The password for the given user. Required. .SS use_ssl .sp Whether to use HTTPS messaging to speak to the API. .SS port .sp The port that the Cisco NSO API is running on, 8080 by default .SS Salt Proxy .sp After your pillar is in place, you can test the proxy. The proxy can run on any machine that has network connectivity to your Salt Master and to the Cisco NSO host in question. SaltStack recommends that the machine running the salt\-proxy process also run a regular minion, though it is not strictly necessary. .sp On the machine that will run the proxy, make sure there is an \fB/etc/salt/proxy\fP file with at least the following in it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: <ip or hostname of salt\-master> .ft P .fi .UNINDENT .UNINDENT .sp You can then start the salt\-proxy process with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid <id you want to give the host> .ft P .fi .UNINDENT .UNINDENT .sp You may want to add \fB\-l debug\fP to run the above in the foreground in debug mode just to make sure everything is OK. .sp Next, accept the key for the proxy on your salt\-master, just like you would for a regular minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-a <id you gave the cisconso host> .ft P .fi .UNINDENT .UNINDENT .sp You can confirm that the pillar data is in place for the proxy: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <id> pillar.items .ft P .fi .UNINDENT .UNINDENT .sp And now you should be able to ping the Cisco NSO host to make sure it is responding: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <id> test.ping .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cisconso.apply_rollback(datastore, name) Apply a system rollback .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdatastore\fP (\fBDatastoreType\fP (\fBstr\fP enum).) \-\- The datastore, e.g. running, operational. One of the NETCONF store IETF types .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- an ID of the rollback to restore .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cisconso.get_data(datastore, path) Get the configuration of the device tree at the given path .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdatastore\fP (\fBDatastoreType\fP (\fBstr\fP enum).) \-\- The datastore, e.g. running, operational. One of the NETCONF store IETF types .IP \(bu 2 \fBpath\fP (\fBlist\fP of \fBstr\fP OR \fBtuple\fP) \-\- The device path, a list of element names in order, comma separated .UNINDENT .TP .B Returns The network configuration at that tree .TP .B Return type \fBdict\fP .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt cisco\-nso cisconso.get_data devices .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cisconso.get_rollback(name) Get the backup of stored a configuration rollback .INDENT 7.0 .TP .B Parameters \fBname\fP (\fBstr\fP) \-\- Typically an ID of the backup .TP .B Return type \fBstr\fP .TP .B Returns the contents of the rollback snapshot .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cisconso.get_rollbacks() Get a list of stored configuration rollbacks .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cisconso.grains() Get the grains from the proxy device. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cisconso.init(opts) .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cisconso.ping() Check to see if the host is responding. Returns False if the host didn\(aqt respond, True otherwise. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt cisco\-nso test.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cisconso.set_data_value(datastore, path, data) Get a data entry in a datastore .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdatastore\fP (\fBDatastoreType\fP (\fBstr\fP enum).) \-\- The datastore, e.g. running, operational. One of the NETCONF store IETF types .IP \(bu 2 \fBpath\fP (\fBlist\fP of \fBstr\fP OR \fBtuple\fP) \-\- The device path to set the value at, a list of element names in order, comma separated .IP \(bu 2 \fBdata\fP (\fBdict\fP) \-\- The new value at the given path .UNINDENT .TP .B Return type \fBbool\fP .TP .B Returns \fBTrue\fP if successful, otherwise error. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.cisconso.shutdown() Shutdown the connection to the proxy device. For this proxy, shutdown is a no\-op. .UNINDENT .SS salt.proxy.deltaproxy .sp This is the \(dqmaster\(dq deltaproxy minion, known better as the \fIcontrol proxy\fP because it controls all the deltaproxies underneath it. .INDENT 0.0 .TP .B salt.proxy.deltaproxy.grains() Make up some grains .UNINDENT .INDENT 0.0 .TP .B salt.proxy.deltaproxy.grains_refresh() Refresh the grains .UNINDENT .INDENT 0.0 .TP .B salt.proxy.deltaproxy.init(opts) .UNINDENT .INDENT 0.0 .TP .B salt.proxy.deltaproxy.initialized() Since grains are loaded in many different places and some of those ws places occur before the proxy can be initialized, return whether our init() function has been called .UNINDENT .INDENT 0.0 .TP .B salt.proxy.deltaproxy.ping() Degenerate ping .UNINDENT .INDENT 0.0 .TP .B salt.proxy.deltaproxy.shutdown(opts) For this proxy shutdown is a no\-op .UNINDENT .SS salt.proxy.docker .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%docker Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Docker Proxy Minion .sp New in version 2019.2.0. .INDENT 0.0 .TP .B depends docker .UNINDENT .sp This proxy minion is just a shim to the docker executor, which will use the \fI\%docker.call\fP for everything except state runs. .sp To configure the proxy minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: docker name: festive_leakey .ft P .fi .UNINDENT .UNINDENT .sp It is also possible to just name the proxy minion the same name as the container, and use grains to configure the proxy minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: docker name: {{grains[\(aqid\(aq]}} .ft P .fi .UNINDENT .UNINDENT .sp name .INDENT 0.0 .INDENT 3.5 Name of the docker container .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.docker.init(opts) Always initialize .UNINDENT .INDENT 0.0 .TP .B salt.proxy.docker.initialized() This should always be initialized .UNINDENT .INDENT 0.0 .TP .B salt.proxy.docker.module_executors() List of module executors to use for this Proxy Minion .UNINDENT .INDENT 0.0 .TP .B salt.proxy.docker.shutdown(opts) Nothing needs to be done to shutdown .UNINDENT .SS salt.proxy.dummy .sp This is the a dummy proxy\-minion designed for testing the proxy minion subsystem. .INDENT 0.0 .TP .B salt.proxy.dummy.fns() Method called by grains module. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.grains() Make up some grains .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.grains_refresh() Refresh the grains .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.init(opts) Required. Can be used to initialize the server connection. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.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 .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.package_install(name, **kwargs) Install a \(dqpackage\(dq on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.package_list() List \(dqpackages\(dq installed on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.package_remove(name) Remove a \(dqpackage\(dq on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.package_status(name) Check the installation status of a package on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.ping() Degenerate ping .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.service_list() List \(dqservices\(dq on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.service_restart(name) Restart a \(dqservice\(dq on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.service_start(name) Start a \(dqservice\(dq on the dummy server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.service_status(name) Check if a service is running on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.service_stop(name) Stop a \(dqservice\(dq on the dummy server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.shutdown(opts) For this proxy shutdown is a no\-op .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.test_from_state() Test function so we have something to call from a state :return: .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.upgrade() \(dqUpgrade\(dq packages .UNINDENT .INDENT 0.0 .TP .B salt.proxy.dummy.uptodate() Call the REST endpoint to see if the packages on the \(dqserver\(dq are up to date. .UNINDENT .SS salt.proxy.esxcluster .sp Proxy Minion interface module for managing VMWare ESXi clusters. .SS Dependencies .INDENT 0.0 .IP \(bu 2 pyVmomi .IP \(bu 2 jsonschema .UNINDENT .SS Configuration .sp To use this integration proxy module, please configure the following: .SS Pillar .sp Proxy minions get their configuration from Salt\(aqs Pillar. This can now happen from the proxy\(aqs configuration file. .sp Example pillars: .sp \fBuserpass\fP mechanism: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: esxcluster cluster: <cluster name> datacenter: <datacenter name> vcenter: <ip or dns name of parent vcenter> mechanism: userpass username: <vCenter username> passwords: (required if userpass is used) \- first_password \- second_password \- third_password .ft P .fi .UNINDENT .UNINDENT .sp \fBsspi\fP mechanism: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: esxcluster cluster: <cluster name> datacenter: <datacenter name> vcenter: <ip or dns name of parent vcenter> mechanism: sspi domain: <user domain> principal: <host kerberos principal> .ft P .fi .UNINDENT .UNINDENT .SS proxytype .sp To use this Proxy Module, set this to \fBesxdatacenter\fP\&. .SS cluster .sp Name of the managed cluster. Required. .SS datacenter .sp Name of the datacenter the managed cluster is in. Required. .SS vcenter .sp The location of the VMware vCenter server (host of ip) where the datacenter should be managed. Required. .SS mechanism .sp The mechanism used to connect to the vCenter server. Supported values are \fBuserpass\fP and \fBsspi\fP\&. Required. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Connections are attempted using all (\fBusername\fP, \fBpassword\fP) combinations on proxy startup. .UNINDENT .UNINDENT .SS username .sp The username used to login to the host, such as \fBroot\fP\&. Required if mechanism is \fBuserpass\fP\&. .SS passwords .sp A list of passwords to be used to try and login to the vCenter server. At least one password in this list is required if mechanism is \fBuserpass\fP\&. When the proxy comes up, it will try the passwords listed in order. .SS domain .sp User domain. Required if mechanism is \fBsspi\fP\&. .SS principal .sp Kerberos principal. Rquired if mechanism is \fBsspi\fP\&. .SS protocol .sp If the ESXi host is not using the default protocol, set this value to an alternate protocol. Default is \fBhttps\fP\&. .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 Salt Proxy .sp After your pillar is in place, you can test the proxy. The proxy can run on any machine that has network connectivity to your Salt Master and to the vCenter server in the pillar. SaltStack recommends that the machine running the salt\-proxy process also run a regular minion, though it is not strictly necessary. .sp To start a proxy minion one needs to establish its identity <id>: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid <proxy_id> .ft P .fi .UNINDENT .UNINDENT .sp On the machine that will run the proxy, make sure there is a configuration file present. By default this is \fB/etc/salt/proxy\fP\&. If in a different location, the \fB<configuration_folder>\fP has to be specified when running the proxy: file with at least the following in it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid <proxy_id> \-c <configuration_folder> .ft P .fi .UNINDENT .UNINDENT .SS Commands .sp Once the proxy is running it will connect back to the specified master and individual commands can be runs against it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Master \- minion communication salt <cluster_name> test.ping # Test vcenter connection salt <cluster_name> vsphere.test_vcenter_connection .ft P .fi .UNINDENT .UNINDENT .SS States .sp Associated states are documented in \fBsalt.states.esxcluster\fP\&. Look there to find an example structure for Pillar as well as an example \fB\&.sls\fP file for configuring an ESX cluster from scratch. .INDENT 0.0 .TP .B salt.proxy.esxcluster.find_credentials() Cycle through all the possible credentials and return the first one that works. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxcluster.get_details() Function that returns the cached details .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxcluster.init(opts) This function gets called when the proxy starts up. For login the protocol and port are cached. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxcluster.ping() Returns True. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt esx\-cluster test.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxcluster.shutdown() Shutdown the connection to the proxy device. For this proxy, shutdown is a no\-op. .UNINDENT .SS salt.proxy.esxdatacenter .sp Proxy Minion interface module for managing VMWare ESXi clusters. .SS Dependencies .INDENT 0.0 .IP \(bu 2 pyVmomi .IP \(bu 2 jsonschema .UNINDENT .SS Configuration .sp To use this integration proxy module, please configure the following: .SS Pillar .sp Proxy minions get their configuration from Salt\(aqs Pillar. This can now happen from the proxy\(aqs configuration file. .sp Example pillars: .sp \fBuserpass\fP mechanism: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: esxdatacenter datacenter: <datacenter name> vcenter: <ip or dns name of parent vcenter> mechanism: userpass username: <vCenter username> passwords: (required if userpass is used) \- first_password \- second_password \- third_password .ft P .fi .UNINDENT .UNINDENT .sp \fBsspi\fP mechanism: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: esxdatacenter datacenter: <datacenter name> vcenter: <ip or dns name of parent vcenter> mechanism: sspi domain: <user domain> principal: <host kerberos principal> .ft P .fi .UNINDENT .UNINDENT .SS proxytype .sp To use this Proxy Module, set this to \fBesxdatacenter\fP\&. .SS datacenter .sp Name of the managed datacenter. Required. .SS vcenter .sp The location of the VMware vCenter server (host of ip) where the datacenter should be managed. Required. .SS mechanism .sp The mechanism used to connect to the vCenter server. Supported values are \fBuserpass\fP and \fBsspi\fP\&. Required. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Connections are attempted using all (\fBusername\fP, \fBpassword\fP) combinations on proxy startup. .UNINDENT .UNINDENT .SS username .sp The username used to login to the host, such as \fBroot\fP\&. Required if mechanism is \fBuserpass\fP\&. .SS passwords .sp A list of passwords to be used to try and login to the vCenter server. At least one password in this list is required if mechanism is \fBuserpass\fP\&. When the proxy comes up, it will try the passwords listed in order. .SS domain .sp User domain. Required if mechanism is \fBsspi\fP\&. .SS principal .sp Kerberos principal. Rquired if mechanism is \fBsspi\fP\&. .SS protocol .sp If the ESXi host is not using the default protocol, set this value to an alternate protocol. Default is \fBhttps\fP\&. .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 Salt Proxy .sp After your pillar is in place, you can test the proxy. The proxy can run on any machine that has network connectivity to your Salt Master and to the vCenter server in the pillar. SaltStack recommends that the machine running the salt\-proxy process also run a regular minion, though it is not strictly necessary. .sp To start a proxy minion one needs to establish its identity <id>: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid <proxy_id> .ft P .fi .UNINDENT .UNINDENT .sp On the machine that will run the proxy, make sure there is a configuration file present. By default this is \fB/etc/salt/proxy\fP\&. If in a different location, the \fB<configuration_folder>\fP has to be specified when running the proxy: file with at least the following in it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid <proxy_id> \-c <configuration_folder> .ft P .fi .UNINDENT .UNINDENT .SS Commands .sp Once the proxy is running it will connect back to the specified master and individual commands can be runs against it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Master \- minion communication salt <datacenter_name> test.ping # Test vcenter connection salt <datacenter_name> vsphere.test_vcenter_connection .ft P .fi .UNINDENT .UNINDENT .SS States .sp Associated states are documented in \fBsalt.states.esxdatacenter\fP\&. Look there to find an example structure for Pillar as well as an example \fB\&.sls\fP file for configuring an ESX datacenter from scratch. .INDENT 0.0 .TP .B salt.proxy.esxdatacenter.find_credentials() Cycle through all the possible credentials and return the first one that works. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxdatacenter.get_details() Function that returns the cached details .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxdatacenter.init(opts) This function gets called when the proxy starts up. All login details are cached. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxdatacenter.ping() Returns True. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt dc_id test.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxdatacenter.shutdown() Shutdown the connection to the proxy device. For this proxy, shutdown is a no\-op. .UNINDENT .SS salt.proxy.esxi .sp Proxy Minion interface module for managing VMware ESXi hosts. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be deprecated in a future release of Salt. VMware strongly recommends using the \fI\%VMware Salt extensions\fP instead of the ESXi module. Because the Salt extensions are newer and actively supported by VMware, they are more compatible with current versions of ESXi and they work well with the latest features in the VMware product line. .UNINDENT .UNINDENT .sp \fBSpecial Note: SaltStack thanks\fP \fI\%Adobe Corporation\fP \fBfor their support in creating this Proxy Minion integration.\fP .sp This proxy minion enables VMware ESXi (hereafter referred to as simply \(aqESXi\(aq) hosts to be treated individually like a Salt Minion. .sp Since the ESXi host may not necessarily run on an OS capable of hosting a Python stack, the ESXi host can\(aqt run a Salt Minion directly. Salt\(aqs \(dqProxy Minion\(dq functionality enables you to designate another machine to host a minion process that \(dqproxies\(dq communication from the Salt Master. The master does not know nor care that the target is not a \(dqreal\(dq Salt Minion. .sp More in\-depth conceptual reading on Proxy Minions can be found in the \fI\%Proxy Minion\fP section of Salt\(aqs documentation. .SS Dependencies .INDENT 0.0 .IP \(bu 2 pyVmomi Python Module .IP \(bu 2 ESXCLI .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 ESXi State Module was developed against. .SS ESXCLI .sp Currently, about a third of the functions used in the vSphere Execution Module 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 or vCenter server by running the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C esxcli \-s <host\-location> \-u <username> \-p <password> 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 To use this integration proxy module, please configure the following: .SS Pillar .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 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: <ip or dns name of esxi host> username: <ESXi username> passwords: \- first_password \- second_password \- third_password credstore: <path to credential store> .ft P .fi .UNINDENT .UNINDENT .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 \fI\%vsphere.update_host_password\fP execution module function or via the \fI\%esxi.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 This also allows you to use any number of potential fallback passwords. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When a password is changed on the host to one in the list of possible passwords, the further down on the list the password is, the longer individual commands will take to return. This is due to the nature of pyVmomi\(aqs login system. We have to wait for the first attempt to fail before trying the next password on the list. .sp This scenario is especially true, and even slower, when the proxy minion first starts. If the correct password is not the first password on the list, it may take up to a minute for \fBtest.ping\fP to respond with a \fBTrue\fP result. Once the initial authorization is complete, the responses for commands will be a little faster. .sp To avoid these longer waiting periods, SaltStack recommends moving the correct password to the top of the list and restarting the proxy minion at your earliest convenience. .UNINDENT .UNINDENT .SS protocol .sp If the ESXi host is not using the default protocol, set this value to an alternate protocol. Default is \fBhttps\fP\&. .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 credstore .sp If the ESXi host is using an untrusted SSL certificate, set this value to the file path where the credential store is located. This file is passed to \fBesxcli\fP\&. Default is \fB<HOME>/.vmware/credstore/vicredentials.xml\fP on Linux and \fB<APPDATA>/VMware/credstore/vicredentials.xml\fP on Windows. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBHOME\fP variable is sometimes not set for processes running as system services. If you want to rely on the default credential store location, make sure \fBHOME\fP is set for the proxy process. .UNINDENT .UNINDENT .SS Salt Proxy .sp After your pillar is in place, you can test the proxy. The proxy can run on any machine that has network connectivity to your Salt Master and to the ESXi host in question. SaltStack recommends that the machine running the salt\-proxy process also run a regular minion, though it is not strictly necessary. .sp On the machine that will run the proxy, make sure there is an \fB/etc/salt/proxy\fP file with at least the following in it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: <ip or hostname of salt\-master> .ft P .fi .UNINDENT .UNINDENT .sp You can then start the salt\-proxy process with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid <id you want to give the host> .ft P .fi .UNINDENT .UNINDENT .sp You may want to add \fB\-l debug\fP to run the above in the foreground in debug mode just to make sure everything is OK. .sp Next, accept the key for the proxy on your salt\-master, just like you would for a regular minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-a <id you gave the esxi host> .ft P .fi .UNINDENT .UNINDENT .sp You can confirm that the pillar data is in place for the proxy: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <id> pillar.items .ft P .fi .UNINDENT .UNINDENT .sp And now you should be able to ping the ESXi host to make sure it is responding: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <id> test.ping .ft P .fi .UNINDENT .UNINDENT .sp At this point you can execute one\-off commands against the host. For example, you can get the ESXi host\(aqs system information: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <id> esxi.cmd system_info .ft P .fi .UNINDENT .UNINDENT .sp Note that you don\(aqt need to provide credentials or an ip/hostname. Salt knows to use the credentials you stored in Pillar. .sp It\(aqs important to understand how this particular proxy works. \fI\%Salt.modules.vsphere\fP is a standard Salt execution module. If you pull up the docs for it you\(aqll see that almost every function in the module takes credentials and a target host. When credentials and a host aren\(aqt passed, Salt runs commands through \fBpyVmomi\fP against the local machine. If you wanted, you could run functions from this module on any host where an appropriate version of \fBpyVmomi\fP is installed, and that host would reach out over the network and communicate with the ESXi host. .sp \fBesxi.cmd\fP acts as a \(dqshim\(dq between the execution module and the proxy. Its first parameter is always the function from salt.modules.vsphere. 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 this 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 \fI\%salt.modules.vsphere\fP instead of \fI\%salt.modules.esxi\fP\&. .SS States .sp Associated states are thoroughly documented in \fI\%salt.states.esxi\fP\&. Look there to find an example structure for Pillar as well as an example \fB\&.sls\fP file for standing up an ESXi host from scratch. .INDENT 0.0 .TP .B salt.proxy.esxi.ch_config(cmd, *args, **kwargs) This function is called by the \fI\%salt.modules.esxi.cmd\fP shim. It then calls whatever is passed in \fBcmd\fP inside the \fI\%salt.modules.vsphere\fP module. Passes the return through from the vsphere module. .INDENT 7.0 .TP .B cmd The command to call inside salt.modules.vsphere .TP .B args Arguments that need to be passed to that command. .TP .B kwargs Keyword arguments that need to be passed to that command. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxi.find_credentials(host) Cycle through all the possible credentials and return the first one that works. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxi.get_details() Return the proxy details .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxi.grains() Get the grains from the proxy device. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxi.grains_refresh() Refresh the grains from the proxy device. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxi.init(opts) This function gets called when the proxy starts up. For ESXi devices, the host, login credentials, and, if configured, the protocol and port are cached. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxi.is_connected_via_vcenter() .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxi.ping() Returns True if connection is to be done via a vCenter (no connection is attempted). Check to see if the host is responding when connecting directly via an ESXi host. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt esxi\-host test.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxi.shutdown() Shutdown the connection to the proxy device. For this proxy, shutdown is a no\-op. .UNINDENT .SS salt.proxy.esxvm .sp Proxy Minion interface module for managing VMWare ESXi virtual machines. .SS Dependencies .INDENT 0.0 .IP \(bu 2 pyVmomi .IP \(bu 2 jsonschema .UNINDENT .SS Configuration .sp To use this integration proxy module, please configure the following: .SS Pillar .sp Proxy minions get their configuration from Salt\(aqs Pillar. This can now happen from the proxy\(aqs configuration file. .sp Example pillars: .sp \fBuserpass\fP mechanism: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: esxvm datacenter: <datacenter name> vcenter: <ip or dns name of parent vcenter> mechanism: userpass username: <vCenter username> passwords: (required if userpass is used) \- first_password \- second_password \- third_password .ft P .fi .UNINDENT .UNINDENT .sp \fBsspi\fP mechanism: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: esxvm datacenter: <datacenter name> vcenter: <ip or dns name of parent vcenter> mechanism: sspi domain: <user domain> principal: <host kerberos principal> .ft P .fi .UNINDENT .UNINDENT .SS proxytype .sp To use this Proxy Module, set this to \fBesxvm\fP\&. .SS datacenter .sp Name of the datacenter where the virtual machine should be deployed. Required. .SS vcenter .sp The location of the VMware vCenter server (host of ip) where the virtual machine should be managed. Required. .SS mechanism .sp The mechanism used to connect to the vCenter server. Supported values are \fBuserpass\fP and \fBsspi\fP\&. Required. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Connections are attempted using all (\fBusername\fP, \fBpassword\fP) combinations on proxy startup. .UNINDENT .UNINDENT .SS username .sp The username used to login to the host, such as \fBroot\fP\&. Required if mechanism is \fBuserpass\fP\&. .SS passwords .sp A list of passwords to be used to try and login to the vCenter server. At least one password in this list is required if mechanism is \fBuserpass\fP\&. When the proxy comes up, it will try the passwords listed in order. .SS domain .sp User realm domain. Required if mechanism is \fBsspi\fP\&. .SS principal .sp Kerberos principal. Rquired if mechanism is \fBsspi\fP\&. .SS protocol .sp If the ESXi host is not using the default protocol, set this value to an alternate protocol. Default is \fBhttps\fP\&. .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 Salt Proxy .sp After your pillar is in place, you can test the proxy. The proxy can run on any machine that has network connectivity to your Salt Master and to the vCenter server in the pillar. SaltStack recommends that the machine running the salt\-proxy process also run a regular minion, though it is not strictly necessary. .sp To start a proxy minion one needs to establish its identity <id>: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid <proxy_id> .ft P .fi .UNINDENT .UNINDENT .sp On the machine that will run the proxy, make sure there is a configuration file present. By default this is \fB/etc/salt/proxy\fP\&. If in a different location, the \fB<configuration_folder>\fP has to be specified when running the proxy: file with at least the following in it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid <proxy_id> \-c <configuration_folder> .ft P .fi .UNINDENT .UNINDENT .SS Commands .sp Once the proxy is running it will connect back to the specified master and individual commands can be runs against it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Master \- minion communication salt <proxy_id> test.ping # Test vcenter connection salt <proxy_id> vsphere.test_vcenter_connection .ft P .fi .UNINDENT .UNINDENT .SS States .sp Associated states are documented in \fBsalt.states.esxvm\fP\&. Look there to find an example structure for Pillar as well as an example \fB\&.sls\fP file for configuring an ESX virtual machine from scratch. .INDENT 0.0 .TP .B salt.proxy.esxvm.find_credentials() Cycle through all the possible credentials and return the first one that works. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxvm.get_details() Function that returns the cached details .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxvm.init(opts) This function gets called when the proxy starts up. For login the protocol and port are cached. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxvm.ping() Returns True. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt esx\-vm test.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.esxvm.shutdown() Shutdown the connection to the proxy device. For this proxy, shutdown is a no\-op. .UNINDENT .SS salt.proxy.fx2 .SS Dell FX2 chassis .sp New in version 2015.8.2. .sp Proxy minion interface module for managing Dell FX2 chassis (Dell Chassis Management Controller version 1.2 and above, iDRAC8 version 2.00 and above) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \fI\%iDRAC Remote execution module (salt.modules.dracr)\fP .IP \(bu 2 \fI\%Chassis command shim (salt.modules.chassis)\fP .IP \(bu 2 \fI\%Dell Chassis States (salt.states.dellchassis)\fP .IP \(bu 2 Dell\(aqs \fBracadm\fP command line interface to CMC and iDRAC devices. .UNINDENT .sp \fBSpecial Note: SaltStack thanks\fP \fI\%Adobe Corporation\fP \fBfor their support in creating this proxy minion integration.\fP .sp This proxy minion enables Dell FX2 and FX2s (hereafter referred to as simply \(dqchassis\(dq, \(dqCMC\(dq, or \(dqFX2\(dq) chassis to be treated individually like a salt\-minion. .sp Since the CMC embedded in the chassis does not run an OS capable of hosting a Python stack, the chassis can\(aqt run a minion directly. Salt\(aqs \(dqProxy Minion\(dq functionality enables you to designate another machine to host a minion process that \(dqproxies\(dq communication from the salt\-master. The master does not know nor care that the target is not a real minion. .sp More in\-depth conceptual reading on Proxy Minions can be found \fI\%in the Proxy Minion section\fP of Salt\(aqs documentation. .sp To configure this integration, follow these steps: .SS Pillar .sp Proxy minions get their configuration from Salt\(aqs Pillar. Every proxy must have a stanza in Pillar, and a reference in the Pillar topfile that matches the ID. At a minimum for communication with the chassis the pillar should look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: host: <ip or dns name of chassis controller> admin_username: <iDRAC username for the CMC, usually \(aqroot\(aq> fallback_admin_username: <username to try if the first fails> passwords: \- first_password \- second_password \- third\-password proxytype: fx2 .ft P .fi .UNINDENT .UNINDENT .sp The \fBproxytype\fP line above is critical, 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). .sp The proxy integration will try the passwords listed in order. It is configured this way so you can have a regular password, a potential fallback password, and the third password can be the one you intend to change the chassis to use. This way, after it is changed, you should not need to restart the proxy minion\-\-it should just pick up the third password in the list. You can then change pillar at will to move that password to the front and retire the unused ones. .sp Beware, many Dell CMC and iDRAC units are configured to lockout IP addresses or users after too many failed password attempts. This can generate user panic in the form of \(dqI no longer know what the password is!!!\(dq. To mitigate panic try the web interface from a different IP, or setup a emergency administrator user in the CMC before doing a wholesale password rotation. .sp The automatic lockout can be disabled via Salt with the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <cmc> chassis.cmd set_general cfgRacTuning cfgRacTuneIpBlkEnable 0 .ft P .fi .UNINDENT .UNINDENT .sp and then verified with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <cmc> chassis.cmd get_general cfgRacTuning cfgRacTuneIpBlkEnable .ft P .fi .UNINDENT .UNINDENT .SS salt\-proxy .sp After your pillar is in place, you can test the proxy. The proxy can run on any machine that has network connectivity to your salt\-master and to the chassis in question. SaltStack recommends that this machine also run a regular minion, though it is not strictly necessary. .sp On the machine that will run the proxy, make sure there is an \fB/etc/salt/proxy\fP file with at least the following in it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: <ip or hostname of salt\-master> .ft P .fi .UNINDENT .UNINDENT .sp You can start the proxy with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid <id you want to give the chassis> .ft P .fi .UNINDENT .UNINDENT .sp You may want to add \fB\-l debug\fP to run the above in the foreground in debug mode just to make sure everything is OK. .sp Next, accept the key for the proxy on your salt\-master, just like you would for a regular minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-a <id you want to give the chassis> .ft P .fi .UNINDENT .UNINDENT .sp You can confirm that the pillar data is in place for the proxy: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <id> pillar.items .ft P .fi .UNINDENT .UNINDENT .sp And now you should be able to ping the chassis to make sure it is responding: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <id> test.ping .ft P .fi .UNINDENT .UNINDENT .sp At this point you can execute one\-off commands against the chassis. For example, you can get the chassis inventory: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <id> chassis.cmd inventory .ft P .fi .UNINDENT .UNINDENT .sp Note that you don\(aqt need to provide credentials or an ip/hostname. Salt knows to use the credentials you stored in Pillar. .sp It\(aqs important to understand how this particular proxy works. \fI\%Salt.modules.dracr\fP is a standard Salt execution module. If you pull up the docs for it you\(aqll see that almost every function in the module takes credentials and a target host. When credentials and a host aren\(aqt passed, Salt runs \fBracadm\fP against the local machine. If you wanted you could run functions from this module on any host where an appropriate version of \fBracadm\fP is installed, and that host would reach out over the network and communicate with the chassis. .sp \fBChassis.cmd\fP acts as a \(dqshim\(dq between the execution module and the proxy. Its first parameter is always the function from salt.modules.dracr to execute. If the function takes more positional or keyword arguments you can append them to the call. It\(aqs this shim that speaks to the chassis through the proxy, arranging for the credentials and hostname to be pulled from the pillar section for this proxy minion. .sp Because of the presence of the shim, to lookup documentation for what functions you can use to interface with the chassis, you\(aqll want to look in \fI\%salt.modules.dracr\fP instead of \fI\%salt.modules.chassis\fP\&. .SS States .sp Associated states are thoroughly documented in \fI\%salt.states.dellchassis\fP\&. Look there to find an example structure for pillar as well as an example \fB\&.sls\fP file for standing up a Dell Chassis from scratch. .INDENT 0.0 .TP .B salt.proxy.fx2.admin_password() Return the admin_password in the DETAILS dictionary, or \(aqcalvin\(aq (the Dell default) if there is none present .UNINDENT .INDENT 0.0 .TP .B salt.proxy.fx2.admin_username() Return the admin_username in the DETAILS dictionary, or root if there is none present .UNINDENT .INDENT 0.0 .TP .B salt.proxy.fx2.chconfig(cmd, *args, **kwargs) This function is called by the \fI\%salt.modules.chassis.cmd\fP shim. It then calls whatever is passed in \fBcmd\fP inside the \fI\%salt.modules.dracr\fP module. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcmd\fP \-\- The command to call inside salt.modules.dracr .IP \(bu 2 \fBargs\fP \-\- Arguments that need to be passed to that command .IP \(bu 2 \fBkwargs\fP \-\- Keyword arguments that need to be passed to that command .UNINDENT .TP .B Returns Passthrough the return from the dracr module. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.fx2.find_credentials() Cycle through all the possible credentials and return the first one that works .UNINDENT .INDENT 0.0 .TP .B salt.proxy.fx2.grains() Get the grains from the proxied device .UNINDENT .INDENT 0.0 .TP .B salt.proxy.fx2.grains_refresh() Refresh the grains from the proxied device .UNINDENT .INDENT 0.0 .TP .B salt.proxy.fx2.host() .UNINDENT .INDENT 0.0 .TP .B salt.proxy.fx2.init(opts) This function gets called when the proxy starts up. We check opts to see if a fallback user and password are supplied. If they are present, and the primary credentials don\(aqt work, then we try the backup before failing. .sp Whichever set of credentials works is placed in the persistent DETAILS dictionary and will be used for further communication with the chassis. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.fx2.ping() Is the chassis responding? .INDENT 7.0 .TP .B Returns Returns False if the chassis didn\(aqt respond, True otherwise. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.fx2.shutdown(opts) Shutdown the connection to the proxied device. For this proxy shutdown is a no\-op. .UNINDENT .SS salt.proxy.junos .sp Interface with a Junos device via proxy\-minion. To connect to a junos device via junos proxy, specify the host information in the pillar in \(aq/srv/pillar/details.sls\(aq .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: junos host: <ip or dns name of host> username: <username> port: 830 password: <secret> .ft P .fi .UNINDENT .UNINDENT .sp In \(aq/srv/pillar/top.sls\(aq map the device details with the proxy name. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqvmx\(aq: \- details .ft P .fi .UNINDENT .UNINDENT .sp After storing the device information in the pillar, configure the proxy in \(aq/etc/salt/proxy\(aq .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: <ip or hostname of salt\-master> .ft P .fi .UNINDENT .UNINDENT .sp Run the salt proxy via the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid=vmx .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.proxy.junos.RebootActive(**kwargs) Class to get static variable, to indicate when a reboot/shutdown is being processed and the keep_alive should not probe the connection since it interferes with the shutdown process. .INDENT 7.0 .TP .B reboot_shutdown = False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.junos.alive(opts) Validate and return the connection status with the remote device. .sp New in version 2018.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.junos.conn() .UNINDENT .INDENT 0.0 .TP .B salt.proxy.junos.get_reboot_active() .UNINDENT .INDENT 0.0 .TP .B salt.proxy.junos.get_serialized_facts() .UNINDENT .INDENT 0.0 .TP .B salt.proxy.junos.init(opts) Open the connection to the Junos device, login, and bind to the Resource class .UNINDENT .INDENT 0.0 .TP .B salt.proxy.junos.initialized() .UNINDENT .INDENT 0.0 .TP .B salt.proxy.junos.ping() Ping? Pong! .UNINDENT .INDENT 0.0 .TP .B salt.proxy.junos.proxytype() Returns the name of this proxy .UNINDENT .INDENT 0.0 .TP .B salt.proxy.junos.reboot_active() .UNINDENT .INDENT 0.0 .TP .B salt.proxy.junos.reboot_clear() .UNINDENT .INDENT 0.0 .TP .B salt.proxy.junos.shutdown(opts) This is called when the proxy\-minion is exiting to make sure the connection to the device is closed cleanly. .UNINDENT .SS salt.proxy.marathon .SS Marathon .sp Proxy minion for managing a Marathon cluster. .SS Dependencies .INDENT 0.0 .IP \(bu 2 \fI\%marathon execution module (salt.modules.marathon)\fP .UNINDENT .SS Pillar .sp The marathon proxy configuration requires a \(aqbase_url\(aq property that points to the marathon endpoint: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: marathon base_url: http://my\-marathon\-master.mydomain.com:8080 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.2. .INDENT 0.0 .TP .B salt.proxy.marathon.init(opts) Perform any needed setup. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.marathon.ping() Is the marathon api responding? .UNINDENT .INDENT 0.0 .TP .B salt.proxy.marathon.shutdown(opts) For this proxy shutdown is a no\-op .UNINDENT .SS salt.proxy.napalm .SS NAPALM: Network Automation and Programmability Abstraction Layer with Multivendor support .sp New in version 2016.11.0. .sp Proxy minion for managing network devices via \fI\%NAPALM\fP library. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> & Jerome Fleury <\fI\%jf@cloudflare.com\fP> .TP .B maturity new .TP .B depends napalm .TP .B platform unix .UNINDENT .SS Dependencies .sp The \fBnapalm\fP proxy module requires \fI\%NAPALM\fP library to be installed: \fBpip install napalm\fP Please check \fI\%Installation\fP for complete details. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Beginning with Salt release 2017.7.3, it is recommended to use \fBnapalm\fP >= \fB2.0.0\fP\&. The library has been unified into a monolithic package, as in opposite to separate packages per driver. For more details you can check \fI\%this document\fP\&. While it will still work with the old packages, bear in mind that the NAPALM core team will maintain only the main \fBnapalm\fP package. .sp Moreover, for additional capabilities, the users can always define a library that extends NAPALM\(aqs base capabilities and configure the \fBprovider\fP option (see below). .UNINDENT .UNINDENT .SS Pillar .sp The napalm proxy configuration requires the following parameters in order to connect to the network device: .INDENT 0.0 .TP .B driver Specifies the network device operating system. For a complete list of the supported operating systems please refer to the \fI\%NAPALM Read the Docs page\fP\&. .TP .B host The IP Address or FQDN to use when connecting to the device. Alternatively, the following field names can be used instead: \fBhostname\fP, \fBfqdn\fP, \fBip\fP\&. .TP .B username The username to be used when connecting to the device. .TP .B passwd The password needed to establish the connection. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This field may not be mandatory when working with SSH\-based drivers, and the username has a SSH key properly configured on the device targeted to be managed. .UNINDENT .UNINDENT .TP .B optional_args Dictionary with the optional arguments. Check the complete list of supported \fI\%optional arguments\fP\&. .TP .B always_alive: \fBTrue\fP In certain less dynamic environments, maintaining the remote connection permanently open with the network device is not always beneficial. In that case, the user can select to initialize the connection only when needed, by specifying this field to \fBfalse\fP\&. Default: \fBtrue\fP (maintains the connection with the remote network device). .sp New in version 2017.7.0. .TP .B provider: \fBnapalm_base\fP The library that provides the \fBget_network_device\fP function. This option is useful when the user has more specific needs and requires to extend the NAPALM capabilities using a private library implementation. The only constraint is that the alternative library needs to have the \fBget_network_device\fP function available. .sp New in version 2017.7.1. .TP .B multiprocessing: \fBFalse\fP Overrides the \fI\%multiprocessing\fP option, per proxy minion. The \fBmultiprocessing\fP option must be turned off for SSH\-based proxies. However, some NAPALM drivers (e.g. Arista, NX\-OS) are not SSH\-based. As multiple proxy minions may share the same configuration file, this option permits the configuration of the \fBmultiprocessing\fP option more specifically, for some proxy minions. .sp New in version 2017.7.2. .UNINDENT .sp Proxy pillar file example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: napalm driver: junos host: core05.nrt02 username: my_username passwd: my_password optional_args: port: 12201 .ft P .fi .UNINDENT .UNINDENT .sp Example using a user\-specific library, extending NAPALM\(aqs capabilities, e.g. \fBcustom_napalm_base\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: napalm driver: ios fqdn: cr1.th2.par.as1234.net username: salt password: \(aq\(aq provider: custom_napalm_base .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%NAPALM grains: select network devices based on their characteristics\fP .IP \(bu 2 \fI\%NET module: network basic features\fP .IP \(bu 2 \fI\%Network config state: Manage the configuration using arbitrary templates\fP .IP \(bu 2 \fBNAPALM YANG state: Manage the configuration according to the YANG models (OpenConfig/IETF)\fP .IP \(bu 2 \fBNetwork ACL module: Generate and load ACL (firewall) configuration\fP .IP \(bu 2 \fI\%Network ACL state: Manage the firewall configuration\fP .IP \(bu 2 \fI\%NTP operational and configuration management module\fP .IP \(bu 2 \fI\%BGP operational and configuration management module\fP .IP \(bu 2 \fI\%Routes details\fP .IP \(bu 2 \fI\%SNMP configuration module\fP .IP \(bu 2 \fI\%Users configuration management\fP .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Beginning with release codename 2019.2.0, any NAPALM command executed when running under a NAPALM Proxy Minion supports the \fBforce_reconnect\fP magic argument. .sp Proxy Minions generally establish a connection with the remote network device at the time of the Minion startup and that connection is going to be used forever. .sp If one would need execute a command on the device but connecting using different parameters (due to various causes, e.g., unable to authenticate the user specified in the Pillar as the authentication system \- say TACACS+ is not available, or the DNS resolver is currently down and would like to temporarily use the IP address instead, etc.), it implies updating the Pillar data and restarting the Proxy Minion process restart. In particular cases like that, you can pass the \fBforce_reconnect=True\fP keyword argument, together with the alternative connection details, to enforce the command to be executed over a separate connection. .sp For example, if the usual command is \fBsalt \(aq*\(aq net.arp\fP, you can use the following to connect using a different username instead: \fBsalt \(aq*\(aq net.arp username=my\-alt\-usr force_reconnect=True\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.napalm.alive(opts) Return the connection status with the remote device. .sp New in version 2017.7.0. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.napalm.call(method, *args, **kwargs) Calls a specific method from the network driver instance. Please check the \fI\%readthedocs\fP page for the updated list of getters. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmethod\fP \-\- specifies the name of the method to be called .IP \(bu 2 \fBparams\fP \-\- contains the mapping between the name and the values of the parameters needed to call the method .UNINDENT .TP .B Returns A dictionary with three keys: .UNINDENT .INDENT 7.0 .IP \(bu 2 result (True/False): if the operation succeeded .IP \(bu 2 out (object): returns the object as\-is from the call .IP \(bu 2 comment (string): provides more details in case the call failed .IP \(bu 2 traceback (string): complete traceback in case of exception. Please submit an issue including this traceback on the \fI\%correct driver repo\fP and make sure to read the \fI\%FAQ\fP .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C __proxy__[\(aqnapalm.call\(aq](\(aqcli\(aq **{ \(aqcommands\(aq: [ \(aqshow version\(aq, \(aqshow chassis fan\(aq ] }) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.napalm.fns() Method called by NAPALM grains module. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.napalm.get_device() Returns the network device object. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.napalm.get_grains() Retrieve facts from the network device. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.napalm.grains_refresh() Refresh the grains. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.napalm.init(opts) Opens the connection with the network device. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.napalm.initialized() Connection finished initializing? .UNINDENT .INDENT 0.0 .TP .B salt.proxy.napalm.ping() Connection open successfully? .UNINDENT .INDENT 0.0 .TP .B salt.proxy.napalm.shutdown(opts) Closes connection with the device. .UNINDENT .SS salt.proxy.netmiko_px .SS Netmiko .sp New in version 2019.2.0. .sp Proxy module for managing network devices via \fI\%Netmiko\fP\&. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> & Kirk Byers <\fI\%ktbyers@twb\-tech.com\fP> .TP .B maturity new .TP .B depends netmiko .TP .B platform unix .UNINDENT .SS Dependencies .sp The \fBnetmiko\fP proxy modules requires Netmiko to be installed: \fBpip install netmiko\fP\&. .SS Pillar .sp The \fBnetmiko\fP proxy configuration requires the following parameters in order to connect to the network device: .INDENT 0.0 .IP \(bu 2 \fBdevice_type\fP \- Class selection based on device type. Supported options: .INDENT 2.0 .IP \(bu 2 \fBa10\fP: A10 Networks .IP \(bu 2 \fBaccedian\fP: Accedian Networks .IP \(bu 2 \fBalcatel_aos\fP: Alcatel AOS .IP \(bu 2 \fBalcatel_sros\fP: Alcatel SROS .IP \(bu 2 \fBapresia_aeos\fP: Apresia AEOS .IP \(bu 2 \fBarista_eos\fP: Arista EOS .IP \(bu 2 \fBaruba_os\fP: Aruba .IP \(bu 2 \fBavaya_ers\fP: Avaya ERS .IP \(bu 2 \fBavaya_vsp\fP: Avaya VSP .IP \(bu 2 \fBbrocade_fastiron\fP: Brocade Fastiron .IP \(bu 2 \fBbrocade_netiron\fP: Brocade Netiron .IP \(bu 2 \fBbrocade_nos\fP: Brocade NOS .IP \(bu 2 \fBbrocade_vdx\fP: Brocade NOS .IP \(bu 2 \fBbrocade_vyos\fP: VyOS .IP \(bu 2 \fBcheckpoint_gaia\fP: Check Point GAiA .IP \(bu 2 \fBcalix_b6\fP: Calix B6 .IP \(bu 2 \fBciena_saos\fP: Ciena SAOS .IP \(bu 2 \fBcisco_asa\fP: Cisco SA .IP \(bu 2 \fBcisco_ios\fP: Cisco IOS .IP \(bu 2 \fBcisco_nxos\fP: Cisco NX\-oS .IP \(bu 2 \fBcisco_s300\fP: Cisco S300 .IP \(bu 2 \fBcisco_tp\fP: Cisco TpTcCe .IP \(bu 2 \fBcisco_wlc\fP: Cisco WLC .IP \(bu 2 \fBcisco_xe\fP: Cisco IOS .IP \(bu 2 \fBcisco_xr\fP: Cisco XR .IP \(bu 2 \fBcoriant\fP: Coriant .IP \(bu 2 \fBdell_force10\fP: Dell Force10 .IP \(bu 2 \fBdell_os10\fP: Dell OS10 .IP \(bu 2 \fBdell_powerconnect\fP: Dell PowerConnect .IP \(bu 2 \fBeltex\fP: Eltex .IP \(bu 2 \fBenterasys\fP: Enterasys .IP \(bu 2 \fBextreme\fP: Extreme .IP \(bu 2 \fBextreme_wing\fP: Extreme Wing .IP \(bu 2 \fBf5_ltm\fP: F5 LTM .IP \(bu 2 \fBfortinet\fP: Fortinet .IP \(bu 2 \fBgeneric_termserver\fP: TerminalServer .IP \(bu 2 \fBhp_comware\fP: HP Comware .IP \(bu 2 \fBhp_procurve\fP: HP Procurve .IP \(bu 2 \fBhuawei\fP: Huawei .IP \(bu 2 \fBhuawei_vrpv8\fP: Huawei VRPV8 .IP \(bu 2 \fBjuniper\fP: Juniper Junos .IP \(bu 2 \fBjuniper_junos\fP: Juniper Junos .IP \(bu 2 \fBlinux\fP: Linux .IP \(bu 2 \fBmellanox\fP: Mellanox .IP \(bu 2 \fBmrv_optiswitch\fP: MrvOptiswitch .IP \(bu 2 \fBnetapp_cdot\fP: NetAppcDot .IP \(bu 2 \fBnetscaler\fP: Netscaler .IP \(bu 2 \fBovs_linux\fP: OvsLinux .IP \(bu 2 \fBpaloalto_panos\fP: PaloAlto Panos .IP \(bu 2 \fBpluribus\fP: Pluribus .IP \(bu 2 \fBquanta_mesh\fP: Quanta Mesh .IP \(bu 2 \fBruckus_fastiron\fP: Ruckus Fastiron .IP \(bu 2 \fBubiquiti_edge\fP: Ubiquiti Edge .IP \(bu 2 \fBubiquiti_edgeswitch\fP: Ubiquiti Edge .IP \(bu 2 \fBvyatta_vyos\fP: VyOS .IP \(bu 2 \fBvyos\fP: VyOS .IP \(bu 2 \fBbrocade_fastiron_telnet\fP: Brocade Fastiron over Telnet .IP \(bu 2 \fBbrocade_netiron_telnet\fP: Brocade Netiron over Telnet .IP \(bu 2 \fBcisco_ios_telnet\fP: Cisco IOS over Telnet .IP \(bu 2 \fBapresia_aeos_telnet\fP: Apresia AEOS over Telnet .IP \(bu 2 \fBarista_eos_telnet\fP: Arista EOS over Telnet .IP \(bu 2 \fBhp_procurve_telnet\fP: HP Procurve over Telnet .IP \(bu 2 \fBhp_comware_telnet\fP: HP Comware over Telnet .IP \(bu 2 \fBjuniper_junos_telnet\fP: Juniper Junos over Telnet .IP \(bu 2 \fBcalix_b6_telnet\fP: Calix B6 over Telnet .IP \(bu 2 \fBdell_powerconnect_telnet\fP: Dell PowerConnect over Telnet .IP \(bu 2 \fBgeneric_termserver_telnet\fP: TerminalServer over Telnet .IP \(bu 2 \fBextreme_telnet\fP: Extreme Networks over Telnet .IP \(bu 2 \fBruckus_fastiron_telnet\fP: Ruckus Fastiron over Telnet .IP \(bu 2 \fBcisco_ios_serial\fP: Cisco IOS over serial port .UNINDENT .IP \(bu 2 \fBip\fP \- IP address of target device (not required if \fBhost\fP is provided) .IP \(bu 2 \fBhost\fP \- Hostname of target device (not required if \fBip\fP is provided) .IP \(bu 2 \fBusername\fP \- Username to authenticate against target device, if required .IP \(bu 2 \fBpassword\fP \- Password to authenticate against target device, if required .IP \(bu 2 \fBsecret\fP \- The enable password if target device requires one .IP \(bu 2 \fBport\fP \- The destination port used to connect to the target device .IP \(bu 2 \fBglobal_delay_factor\fP \- Multiplication factor affecting Netmiko delays (default: \fB1\fP) .IP \(bu 2 \fBuse_keys\fP \- Connect to target device using SSH keys (default: \fBFalse\fP) .IP \(bu 2 \fBkey_file\fP \- Filename path of the SSH key file to use .IP \(bu 2 \fBallow_agent\fP \- Enable use of SSH key\-agent .IP \(bu 2 \fBssh_strict\fP \- Automatically reject unknown SSH host keys (default: \fBFalse\fP, which means unknown SSH host keys will be accepted) .IP \(bu 2 \fBsystem_host_keys\fP \- Load host keys from the user\(aqs \(dqknown_hosts\(dq file (default: \fBFalse\fP) .IP \(bu 2 \fBalt_host_keys\fP \- If \fBTrue\fP, host keys will be loaded from the file specified in \fBalt_key_file\fP (default: \fBFalse\fP) .IP \(bu 2 \fBalt_key_file\fP \- SSH host key file to use (if \fBalt_host_keys=True\fP) .IP \(bu 2 \fBssh_config_file\fP \- File name of OpenSSH configuration file .IP \(bu 2 \fBtimeout\fP \- Connection timeout, in seconds (default: \fB90\fP) .IP \(bu 2 \fBsession_timeout\fP \- Set a timeout for parallel requests, in seconds (default: \fB60\fP) .IP \(bu 2 \fBkeepalive\fP \- Send SSH keepalive packets at a specific interval, in seconds. Currently defaults to \fB0\fP, for backwards compatibility (it will not attempt to keep the connection alive using the KEEPALIVE packets). .IP \(bu 2 \fBdefault_enter\fP \- Character(s) to send to correspond to enter key (default: \fB\en\fP) .IP \(bu 2 \fBresponse_return\fP \- Character(s) to use in normalized return data to represent enter key (default: \fB\en\fP) .IP \(bu 2 \fBalways_alive\fP \- In certain less dynamic environments, maintaining the remote connection permanently open with the network device is not always beneficial. In that case, the user can select to initialize the connection only when needed, by setting this option to \fBFalse\fP\&. By default this option is set to \fBTrue\fP (maintains the connection with the remote network device) .IP \(bu 2 \fBmultiprocessing\fP \- Overrides the \fI\%multiprocessing\fP option, per proxy minion, as the Netmiko communication channel is mainly SSH (default: \fBFalse\fP) .IP \(bu 2 \fBconnection_timeout\fP \- The number of seconds to attempt to connect to the device in seconds. (default: \fB300\fP) .UNINDENT .SS Proxy Pillar Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: netmiko device_type: juniper_junos host: router1.example.com username: example password: example .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: netmiko device_type: cisco_ios ip: 1.2.3.4 username: test use_keys: true secret: w3@k .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.netmiko_px.alive(opts) Return the connection status with the network device. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.netmiko_px.args() Return the Netmiko device args. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.netmiko_px.call(method, *args, **kwargs) Calls an arbitrary netmiko method. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.netmiko_px.conn() Return the connection object. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.netmiko_px.connection(connection_timeout=300) .UNINDENT .INDENT 0.0 .TP .B salt.proxy.netmiko_px.init(opts) Open the connection to the network device managed through netmiko. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.netmiko_px.initialized() Connection finished initializing? .UNINDENT .INDENT 0.0 .TP .B salt.proxy.netmiko_px.make_con(connection_timeout=300) .UNINDENT .INDENT 0.0 .TP .B salt.proxy.netmiko_px.ping() Connection open successfully? .UNINDENT .INDENT 0.0 .TP .B salt.proxy.netmiko_px.shutdown(opts) Closes connection with the device. .UNINDENT .SS salt.proxy.nxos .sp Proxy Minion for Cisco NX\-OS Switches .sp New in version 2016.11.0. .sp The Cisco NX\-OS Proxy Minion is supported on NX\-OS devices for the following connection types: 1) Connection Type SSH 2) Connection Type NX\-API (If Supported By The Device and Image Version). .INDENT 0.0 .TP .B maturity new .TP .B platform nxos .UNINDENT .sp SSH uses the built in SSHConnection module in \fBsalt.utils.vt_helper\fP .sp To configure the proxy minion for ssh: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: nxos connection: ssh host: 192.168.187.100 username: admin password: admin prompt_name: nxos\-switch ssh_args: \(aq\-o PubkeyAuthentication=no\(aq key_accept: True .ft P .fi .UNINDENT .UNINDENT .sp To configure the proxy minion for nxapi: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: nxos connection: nxapi host: 192.168.187.100 username: admin password: admin transport: http port: 80 verify: False save_config: False .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B proxytype: (REQUIRED) Use this proxy minion \fInxos\fP .TP .B connection: (REQUIRED) connection transport type. Choices: \fIssh, nxapi\fP Default: \fIssh\fP .TP .B host: (REQUIRED) login ip address or dns hostname. .TP .B username: (REQUIRED) login username. .TP .B password: (REQUIRED) login password. .TP .B save_config: If True, \(aqcopy running\-config starting\-config\(aq is issues for every configuration command. If False, Running config is not saved to startup config Default: True .sp The recommended approach is to use the \fIsave_running_config\fP function instead of this option to improve performance. The default behavior controlled by this option is preserved for backwards compatibility. .UNINDENT .sp Connection SSH Args: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B prompt_name: (REQUIRED when \fIconnection\fP is \fIssh\fP) (REQUIRED, this or \fIprompt_regex\fP below, but not both) The name in the prompt on the switch. Recommended to use your device\(aqs hostname. .TP .B prompt_regex: (REQUIRED when \fIconnection\fP is \fIssh\fP) (REQUIRED, this or \fIprompt_name\fP above, but not both) A regular expression that matches the prompt on the switch and any other possible prompt at which you need the proxy minion to continue sending input. This feature was specifically developed for situations where the switch may ask for confirmation. \fIprompt_name\fP above would not match these, and so the session would timeout. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C nxos\-switch#.*|\e(y\e/n\e)\e?.* .ft P .fi .UNINDENT .UNINDENT .sp This should match .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C nxos\-switch# .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Flash complete. Reboot this switch (y/n)? [n] .ft P .fi .UNINDENT .UNINDENT .sp If neither \fIprompt_name\fP nor \fIprompt_regex\fP is specified the prompt will be defaulted to .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \&.+#$ .ft P .fi .UNINDENT .UNINDENT .sp which should match any number of characters followed by a \fI#\fP at the end of the line. This may be far too liberal for most installations. .TP .B ssh_args: Extra optional arguments used for connecting to switch. .TP .B key_accept: Whether or not to accept the host key of the switch on initial login. Default: \fIFalse\fP .UNINDENT .UNINDENT .UNINDENT .sp Connection NXAPI Args: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B transport: (REQUIRED) when \fIconnection\fP is \fInxapi\fP\&. Choices: \fIhttp, https\fP Default: \fIhttps\fP .TP .B port: (REQUIRED) when \fIconnection\fP is \fInxapi\fP\&. Default: \fI80\fP .TP .B verify: (REQUIRED) when \fIconnection\fP is \fInxapi\fP\&. Either a boolean, in which case it controls whether we verify the NX\-API TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Default: \fITrue\fP .sp When there is no certificate configuration on the device and this option is set as \fBTrue\fP (default), the commands will fail with the following error: \fBSSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:581)\fP\&. In this case, you either need to configure a proper certificate on the device (\fIrecommended\fP), or bypass the checks setting this argument as \fBFalse\fP with all the security risks considered. .sp Check \fI\%https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus3000/sw/programmability/6_x/b_Cisco_Nexus_3000_Series_NX\-OS_Programmability_Guide/b_Cisco_Nexus_3000_Series_NX\-OS_Programmability_Guide_chapter_01.html\fP to see how to properly configure the certificate. .UNINDENT .UNINDENT .UNINDENT .sp The functions from the proxy minion can be run from the salt commandline using the \fI\%salt.modules.nxos\fP execution module. .INDENT 0.0 .TP .B salt.proxy.nxos.grains() Helper function for nxos execution module functions that need to retrieve nxos grains using the proxy minion. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos.grains_refresh() Helper function for nxos execution module functions that need to refresh nxos grains using the proxy minion. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos.init(opts=None) Required. Initialize device connection using ssh or nxapi connection type. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos.initialized() Since grains are loaded in many different places and some of those places occur before the proxy can be initialized, return whether the init() function has been called. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos.ping() Helper function for nxos execution module functions that need to ping the nxos device using the proxy minion. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos.proxy_config(commands, save_config=None) Helper function for nxos execution module functions that need to configure an nxos device using the proxy minion. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos.sendline(commands, method=\(aqcli_show_ascii\(aq, **kwargs) Helper function for nxos execution module functions that need to send commands to an nxos device using the proxy minion. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos.shutdown() Not supported. Only used as a place holder to satisfy shutdown function requirement. .UNINDENT .SS salt.proxy.nxos_api .sp Proxy Minion to manage Cisco Nexus Switches (NX\-OS) over the NX\-API .sp New in version 2019.2.0. .sp Proxy module for managing Cisco Nexus switches via the NX\-API. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> .TP .B maturity new .TP .B platform any .UNINDENT .SS Usage .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To be able to use this module you need to enable to NX\-API on your switch, by executing \fBfeature nxapi\fP in configuration mode. .sp Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C switch# conf t switch(config)# feature nxapi .ft P .fi .UNINDENT .UNINDENT .sp To check that NX\-API is properly enabled, execute \fBshow nxapi\fP\&. .sp Output example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C switch# show nxapi nxapi enabled HTTPS Listen on port 443 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 NX\-API requires modern NXOS distributions, typically at least 7.0 depending on the hardware. Due to reliability reasons it is recommended to run the most recent version. .sp Check \fI\%https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus7000/sw/programmability/guide/b_Cisco_Nexus_7000_Series_NX\-OS_Programmability_Guide/b_Cisco_Nexus_7000_Series_NX\-OS_Programmability_Guide_chapter_0101.html\fP for more details. .UNINDENT .UNINDENT .SS Pillar .sp The \fBnxos_api\fP proxy configuration requires the following parameters in order to connect to the network switch: .INDENT 0.0 .TP .B transport: \fBhttps\fP Specifies the type of connection transport to use. Valid values for the connection are \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 NX\-API connection. .TP .B password The password to pass to the device to authenticate the NX\-API connection. .TP .B port The TCP port of the endpoint for the NX\-API 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 timeout: \fB60\fP Time in seconds to wait for the device to respond. Default: 60 seconds. .TP .B verify: \fBTrue\fP Either a boolean, in which case it controls whether we verify the NX\-API TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to \fBTrue\fP\&. .sp When there is no certificate configuration on the device and this option is set as \fBTrue\fP (default), the commands will fail with the following error: \fBSSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:581)\fP\&. In this case, you either need to configure a proper certificate on the device (\fIrecommended\fP), or bypass the checks setting this argument as \fBFalse\fP with all the security risks considered. .sp Check \fI\%https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus3000/sw/programmability/6_x/b_Cisco_Nexus_3000_Series_NX\-OS_Programmability_Guide/b_Cisco_Nexus_3000_Series_NX\-OS_Programmability_Guide_chapter_01.html\fP to see how to properly configure the certificate. .UNINDENT .sp All the arguments may be optional, depending on your setup. .SS Proxy Pillar Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: nxos_api host: switch1.example.com username: example password: example .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos_api.get_conn_args() Returns the connection arguments of the Proxy Minion. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos_api.init(opts) Open the connection to the Nexsu switch over the NX\-API. .sp As the communication is HTTP based, there is no connection to maintain, however, in order to test the connectivity and make sure we are able to bring up this Minion, we are executing a very simple command (\fBshow clock\fP) which doesn\(aqt come with much overhead and it\(aqs sufficient to confirm we are indeed able to connect to the NX\-API endpoint as configured. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos_api.initialized() Connection finished initializing? .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos_api.ping() Connection open successfully? .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos_api.rpc(commands, method=\(aqcli\(aq, **kwargs) Executes an RPC request over the NX\-API. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.nxos_api.shutdown(opts) Closes connection with the device. .UNINDENT .SS salt.proxy.panos .SS Proxy Minion interface module for managing Palo Alto firewall devices .sp New in version 2018.3.0. .INDENT 0.0 .TP .B codeauthor \fBSpencer Ervin <spencer_ervin@hotmail.com>\fP .TP .B maturity new .TP .B depends none .TP .B platform unix .UNINDENT .sp This proxy minion enables Palo Alto firewalls (hereafter referred to as simply \(aqpanos\(aq) to be treated individually like a Salt Minion. .sp The panos proxy leverages the XML API functionality on the Palo Alto firewall. The Salt proxy must have access to the Palo Alto firewall on HTTPS (tcp/443). .sp More in\-depth conceptual reading on Proxy Minions can be found in the \fI\%Proxy Minion\fP section of Salt\(aqs documentation. .SS Configuration .sp To use this integration proxy module, please configure the following: .SS Pillar .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 ID. There are four connection options available for the panos proxy module. .INDENT 0.0 .IP \(bu 2 Direct Device (Password) .IP \(bu 2 Direct Device (API Key) .IP \(bu 2 Panorama Pass\-Through (Password) .IP \(bu 2 Panorama Pass\-Through (API Key) .UNINDENT .SS Direct Device (Password) .sp The direct device configuration configures the proxy to connect directly to the device with username and password. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: panos host: <ip or dns name of panos host> username: <panos username> password: <panos password> verify_ssl: True .ft P .fi .UNINDENT .UNINDENT .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 panos Proxy Module, set this to \fBpanos\fP\&. .SS host .sp The location, or ip/dns, of the panos host. Required. .SS username .sp The username used to login to the panos host. Required. .SS password .sp The password used to login to the panos host. Required. .SS Direct Device (API Key) .sp Palo Alto devices allow for access to the XML API with a generated \(aqAPI key\(aq_ instead of username and password. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: panos host: <ip or dns name of panos host> apikey: <panos generated api key> .ft P .fi .UNINDENT .UNINDENT .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 panos Proxy Module, set this to \fBpanos\fP\&. .SS host .sp The location, or ip/dns, of the panos host. Required. .SS apikey .sp The generated XML API key for the panos host. Required. .SS Panorama Pass\-Through (Password) .sp The Panorama pass\-through method sends all connections through the Panorama management system. It passes the connections to the appropriate device using the serial number of the Palo Alto firewall. .sp This option will reduce the number of connections that must be present for the proxy server. It will only require a connection to the Panorama server. .sp The username and password will be for authentication to the Panorama server, not the panos device. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: panos serial: <serial number of panos host> host: <ip or dns name of the panorama server> username: <panorama server username> password: <panorama server password> .ft P .fi .UNINDENT .UNINDENT .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 panos Proxy Module, set this to \fBpanos\fP\&. .SS serial .sp The serial number of the panos host. Required. .SS host .sp The location, or ip/dns, of the Panorama server. Required. .SS username .sp The username used to login to the Panorama server. Required. .SS password .sp The password used to login to the Panorama server. Required. .SS Panorama Pass\-Through (API Key) .sp The Panorama server can also utilize a generated \(aqAPI key\(aq_ for authentication. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: panos serial: <serial number of panos host> host: <ip or dns name of the panorama server> apikey: <panos generated api key> .ft P .fi .UNINDENT .UNINDENT .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 panos Proxy Module, set this to \fBpanos\fP\&. .SS serial .sp The serial number of the panos host. Required. .SS host .sp The location, or ip/dns, of the Panorama server. Required. .SS apikey .sp The generated XML API key for the Panorama server. Required. .INDENT 0.0 .TP .B salt.proxy.panos.call(payload=None) This function captures the query string and sends it to the Palo Alto device. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.panos.grains() Get the grains from the proxied device .UNINDENT .INDENT 0.0 .TP .B salt.proxy.panos.grains_refresh() Refresh the grains from the proxied device .UNINDENT .INDENT 0.0 .TP .B salt.proxy.panos.init(opts) This function gets called when the proxy starts up. For panos devices, a determination is made on the connection type and the appropriate connection details that must be cached. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.panos.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 .UNINDENT .INDENT 0.0 .TP .B salt.proxy.panos.is_required_version(required_version=\(aq0.0.0\(aq) Because different versions of Palo Alto support different command sets, this function will return true if the current version of Palo Alto supports the required command. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.panos.ping() Returns true if the device is reachable, else false. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.panos.shutdown() Shutdown the connection to the proxy device. For this proxy, shutdown is a no\-op. .UNINDENT .SS salt.proxy.philips_hue .sp Philips HUE lamps module for proxy. .sp New in version 2015.8.3. .sp First create a new user on the Hue bridge by following the \fI\%Meet hue\fP instructions. .sp To configure the proxy minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: philips_hue host: [hostname or ip] user: [username] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.proxy.philips_hue.Const Constants for the lamp operations. .INDENT 7.0 .TP .B COLOR_BLUE = {\(aqhue\(aq: 46920, \(aqsat\(aq: 254} .UNINDENT .INDENT 7.0 .TP .B COLOR_DAYLIGHT = {\(aqxy\(aq: [0.3806, 0.3576]} .UNINDENT .INDENT 7.0 .TP .B COLOR_GREEN = {\(aqhue\(aq: 25500, \(aqsat\(aq: 254} .UNINDENT .INDENT 7.0 .TP .B COLOR_ORANGE = {\(aqhue\(aq: 12000, \(aqsat\(aq: 254} .UNINDENT .INDENT 7.0 .TP .B COLOR_PINK = {\(aqxy\(aq: [0.3688, 0.2095]} .UNINDENT .INDENT 7.0 .TP .B COLOR_PURPLE = {\(aqxy\(aq: [0.3787, 0.1724]} .UNINDENT .INDENT 7.0 .TP .B COLOR_RED = {\(aqhue\(aq: 0, \(aqsat\(aq: 254} .UNINDENT .INDENT 7.0 .TP .B COLOR_WHITE = {\(aqxy\(aq: [0.3227, 0.329]} .UNINDENT .INDENT 7.0 .TP .B COLOR_YELLOW = {\(aqxy\(aq: [0.4432, 0.5154]} .UNINDENT .INDENT 7.0 .TP .B LAMP_OFF = {\(aqon\(aq: False, \(aqtransitiontime\(aq: 0} .UNINDENT .INDENT 7.0 .TP .B LAMP_ON = {\(aqon\(aq: True, \(aqtransitiontime\(aq: 0} .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.call_alert(*args, **kwargs) Lamp alert .sp Options: .INDENT 7.0 .IP \(bu 2 \fBid\fP: Specifies a device ID. Can be a comma\-separated values. All, if omitted. .IP \(bu 2 \fBon\fP: Turns on or off an alert. Default is True. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hue.alert salt \(aq*\(aq hue.alert id=1 salt \(aq*\(aq hue.alert id=1,2,3 on=false .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.call_blink(*args, **kwargs) Blink a lamp. If lamp is ON, then blink ON\-OFF\-ON, otherwise OFF\-ON\-OFF. .sp Options: .INDENT 7.0 .IP \(bu 2 \fBid\fP: Specifies a device ID. Can be a comma\-separated values. All, if omitted. .IP \(bu 2 \fBpause\fP: Time in seconds. Can be less than 1, i.e. 0.7, 0.5 sec. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hue.blink id=1 salt \(aq*\(aq hue.blink id=1,2,3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.call_brightness(*args, **kwargs) Set an effect to the lamp. .sp Arguments: .INDENT 7.0 .IP \(bu 2 \fBvalue\fP: 0~255 brightness of the lamp. .UNINDENT .sp Options: .INDENT 7.0 .IP \(bu 2 \fBid\fP: Specifies a device ID. Can be a comma\-separated values. All, if omitted. .IP \(bu 2 \fBtransition\fP: Transition 0~200. Default 0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hue.brightness value=100 salt \(aq*\(aq hue.brightness id=1 value=150 salt \(aq*\(aq hue.brightness id=1,2,3 value=255 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.call_color(*args, **kwargs) Set a color to the lamp. .sp Options: .INDENT 7.0 .IP \(bu 2 \fBid\fP: Specifies a device ID. Can be a comma\-separated values. All, if omitted. .IP \(bu 2 .INDENT 2.0 .TP \fBcolor\fP: Fixed color. Values are: red, green, blue, orange, pink, white, yellow, daylight, purple. Default white. .UNINDENT .IP \(bu 2 \fBtransition\fP: Transition 0~200. .UNINDENT .sp Advanced: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP \fBgamut\fP: XY coordinates. Use gamut according to the Philips HUE devices documentation. More: \fI\%http://www.developers.meethue.com/documentation/hue\-xy\-values\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hue.color salt \(aq*\(aq hue.color id=1 salt \(aq*\(aq hue.color id=1,2,3 oolor=red transition=30 salt \(aq*\(aq hue.color id=1 gamut=0.3,0.5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.call_effect(*args, **kwargs) Set an effect to the lamp. .sp Options: .INDENT 7.0 .IP \(bu 2 \fBid\fP: Specifies a device ID. Can be a comma\-separated values. All, if omitted. .IP \(bu 2 \fBtype\fP: Type of the effect. Possible values are \(dqnone\(dq or \(dqcolorloop\(dq. Default \(dqnone\(dq. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hue.effect salt \(aq*\(aq hue.effect id=1 salt \(aq*\(aq hue.effect id=1,2,3 type=colorloop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.call_lights(*args, **kwargs) Get info about all available lamps. .sp Options: .INDENT 7.0 .IP \(bu 2 \fBid\fP: Specifies a device ID. Can be a comma\-separated values. All, if omitted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hue.lights salt \(aq*\(aq hue.lights id=1 salt \(aq*\(aq hue.lights id=1,2,3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.call_ping(*args, **kwargs) Ping the lamps by issuing a short inversion blink to all available devices. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hue.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.call_rename(*args, **kwargs) Rename a device. .sp Options: .INDENT 7.0 .IP \(bu 2 \fBid\fP: Specifies a device ID. Only one device at a time. .IP \(bu 2 \fBtitle\fP: Title of the device. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hue.rename id=1 title=\(aqWC for cats\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.call_status(*args, **kwargs) Return the status of the lamps. .sp Options: .INDENT 7.0 .IP \(bu 2 \fBid\fP: Specifies a device ID. Can be a comma\-separated values. All, if omitted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hue.status salt \(aq*\(aq hue.status id=1 salt \(aq*\(aq hue.status id=1,2,3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.call_switch(*args, **kwargs) Switch lamp ON/OFF. .sp If no particular state is passed, then lamp will be switched to the opposite state. .sp Options: .INDENT 7.0 .IP \(bu 2 \fBid\fP: Specifies a device ID. Can be a comma\-separated values. All, if omitted. .IP \(bu 2 \fBon\fP: True or False. Inverted current, if omitted .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hue.switch salt \(aq*\(aq hue.switch id=1 salt \(aq*\(aq hue.switch id=1,2,3 on=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.call_temperature(*args, **kwargs) Set the mired color temperature. More: \fI\%http://en.wikipedia.org/wiki/Mired\fP .sp Arguments: .INDENT 7.0 .IP \(bu 2 \fBvalue\fP: 150~500. .UNINDENT .sp Options: .INDENT 7.0 .IP \(bu 2 \fBid\fP: Specifies a device ID. Can be a comma\-separated values. All, if omitted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq hue.temperature value=150 salt \(aq*\(aq hue.temperature value=150 id=1 salt \(aq*\(aq hue.temperature value=150 id=1,2,3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.init(cnf) Initialize the module. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.ping(*args, **kw) Ping the lamps. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.philips_hue.shutdown(opts, *args, **kw) Shuts down the service. .UNINDENT .SS salt.proxy.rest_sample .sp This is a simple proxy\-minion designed to connect to and communicate with the bottle\-based web service contained in \fI\%https://github.com/saltstack/salt\-contrib/tree/master/proxyminion_rest_example\fP .INDENT 0.0 .TP .B salt.proxy.rest_sample.alive(opts) .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.fix_outage() .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.fns() .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.grains() Get the grains from the proxied device .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.grains_refresh() Refresh the grains from the proxied device .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.id(opts) Return a unique ID for this proxy minion. This ID MUST NOT CHANGE. If it changes while the proxy is running the salt\-master will get really confused and may stop talking to this minion .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.init(opts) .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.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 .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.package_install(name, **kwargs) Install a \(dqpackage\(dq on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.package_list() List \(dqpackages\(dq installed on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.package_remove(name) Remove a \(dqpackage\(dq on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.package_status(name) Check the installation status of a package on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.ping() Is the REST server up? .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.service_list() List \(dqservices\(dq on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.service_restart(name) Restart a \(dqservice\(dq on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.service_start(name) Start a \(dqservice\(dq on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.service_status(name) Check if a service is running on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.service_stop(name) Stop a \(dqservice\(dq on the REST server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.shutdown(opts) For this proxy shutdown is a no\-op .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.test_from_state() Test function so we have something to call from a state :return: .UNINDENT .INDENT 0.0 .TP .B salt.proxy.rest_sample.uptodate(name) Call the REST endpoint to see if the packages on the \(dqserver\(dq are up to date. .UNINDENT .SS salt.proxy.restconf .sp Proxy Minion to manage RESTCONF Devices .INDENT 0.0 .TP .B codeauthor Jamie (Bear) Murphy <\fI\%jamiemurphyit@gmail.com\fP> .TP .B maturity new .TP .B platform any .UNINDENT .SS Usage .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To be able to use this module you need to enable RESTCONF on your device and have https enabled. .sp Cisco Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C switch# conf t switch(config)# restconf switch(config)# ip http secure\-server .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 RESTCONF requires modern OS distributions. This plugin has been written specifically to use JSON RESTCONF endpoints .UNINDENT .UNINDENT .SS Pillar .sp The \fBrestconf\fP proxy configuration requires the following parameters in order to connect to the network switch: .INDENT 0.0 .TP .B transport: \fBhttps\fP (str) Specifies the type of connection transport to use. Valid values for the connection are \fBhttps\fP, and \fBhttp\fP\&. The RESTCONF standard explicitly requires https, but http is included as an option as some manufacturers have ignored this requirement. .TP .B hostname: (str) The IP address or DNS host name of the RESTCONF device. .TP .B username: (str) The username for the device to authenticate the RESTCONF requests. .TP .B password: (str) The password for the device to authenticate the RESTCONF requests. .TP .B verify: \fBTrue\fP or \fBFalse\fP (str, optional, default:true) Verify the RESTCONF SSL certificate? .sp When there is no certificate configuration on the device and this option is set as \fBTrue\fP (default), the commands will fail with the following error: \fBSSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed\fP\&. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 In this case, you either need to configure a proper certificate on the device (\fIrecommended\fP), or bypass the checks setting this argument as \fBFalse\fP with all the security risks considered as you may be MITM\(aqd. .UNINDENT .UNINDENT .UNINDENT .SS Proxy Pillar Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: restconf host: switch1.example.com username: example password: example verify: false .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.restconf.connection_test() Runs a connection test via http/https. Returns an array. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.restconf.init(opts) Required. Initialize device config and test an initial connection .UNINDENT .INDENT 0.0 .TP .B salt.proxy.restconf.initialized() Connection finished initializing? .UNINDENT .INDENT 0.0 .TP .B salt.proxy.restconf.ping() Triggers connection test. Returns True or False .UNINDENT .INDENT 0.0 .TP .B salt.proxy.restconf.request(path, method=\(aqGET\(aq, dict_payload=None) Trigger http request to device .UNINDENT .INDENT 0.0 .TP .B salt.proxy.restconf.shutdown(opts) Closes connection with the device. .UNINDENT .SS salt.proxy.ssh_sample .sp 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. .INDENT 0.0 .TP .B salt.proxy.ssh_sample.fns() Method called by grains module. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.grains() Get the grains from the proxied device .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.grains_refresh() Refresh the grains from the proxied device .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.init(opts) Required. Can be used to initialize the server connection. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.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 .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.package_install(name, **kwargs) Install a \(dqpackage\(dq on the ssh server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.package_list() List \(dqpackages\(dq by executing a command via ssh This function is called in response to the salt command .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt target_minion pkg.list_pkgs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.package_remove(name) Remove a \(dqpackage\(dq on the ssh server .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.parse(out) Extract json from out. .INDENT 7.0 .TP .B Parameter out: Type string. The data returned by the ssh command. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.ping() Required. Ping the device on the other end of the connection .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.service_list() Start a \(dqservice\(dq on the ssh server .sp New in version 2015.8.2. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.service_restart(name) Restart a \(dqservice\(dq on the ssh server .sp New in version 2015.8.2. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.service_start(name) Start a \(dqservice\(dq on the ssh server .sp New in version 2015.8.2. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.service_stop(name) Stop a \(dqservice\(dq on the ssh server .sp New in version 2015.8.2. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.ssh_sample.shutdown(opts) Disconnect .UNINDENT .SS salt.proxy.vcenter .sp Proxy Minion interface module for managing VMWare vCenters. .INDENT 0.0 .TP .B codeauthor \fIRod McKenzie (roderick.mckenzie@morganstanley.com)\fP .TP .B codeauthor \fIAlexandru Bleotu (alexandru.bleotu@morganstanley.com)\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 ESXi State Module was developed against. .SS Configuration .sp To use this proxy module, please use on of the following configurations: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: vcenter vcenter: <ip or dns name of parent vcenter> username: <vCenter username> mechanism: userpass passwords: \- first_password \- second_password \- third_password proxy: proxytype: vcenter vcenter: <ip or dns name of parent vcenter> username: <vCenter username> domain: <user domain> mechanism: sspi principal: <host kerberos principal> .ft P .fi .UNINDENT .UNINDENT .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 Proxy Module, set this to \fBvcenter\fP\&. .SS vcenter .sp The location of the VMware vCenter server (host of ip). Required .SS username .sp The username used to login to the vcenter, such as \fBroot\fP\&. Required only for userpass. .SS mechanism .sp The mechanism used to connect to the vCenter server. Supported values are \fBuserpass\fP and \fBsspi\fP\&. Required. .SS passwords .sp A list of passwords to be used to try and login to the vCenter server. At least one password in this list is required if mechanism is \fBuserpass\fP .sp The proxy integration will try the passwords listed in order. .SS domain .sp User domain. Required if mechanism is \fBsspi\fP .SS principal .sp Kerberos principal. Rquired if mechanism is \fBsspi\fP .SS protocol .sp If the vCenter is not using the default protocol, set this value to an alternate protocol. Default is \fBhttps\fP\&. .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 Salt Proxy .sp After your pillar is in place, you can test the proxy. The proxy can run on any machine that has network connectivity to your Salt Master and to the vCenter server in the pillar. SaltStack recommends that the machine running the salt\-proxy process also run a regular minion, though it is not strictly necessary. .sp On the machine that will run the proxy, make sure there is an \fB/etc/salt/proxy\fP file with at least the following in it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: <ip or hostname of salt\-master> .ft P .fi .UNINDENT .UNINDENT .sp You can then start the salt\-proxy process with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid <id of the cluster> .ft P .fi .UNINDENT .UNINDENT .sp You may want to add \fB\-l debug\fP to run the above in the foreground in debug mode just to make sure everything is OK. .sp Next, accept the key for the proxy on your salt\-master, just like you would for a regular minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-a <id you gave the vcenter host> .ft P .fi .UNINDENT .UNINDENT .sp You can confirm that the pillar data is in place for the proxy: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <id> pillar.items .ft P .fi .UNINDENT .UNINDENT .sp And now you should be able to ping the ESXi host to make sure it is responding: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <id> test.ping .ft P .fi .UNINDENT .UNINDENT .sp At this point you can execute one\-off commands against the vcenter. For example, you can get if the proxy can actually connect to the vCenter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt <id> vsphere.test_vcenter_connection .ft P .fi .UNINDENT .UNINDENT .sp Note that you don\(aqt need to provide credentials or an ip/hostname. Salt knows to use the credentials you stored in Pillar. .sp It\(aqs important to understand how this particular proxy works. \fBSalt.modules.vsphere\fP is a standard Salt execution module. .sp If you pull up the docs for it you\(aqll see that almost every function in the module takes credentials and a targets either a vcenter or a host. When credentials and a host aren\(aqt passed, Salt runs commands through \fBpyVmomi\fP against the local machine. If you wanted, you could run functions from this module on any host where an appropriate version of \fBpyVmomi\fP is installed, and that host would reach out over the network and communicate with the ESXi host. .INDENT 0.0 .TP .B salt.proxy.vcenter.find_credentials() Cycle through all the possible credentials and return the first one that works. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.vcenter.get_details() Function that returns the cached details .UNINDENT .INDENT 0.0 .TP .B salt.proxy.vcenter.init(opts) This function gets called when the proxy starts up. For login the protocol and port are cached. .UNINDENT .INDENT 0.0 .TP .B salt.proxy.vcenter.ping() Returns True. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt vcenter test.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.proxy.vcenter.shutdown() Shutdown the connection to the proxy device. For this proxy, shutdown is a no\-op. .UNINDENT .SS queue modules .TS center; |l|l|. _ T{ \fI\%pgjsonb_queue\fP T} T{ New in version 2016.3.0. T} _ T{ \fI\%sqlite_queue\fP T} T{ New in version 2014.7.0. T} _ .TE .SS salt.queues.pgjsonb_queue .sp New in version 2016.3.0. .sp This is a queue with postgres as the backend. It uses the jsonb store to store information for queues. .INDENT 0.0 .TP .B depends python\-psycopg2 .UNINDENT .sp To enable this queue, the following needs to be configured in your master config. These are the defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C queue.pgjsonb.host: \(aqsalt\(aq queue.pgjsonb.user: \(aqsalt\(aq queue.pgjsonb.password: \(aqsalt\(aq queue.pgjsonb.dbname: \(aqsalt\(aq queue.pgjsonb.port: 5432 .ft P .fi .UNINDENT .UNINDENT .sp Use the following Pg database schema: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C CREATE DATABASE salt WITH ENCODING \(aqutf\-8\(aq; \-\- \-\- Table structure for table \(gasalt\(ga \-\- DROP TABLE IF EXISTS salt; CREATE OR REPLACE TABLE salt( id SERIAL PRIMARY KEY, data jsonb NOT NULL ); .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run queue.insert test \(aq{\(dqname\(dq: \(dqredis\(dq, \(dqhost\(dq: \(dq172.16.0.8\(dq, \(dqport\(dq: 6379}\(aq backend=pgjsonb salt\-run queue.process_queue test all backend=pgjsonb .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.queues.pgjsonb_queue.delete(queue, items) Delete an item or items from a queue .UNINDENT .INDENT 0.0 .TP .B salt.queues.pgjsonb_queue.handle_queue_creation(queue) .UNINDENT .INDENT 0.0 .TP .B salt.queues.pgjsonb_queue.insert(queue, items) Add an item or items to a queue .UNINDENT .INDENT 0.0 .TP .B salt.queues.pgjsonb_queue.list_items(queue) List contents of a queue .UNINDENT .INDENT 0.0 .TP .B salt.queues.pgjsonb_queue.list_length(queue) Provide the number of items in a queue .UNINDENT .INDENT 0.0 .TP .B salt.queues.pgjsonb_queue.list_queues() Return a list of Salt Queues on the Salt Master .UNINDENT .INDENT 0.0 .TP .B salt.queues.pgjsonb_queue.pop(queue, quantity=1, is_runner=False) Pop one or more or all items from the queue return them. .UNINDENT .SS salt.queues.sqlite_queue .sp New in version 2014.7.0. .sp This is the default local master event queue built on sqlite. By default, an sqlite3 database file is created in the \fIsqlite_queue_dir\fP which is found at: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /var/cache/salt/master/queues .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs possible to store the sqlite3 database files by setting \fIsqlite_queue_dir\fP to another location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sqlite_queue_dir: /home/myuser/salt/master/queues .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.queues.sqlite_queue.delete(queue, items) Delete an item or items from a queue .UNINDENT .INDENT 0.0 .TP .B salt.queues.sqlite_queue.insert(queue, items) Add an item or items to a queue .UNINDENT .INDENT 0.0 .TP .B salt.queues.sqlite_queue.list_items(queue) List contents of a queue .UNINDENT .INDENT 0.0 .TP .B salt.queues.sqlite_queue.list_length(queue) Provide the number of items in a queue .UNINDENT .INDENT 0.0 .TP .B salt.queues.sqlite_queue.list_queues() Return a list of Salt Queues on the Salt Master .UNINDENT .INDENT 0.0 .TP .B salt.queues.sqlite_queue.pop(queue, quantity=1, is_runner=False) Pop one or more or all items from the queue return them. .UNINDENT .SS roster modules .TS center; |l|l|. _ T{ \fI\%ansible\fP T} T{ Read in an Ansible inventory file or script. T} _ T{ \fI\%cache\fP T} T{ The \fBcache\fP roster provides a flexible interface to the Salt Masters\(aq minion cache to access regular minions over \fBsalt\-ssh\fP\&. T} _ T{ \fI\%cloud\fP T} T{ Use the cloud cache on the master to derive IPv4 addresses based on minion ID. T} _ T{ \fI\%clustershell\fP T} T{ This roster resolves hostname in a pdsh/clustershell style. T} _ T{ \fI\%dir\fP T} T{ Create a salt roster out of a flat directory of files. T} _ T{ \fI\%flat\fP T} T{ Read in the roster from a flat file using the renderer system T} _ T{ \fI\%range\fP T} T{ This roster resolves targets from a range server. T} _ T{ \fI\%scan\fP T} T{ Scan a netmask or ipaddr for open ssh ports T} _ T{ \fI\%sshconfig\fP T} T{ Parses roster entries out of Host directives from SSH config T} _ T{ \fI\%sshknownhosts\fP T} T{ Parses roster entries out of Host directives from SSH known_hosts T} _ T{ \fI\%terraform\fP T} T{ Dynamic roster from terraform current state T} _ .TE .SS salt.roster.ansible .sp Read in an Ansible inventory file or script. .sp Flat inventory files should be in the regular ansible inventory format. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /tmp/example_roster [servers] salt.gtmanfred.com ansible_ssh_user=gtmanfred ansible_ssh_host=127.0.0.1 ansible_ssh_port=22 ansible_ssh_pass=\(aqpassword\(aq ansible_sudo_pass=\(aqpassword\(aq [desktop] home ansible_ssh_user=gtmanfred ansible_ssh_host=12.34.56.78 ansible_ssh_port=23 ansible_ssh_pass=\(aqpassword\(aq ansible_sudo_pass=\(aqpassword\(aq [computers:children] desktop servers [computers:vars] http_port=80 .ft P .fi .UNINDENT .UNINDENT .sp then salt\-ssh can be used to hit any of them .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [~]# salt\-ssh \-\-roster=ansible \-\-roster\-file=/tmp/example_roster \-N all test.ping salt.gtmanfred.com: True home: True [~]# salt\-ssh \-\-roster=ansible \-\-roster\-file=/tmp/example_roster \-N desktop test.ping home: True [~]# salt\-ssh \-\-roster=ansible \-\-roster\-file=/tmp/example_roster \-N computers test.ping salt.gtmanfred.com: True home: True [~]# salt\-ssh \-\-roster=ansible \-\-roster\-file=/tmp/example_roster salt.gtmanfred.com test.ping salt.gtmanfred.com: True .ft P .fi .UNINDENT .UNINDENT .sp There is also the option of specifying a dynamic inventory, and generating it on the fly .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!/bin/bash # filename: /etc/salt/hosts echo \(aq{ \(dqservers\(dq: [ \(dqsalt.gtmanfred.com\(dq ], \(dqdesktop\(dq: [ \(dqhome\(dq ], \(dqcomputers\(dq: { \(dqhosts\(dq: [], \(dqchildren\(dq: [ \(dqdesktop\(dq, \(dqservers\(dq ], \(dqvars\(dq: { \(dqhttp_port\(dq: 80 } }, \(dq_meta\(dq: { \(dqhostvars\(dq: { \(dqsalt.gtmanfred.com\(dq: { \(dqansible_ssh_user\(dq: \(dqgtmanfred\(dq, \(dqansible_ssh_host\(dq: \(dq127.0.0.1\(dq, \(dqansible_sudo_pass\(dq: \(dqpassword\(dq, \(dqansible_ssh_pass\(dq: \(dqpassword\(dq, \(dqansible_ssh_port\(dq: 22 }, \(dqhome\(dq: { \(dqansible_ssh_user\(dq: \(dqgtmanfred\(dq, \(dqansible_ssh_host\(dq: \(dq12.34.56.78\(dq, \(dqansible_sudo_pass\(dq: \(dqpassword\(dq, \(dqansible_ssh_pass\(dq: \(dqpassword\(dq, \(dqansible_ssh_port\(dq: 23 } } } }\(aq .ft P .fi .UNINDENT .UNINDENT .sp This is the format that an inventory script needs to output to work with ansible, and thus here. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [~]# salt\-ssh \-\-roster=ansible \-\-roster\-file /etc/salt/hosts salt.gtmanfred.com test.ping salt.gtmanfred.com: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 A dynamic inventory script must have the executable bit set. In the above example, \fBchmod +x /etc/salt/hosts\fP\&. .UNINDENT .UNINDENT .sp Any of the [groups] or direct hostnames will return. The \(aqall\(aq is special, and returns everything. .INDENT 0.0 .TP .B salt.roster.ansible.targets(tgt, tgt_type=\(aqglob\(aq, **kwargs) Return the targets from the ansible inventory_file Default: /etc/salt/roster .UNINDENT .SS salt.roster.cache .sp The \fBcache\fP roster provides a flexible interface to the Salt Masters\(aq minion cache to access regular minions over \fBsalt\-ssh\fP\&. .sp New in version 2017.7.0: .INDENT 0.0 .IP \(bu 2 grains, pillar, mine data matching .IP \(bu 2 SDB URLs .IP \(bu 2 IPv6 support .IP \(bu 2 roster_order per config key .IP \(bu 2 default order changed to industry\-wide best practices .IP \(bu 2 CIDR range selection .UNINDENT .SS Targeting .sp This roster supports all matching and targeting of the Salt Master. The matching will be done using only the Salt Master\(aqs cache. .SS The Roster Order .sp The roster\(aqs composition can be configured using \fBroster_order\fP\&. In the \fBroster_order\fP you can define \fIany\fP roster key and fill it with a parameter overriding the one in \fBroster_defaults\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C roster_order: host: id # use the minion id as hostname .ft P .fi .UNINDENT .UNINDENT .sp You can define lists of parameters as well, the first result from the list will become the value. .SS Selecting a host .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # default roster_order: host: \- ipv6\-private # IPv6 addresses in private ranges \- ipv6\-global # IPv6 addresses in global ranges \- ipv4\-private # IPv4 addresses in private ranges \- ipv4\-public # IPv4 addresses in public ranges \- ipv4\-local # loopback addresses .ft P .fi .UNINDENT .UNINDENT .sp This is the default \fBroster_order\fP\&. It prefers IPv6 over IPv4 addresses and private addresses over public ones. The relevant data will be fetched from the cache in\-order, and the first match will fill the \fBhost\fP key. .sp Other address selection parameters are also possible: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C roster_order: host: \- global|public|private|local # Both IPv6 and IPv4 addresses in that range \- 2000::/3 # CIDR networks, both IPv4 and IPv6 are supported .ft P .fi .UNINDENT .UNINDENT .SS Using cached data .sp Several cached libraries can be selected using the \fBlibrary: \(ga\(ga prefix, followed by the library key. This can be referenced using the same \(ga\(ga:\fP syntax as e.g. \fI\%pillar.get\fP\&. Lists of references are also supported during the lookup, as are Salt SDB URLs. .sp This should be especially useful for the other roster keys: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C roster_order: host: \- grain: fqdn_ip4 # Lookup this grain \- mine: network.ip_addrs # Mine data lookup works the same password: sdb://vault/ssh_pass # Salt SDB URLs are also supported user: \- pillar: ssh:auth:user # Lookup this pillar key \- sdb://osenv/USER # Lookup this env var through sdb priv: \- pillar: # Lists are also supported \- salt:ssh:private_key \- ssh:auth:private_key .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.roster.cache.targets(tgt, tgt_type=\(aqglob\(aq, **kwargs) Return the targets from the Salt Masters\(aq minion cache. All targets and matchers are supported. .sp The resulting roster can be configured using \fBroster_order\fP and \fBroster_default\fP\&. .UNINDENT .SS salt.roster.cloud .sp Use the cloud cache on the master to derive IPv4 addresses based on minion ID. .sp This roster requires that the minion in question was created using at least the 2015.5.0 version of Salt Cloud. Starting with the 2015.5.0 release, Salt Cloud maintains an index of minions that it creates and deletes. This index tracks the provider and profile configuration used to provision the minion, including authentication information. So long as this configuration remains current, it can be used by Salt SSH to log into any minion in the index. .sp To connect as a user other than root, modify the cloud configuration file usually located at /etc/salt/cloud. For example, add the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_username: my_user sudo: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.roster.cloud.extract_ipv4(roster_order, ipv4) Extract the preferred IP address from the ipv4 grain .UNINDENT .INDENT 0.0 .TP .B salt.roster.cloud.targets(tgt, tgt_type=\(aqglob\(aq, **kwargs) Return the targets from the flat yaml file, checks opts for location but defaults to /etc/salt/roster .UNINDENT .SS salt.roster.clustershell .sp This roster resolves hostname in a pdsh/clustershell style. .INDENT 0.0 .TP .B depends clustershell, \fI\%https://github.com/cea\-hpc/clustershell\fP .UNINDENT .sp When you want to use host globs for target matching, use \fB\-\-roster clustershell\fP\&. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh \-\-roster clustershell \(aqserver_[1\-10,21\-30],test_server[5,7,9]\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.roster.clustershell.targets(tgt, tgt_type=\(aqglob\(aq, **kwargs) Return the targets .UNINDENT .SS salt.roster.dir .sp Create a salt roster out of a flat directory of files. .sp Each filename in the directory is a minion id. The contents of each file is rendered using the salt renderer system. .sp Consider the following configuration for example: .sp config/master: .INDENT 0.0 .INDENT 3.5 \&... roster: dir roster_dir: config/roster.d \&... .UNINDENT .UNINDENT .sp Where the directory config/roster.d contains two files: .sp config/roster.d/minion\-x: .INDENT 0.0 .INDENT 3.5 host: minion\-x.example.com port: 22 sudo: true user: ubuntu .UNINDENT .UNINDENT .sp config/roster.d/minion\-y: .INDENT 0.0 .INDENT 3.5 host: minion\-y.example.com port: 22 sudo: true user: gentoo .UNINDENT .UNINDENT .sp The roster would find two minions: minion\-x and minion\-y, with the given host, port, sudo and user settings. .sp The directory roster also extends the concept of roster defaults by supporting a roster_domain value in config: .INDENT 0.0 .INDENT 3.5 \&... roster_domain: example.org \&... .UNINDENT .UNINDENT .sp If that option is set, then any roster without a \(aqhost\(aq setting will have an implicit host of its minion id + \(aq.\(aq + the roster_domain. (The default roster_domain is the empty string, so you can also name the files the fully qualified name of each host. However, if you do that, then the fully qualified name of each host is also the minion id.) .sp This makes it possible to avoid having to specify the hostnames when you always want them to match their minion id plus some domain. .INDENT 0.0 .TP .B salt.roster.dir.targets(tgt, tgt_type=\(aqglob\(aq, **kwargs) Return the targets from the directory of flat yaml files, checks opts for location. .UNINDENT .SS salt.roster.flat .sp Read in the roster from a flat file using the renderer system .INDENT 0.0 .TP .B salt.roster.flat.targets(tgt, tgt_type=\(aqglob\(aq, **kwargs) Return the targets from the flat yaml file, checks opts for location but defaults to /etc/salt/roster .UNINDENT .SS salt.roster.range .sp This roster resolves targets from a range server. .INDENT 0.0 .TP .B depends seco.range, \fI\%https://github.com/ytoolshed/range\fP .UNINDENT .sp When you want to use a range query for target matching, use \fB\-\-roster range\fP\&. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh \-\-roster range \(aq%%%example.range.cluster\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.roster.range.target_glob(tgt, hosts) .UNINDENT .INDENT 0.0 .TP .B salt.roster.range.target_range(tgt, hosts) .UNINDENT .INDENT 0.0 .TP .B salt.roster.range.targets(tgt, tgt_type=\(aqrange\(aq, **kwargs) Return the targets from a range query .UNINDENT .SS salt.roster.scan .sp Scan a netmask or ipaddr for open ssh ports .INDENT 0.0 .TP .B class salt.roster.scan.RosterMatcher(tgt, tgt_type) Matcher for the roster data structure .INDENT 7.0 .TP .B targets() Return ip addrs based on netmask, sitting in the \(dqglob\(dq spot because it is the default .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.roster.scan.targets(tgt, tgt_type=\(aqglob\(aq, **kwargs) Return the targets from the flat yaml file, checks opts for location but defaults to /etc/salt/roster .UNINDENT .SS salt.roster.sshconfig .sp Parses roster entries out of Host directives from SSH config .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh \-\-roster sshconfig \(aq*\(aq \-r \(dqecho hi\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.roster.sshconfig.RosterMatcher(raw, tgt, tgt_type) Matcher for the roster data structure .INDENT 7.0 .TP .B get_data(minion) Return the configured ip .UNINDENT .INDENT 7.0 .TP .B ret_glob_minions() Return minions that match via glob .UNINDENT .INDENT 7.0 .TP .B targets() Execute the correct tgt_type routine and return .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.roster.sshconfig.parse_ssh_config(lines) Parses lines from the SSH config to create roster targets. .INDENT 7.0 .TP .B Parameters \fBlines\fP \-\- Individual lines from the ssh config file .TP .B Returns Dictionary of targets in similar style to the flat roster .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.roster.sshconfig.targets(tgt, tgt_type=\(aqglob\(aq, **kwargs) Return the targets from the flat yaml file, checks opts for location but defaults to /etc/salt/roster .UNINDENT .SS salt.roster.sshknownhosts .sp Parses roster entries out of Host directives from SSH known_hosts .sp New in version 3006.0. .sp Sample configuration: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBknown_hosts\fP file only contains hostname/IP. To pass other parameters, use \fBroster_defaults\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_known_hosts_file: /Users/user1/.ssh/known_hosts roster_defaults: user: user1 sudo: True .ft P .fi .UNINDENT .UNINDENT .sp Now you can use the module .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh \-\-roster sshknownhosts \(aq*\(aq \-r \(dqecho hi\(dq .ft P .fi .UNINDENT .UNINDENT .sp Or with a Saltfile .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh: ssh_known_hosts_file: /Users/user1/.ssh/known_hosts .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh \-\-roster sshknownhosts \(aq*\(aq \-r \(dqecho hi\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.roster.sshknownhosts.targets(tgt, tgt_type=\(aqglob\(aq) Return the targets from a known_hosts file .UNINDENT .SS salt.roster.terraform .SS Dynamic roster from terraform current state .sp This roster module allows you dynamically generate the roster from the terraform resources defined with the \fI\%Terraform Salt\fP provider. .sp It exposes all salt_host resources with the same attributes to the salt\-ssh roster, making it completely independent of the type of terraform resource, and providing the integration using terraform constructs with interpolation. .SS Basic Example .sp Given a simple salt\-ssh tree with a Saltfile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh: config_dir: etc/salt max_procs: 30 wipe_ssh: True .ft P .fi .UNINDENT .UNINDENT .sp and \fBetc/salt/master\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root_dir: . file_roots: base: \- srv/salt pillar_roots: base: \- srv/pillar roster: terraform .ft P .fi .UNINDENT .UNINDENT .sp In the same folder as your \fBSaltfile\fP, create terraform file with resources like cloud instances, virtual machines, etc. For every single one of those that you want to manage with Salt, create a \fBsalt_host\fP resource: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C resource \(dqsalt_host\(dq \(dqdbminion\(dq { salt_id = \(dqdbserver\(dq host = \(dq${libvirt_domain.vm\-db.network_interface.0.addresses.0}\(dq user = \(dqroot\(dq passwd = \(dqlinux\(dq } .ft P .fi .UNINDENT .UNINDENT .sp You can use the count attribute to create multiple roster entries with a single definition. Please refer to the \fI\%Terraform Salt\fP provider for more detailed examples. .INDENT 0.0 .TP .B salt.roster.terraform.targets(tgt, tgt_type=\(aqglob\(aq, **kwargs) Returns the roster from the terraform state file, checks opts for location, but defaults to terraform.tfstate .UNINDENT .SS runner modules .TS center; |l|l|. _ T{ \fI\%asam\fP T} T{ Novell ASAM Runner T} _ T{ \fI\%auth\fP T} T{ Authentication runner for creating, deleting, and managing eauth tokens. T} _ T{ \fI\%bgp\fP T} T{ BGP Finder T} _ T{ \fI\%cache\fP T} T{ Return cached data from minions T} _ T{ \fI\%cloud\fP T} T{ The Salt Cloud Runner T} _ T{ \fI\%config\fP T} T{ This runner is designed to mirror the execution module config.py, but for master settings T} _ T{ \fI\%ddns\fP T} T{ Dynamic DNS Runner T} _ T{ \fI\%digicertapi\fP T} T{ Support for Digicert. T} _ T{ \fI\%doc\fP T} T{ A runner module to collect and display the inline documentation from the various module types T} _ T{ \fI\%drac\fP T} T{ Manage Dell DRAC from the Master T} _ T{ \fI\%error\fP T} T{ Error generator to enable integration testing of salt runner error handling T} _ T{ \fI\%event\fP T} T{ Module for sending events using the runner system. T} _ T{ \fI\%f5\fP T} T{ Runner to provide F5 Load Balancer functionality T} _ T{ \fI\%fileserver\fP T} T{ Directly manage the Salt fileserver plugins T} _ T{ \fI\%git_pillar\fP T} T{ Runner module to directly manage the git external pillar T} _ T{ \fI\%http\fP T} T{ Module for making various web calls. T} _ T{ \fI\%jobs\fP T} T{ A convenience system to manage jobs, both active and already run T} _ T{ \fI\%launchd\fP T} T{ Manage launchd plist files T} _ T{ \fI\%lxc\fP T} T{ Control Linux Containers via Salt T} _ T{ \fI\%manage\fP T} T{ General management functions for salt, tools like seeing what hosts are up and what hosts are down T} _ T{ \fI\%match\fP T} T{ Run matchers from the master context. T} _ T{ \fI\%mattermost\fP T} T{ Module for sending messages to Mattermost T} _ T{ \fI\%mine\fP T} T{ A runner to access data from the salt mine T} _ T{ \fI\%nacl\fP T} T{ This module helps include encrypted passwords in pillars, grains and salt state files. T} _ T{ \fI\%net\fP T} T{ NET Finder T} _ T{ \fI\%network\fP T} T{ Network tools to run from the Master T} _ T{ \fI\%pagerduty\fP T} T{ Runner Module for Firing Events via PagerDuty T} _ T{ \fI\%pillar\fP T} T{ Functions to interact with the pillar compiler on the master T} _ T{ \fI\%pkg\fP T} T{ Package helper functions using \fBsalt.modules.pkg\fP T} _ T{ \fI\%queue\fP T} T{ General management and processing of queues. T} _ T{ \fI\%reactor\fP T} T{ A convenience system to manage reactors T} _ T{ \fI\%salt\fP T} T{ This runner makes Salt\(aqs execution modules available on the salt master. T} _ T{ \fI\%saltutil\fP T} T{ The Saltutil runner is used to sync custom types to the Master. T} _ T{ \fI\%sdb\fP T} T{ Runner for setting and querying data via the sdb API on the master T} _ T{ \fI\%smartos_vmadm\fP T} T{ Runner for SmartOS minions control vmadm T} _ T{ \fI\%spacewalk\fP T} T{ Spacewalk Runner T} _ T{ \fI\%ssh\fP T} T{ A Runner module interface on top of the salt\-ssh Python API. T} _ T{ \fI\%state\fP T} T{ Execute orchestration functions T} _ T{ \fI\%survey\fP T} T{ A general map/reduce style salt runner for aggregating results returned by several different minions. T} _ T{ \fI\%test\fP T} T{ This runner is used only for test purposes and serves no production purpose T} _ T{ \fI\%thin\fP T} T{ The thin runner is used to manage the salt thin systems. T} _ T{ \fI\%vault\fP T} T{ T} _ T{ \fI\%venafiapi\fP T} T{ Support for Venafi T} _ T{ \fI\%virt\fP T} T{ Control virtual machines via Salt T} _ T{ \fI\%vistara\fP T} T{ Vistara Runner T} _ T{ \fI\%winrepo\fP T} T{ Runner to manage Windows software repo T} _ .TE .SS salt.runners.asam .SS Novell ASAM Runner .sp New in version 2015.8.0. .sp Runner to interact with Novell ASAM Fan\-Out Driver .INDENT 0.0 .TP .B codeauthor Nitin Madhok <\fI\%nmadhok@g.clemson.edu\fP> .UNINDENT .sp To use this runner, set up the Novell Fan\-Out Driver URL, username and password in the master configuration at \fB/etc/salt/master\fP or \fB/etc/salt/master.d/asam.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C asam: prov1.domain.com username: \(dqtestuser\(dq password: \(dqverybadpass\(dq verify_ssl: true prov2.domain.com username: \(dqtestuser\(dq password: \(dqverybadpass\(dq verify_ssl: true .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 Fan\-Out Driver server is not using the defaults. Default is \fBprotocol: https\fP and \fBport: 3451\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.runners.asam.ASAMHTMLParser .INDENT 7.0 .TP .B handle_starttag(tag, attrs) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.asam.add_platform(name, platform_set, server_url) To add an ASAM platform using the specified ASAM platform set on the Novell Fan\-Out Driver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run asam.add_platform my\-test\-vm test\-platform\-set prov1.domain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.asam.list_platform_sets(server_url) To list all ASAM platform sets present on the Novell Fan\-Out Driver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run asam.list_platform_sets prov1.domain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.asam.list_platforms(server_url) To list all ASAM platforms present on the Novell Fan\-Out Driver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run asam.list_platforms prov1.domain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.asam.remove_platform(name, server_url) To remove specified ASAM platform from the Novell Fan\-Out Driver .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run asam.remove_platform my\-test\-vm prov1.domain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.auth .sp Authentication runner for creating, deleting, and managing eauth tokens. .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.runners.auth.del_token(token) Delete an eauth token by name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run auth.del_token 6556760736e4077daa601baec2b67c24 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.auth.mk_token(**load) Create an eauth token using provided credentials .sp Non\-root users may specify an expiration date \-\- if allowed via the \fI\%token_expire_user_override\fP setting \-\- by passing an additional \fBtoken_expire\fP param. This overrides the \fI\%token_expire\fP setting of the same name in the Master config and is how long a token should live in seconds. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run auth.mk_token username=saltdev password=saltdev eauth=auto # Create a token valid for three years. salt\-run auth.mk_token username=saltdev password=saltdev eauth=auto \e token_expire=94670856 # Calculate the number of seconds using expr. salt\-run auth.mk_token username=saltdev password=saltdev eauth=auto \e token_expire=$(expr \e( 365 \e* 24 \e* 60 \e* 60 \e) \e* 3) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.bgp .SS BGP Finder .sp New in version 2017.7.0. .sp Runner to search BGP neighbors details. .SS Configuration .INDENT 0.0 .IP \(bu 2 Minion (proxy) config .INDENT 2.0 .INDENT 3.5 The \fBbgp.neighbors\fP function must be appened in the list of \fBmine_functions\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_functions: bgp.neighbors: [] .ft P .fi .UNINDENT .UNINDENT .sp Which instructs Salt to cache the data returned by the \fBneighbors\fP function from the \fI\%NAPALM BGP module\fP\&. .sp How often the mines are refreshed, can be specified using: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_interval: <X minutes> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 Master config .INDENT 2.0 .INDENT 3.5 By default the following options can be configured on the master. They are not mandatory, but available in case the user has different requirements. .INDENT 0.0 .TP .B tgt: \fB*\fP From what minions will collect the mine data. Default: \fB*\fP (collect mine data from all minions) .TP .B tgt_type: \fBglob\fP Minion matching expression form. Default: \fBglob\fP\&. .TP .B return_fields What fields to return in the output. It can display all the fields from the \fBneighbors\fP function from the \fI\%NAPALM BGP module\fP\&. .sp Some fields cannot be removed: .INDENT 7.0 .IP \(bu 2 \fBas_number\fP: the AS number of the neighbor .IP \(bu 2 \fBdevice\fP: the minion ID .IP \(bu 2 \fBneighbor_address\fP: the neighbor remote IP address .UNINDENT .sp By default, the following extra fields are returned (displayed): .INDENT 7.0 .IP \(bu 2 \fBconnection_stats\fP: connection stats, as described below .IP \(bu 2 \fBimport_policy\fP: the name of the import policy .IP \(bu 2 \fBexport_policy\fP: the name of the export policy .UNINDENT .sp Special fields: .INDENT 7.0 .IP \(bu 2 \fBvrf\fP: return the name of the VRF. .IP \(bu 2 \fBconnection_stats\fP: returning an output of the form \fB<State> <Active>/<Received>/<Accepted>/<Damped>\fP, e.g. \fBEstablished 398/399/399/0\fP similar to the usual output from network devices. .IP \(bu 2 \fBinterface_description\fP: matches the neighbor details with the corresponding interface and returns its description. This will reuse functionality from the \fI\%net runner\fP, so the user needs to enable the mines as specified in the documentation. .IP \(bu 2 \fBinterface_name\fP: matches the neighbor details with the corresponding interface and returns the name. Similar to \fBinterface_description\fP, this will reuse functionality from the \fI\%net runner\fP, so the user needs to enable the mines as specified in the documentation. .UNINDENT .TP .B display: \fBTrue\fP Display on the screen or return structured object? Default: \fBTrue\fP (return on the CLI). .TP .B outputter: \fBtable\fP Specify the outputter name when displaying on the CLI. Default: \fI\%table\fP\&. .UNINDENT .sp Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C runners: bgp: tgt: \(aqedge*\(aq tgt_type: \(aqglob\(aq return_fields: \- up \- connection_state \- previous_connection_state \- suppress_4byte_as \- holdtime \- flap_count outputter: yaml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.bgp.neighbors(*asns, **kwargs) Search for BGP neighbors details in the mines of the \fBbgp.neighbors\fP function. .sp Arguments: .INDENT 7.0 .TP .B asns A list of AS numbers to search for. The runner will return only the neighbors of these AS numbers. .TP .B device Filter by device name (minion ID). .TP .B ip Search BGP neighbor using the IP address. In multi\-VRF environments, the same IP address could be used by more than one neighbors, in different routing tables. .TP .B network Search neighbors within a certain IP network. .TP .B title Custom title. .TP .B display: \fBTrue\fP Display on the screen or return structured object? Default: \fBTrue\fP (return on the CLI). .TP .B outputter: \fBtable\fP Specify the outputter name when displaying on the CLI. Default: \fI\%table\fP\&. .UNINDENT .sp In addition, any field from the output of the \fBneighbors\fP function from the \fI\%NAPALM BGP module\fP can be used as a filter. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run bgp.neighbors 13335 15169 salt\-run bgp.neighbors 13335 ip=172.17.19.1 salt\-run bgp.neighbors multipath=True salt\-run bgp.neighbors up=False export_policy=my\-export\-policy multihop=False salt\-run bgp.neighbors network=192.168.0.0/16 .ft P .fi .UNINDENT .UNINDENT .sp Output example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C BGP Neighbors for 13335, 15169 ________________________________________________________________________________________________________________________________________________________________ | Device | AS Number | Neighbor Address | State|#Active/Received/Accepted/Damped | Policy IN | Policy OUT | ________________________________________________________________________________________________________________________________________________________________ | edge01.bjm01 | 13335 | 172.17.109.11 | Established 0/398/398/0 | import\-policy | export\-policy | ________________________________________________________________________________________________________________________________________________________________ | edge01.bjm01 | 13335 | 172.17.109.12 | Established 397/398/398/0 | import\-policy | export\-policy | ________________________________________________________________________________________________________________________________________________________________ | edge01.flw01 | 13335 | 192.168.172.11 | Established 1/398/398/0 | import\-policy | export\-policy | ________________________________________________________________________________________________________________________________________________________________ | edge01.oua01 | 13335 | 172.17.109.17 | Established 0/0/0/0 | import\-policy | export\-policy | ________________________________________________________________________________________________________________________________________________________________ | edge01.bjm01 | 15169 | 2001::1 | Established 102/102/102/0 | import\-policy | export\-policy | ________________________________________________________________________________________________________________________________________________________________ | edge01.bjm01 | 15169 | 2001::2 | Established 102/102/102/0 | import\-policy | export\-policy | ________________________________________________________________________________________________________________________________________________________________ | edge01.tbg01 | 13335 | 192.168.172.17 | Established 0/1/1/0 | import\-policy | export\-policy | ________________________________________________________________________________________________________________________________________________________________ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.cache .sp Return cached data from minions .INDENT 0.0 .TP .B salt.runners.cache.clear_all(tgt=None, tgt_type=\(aqglob\(aq) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Clear the cached pillar, grains, and mine data of the targeted minions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.clear_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.clear_git_lock(role, remote=None, **kwargs) New in version 2015.8.2. .sp Remove the update locks for Salt components (gitfs, git_pillar, winrepo) which use gitfs backend code from salt.utils.gitfs. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Running \fI\%cache.clear_all\fP will not include this function as it does for pillar, grains, and mine. .sp Additionally, executing this function with a \fBrole\fP of \fBgitfs\fP is equivalent to running \fBsalt\-run fileserver.clear_lock backend=git\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B role Which type of lock to remove (\fBgitfs\fP, \fBgit_pillar\fP, or \fBwinrepo\fP) .TP .B remote If specified, then any remotes which contain the passed string will have their lock cleared. For example, a \fBremote\fP value of \fBgithub\fP will remove the lock from all github.com remotes. .TP .B type update,checkout,mountpoint The types of lock to clear. Can be one or more of \fBupdate\fP, \fBcheckout\fP, and \fBmountpoint\fP, and can be passed either as a comma\-separated or Python list. .sp New in version 2015.8.8. .sp Changed in version 2018.3.0: \fBmountpoint\fP lock type added .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.clear_git_lock gitfs salt\-run cache.clear_git_lock git_pillar salt\-run cache.clear_git_lock git_pillar type=update salt\-run cache.clear_git_lock git_pillar type=update,checkout salt\-run cache.clear_git_lock git_pillar type=\(aq[\(dqupdate\(dq, \(dqmountpoint\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.clear_grains(tgt=None, tgt_type=\(aqglob\(aq) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Clear the cached grains data of the targeted minions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.clear_grains .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.clear_mine(tgt=None, tgt_type=\(aqglob\(aq) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Clear the cached mine data of the targeted minions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.clear_mine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.clear_mine_func(tgt=None, tgt_type=\(aqglob\(aq, clear_mine_func_flag=None) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Clear the cached mine function data of the targeted minions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.clear_mine_func tgt=\(aq*\(aq clear_mine_func_flag=\(aqnetwork.interfaces\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.clear_pillar(tgt=None, tgt_type=\(aqglob\(aq) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Clear the cached pillar data of the targeted minions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.clear_pillar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.cloud(tgt, provider=None) Return cloud cache data for target. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Only works with glob matching .UNINDENT .UNINDENT .INDENT 7.0 .TP .B tgt Glob Target to match minion ids .TP .B provider Cloud Provider .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.cloud \(aqsalt*\(aq salt\-run cache.cloud glance.example.org provider=openstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.fetch(bank, key, cachedir=None) Fetch data from a salt.cache bank. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.fetch cloud/active/ec2/myec2 myminion cachedir=/var/cache/salt/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.flush(bank, key=None, cachedir=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. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.flush cloud/active/ec2/myec2 cachedir=/var/cache/salt/ salt\-run cache.flush cloud/active/ec2/myec2 myminion cachedir=/var/cache/salt/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.grains(tgt, tgt_type=\(aqglob\(aq, **kwargs) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Return cached grains of the targeted minions. .INDENT 7.0 .TP .B tgt Target to match minion ids. .sp Changed in version 2017.7.5,2018.3.0: The \fBtgt\fP argument is now required to display cached grains. If not used, the function will not return grains. This optional argument will become mandatory in the Salt \fB3001\fP release. .TP .B tgt_type The type of targeting to use for matching, such as \fBglob\fP, \fBlist\fP, etc. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.grains \(aq*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.list_(bank, cachedir=None) Lists entries stored in the specified bank. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.list cloud/active/ec2/myec2 cachedir=/var/cache/salt/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.mine(tgt=None, tgt_type=\(aqglob\(aq, **kwargs) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Return cached mine data of the targeted minions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.mine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.pillar(tgt=None, tgt_type=\(aqglob\(aq, **kwargs) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Return cached pillars of the targeted minions if tgt is set. If tgt is not set will return cached pillars for all minions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.pillar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cache.store(bank, key, data, cachedir=None) Lists entries stored in the specified bank. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cache.store mycache mykey \(aqThe time has come the walrus said\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.cloud .SS The Salt Cloud Runner .sp This runner wraps the functionality of salt cloud making salt cloud routines available to all internal apis via the runner system .INDENT 0.0 .TP .B salt.runners.cloud.action(func=None, cloudmap=None, instances=None, provider=None, instance=None, opts=None, **kwargs) Execute a single action on the given map/provider/instance .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cloud.action start my\-salt\-vm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cloud.create(provider, instances, opts=None, **kwargs) Create an instance using Salt Cloud .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cloud.create my\-ec2\-config myinstance \e image=ami\-1624987f size=\(aqt1.micro\(aq ssh_username=ec2\-user \e securitygroup=default delvol_on_destroy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cloud.destroy(instances, opts=None) Destroy the named vm(s) .UNINDENT .INDENT 0.0 .TP .B salt.runners.cloud.full_query(query_type=\(aqlist_nodes_full\(aq) List all available cloud provider data .UNINDENT .INDENT 0.0 .TP .B salt.runners.cloud.list_images(provider=\(aqall\(aq) List cloud provider images for the given providers .UNINDENT .INDENT 0.0 .TP .B salt.runners.cloud.list_locations(provider=\(aqall\(aq) List cloud provider sizes for the given providers .UNINDENT .INDENT 0.0 .TP .B salt.runners.cloud.list_sizes(provider=\(aqall\(aq) List cloud provider sizes for the given providers .UNINDENT .INDENT 0.0 .TP .B salt.runners.cloud.map_run(path=None, opts=None, **kwargs) Execute a salt cloud map file .UNINDENT .INDENT 0.0 .TP .B salt.runners.cloud.profile(prof=None, instances=None, opts=None, **kwargs) Create a cloud vm with the given profile and instances, instances can be a list or comma\-delimited string .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run cloud.profile prof=my\-ec2 instances=node1,node2,node3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.cloud.query(query_type=\(aqlist_nodes\(aq) List cloud provider data for all providers .UNINDENT .INDENT 0.0 .TP .B salt.runners.cloud.select_query(query_type=\(aqlist_nodes_select\(aq) List selected nodes .UNINDENT .SS salt.runners.config .sp This runner is designed to mirror the execution module config.py, but for master settings .INDENT 0.0 .TP .B salt.runners.config.get(key, default=\(aq\(aq, delimiter=\(aq:\(aq) Retrieve master config options, with optional nesting via the delimiter argument. .sp \fBArguments\fP .sp default .INDENT 7.0 .INDENT 3.5 If the key is not found, the default will be returned instead .UNINDENT .UNINDENT .sp delimiter .INDENT 7.0 .INDENT 3.5 Override the delimiter used to separate nested levels of a data structure. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run config.get gitfs_remotes salt\-run config.get file_roots:base salt\-run config.get file_roots,base delimiter=\(aq,\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.ddns .SS Dynamic DNS Runner .sp New in version 2015.8.0. .sp Runner to interact with DNS server and create/delete/update DNS records .INDENT 0.0 .TP .B codeauthor Nitin Madhok <\fI\%nmadhok@g.clemson.edu\fP> .UNINDENT .INDENT 0.0 .TP .B salt.runners.ddns.add_host(zone, name, ttl, ip, keyname, keyfile, nameserver, timeout, port=53, keyalgorithm=\(aqhmac\-md5\(aq) Create both A and PTR (reverse) records for a host. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run ddns.add_host domain.com my\-test\-vm 3600 10.20.30.40 my\-tsig\-key /etc/salt/tsig.keyring 10.0.0.1 5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.ddns.create(zone, name, ttl, rdtype, data, keyname, keyfile, nameserver, timeout, port=53, keyalgorithm=\(aqhmac\-md5\(aq) Create a DNS record. The nameserver must be an IP address and the master running this runner must have create privileges on that server. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run ddns.create domain.com my\-test\-vm 3600 A 10.20.30.40 my\-tsig\-key /etc/salt/tsig.keyring 10.0.0.1 5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.ddns.delete(zone, name, keyname, keyfile, nameserver, timeout, rdtype=None, data=None, port=53, keyalgorithm=\(aqhmac\-md5\(aq) Delete a DNS record. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run ddns.delete domain.com my\-test\-vm my\-tsig\-key /etc/salt/tsig.keyring 10.0.0.1 5 A .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.ddns.delete_host(zone, name, keyname, keyfile, nameserver, timeout, port=53, keyalgorithm=\(aqhmac\-md5\(aq) Delete both forward (A) and reverse (PTR) records for a host only if the forward (A) record exists. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run ddns.delete_host domain.com my\-test\-vm my\-tsig\-key /etc/salt/tsig.keyring 10.0.0.1 5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.ddns.update(zone, name, ttl, rdtype, data, keyname, keyfile, nameserver, timeout, replace=False, port=53, keyalgorithm=\(aqhmac\-md5\(aq) Replace, or update a DNS record. The nameserver must be an IP address and the master running this runner must have update privileges on that server. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If \fBreplace\fP is set to True, all records for this name and type will first be deleted and then recreated. Default is \fBreplace=False\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run ddns.update domain.com my\-test\-vm 3600 A 10.20.30.40 my\-tsig\-key /etc/salt/tsig.keyring 10.0.0.1 5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.digicertapi .sp Support for Digicert. Heavily based on the Venafi runner by Joseph Hall (\fI\%jphall@saltstack.com\fP). .sp Before using this module you need to register an account with Digicert\(aqs CertCentral. .sp Login to CertCentral, ensure you have a payment method configured and/or there are adequate funds attached to your account. Click the \fBAccount\fP item in the left sidebar, and select \fBAccount Access\fP\&. The right hand pane should show \(dqAccount Access\(dq and a link to create an API key. Create a new API key and assign it to the user that should be attached to requests coming from Salt. .sp NOTE CertCentral will not show the API key again after revealing it the first time. Make sure you copy it right away or you will have to revoke it and generate a new one. .sp Now open \fB/etc/salt/master\fP and add the API key as shown below. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C digicert: api_key: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABC .ft P .fi .UNINDENT .UNINDENT .sp Restart your Salt Master. .sp You can also include default values of the following variables to help with creating CSRs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C digicert: api_key: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABC shatype: sha256 .ft P .fi .UNINDENT .UNINDENT .sp This API currently only supports RSA key types. Support for other key types will be added if interest warrants. .INDENT 0.0 .TP .B salt.runners.digicertapi.del_cached_domain(domains) Delete cached domains from the master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.del_cached_domain domain1.example.com,domain2.example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.gen_csr(minion_id, dns_name, organization_id, ou_name=None, key_len=2048, shatype=\(aqsha256\(aq, password=None) CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.gen_csr <minion_id> <dns_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.gen_key(minion_id, dns_name=None, password=None, key_len=2048) Generate and return a private_key. If a \fBdns_name\fP is passed in, the private_key will be cached under that name. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.gen_key <minion_id> [dns_name] [password] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.get_certificate(order_id=None, certificate_id=None, minion_id=None, cert_format=\(aqpem_all\(aq, filename=None) Retrieve a certificate by order_id or certificate_id and write it to stdout or a filename. .INDENT 7.0 .TP .B A list of permissible cert_formats is here: \fI\%https://www.digicert.com/services/v2/documentation/appendix\-certificate\-formats\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.get_certificate order_id=48929454 cert_format=apache .ft P .fi .UNINDENT .UNINDENT .sp Including a \(aqfilename\(aq will write the certificate to the desired file. Note that some cert formats are zipped files, and some are binary. .sp If the certificate has not been issued, this function will return the order details inside of which will be a status (one of pending, rejected, processing, issued, revoked, canceled, needs_csr, and needs_approval) .sp If for some reason you want to pipe the output of this command to a file or other command you will want to leave off the \fBfilename\fP argument and make sure to include \fB\-\-no\-color\fP so there will be no terminal ANSI escape sequences. .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.get_org_details(organization_id) Return the details for an organization .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.get_org_details 34 .ft P .fi .UNINDENT .UNINDENT .sp Returns a dictionary with the org details, or with \(aqerror\(aq and \(aqstatus\(aq keys. .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.list_domain_cache() List domains that have been cached .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.list_domain_cache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.list_domains(container_id=None) List domains that CertCentral knows about. You can filter by container_id (also known as \(dqDivision\(dq) by passing a container_id. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.list_domains .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.list_orders(status=None) List certificate orders made to CertCentral. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.list_orders .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.list_organizations(container_id=None, include_validation=True) List organizations that CertCentral knows about. You can filter by container_id (also known as \(dqDivision\(dq) by passing a container_id. This function returns validation information by default; pass \fBinclude_validation=False\fP to turn it off. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.list_organizations .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.list_requests(status=None) List certificate requests made to CertCentral. You can filter by status: \fBpending\fP, \fBapproved\fP, \fBrejected\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.list_requests pending .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.order_certificate(minion_id, common_name, organization_id, validity_years, cert_key_passphrase=None, signature_hash=None, key_len=2048, dns_names=None, organization_units=None, server_platform=None, custom_expiration_date=None, comments=None, disable_renewal_notifications=False, product_type_hint=None, renewal_of_order_id=None) Order a certificate. Requires that an Organization has been created inside Digicert\(aqs CertCentral. .sp See here for API documentation: \fI\%https://www.digicert.com/services/v2/documentation/order/order\-ssl\-determinator\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.order_certificate my_minionid my.domain.com 10 3 signature_hash=sha256 dns_names=[\(aqthis.domain.com\(aq, \(aqthat.domain.com\(aq] organization_units=\(aqMy Domain Org Unit\(aq comments=\(aqComment goes here for the approver\(aq .ft P .fi .UNINDENT .UNINDENT .sp This runner can also be used to renew a certificate by passing \fIrenewal_of_order_id\fP\&. Previous order details can be retrieved with digicertapi.list_orders. .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.show_csrs() Show certificate requests for this API key .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.show_csrs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.show_organization(domain) Show organization information, especially the company id .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.show_company example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.digicertapi.show_rsa(minion_id, dns_name) Show a private RSA key .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run digicert.show_rsa myminion domain.example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.doc .sp A runner module to collect and display the inline documentation from the various module types .INDENT 0.0 .TP .B salt.runners.doc.execution() Collect all the sys.doc output from each minion and return the aggregate .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run doc.execution .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.doc.runner() Return all inline documentation for runner modules .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run doc.runner .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.doc.wheel() Return all inline documentation for wheel modules .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run doc.wheel .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.drac .sp Manage Dell DRAC from the Master .sp The login credentials need to be configured in the Salt master configuration file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C drac: username: admin password: secret .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.drac.poweroff(hostname, timeout=20, username=None, password=None) Power server off .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run drac.poweroff example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.drac.poweron(hostname, timeout=20, username=None, password=None) Power server on .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run drac.poweron example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.drac.pxe(hostname, timeout=20, username=None, password=None) Connect to the Dell DRAC and have the boot order set to PXE and power cycle the system to PXE boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run drac.pxe example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.drac.reboot(hostname, timeout=20, username=None, password=None) Reboot a server using the Dell DRAC .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run drac.reboot example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.drac.version(hostname, timeout=20, username=None, password=None) Display the version of DRAC .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run drac.version example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.error .sp Error generator to enable integration testing of salt runner error handling .INDENT 0.0 .TP .B salt.runners.error.error(name=None, message=\(aq\(aq) If name is None Then return empty dict .sp Otherwise raise an exception with __name__ from name, message from message .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run error salt\-run error.error name=\(dqException\(dq message=\(dqThis is an error.\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.event .sp Module for sending events using the runner system. .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.runners.event.send(tag, data=None) Send an event with the given tag and data. .sp This is useful for sending events directly to the master from the shell with salt\-run. It is also quite useful for sending events in orchestration states where the \fBfire_event\fP requisite isn\(aqt sufficient because it does not support sending custom data with the event. .sp Note that event tags will \fInot\fP be namespaced like events sent with the \fBfire_event\fP requisite! Whereas events produced from \fBfire_event\fP are prefixed with \fBsalt/state_result/<jid>/<minion_id>/<name>\fP, events sent using this runner module will have no such prefix. Make sure your reactors don\(aqt expect a prefix! .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtag\fP \-\- the tag to send with the event .IP \(bu 2 \fBdata\fP \-\- an optional dictionary of data to send with the event .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run event.send my/custom/event \(aq{\(dqfoo\(dq: \(dqbar\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .sp Orchestration Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # orch/command.sls run_a_command: salt.function: \- name: cmd.run \- tgt: my_minion \- arg: \- exit {{ pillar[\(aqexit_code\(aq] }} send_success_event: salt.runner: \- name: event.send \- tag: my_event/success \- data: foo: bar \- require: \- salt: run_a_command send_failure_event: salt.runner: \- name: event.send \- tag: my_event/failure \- data: baz: qux \- onfail: \- salt: run_a_command .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate orch.command pillar=\(aq{\(dqexit_code\(dq: 0}\(aq salt\-run state.orchestrate orch.command pillar=\(aq{\(dqexit_code\(dq: 1}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.f5 .sp Runner to provide F5 Load Balancer functionality .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 pycontrol Python module .UNINDENT .TP .B configuration In order to connect to a F5 Load Balancer, you must specify in the Salt master configuration the currently available load balancers .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C load_balancers: bigip1.example.com: username: admin password: secret bigip2.example.com: username: admin password: secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.runners.f5.F5Mgmt(lb, username, password) .INDENT 7.0 .TP .B add_pool_member(name, port, pool_name) Add a node to a pool .UNINDENT .INDENT 7.0 .TP .B check_member_pool(member, pool_name) Check a pool member exists in a specific pool .UNINDENT .INDENT 7.0 .TP .B check_pool(name) Check to see if a pool exists .UNINDENT .INDENT 7.0 .TP .B check_virtualserver(name) Check to see if a virtual server exists .UNINDENT .INDENT 7.0 .TP .B create_pool(name, method=\(aqROUND_ROBIN\(aq) Create a pool on the F5 load balancer .UNINDENT .INDENT 7.0 .TP .B create_vs(name, ip, port, protocol, profile, pool_name) Create a virtual server .UNINDENT .INDENT 7.0 .TP .B lbmethods() List all the load balancer methods .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.f5.add_pool_member(lb, name, port, pool_name) Add a node to a pool .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run f5.add_pool_member load_balancer 10.0.0.1 80 my_pool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.f5.check_member_pool(lb, member, pool_name) Check a pool member exists in a specific pool .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run f5.check_member_pool load_balancer 10.0.0.1 my_pool .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.f5.check_pool(lb, name) Check to see if a pool exists .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run f5.check_pool load_balancer pool_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.f5.check_virtualserver(lb, name) Check to see if a virtual server exists .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run f5.check_virtualserver load_balancer virtual_server .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.f5.create_pool(lb, name, method=\(aqROUND_ROBIN\(aq) Create a pool on the F5 load balancer .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run f5.create_pool load_balancer pool_name loadbalance_method salt\-run f5.create_pool load_balancer my_pool ROUND_ROBIN .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.f5.create_vs(lb, name, ip, port, protocol, profile, pool_name) Create a virtual server .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run f5.create_vs lbalancer vs_name 10.0.0.1 80 tcp http poolname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.fileserver .sp Directly manage the Salt fileserver plugins .INDENT 0.0 .TP .B salt.runners.fileserver.clear_cache(backend=None) New in version 2015.5.0. .sp Clear the fileserver cache from VCS fileserver backends (\fI\%git\fP, \fI\%hg\fP, \fI\%svn\fP). Executing this runner with no arguments will clear the cache for all enabled VCS fileserver backends, but this can be narrowed using the \fBbackend\fP argument. .INDENT 7.0 .TP .B backend Only clear the update lock for the specified backend(s). If all passed backends start with a minus sign (\fB\-\fP), then these backends will be excluded from the enabled backends. However, if there is a mix of backends with and without a minus sign (ex: \fBbackend=\-roots,git\fP) then the ones starting with a minus sign will be disregarded. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run fileserver.clear_cache salt\-run fileserver.clear_cache backend=git,hg salt\-run fileserver.clear_cache hg salt\-run fileserver.clear_cache \-roots .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.fileserver.clear_file_list_cache(saltenv=None, backend=None) New in version 2016.11.0. .sp The Salt fileserver caches the files/directories/symlinks for each fileserver backend and environment as they are requested. This is done to help the fileserver scale better. Without this caching, when hundreds/thousands of minions simultaneously ask the master what files are available, this would cause the master\(aqs CPU load to spike as it obtains the same information separately for each minion. .INDENT 7.0 .TP .B saltenv By default, this runner will clear the file list caches for all environments. This argument allows for a list of environments to be passed, to clear more selectively. This list can be passed either as a comma\-separated string, or a Python list. .TP .B backend Similar to the \fBsaltenv\fP parameter, this argument will restrict the cache clearing to specific fileserver backends (the default behavior is to clear from all enabled fileserver backends). This list can be passed either as a comma\-separated string, or a Python list. .UNINDENT .sp Since the ability to clear these caches is often required by users writing custom runners which add/remove files, this runner can easily be called from within a custom runner using any of the following examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Clear all file list caches __salt__[\(aqfileserver.clear_file_list_cache\(aq]() # Clear just the \(aqbase\(aq saltenv file list caches __salt__[\(aqfileserver.clear_file_list_cache\(aq](saltenv=\(aqbase\(aq) # Clear just the \(aqbase\(aq saltenv file list caches from just the \(aqroots\(aq # fileserver backend __salt__[\(aqfileserver.clear_file_list_cache\(aq](saltenv=\(aqbase\(aq, backend=\(aqroots\(aq) # Clear all file list caches from the \(aqroots\(aq fileserver backend __salt__[\(aqfileserver.clear_file_list_cache\(aq](backend=\(aqroots\(aq) .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 In runners, the \fB__salt__\fP dictionary will likely be renamed to \fB__runner__\fP in a future Salt release to distinguish runner functions from remote execution functions. See \fI\%this GitHub issue\fP for discussion/updates on this. .UNINDENT .UNINDENT .sp If using Salt\(aqs Python API (not a runner), the following examples are equivalent to the ones above: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C import salt.config import salt.runner opts = salt.config.master_config(\(aq/etc/salt/master\(aq) opts[\(aqfun\(aq] = \(aqfileserver.clear_file_list_cache\(aq # Clear all file list_caches opts[\(aqarg\(aq] = [] # No arguments runner = salt.runner.Runner(opts) cleared = runner.run() # Clear just the \(aqbase\(aq saltenv file list caches opts[\(aqarg\(aq] = [\(aqbase\(aq, None] runner = salt.runner.Runner(opts) cleared = runner.run() # Clear just the \(aqbase\(aq saltenv file list caches from just the \(aqroots\(aq # fileserver backend opts[\(aqarg\(aq] = [\(aqbase\(aq, \(aqroots\(aq] runner = salt.runner.Runner(opts) cleared = runner.run() # Clear all file list caches from the \(aqroots\(aq fileserver backend opts[\(aqarg\(aq] = [None, \(aqroots\(aq] runner = salt.runner.Runner(opts) cleared = runner.run() .ft P .fi .UNINDENT .UNINDENT .sp This function will return a dictionary showing a list of environments which were cleared for each backend. An empty return dictionary means that no changes were made. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Clear all file list caches salt\-run fileserver.clear_file_list_cache # Clear just the \(aqbase\(aq saltenv file list caches salt\-run fileserver.clear_file_list_cache saltenv=base # Clear just the \(aqbase\(aq saltenv file list caches from just the \(aqroots\(aq # fileserver backend salt\-run fileserver.clear_file_list_cache saltenv=base backend=roots # Clear all file list caches from the \(aqroots\(aq fileserver backend salt\-run fileserver.clear_file_list_cache backend=roots .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.fileserver.clear_lock(backend=None, remote=None) New in version 2015.5.0. .sp Clear the fileserver update lock from VCS fileserver backends (\fI\%git\fP, \fI\%hg\fP, \fI\%svn\fP). This should only need to be done if a fileserver update was interrupted and a remote is not updating (generating a warning in the Master\(aqs log file). Executing this runner with no arguments will remove all update locks from all enabled VCS fileserver backends, but this can be narrowed by using the following arguments: .INDENT 7.0 .TP .B backend Only clear the update lock for the specified backend(s). .TP .B remote If specified, then any remotes which contain the passed string will have their lock cleared. For example, a \fBremote\fP value of \fBgithub\fP will remove the lock from all github.com remotes. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run fileserver.clear_lock salt\-run fileserver.clear_lock backend=git,hg salt\-run fileserver.clear_lock backend=git remote=github salt\-run fileserver.clear_lock remote=bitbucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.fileserver.dir_list(saltenv=\(aqbase\(aq, backend=None) Return a list of directories in the given environment .INDENT 7.0 .TP .B saltenv base The salt fileserver environment to be listed .TP .B backend Narrow fileserver backends to a subset of the enabled ones. If all passed backends start with a minus sign (\fB\-\fP), then these backends will be excluded from the enabled backends. However, if there is a mix of backends with and without a minus sign (ex: \fBbackend=\-roots,git\fP) then the ones starting with a minus sign will be disregarded. .sp New in version 2015.5.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run fileserver.dir_list salt\-run fileserver.dir_list saltenv=prod salt\-run fileserver.dir_list saltenv=dev backend=git salt\-run fileserver.dir_list base hg,roots salt\-run fileserver.dir_list \-git .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.fileserver.empty_dir_list(saltenv=\(aqbase\(aq, backend=None) New in version 2015.5.0. .sp Return a list of empty directories in the given environment .INDENT 7.0 .TP .B saltenv base The salt fileserver environment to be listed .TP .B backend Narrow fileserver backends to a subset of the enabled ones. If all passed backends start with a minus sign (\fB\-\fP), then these backends will be excluded from the enabled backends. However, if there is a mix of backends with and without a minus sign (ex: \fBbackend=\-roots,git\fP) then the ones starting with a minus sign will be disregarded. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Some backends (such as \fI\%git\fP and \fI\%hg\fP) do not support empty directories. So, passing \fBbackend=git\fP or \fBbackend=hg\fP will result in an empty list being returned. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run fileserver.empty_dir_list salt\-run fileserver.empty_dir_list saltenv=prod salt\-run fileserver.empty_dir_list backend=roots .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.fileserver.envs(backend=None, sources=False) Return the available fileserver environments. If no backend is provided, then the environments for all configured backends will be returned. .INDENT 7.0 .TP .B backend Narrow fileserver backends to a subset of the enabled ones. .sp Changed in version 2015.5.0: If all passed backends start with a minus sign (\fB\-\fP), then these backends will be excluded from the enabled backends. However, if there is a mix of backends with and without a minus sign (ex: \fBbackend=\-roots,git\fP) then the ones starting with a minus sign will be disregarded. .sp Additionally, fileserver backends can now be passed as a comma\-separated list. In earlier versions, they needed to be passed as a python list (ex: \fBbackend=\(dq[\(aqroots\(aq, \(aqgit\(aq]\(dq\fP) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run fileserver.envs salt\-run fileserver.envs backend=roots,git salt\-run fileserver.envs git .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.fileserver.file_list(saltenv=\(aqbase\(aq, backend=None) Return a list of files from the salt fileserver .INDENT 7.0 .TP .B saltenv base The salt fileserver environment to be listed .TP .B backend Narrow fileserver backends to a subset of the enabled ones. If all passed backends start with a minus sign (\fB\-\fP), then these backends will be excluded from the enabled backends. However, if there is a mix of backends with and without a minus sign (ex: \fBbackend=\-roots,git\fP) then the ones starting with a minus sign will be disregarded. .sp New in version 2015.5.0. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run fileserver.file_list salt\-run fileserver.file_list saltenv=prod salt\-run fileserver.file_list saltenv=dev backend=git salt\-run fileserver.file_list base hg,roots salt\-run fileserver.file_list \-git .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.fileserver.lock(backend=None, remote=None) New in version 2015.5.0. .sp Set a fileserver update lock for VCS fileserver backends (\fI\%git\fP, \fI\%hg\fP, \fI\%svn\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This will only operate on enabled backends (those configured in \fI\%fileserver_backend\fP). .UNINDENT .UNINDENT .INDENT 7.0 .TP .B backend Only set the update lock for the specified backend(s). .TP .B remote If not None, then any remotes which contain the passed string will have their lock cleared. For example, a \fBremote\fP value of \fB*github.com*\fP will remove the lock from all github.com remotes. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run fileserver.lock salt\-run fileserver.lock backend=git,hg salt\-run fileserver.lock backend=git remote=\(aq*github.com*\(aq salt\-run fileserver.lock remote=bitbucket .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.fileserver.symlink_list(saltenv=\(aqbase\(aq, backend=None) Return a list of symlinked files and dirs .INDENT 7.0 .TP .B saltenv base The salt fileserver environment to be listed .TP .B backend Narrow fileserver backends to a subset of the enabled ones. If all passed backends start with a minus sign (\fB\-\fP), then these backends will be excluded from the enabled backends. However, if there is a mix of backends with and without a minus sign (ex: \fBbackend=\-roots,git\fP) then the ones starting with a minus sign will be disregarded. .sp New in version 2015.5.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run fileserver.symlink_list salt\-run fileserver.symlink_list saltenv=prod salt\-run fileserver.symlink_list saltenv=dev backend=git salt\-run fileserver.symlink_list base hg,roots salt\-run fileserver.symlink_list \-git .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.fileserver.update(backend=None, **kwargs) Update the fileserver cache. If no backend is provided, then the cache for all configured backends will be updated. .INDENT 7.0 .TP .B backend Narrow fileserver backends to a subset of the enabled ones. .sp Changed in version 2015.5.0: If all passed backends start with a minus sign (\fB\-\fP), then these backends will be excluded from the enabled backends. However, if there is a mix of backends with and without a minus sign (ex: \fBbackend=\-roots,git\fP) then the ones starting with a minus sign will be disregarded. .sp Additionally, fileserver backends can now be passed as a comma\-separated list. In earlier versions, they needed to be passed as a python list (ex: \fBbackend=\(dq[\(aqroots\(aq, \(aqgit\(aq]\(dq\fP) .TP .B kwargs Pass additional arguments to backend. See example below .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run fileserver.update salt\-run fileserver.update backend=roots,git salt\-run fileserver.update backend=git remotes=myrepo,yourrepo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.git_pillar .sp Runner module to directly manage the git external pillar .INDENT 0.0 .TP .B salt.runners.git_pillar.update(branch=None, repo=None) New in version 2014.1.0. .sp Changed in version 2015.8.4: This runner function now supports the \fI\%git_pillar configuration schema\fP introduced in 2015.8.0. Additionally, the branch and repo can now be omitted to update all git_pillar remotes. The return data has also changed to a dictionary. The values will be \fBTrue\fP only if new commits were fetched, and \fBFalse\fP if there were errors or no new commits were fetched. .sp Changed in version 2018.3.0: The return for a given git_pillar remote will now be \fBNone\fP when no changes were fetched. \fBFalse\fP now is reserved only for instances in which there were errors. .sp Changed in version 3001: The repo parameter also matches against the repo name. .sp Fetch one or all configured git_pillar remotes. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This will \fInot\fP fast\-forward the git_pillar cachedir on the master. All it does is perform a \fBgit fetch\fP\&. If this runner is executed with \fB\-l debug\fP, you may see a log message that says that the repo is up\-to\-date. Keep in mind that Salt automatically fetches git_pillar repos roughly every 60 seconds (or whatever \fI\%loop_interval\fP is set to). So, it is possible that the repo was fetched automatically in the time between when changes were pushed to the repo, and when this runner was executed. When in doubt, simply refresh pillar data using \fI\%saltutil.refresh_pillar\fP and then use \fI\%pillar.item\fP to check if the pillar data has changed as expected. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Update specific branch and repo salt\-run git_pillar.update branch=\(aqbranch\(aq repo=\(aqhttps://foo.com/bar.git\(aq # Update specific repo, by name salt\-run git_pillar.update repo=myrepo # Update all repos salt\-run git_pillar.update # Run with debug logging salt\-run git_pillar.update \-l debug .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.http .sp Module for making various web calls. Primarily designed for webhooks and the like, but also useful for basic http testing. .sp New in version 2015.5.0. .INDENT 0.0 .TP .B salt.runners.http.query(url, output=True, **kwargs) Query a resource, and decode the return data .sp Passes through all the parameters described in the \fI\%utils.http.query function\fP: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run http.query http://somelink.com/ salt\-run http.query http://somelink.com/ method=POST params=\(aqkey1=val1&key2=val2\(aq salt\-run http.query http://somelink.com/ method=POST data=\(aq<xml>somecontent</xml>\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.http.update_ca_bundle(target=None, source=None, merge_files=None) Update the local CA bundle file from a URL .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run http.update_ca_bundle salt\-run http.update_ca_bundle target=/path/to/cacerts.pem salt\-run http.update_ca_bundle source=https://example.com/cacerts.pem .ft P .fi .UNINDENT .UNINDENT .sp If the \fBtarget\fP is not specified, it will be pulled from the \fBca_cert\fP configuration variable available to the master. If it cannot be found there, it will be placed at \fB<<FILE_ROOTS>>/cacerts.pem\fP\&. .sp If the \fBsource\fP is not specified, it will be pulled from the \fBca_cert_url\fP configuration variable available to the master. If it cannot be found, it will be downloaded from the cURL website, using an http (not https) URL. USING THE DEFAULT URL SHOULD BE AVOIDED! .sp \fBmerge_files\fP may also be specified, which includes a string or list of strings representing a file or files to be appended to the end of the CA bundle, once it is downloaded. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run http.update_ca_bundle merge_files=/path/to/mycert.pem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.jobs .sp A convenience system to manage jobs, both active and already run .INDENT 0.0 .TP .B salt.runners.jobs.active(display_progress=False) Return a report on all actively running jobs from a job id centric perspective .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.active .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.jobs.exit_success(jid, ext_source=None) Check if a job has been executed and exit successfully .INDENT 7.0 .TP .B jid The jid to look up. .TP .B ext_source The external job cache to use. Default: \fINone\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.exit_success 20160520145827701627 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.jobs.last_run(ext_source=None, outputter=None, metadata=None, function=None, target=None, display_progress=False) New in version 2015.8.0. .sp List all detectable jobs and associated functions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.last_run salt\-run jobs.last_run target=nodename salt\-run jobs.last_run function=\(aqcmd.run\(aq salt\-run jobs.last_run metadata=\(dq{\(aqfoo\(aq: \(aqbar\(aq}\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.jobs.list_job(jid, ext_source=None, display_progress=False) List a specific job given by its jid .INDENT 7.0 .TP .B ext_source If provided, specifies which external job cache to use. .TP .B display_progress False If \fBTrue\fP, fire progress events. .sp New in version 2015.8.8. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.list_job 20130916125524463507 salt\-run jobs.list_job 20130916125524463507 \-\-out=pprint .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.jobs.list_jobs(ext_source=None, outputter=None, search_metadata=None, search_function=None, search_target=None, start_time=None, end_time=None, display_progress=False) List all detectable jobs and associated functions .INDENT 7.0 .TP .B ext_source If provided, specifies which external job cache to use. .UNINDENT .sp \fBFILTER OPTIONS\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If more than one of the below options are used, only jobs which match \fIall\fP of the filters will be returned. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B search_metadata Specify a dictionary to match to the job\(aqs metadata. If any of the key\-value pairs in this dictionary match, the job will be returned. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.list_jobs search_metadata=\(aq{\(dqfoo\(dq: \(dqbar\(dq, \(dqbaz\(dq: \(dqqux\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B search_function Can be passed as a string or a list. Returns jobs which match the specified function. Globbing is allowed. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.list_jobs search_function=\(aqtest.*\(aq salt\-run jobs.list_jobs search_function=\(aq[\(dqtest.*\(dq, \(dqpkg.install\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2015.8.8: Multiple targets can now also be passed as a comma\-separated list. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.list_jobs search_function=\(aqtest.*,pkg.install\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B search_target Can be passed as a string or a list. Returns jobs which match the specified minion name. Globbing is allowed. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.list_jobs search_target=\(aq*.mydomain.tld\(aq salt\-run jobs.list_jobs search_target=\(aq[\(dqdb*\(dq, \(dqmyminion\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2015.8.8: Multiple targets can now also be passed as a comma\-separated list. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.list_jobs search_target=\(aqdb*,myminion\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B start_time Accepts any timestamp supported by the \fI\%dateutil\fP Python module (if this module is not installed, this argument will be ignored). Returns jobs which started after this timestamp. .TP .B end_time Accepts any timestamp supported by the \fI\%dateutil\fP Python module (if this module is not installed, this argument will be ignored). Returns jobs which started before this timestamp. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.list_jobs salt\-run jobs.list_jobs search_function=\(aqtest.*\(aq search_target=\(aqlocalhost\(aq search_metadata=\(aq{\(dqbar\(dq: \(dqfoo\(dq}\(aq salt\-run jobs.list_jobs start_time=\(aq2015, Mar 16 19:00\(aq end_time=\(aq2015, Mar 18 22:00\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.jobs.list_jobs_filter(count, filter_find_job=True, ext_source=None, outputter=None, display_progress=False) List all detectable jobs and associated functions .INDENT 7.0 .TP .B ext_source The external job cache to use. Default: \fINone\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.list_jobs_filter 50 salt\-run jobs.list_jobs_filter 100 filter_find_job=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.jobs.lookup_jid(jid, ext_source=None, returned=True, missing=False, display_progress=False) Return the printout from a previously executed job .INDENT 7.0 .TP .B jid The jid to look up. .TP .B ext_source The external job cache to use. Default: \fINone\fP\&. .TP .B returned True If \fBTrue\fP, include the minions that did return from the command. .sp New in version 2015.8.0. .TP .B missing False If \fBTrue\fP, include the minions that did \fInot\fP return from the command. .TP .B display_progress False If \fBTrue\fP, fire progress events. .sp New in version 2015.5.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.lookup_jid 20130916125524463507 salt\-run jobs.lookup_jid 20130916125524463507 \-\-out=highstate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.jobs.master() Return the actively executing runners for the master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.jobs.print_job(jid, ext_source=None) Print a specific job\(aqs detail given by its jid, including the return data. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.print_job 20130916125524463507 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.launchd .sp Manage launchd plist files .INDENT 0.0 .TP .B salt.runners.launchd.write_launchd_plist(program) Write a launchd plist for managing salt\-master or salt\-minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run launchd.write_launchd_plist salt\-master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.lxc .sp Control Linux Containers via Salt .INDENT 0.0 .TP .B depends lxc execution module .UNINDENT .INDENT 0.0 .TP .B salt.runners.lxc.cloud_init(names, host=None, quiet=False, **kwargs) Wrapper for using lxc.init in saltcloud compatibility mode .INDENT 7.0 .TP .B names Name of the containers, supports a single name or a comma delimited list of names. .TP .B host Minion to start the container on. Required. .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B saltcloud_mode init the container with the saltcloud opts format instead .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.lxc.find_guest(name, quiet=False, path=None) Returns the host for a container. .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run lxc.find_guest name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.lxc.find_guests(names, path=None) Return a dict of hosts and named guests .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.lxc.freeze(name, quiet=False, path=None) Freeze the named container .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run lxc.freeze name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.lxc.info(name, quiet=False, path=None) Returns information about a container. .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run lxc.info name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.lxc.init(names, host=None, saltcloud_mode=False, quiet=False, **kwargs) Initialize a new container .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run lxc.init name host=minion_id [cpuset=cgroups_cpuset] \e [cpushare=cgroups_cpushare] [memory=cgroups_memory] \e [template=lxc_template_name] [clone=original name] \e [profile=lxc_profile] [network_proflile=network_profile] \e [nic=network_profile] [nic_opts=nic_opts] \e [start=(true|false)] [seed=(true|false)] \e [install=(true|false)] [config=minion_config] \e [snapshot=(true|false)] .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B names Name of the containers, supports a single name or a comma delimited list of names. .TP .B host Minion on which to initialize the container \fB(required)\fP .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B saltcloud_mode init the container with the saltcloud opts format instead See lxc.init_interface module documentation .TP .B cpuset cgroups cpuset. .TP .B cpushare cgroups cpu shares. .TP .B memory cgroups memory limit, in MB .sp Changed in version 2015.5.0: If no value is passed, no limit is set. In earlier Salt versions, not passing this value causes a 1024MB memory limit to be set, and it was necessary to pass \fBmemory=0\fP to set no limit. .TP .B template Name of LXC template on which to base this container .TP .B clone Clone this container from an existing container .TP .B profile A LXC profile (defined in config or pillar). .TP .B network_profile Network profile to use for the container .sp New in version 2015.5.2. .TP .B nic Deprecated since version 2015.5.0: Use \fBnetwork_profile\fP instead .TP .B nic_opts Extra options for network interfaces. E.g.: .sp \fB{\(dqeth0\(dq: {\(dqmac\(dq: \(dqaa:bb:cc:dd:ee:ff\(dq, \(dqipv4\(dq: \(dq10.1.1.1\(dq, \(dqipv6\(dq: \(dq2001:db8::ff00:42:8329\(dq}}\fP .TP .B start Start the newly created container. .TP .B seed Seed the container with the minion config and autosign its key. Default: true .TP .B install If salt\-minion is not already installed, install it. Default: true .TP .B config Optional config parameters. By default, the id is set to the name of the container. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.lxc.list_(host=None, quiet=False, path=None) List defined containers (running, stopped, and frozen) for the named (or all) host(s). .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run lxc.list [host=minion_id] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.lxc.purge(name, delete_key=True, quiet=False, path=None) Purge the named container and delete its minion key if present. WARNING: Destroys all data associated with the container. .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run lxc.purge name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.lxc.start(name, quiet=False, path=None) Start the named container. .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run lxc.start name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.lxc.stop(name, quiet=False, path=None) Stop the named container. .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run lxc.stop name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.lxc.unfreeze(name, quiet=False, path=None) Unfreeze the named container .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run lxc.unfreeze name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.manage .sp General management functions for salt, tools like seeing what hosts are up and what hosts are down .INDENT 0.0 .TP .B salt.runners.manage.alived(subset=None, show_ip=False) New in version 2015.8.0. .sp Changed in version 2019.2.0. .sp Print a list of all minions that are up according to Salt\(aqs presence detection (no commands will be sent to minions) .INDENT 7.0 .TP .B subset None Pass in a list of minion ids. .TP .B show_ip False Also show the IP address each minion is connecting from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.alived .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.allowed(subset=None, show_ip=False) New in version 2015.8.0. .sp Changed in version 2019.2.0. .sp Print a list of all minions that are up according to Salt\(aqs presence detection (no commands will be sent to minions) .INDENT 7.0 .TP .B subset None Pass in a list of minion ids. .TP .B show_ip False Also show the IP address each minion is connecting from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.allowed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.bootstrap(version=\(aqdevelop\(aq, script=\(aqhttps://bootstrap.saltproject.io\(aq, hosts=\(aq\(aq, script_args=\(aq\(aq, roster=\(aqflat\(aq, ssh_user=None, ssh_password=None, ssh_priv_key=None, tmp_dir=\(aq/tmp/.bootstrap\(aq, http_backend=\(aqtornado\(aq) Bootstrap minions with salt\-bootstrap .INDENT 7.0 .TP .B version develop Git tag of version to install .TP .B script \fI\%https://bootstrap.saltproject.io/\fP URL containing the script to execute .TP .B hosts Comma\-separated hosts [example: hosts=\(aqhost1.local,host2.local\(aq]. These hosts need to exist in the specified roster. .TP .B script_args Any additional arguments that you want to pass to the script. .sp New in version 2016.11.0. .TP .B roster flat The roster to use for Salt SSH. More information about roster files can be found in \fI\%Salt\(aqs Roster Documentation\fP\&. .sp A full list of roster types, see the \fI\%builtin roster modules\fP documentation. .sp New in version 2016.11.0. .TP .B ssh_user If \fBuser\fP isn\(aqt found in the \fBroster\fP, a default SSH user can be set here. Keep in mind that \fBssh_user\fP will not override the roster \fBuser\fP value if it is already defined. .sp New in version 2016.11.0. .TP .B ssh_password If \fBpasswd\fP isn\(aqt found in the \fBroster\fP, a default SSH password can be set here. Keep in mind that \fBssh_password\fP will not override the roster \fBpasswd\fP value if it is already defined. .sp New in version 2016.11.0. .TP .B ssh_privkey If \fBpriv\fP isn\(aqt found in the \fBroster\fP, a default SSH private key can be set here. Keep in mind that \fBssh_password\fP will not override the roster \fBpasswd\fP value if it is already defined. .sp New in version 2016.11.0. .TP .B tmp_dir /tmp/.bootstrap The temporary directory to download the bootstrap script in. This directory will have \fB\-<uuid4>\fP appended to it. For example: \fB/tmp/.bootstrap\-a19a728e\-d40a\-4801\-aba9\-d00655c143a7/\fP .sp New in version 2016.11.0. .TP .B http_backend tornado The backend library to use to download the script. If you need to use a \fBfile:///\fP URL, then you should set this to \fBurllib2\fP\&. .sp New in version 2016.11.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.bootstrap hosts=\(aqhost1,host2\(aq salt\-run manage.bootstrap hosts=\(aqhost1,host2\(aq version=\(aqv3004.2\(aq salt\-run manage.bootstrap hosts=\(aqhost1,host2\(aq version=\(aqv3004.2\(aq script=\(aqhttps://bootstrap.saltproject.io/develop\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.bootstrap_psexec(hosts=\(aq\(aq, master=None, version=None, arch=\(aqwin32\(aq, installer_url=None, username=None, password=None) Bootstrap Windows minions via PsExec. .INDENT 7.0 .TP .B hosts Comma separated list of hosts to deploy the Windows Salt minion. .TP .B master Address of the Salt master passed as an argument to the installer. .TP .B version Point release of installer to download. Defaults to the most recent. .TP .B arch Architecture of installer to download. Defaults to win32. .TP .B installer_url URL of minion installer executable. Defaults to the latest version from \fI\%https://repo.saltproject.io/windows/\fP .TP .B username Optional user name for login on remote computer. .TP .B password Password for optional username. If omitted, PsExec will prompt for one to be entered for each host. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.bootstrap_psexec hosts=\(aqhost1,host2\(aq salt\-run manage.bootstrap_psexec hosts=\(aqhost1,host2\(aq version=\(aq0.17\(aq username=\(aqDOMAIN\eAdministrator\(aq salt\-run manage.bootstrap_psexec hosts=\(aqhost1,host2\(aq installer_url=\(aqhttp://exampledomain/salt\-installer.exe\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.down(removekeys=False, tgt=\(aq*\(aq, tgt_type=\(aqglob\(aq, timeout=None, gather_job_timeout=None) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Print a list of all the down or unresponsive salt minions Optionally remove keys of down minions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.down salt\-run manage.down removekeys=True salt\-run manage.down tgt=\(dqwebservers\(dq tgt_type=\(dqnodegroup\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.joined(subset=None, show_ip=False) New in version 2015.8.0. .sp Changed in version 2019.2.0. .sp Print a list of all minions that are up according to Salt\(aqs presence detection (no commands will be sent to minions) .INDENT 7.0 .TP .B subset None Pass in a list of minion ids. .TP .B show_ip False Also show the IP address each minion is connecting from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.joined .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.key_regen() This routine is used to regenerate all keys in an environment. This is invasive! ALL KEYS IN THE SALT ENVIRONMENT WILL BE REGENERATED!! .sp The key_regen routine sends a command out to minions to revoke the master key and remove all minion keys, it then removes all keys from the master and prompts the user to restart the master. The minions will all reconnect and keys will be placed in pending. .sp After the master is restarted and minion keys are in the pending directory execute a salt\-key \-A command to accept the regenerated minion keys. .sp The master \fImust\fP be restarted within 60 seconds of running this command or the minions will think there is something wrong with the keys and abort. .sp Only Execute this runner after upgrading minions and master to 0.15.1 or higher! .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.key_regen .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.list_not_state(subset=None, show_ip=False) New in version 2015.8.0. .sp Changed in version 2019.2.0. .sp Print a list of all minions that are NOT up according to Salt\(aqs presence detection (no commands will be sent to minions) .INDENT 7.0 .TP .B subset None Pass in a list of minion ids. .TP .B show_ip False Also show the IP address each minion is connecting from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.list_not_state .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.list_state(subset=None, show_ip=False) New in version 2015.8.0. .sp Changed in version 2019.2.0. .sp Print a list of all minions that are up according to Salt\(aqs presence detection (no commands will be sent to minions) .INDENT 7.0 .TP .B subset None Pass in a list of minion ids. .TP .B show_ip False Also show the IP address each minion is connecting from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.list_state .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.not_alived(subset=None, show_ip=False) New in version 2015.8.0. .sp Changed in version 2019.2.0. .sp Print a list of all minions that are NOT up according to Salt\(aqs presence detection (no commands will be sent) .INDENT 7.0 .TP .B subset None Pass in a list of minion ids. .TP .B show_ip False Also show the IP address each minion is connecting from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.not_alived .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.not_allowed(subset=None, show_ip=False) New in version 2015.8.0. .sp Changed in version 2019.2.0. .sp Print a list of all minions that are NOT up according to Salt\(aqs presence detection (no commands will be sent) .INDENT 7.0 .TP .B subset None Pass in a list of minion ids. .TP .B show_ip False Also show the IP address each minion is connecting from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.not_allowed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.not_joined(subset=None, show_ip=False) New in version 2015.8.0. .sp Changed in version 2019.2.0. .sp Print a list of all minions that are NOT up according to Salt\(aqs presence detection (no commands will be sent) .INDENT 7.0 .TP .B subset None Pass in a list of minion ids. .TP .B show_ip False Also show the IP address each minion is connecting from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.not_joined .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.not_present(subset=None, show_ip=False) New in version 2015.5.0. .sp Changed in version 2019.2.0. .sp Print a list of all minions that are NOT up according to Salt\(aqs presence detection (no commands will be sent) .INDENT 7.0 .TP .B subset None Pass in a list of minion ids. .TP .B show_ip False Also show the IP address each minion is connecting from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.not_present .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.not_reaped(subset=None, show_ip=False) New in version 2015.8.0. .sp Changed in version 2019.2.0. .sp Print a list of all minions that are NOT up according to Salt\(aqs presence detection (no commands will be sent) .INDENT 7.0 .TP .B subset None Pass in a list of minion ids. .TP .B show_ip False Also show the IP address each minion is connecting from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.not_reaped .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.present(subset=None, show_ip=False) Changed in version 2019.2.0. .sp Print a list of all minions that are up according to Salt\(aqs presence detection (no commands will be sent to minions) .INDENT 7.0 .TP .B subset None Pass in a list of minion ids. .TP .B show_ip False Also show the IP address each minion is connecting from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.present .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.reaped(subset=None, show_ip=False) New in version 2015.8.0. .sp Changed in version 2019.2.0. .sp Print a list of all minions that are up according to Salt\(aqs presence detection (no commands will be sent to minions) .INDENT 7.0 .TP .B subset None Pass in a list of minion ids. .TP .B show_ip False Also show the IP address each minion is connecting from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.reaped .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.safe_accept(target, tgt_type=\(aqglob\(aq) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Accept a minion\(aqs public key after checking the fingerprint over salt\-ssh .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.safe_accept my_minion salt\-run manage.safe_accept minion1,minion2 tgt_type=list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.status(output=True, tgt=\(aq*\(aq, tgt_type=\(aqglob\(aq, timeout=None, gather_job_timeout=None) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Print the status of all known salt minions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.status salt\-run manage.status tgt=\(dqwebservers\(dq tgt_type=\(dqnodegroup\(dq salt\-run manage.status timeout=5 gather_job_timeout=10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.up(tgt=\(aq*\(aq, tgt_type=\(aqglob\(aq, timeout=None, gather_job_timeout=None) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Print a list of all of the minions that are up .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.up salt\-run manage.up tgt=\(dqwebservers\(dq tgt_type=\(dqnodegroup\(dq salt\-run manage.up timeout=5 gather_job_timeout=10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.manage.versions() Check the version of active minions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.versions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.match .sp Run matchers from the master context. .sp New in version 3007.0. .INDENT 0.0 .TP .B salt.runners.match.compound_matches(expr, minion_id) Check whether a minion is matched by a given compound match expression. On success, this function will return the minion ID, otherwise False. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Pillar values will be matched literally only since this function is intended for remote calling. This also applies to node groups defined on the master. Custom matchers are not respected. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If a module calls this runner from a minion, you will need to explicitly allow the remote call. See \fI\%peer_run\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run match.compound_matches \(aqI@foo:bar and G@os:Deb* and not db*\(aq myminion .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B expr The \fI\%Compound Matcher\fP expression to validate against. .TP .B minion_id The minion ID of the minion to check the match for. .UNINDENT .UNINDENT .SS salt.runners.mattermost .sp \fBNote for 2017.7 releases!\fP .sp Due to the \fI\%salt.runners.config\fP module not being available in this release series, importing the \fI\%salt.runners.config\fP module from the master branch is required to make this module work. .sp Ref: \fI\%Mattermost runner failing to retrieve config values due to unavailable config runner #43479\fP .sp Module for sending messages to Mattermost .sp New in version 2017.7.0. .INDENT 0.0 .TP .B configuration This module can be used by either passing an api_url and hook directly or by specifying both in a configuration profile in the salt master/minion config. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mattermost: hook: peWcBiMOS9HrZG15peWcBiMOS9HrZG15 api_url: https://example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.mattermost.post_event(event, channel=None, username=None, api_url=None, hook=None) Send an event to a Mattermost channel. :param channel: The channel name, either will work. :param username: The username of the poster. :param event: The event to send to the Mattermost channel. :param api_url: The Mattermost api url, if not specified in the configuration. :param hook: The Mattermost hook, if not specified in the configuration. :return: Boolean if message was sent successfully. .UNINDENT .INDENT 0.0 .TP .B salt.runners.mattermost.post_message(message, channel=None, username=None, api_url=None, hook=None) Send a message to a Mattermost channel. :param channel: The channel name, either will work. :param username: The username of the poster. :param message: The message to send to the Mattermost channel. :param api_url: The Mattermost api url, if not specified in the configuration. :param hook: The Mattermost hook, if not specified in the configuration. :return: Boolean if message was sent successfully. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run mattermost.post_message message=\(aqBuild is done\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.mine .sp A runner to access data from the salt mine .INDENT 0.0 .TP .B salt.runners.mine.get(tgt, fun, tgt_type=\(aqglob\(aq) Gathers the data from the specified minions\(aq mine, pass in the target, function to look up and the target type .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run mine.get \(aq*\(aq network.interfaces .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.mine.update(tgt, tgt_type=\(aqglob\(aq, clear=False, mine_functions=None) New in version 2017.7.0. .sp Update the mine data on a certain group of minions. .INDENT 7.0 .TP .B tgt Which minions to target for the execution. .TP .B tgt_type: \fBglob\fP The type of \fBtgt\fP\&. .TP .B clear: \fBFalse\fP Boolean flag specifying whether updating will clear the existing mines, or will update. Default: \fBFalse\fP (update). .TP .B mine_functions Update the mine data on certain functions only. This feature can be used when updating the mine for functions that require refresh at different intervals than the rest of the functions specified under \fBmine_functions\fP in the minion/master config or pillar. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run mine.update \(aq*\(aq salt\-run mine.update \(aqjuniper\-edges\(aq tgt_type=\(aqnodegroup\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.nacl .sp This module helps include encrypted passwords in pillars, grains and salt state files. .INDENT 0.0 .TP .B depends PyNaCl, \fI\%https://github.com/pyca/pynacl\fP .UNINDENT .sp This is often useful if you wish to store your pillars in source control or share your pillar data with others that you trust. I don\(aqt advise making your pillars public regardless if they are encrypted or not. .INDENT 0.0 .TP .B configuration The following configuration defaults can be define (pillar or config files) Avoid storing private keys in pillars! Ensure master does not have \fIpillar_opts=True\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # cat /etc/salt/master.d/nacl.conf nacl.config: # NOTE: \(gakey\(ga and \(gakey_file\(ga have been renamed to \(gask\(ga, \(gask_file\(ga # also \(gabox_type\(ga default changed from secretbox to sealedbox. box_type: sealedbox (default) sk_file: /etc/salt/pki/master/nacl (default) pk_file: /etc/salt/pki/master/nacl.pub (default) sk: None pk: None .ft P .fi .UNINDENT .UNINDENT .sp Usage can override the config defaults: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.enc sk_file=/etc/salt/pki/master/nacl pk_file=/etc/salt/pki/master/nacl.pub .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp The nacl lib uses 32byte keys, these keys are base64 encoded to make your life more simple. To generate your \fIsk_file\fP and \fIpk_file\fP use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.keygen sk_file=/etc/salt/pki/master/nacl # or if you want to work without files. salt\-run nacl.keygen local: \-\-\-\-\-\-\-\-\-\- pk: /kfGX7PbWeu099702PBbKWLpG/9p06IQRswkdWHCDk0= sk: SVWut5SqNpuPeNzb1b9y6b2eXg2PLIog43GBzp48Sow= .ft P .fi .UNINDENT .UNINDENT .sp Now with your keypair, you can encrypt data: .sp You have two option, \fIsealedbox\fP or \fIsecretbox\fP\&. .sp SecretBox is data encrypted using private key \fIpk\fP\&. Sealedbox is encrypted using public key \fIpk\fP\&. .sp Recommend using Sealedbox because the one way encryption permits developers to encrypt data for source control but not decrypt. Sealedbox only has one key that is for both encryption and decryption. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.enc asecretpass pk=/kfGX7PbWeu099702PBbKWLpG/9p06IQRswkdWHCDk0= tqXzeIJnTAM9Xf0mdLcpEdklMbfBGPj2oTKmlgrm3S1DTVVHNnh9h8mU1GKllGq/+cYsk6m5WhGdk58= .ft P .fi .UNINDENT .UNINDENT .sp To decrypt the data: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.dec data=\(aqtqXzeIJnTAM9Xf0mdLcpEdklMbfBGPj2oTKmlgrm3S1DTVVHNnh9h8mU1GKllGq/+cYsk6m5WhGdk58=\(aq sk=\(aqSVWut5SqNpuPeNzb1b9y6b2eXg2PLIog43GBzp48Sow=\(aq .ft P .fi .UNINDENT .UNINDENT .sp When the keys are defined in the master config you can use them from the nacl runner without extra parameters: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # cat /etc/salt/master.d/nacl.conf nacl.config: sk_file: /etc/salt/pki/master/nacl pk: \(aqcTIqXwnUiD1ulg4kXsbeCE7/NoeKEzd4nLeYcCFpd9k=\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.enc \(aqasecretpass\(aq salt\-run nacl.dec data=\(aqtqXzeIJnTAM9Xf0mdLcpEdklMbfBGPj2oTKmlgrm3S1DTVVHNnh9h8mU1GKllGq/+cYsk6m5WhGdk58=\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # a salt developers minion could have pillar data that includes a nacl public key nacl.config: pk: \(aq/kfGX7PbWeu099702PBbKWLpG/9p06IQRswkdWHCDk0=\(aq .ft P .fi .UNINDENT .UNINDENT .sp The developer can then use a less\-secure system to encrypt data. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.enc apassword .ft P .fi .UNINDENT .UNINDENT .sp Pillar files can include protected data that the salt master decrypts: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillarexample: user: root password1: {{salt.nacl.dec(\(aqDRB7Q6/X5gGSRCTpZyxS6hlbWj0llUA+uaVyvou3vJ4=\(aq)|json}} cert_key: {{salt.nacl.dec_file(\(aq/srv/salt/certs/example.com/key.nacl\(aq)|json}} cert_key2: {{salt.nacl.dec_file(\(aqsalt:///certs/example.com/key.nacl\(aq)|json}} .ft P .fi .UNINDENT .UNINDENT .sp Larger files like certificates can be encrypted with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.enc_file /tmp/cert.crt out=/tmp/cert.nacl .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.nacl.dec(data, **kwargs) Alias to \fI{box_type}_decrypt\fP .sp box_type: secretbox, sealedbox(default) .UNINDENT .INDENT 0.0 .TP .B salt.runners.nacl.dec_file(name, out=None, **kwargs) This is a helper function to decrypt a file and return its contents. .sp You can provide an optional output file using \fIout\fP .sp \fIname\fP can be a local file or when not using \fIsalt\-run\fP can be a url like \fIsalt://\fP, \fIhttps://\fP etc. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.dec_file name=/tmp/id_rsa.nacl salt\-run nacl.dec_file name=/tmp/id_rsa.nacl box_type=secretbox sk_file=/etc/salt/pki/master/nacl.pub .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.nacl.enc(data, **kwargs) Alias to \fI{box_type}_encrypt\fP .sp box_type: secretbox, sealedbox(default) .UNINDENT .INDENT 0.0 .TP .B salt.runners.nacl.enc_file(name, out=None, **kwargs) This is a helper function to encrypt a file and return its contents. .sp You can provide an optional output file using \fIout\fP .sp \fIname\fP can be a local file or when not using \fIsalt\-run\fP can be a url like \fIsalt://\fP, \fIhttps://\fP etc. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.enc_file name=/tmp/id_rsa salt\-run nacl.enc_file name=/tmp/id_rsa box_type=secretbox sk_file=/etc/salt/pki/master/nacl.pub .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.nacl.keygen(sk_file=None, pk_file=None, **kwargs) Use PyNaCL to generate a keypair. .sp If no \fIsk_file\fP is defined return a keypair. .sp If only the \fIsk_file\fP is defined \fIpk_file\fP will use the same name with a postfix \fI\&.pub\fP\&. .sp When the \fIsk_file\fP is already existing, but \fIpk_file\fP is not. The \fIpk_file\fP will be generated using the \fIsk_file\fP\&. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.keygen salt\-run nacl.keygen sk_file=/etc/salt/pki/master/nacl salt\-run nacl.keygen sk_file=/etc/salt/pki/master/nacl pk_file=/etc/salt/pki/master/nacl.pub salt\-run nacl.keygen .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.nacl.sealedbox_decrypt(data, **kwargs) Decrypt data using a secret key that was encrypted using a public key with \fInacl.sealedbox_encrypt\fP\&. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.sealedbox_decrypt pEXHQM6cuaF7A= salt\-run nacl.sealedbox_decrypt data=\(aqpEXHQM6cuaF7A=\(aq sk_file=/etc/salt/pki/master/nacl salt\-run nacl.sealedbox_decrypt data=\(aqpEXHQM6cuaF7A=\(aq sk=\(aqYmFkcGFzcwo=\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.nacl.sealedbox_encrypt(data, **kwargs) Encrypt data using a public key generated from \fInacl.keygen\fP\&. The encryptd data can be decrypted using \fInacl.sealedbox_decrypt\fP only with the secret key. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.sealedbox_encrypt datatoenc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.nacl.secretbox_decrypt(data, **kwargs) Decrypt data that was encrypted using \fInacl.secretbox_encrypt\fP using the secret key that was generated from \fInacl.keygen\fP\&. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.secretbox_decrypt pEXHQM6cuaF7A= salt\-run nacl.secretbox_decrypt data=\(aqpEXHQM6cuaF7A=\(aq sk_file=/etc/salt/pki/master/nacl salt\-run nacl.secretbox_decrypt data=\(aqpEXHQM6cuaF7A=\(aq sk=\(aqYmFkcGFzcwo=\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.nacl.secretbox_encrypt(data, **kwargs) Encrypt data using a secret key generated from \fInacl.keygen\fP\&. The same secret key can be used to decrypt the data using \fInacl.secretbox_decrypt\fP\&. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run nacl.secretbox_encrypt datatoenc salt\-run nacl.secretbox_encrypt datatoenc sk_file=/etc/salt/pki/master/nacl salt\-run nacl.secretbox_encrypt datatoenc sk=\(aqYmFkcGFzcwo=\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.net .SS NET Finder .sp New in version 2017.7.0. .sp A runner to find network details easily and fast. It\(aqs smart enough to know what you are looking for. .SS Configuration .INDENT 0.0 .IP \(bu 2 Minion (proxy) config .INDENT 2.0 .INDENT 3.5 To have the complete features, one needs to add the following mine configuration in the minion (proxy) config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_functions: net.ipaddrs: [] net.lldp: [] net.mac: [] net.arp: [] net.interfaces: [] .ft P .fi .UNINDENT .UNINDENT .sp Which instructs Salt to cache the data returned by the NAPALM\-functions. While they are not mandatory, the less functions configured, the less details will be found by the runner. .sp How often the mines are refreshed, can be specified using: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_interval: <X minutes> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 Master config .INDENT 2.0 .INDENT 3.5 By default the following options can be configured on the master. They are not necessary, but available in case the user has different requirements. .INDENT 0.0 .TP .B target: \fB*\fP From what minions will collect the mine data. Default: \fB*\fP (collect from all minions). .TP .B expr_form: \fBglob\fP Minion matching expression form. Default: \fBglob\fP\&. .TP .B ignore_interfaces A list of interfaces name to ignore. By default will consider all interfaces. .TP .B display: \fBTrue\fP Display on the screen or return structured object? Default: \fBTrue\fP (return on the CLI). .TP .B outputter: \fBtable\fP Specify the outputter name when displaying on the CLI. Default: \fBtable\fP\&. .UNINDENT .sp Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C runners: net.find: target: \(aqedge*\(aq expr_form: \(aqglob\(aq ignore_interfaces: \- lo0 \- em1 \- jsrv \- fxp0 outputter: yaml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.net.find(addr, best=True, display=True) Search in all possible entities (Interfaces, MAC tables, ARP tables, LLDP neighbors), using the following mine functions: .INDENT 7.0 .IP \(bu 2 net.mac .IP \(bu 2 net.arp .IP \(bu 2 net.lldp .IP \(bu 2 net.ipaddrs .IP \(bu 2 net.interfaces .UNINDENT .sp This function has the advantage that it knows where to look, but the output might become quite long as returns all possible matches. .sp Optional arguments: .INDENT 7.0 .TP .B best: \fBTrue\fP Return only the best match with the interfaces IP networks when the saerching pattern is a valid IP Address or Network. .TP .B display: \fBTrue\fP Display on the screen or return structured object? Default: \fBTrue\fP (return on the CLI). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt\-run net.find 10.10.10.7 .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Details for all interfaces that include network 10.10.10.7/32 \- only best match returned ________________________________________________________________________________________________________________________ | Device | Interface | Interface Description | UP | Enabled | Speed [Mbps] | MAC Address | IP Addresses | ________________________________________________________________________________________________________________________ | edge01.flw01 | irb | | True | True | \-1 | 5C:5E:AB:AC:52:B4 | 10.10.10.1/22 | ________________________________________________________________________________________________________________________ ARP Entries for IP 10.10.10.7 _____________________________________________________________________________ | Device | Interface | MAC | IP | Age | _____________________________________________________________________________ | edge01.flw01 | irb.349 [ae0.349] | 2C:60:0C:2A:4C:0A | 10.10.10.7 | 832.0 | _____________________________________________________________________________ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.net.findarp(device=None, interface=None, mac=None, ip=None, display=True) Search for entries in the ARP tables using the following mine functions: .INDENT 7.0 .IP \(bu 2 net.arp .UNINDENT .sp Optional arguments: .INDENT 7.0 .TP .B device Return interface data from a certain device only. .TP .B interface Return data selecting by interface name. .TP .B mac Search using a specific MAC Address. .TP .B ip Search using a specific IP Address. .TP .B display: \fBTrue\fP Display on the screen or return structured object? Default: \fBTrue\fP, will return on the CLI. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt\-run net.findarp mac=8C:60:0F:78:EC:41 .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ARP Entries for MAC 8C:60:0F:78:EC:41 ________________________________________________________________________________ | Device | Interface | MAC | IP | Age | ________________________________________________________________________________ | edge01.bjm01 | irb.171 [ae0.171] | 8C:60:0F:78:EC:41 | 172.172.17.19 | 956.0 | ________________________________________________________________________________ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.net.findmac(device=None, mac=None, interface=None, vlan=None, display=True) Search in the MAC Address tables, using the following mine functions: .INDENT 7.0 .IP \(bu 2 net.mac .UNINDENT .sp Optional arguments: .INDENT 7.0 .TP .B device Return interface data from a certain device only. .TP .B interface Return data selecting by interface name. .TP .B mac Search using a specific MAC Address. .TP .B vlan Search using a VLAN ID. .TP .B display: \fBTrue\fP Display on the screen or return structured object? Default: \fBTrue\fP, will return on the CLI. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt\-run net.findmac mac=8C:60:0F:78:EC:41 .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C MAC Address(es) _____________________________________________________________________________________________ | Device | Interface | MAC | VLAN | Static | Active | Moves | Last move | _____________________________________________________________________________________________ | edge01.bjm01 | ae0.171 | 8C:60:0F:78:EC:41 | 171 | False | True | 0 | 0.0 | _____________________________________________________________________________________________ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.net.interfaces(device=None, interface=None, title=None, pattern=None, ipnet=None, best=True, display=True) Search for interfaces details in the following mine functions: .INDENT 7.0 .IP \(bu 2 net.interfaces .IP \(bu 2 net.ipaddrs .UNINDENT .sp Optional arguments: .INDENT 7.0 .TP .B device Return interface data from a certain device only. .TP .B interface Return data selecting by interface name. .TP .B pattern Return interfaces that contain a certain pattern in their description. .TP .B ipnet Return interfaces whose IP networks associated include this IP network. .TP .B best: \fBTrue\fP When \fBipnet\fP is specified, this argument says if the runner should return only the best match (the output will contain at most one row). Default: \fBTrue\fP (return only the best match). .TP .B display: True Display on the screen or return structured object? Default: \fBTrue\fP (return on the CLI). .TP .B title Display a custom title for the table. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt\-run net.interfaces interface=vt\-0/0/10 .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Details for interface xe\-0/0/0 _________________________________________________________________________________________________________________ | Device | Interface | Interface Description | UP | Enabled | Speed [Mbps] | MAC Address | IP Addresses | _________________________________________________________________________________________________________________ | edge01.bjm01 | vt\-0/0/10 | | True | True | 1000 | | | _________________________________________________________________________________________________________________ | edge01.flw01 | vt\-0/0/10 | | True | True | 1000 | | | _________________________________________________________________________________________________________________ | edge01.pos01 | vt\-0/0/10 | | True | True | 1000 | | | _________________________________________________________________________________________________________________ | edge01.oua01 | vt\-0/0/10 | | True | True | 1000 | | | _________________________________________________________________________________________________________________ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.net.lldp(device=None, interface=None, title=None, pattern=None, chassis=None, display=True) Search in the LLDP neighbors, using the following mine functions: .INDENT 7.0 .IP \(bu 2 net.lldp .UNINDENT .sp Optional arguments: .INDENT 7.0 .TP .B device Return interface data from a certain device only. .TP .B interface Return data selecting by interface name. .TP .B pattern Return LLDP neighbors that have contain this pattern in one of the following fields: .INDENT 7.0 .IP \(bu 2 Remote Port ID .IP \(bu 2 Remote Port Description .IP \(bu 2 Remote System Name .IP \(bu 2 Remote System Description .UNINDENT .TP .B chassis Search using a specific Chassis ID. .TP .B display: \fBTrue\fP Display on the screen or return structured object? Default: \fBTrue\fP (return on the CLI). .TP .B display: \fBTrue\fP Display on the screen or return structured object? Default: \fBTrue\fP (return on the CLI). .TP .B title Display a custom title for the table. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt\-run net.lldp pattern=Ethernet1/48 .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Pattern \(dqEthernet1/48\(dq found in one of the following LLDP details _________________________________________________________________________________________________________________________________________________________________________________________ | Device | Interface | Parent Interface | Remote Chassis ID | Remote Port ID | Remote Port Description | Remote System Name | Remote System Description | _________________________________________________________________________________________________________________________________________________________________________________________ | edge01.bjm01 | xe\-2/3/4 | ae0 | 8C:60:4F:3B:52:19 | | Ethernet1/48 | edge05.bjm01.dummy.net | Cisco NX\-OS(tm) n6000, Software (n6000\-uk9), | | | | | | | | | Version 7.3(0)N7(5), RELEASE SOFTWARE Copyright | | | | | | | | | (c) 2002\-2012 by Cisco Systems, Inc. Compiled | | | | | | | | | 2/17/2016 22:00:00 | _________________________________________________________________________________________________________________________________________________________________________________________ | edge01.flw01 | xe\-1/2/3 | ae0 | 8C:60:4F:1A:B4:22 | | Ethernet1/48 | edge05.flw01.dummy.net | Cisco NX\-OS(tm) n6000, Software (n6000\-uk9), | | | | | | | | | Version 7.3(0)N7(5), RELEASE SOFTWARE Copyright | | | | | | | | | (c) 2002\-2012 by Cisco Systems, Inc. Compiled | | | | | | | | | 2/17/2016 22:00:00 | _________________________________________________________________________________________________________________________________________________________________________________________ | edge01.oua01 | xe\-0/1/2 | ae1 | 8C:60:4F:51:A4:22 | | Ethernet1/48 | edge05.oua01.dummy.net | Cisco NX\-OS(tm) n6000, Software (n6000\-uk9), | | | | | | | | | Version 7.3(0)N7(5), RELEASE SOFTWARE Copyright | | | | | | | | | (c) 2002\-2012 by Cisco Systems, Inc. Compiled | | | | | | | | | 2/17/2016 22:00:00 | _________________________________________________________________________________________________________________________________________________________________________________________ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.net.multi_find(*patterns, **kwargs) Execute multiple search tasks. This function is based on the \fIfind\fP function. Depending on the search items, some information might overlap. .sp Optional arguments: .INDENT 7.0 .TP .B best: \fBTrue\fP Return only the best match with the interfaces IP networks when the saerching pattern is a valid IP Address or Network. .TP .B display: \fBTrue\fP Display on the screen or return structured object? Default: \fITrue\fP (return on the CLI). .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt\-run net.multi_find Ethernet1/49 xe\-0/1/2 .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Pattern \(dqEthernet1/49\(dq found in one of the following LLDP details \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | Device | Interface | Parent Interface | Remote Chassis ID | Remote Port Description | Remote Port ID | Remote System Description | Remote System Name | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | edge01.oua04 | xe\-0/1/2 | ae1 | DE:AD:BE:EF:DE:AD | Ethernet1/49 | | Cisco NX\-OS(tm) n6000, Software (n6000\-uk9) | edge07.oua04.dummy.net | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- Details for interface xe\-0/1/2 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | Device | Interface | Interface Description | IP Addresses | Enabled | UP | MAC Address | Speed [Mbps] | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | edge01.oua04 | xe\-0/1/2 | ae1 sw01.oua04 | | True | True | BE:EF:DE:AD:BE:EF | 10000 | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- LLDP Neighbors for interface xe\-0/1/2 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | Device | Interface | Parent Interface | Remote Chassis ID | Remote Port Description | Remote Port ID | Remote System Description | Remote System Name | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | edge01.oua04 | xe\-0/1/2 | ae1 | DE:AD:BE:EF:DE:AD | Ethernet1/49 | | Cisco NX\-OS(tm) n6000, Software (n6000\-uk9) | edge07.oua04.dummy.net | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.network .sp Network tools to run from the Master .INDENT 0.0 .TP .B salt.runners.network.wol(mac, bcast=\(aq255.255.255.255\(aq, destport=9) Send a \(dqMagic Packet\(dq to wake up a Minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run network.wol 08\-00\-27\-13\-69\-77 salt\-run network.wol 080027136977 255.255.255.255 7 salt\-run network.wol 08:00:27:13:69:77 255.255.255.255 7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.network.wollist(maclist, bcast=\(aq255.255.255.255\(aq, destport=9) Send a \(dqMagic Packet\(dq to wake up a list of Minions. This list must contain one MAC hardware address per line .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run network.wollist \(aq/path/to/maclist\(aq salt\-run network.wollist \(aq/path/to/maclist\(aq 255.255.255.255 7 salt\-run network.wollist \(aq/path/to/maclist\(aq 255.255.255.255 7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.network.wolmatch(tgt, tgt_type=\(aqglob\(aq, bcast=\(aq255.255.255.255\(aq, destport=9) Send a \(dqMagic Packet\(dq to wake up Minions that are matched in the grains cache .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run network.wolmatch minion_id salt\-run network.wolmatch 192.168.0.0/16 tgt_type=\(aqipcidr\(aq bcast=255.255.255.255 destport=7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.pagerduty .sp Runner Module for Firing Events via PagerDuty .sp New in version 2014.1.0. .INDENT 0.0 .TP .B configuration This module can be used by specifying the name of a configuration profile in the master config. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my\-pagerduty\-account: pagerduty.api_key: F3Rbyjbve43rfFWf2214 pagerduty.subdomain: mysubdomain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.pagerduty.create_event(service_key=None, description=None, details=None, incident_key=None, profile=None) Create an event in PagerDuty. Designed for use in states. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run pagerduty.create_event <service_key> <description> <details> profile=my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B service_key This key can be found by using pagerduty.list_services. .TP .B description This is a short description of the event. .TP .B details This can be a more detailed description of the event. .TP .B profile This refers to the configuration profile to use to connect to the PagerDuty service. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.pagerduty.list_escalation_policies(profile=None, api_key=None) This function is an alias of \fBlist_policies\fP\&. .INDENT 7.0 .INDENT 3.5 List escalation policies belonging to this account .sp CLI Example: .INDENT 0.0 .INDENT 3.5 salt\-run pagerduty.list_policies my\-pagerduty\-account salt\-run pagerduty.list_escalation_policies my\-pagerduty\-account .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.pagerduty.list_incidents(profile=None, api_key=None) List incidents belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt\-run pagerduty.list_incidents my\-pagerduty\-account .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.pagerduty.list_maintenance_windows(profile=None, api_key=None) This function is an alias of \fBlist_windows\fP\&. .INDENT 7.0 .INDENT 3.5 List maintenance windows belonging to this account .sp CLI Example: .INDENT 0.0 .INDENT 3.5 salt\-run pagerduty.list_windows my\-pagerduty\-account salt\-run pagerduty.list_maintenance_windows my\-pagerduty\-account .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.pagerduty.list_policies(profile=None, api_key=None) List escalation policies belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt\-run pagerduty.list_policies my\-pagerduty\-account salt\-run pagerduty.list_escalation_policies my\-pagerduty\-account .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.pagerduty.list_schedules(profile=None, api_key=None) List schedules belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt\-run pagerduty.list_schedules my\-pagerduty\-account .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.pagerduty.list_services(profile=None, api_key=None) List services belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt\-run pagerduty.list_services my\-pagerduty\-account .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.pagerduty.list_users(profile=None, api_key=None) List users belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt\-run pagerduty.list_users my\-pagerduty\-account .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.pagerduty.list_windows(profile=None, api_key=None) List maintenance windows belonging to this account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt\-run pagerduty.list_windows my\-pagerduty\-account salt\-run pagerduty.list_maintenance_windows my\-pagerduty\-account .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.pillar .sp Functions to interact with the pillar compiler on the master .INDENT 0.0 .TP .B salt.runners.pillar.clear_pillar_cache(minion=\(aq*\(aq, **kwargs) Clears the cached values when using pillar_cache .sp New in version 3003. .sp CLI Example: .sp Clears the pillar cache for a specific minion: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run pillar.clear_pillar_cache \(aqminion\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.pillar.show_pillar(minion=\(aq*\(aq, **kwargs) Returns the compiled pillar either of a specific minion or just the global available pillars. This function assumes that no minion has the id \fB*\fP\&. Function also accepts pillarenv as attribute in order to limit to a specific pillar branch of git .sp CLI Example: .sp shows minion specific pillar: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run pillar.show_pillar \(aqwww.example.com\(aq .ft P .fi .UNINDENT .UNINDENT .sp shows global pillar: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run pillar.show_pillar .ft P .fi .UNINDENT .UNINDENT .sp shows global pillar for \(aqdev\(aq pillar environment: (note that not specifying pillarenv will merge all pillar environments using the master config option pillar_source_merging_strategy.) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run pillar.show_pillar \(aqpillarenv=dev\(aq .ft P .fi .UNINDENT .UNINDENT .sp shows global pillar for \(aqdev\(aq pillar environment and specific pillarenv = dev: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run pillar.show_pillar \(aqsaltenv=dev\(aq \(aqpillarenv=dev\(aq .ft P .fi .UNINDENT .UNINDENT .sp API Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C import salt.config import salt.runner opts = salt.config.master_config(\(aq/etc/salt/master\(aq) runner = salt.runner.RunnerClient(opts) pillar = runner.cmd(\(aqpillar.show_pillar\(aq, []) print(pillar) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.pillar.show_pillar_cache(minion=\(aq*\(aq, **kwargs) Shows the cached values in pillar_cache .sp New in version 3003. .sp CLI Example: .sp Shows the pillar cache for a specific minion: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run pillar.show_pillar_cache \(aqminion\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.pillar.show_top(minion=None, saltenv=\(aqbase\(aq) Returns the compiled top data for pillar for a specific minion. If no minion is specified, we use the first minion we find. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run pillar.show_top .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.pkg .sp Package helper functions using \fBsalt.modules.pkg\fP .sp New in version 2015.8.0. .INDENT 0.0 .TP .B salt.runners.pkg.list_upgrades(jid, style=\(aqgroup\(aq, outputter=\(aqnested\(aq, ext_source=None) Show list of available pkg upgrades using a specified format style .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run pkg.list_upgrades jid=20141120114114417719 style=group .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.queue .SS General management and processing of queues. .sp This runner facilitates interacting with various queue backends such as the included sqlite3 queue or the planned AWS SQS and Redis queues .sp The queue functions such as \fIinsert\fP, \fIdelete\fP, and \fIpop\fP can be used for typical management of the queue. .sp The \fIprocess_queue\fP function pops the requested number of items from the queue and creates a Salt Event that can then be processed by a Reactor. The \fIprocess_queue\fP function can be called manually, or can be configured to run on a schedule with the Salt Scheduler or regular system cron. It is also possible to use the peer system to allow a minion to call the runner. .sp This runner, as well as the Queues system, is not api stable at this time. .sp There are many things that could potentially be done with queues within Salt. For the time being the focus will be on queueing infrastructure actions on specific minions. The queues generally will be populated with minion IDs. When the \fIprocess_queue\fP runner function is called events are created on the Salt Event bus that indicate the queue and a list of one or more minion IDs. The reactor is set up to match on event tags for a specific queue and then take infrastructure actions on those minion IDs. These actions might be to delete the minion\(aqs key from the master, use salt\-cloud to destroy the vm, or some other custom action. .SS Queued runners .sp Using the Salt Queues, references to the commandline arguments of other runners can be saved to be processed later. The queue runners require a queue backend that can store json data (default: \fI\%pgjsonb\fP). .sp Once the queue is setup, the \fIrunner_queue\fP will need to be configured. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C runner_queue: queue: runners backend: pgjsonb .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 only the queue is required, this defaults to using pgjsonb .UNINDENT .UNINDENT .sp Once this is set, then the following can be added to the scheduler on the master and it will run the specified amount of commands per time period. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: runner queue: schedule: function: queue.process_runner minutes: 1 kwargs: quantity: 2 .ft P .fi .UNINDENT .UNINDENT .sp The above configuration will pop 2 runner jobs off the runner queue, and then run them. And it will do this every minute, unless there are any jobs that are still running from the last time the process_runner task was executed. .INDENT 0.0 .TP .B salt.runners.queue.delete(queue, items, backend=\(aqsqlite\(aq) Delete an item or items from a queue .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run queue.delete myqueue myitem salt\-run queue.delete myqueue myitem backend=sqlite salt\-run queue.delete myqueue \(dq[\(aqitem1\(aq, \(aqitem2\(aq, \(aqitem3\(aq]\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.queue.insert(queue, items, backend=\(aqsqlite\(aq) Add an item or items to a queue .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run queue.insert myqueue myitem salt\-run queue.insert myqueue \(dq[\(aqitem1\(aq, \(aqitem2\(aq, \(aqitem3\(aq]\(dq salt\-run queue.insert myqueue myitem backend=sqlite salt\-run queue.insert myqueue \(dq[\(aqitem1\(aq, \(aqitem2\(aq, \(aqitem3\(aq]\(dq backend=sqlite .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.queue.insert_runner(fun, args=None, kwargs=None, queue=None, backend=None) Insert a reference to a runner into the queue so that it can be run later. .INDENT 7.0 .TP .B fun The runner function that is going to be run .TP .B args list or comma\-separated string of args to send to fun .TP .B kwargs dictionary of keyword arguments to send to fun .TP .B queue queue to insert the runner reference into .TP .B backend backend that to use for the queue .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run queue.insert_runner test.stdout_print salt\-run queue.insert_runner event.send test_insert_runner kwargs=\(aq{\(dqdata\(dq: {\(dqfoo\(dq: \(dqbar\(dq}}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.queue.list_items(queue, backend=\(aqsqlite\(aq) List contents of a queue .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run queue.list_items myqueue salt\-run queue.list_items myqueue backend=sqlite .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.queue.list_length(queue, backend=\(aqsqlite\(aq) Provide the number of items in a queue .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run queue.list_length myqueue salt\-run queue.list_length myqueue backend=sqlite .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.queue.list_queues(backend=\(aqsqlite\(aq) Return a list of Salt Queues on the backend .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run queue.list_queues salt\-run queue.list_queues backend=sqlite .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.queue.pop(queue, quantity=1, backend=\(aqsqlite\(aq, is_runner=False) Pop one or more or all items from a queue .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run queue.pop myqueue salt\-run queue.pop myqueue 6 salt\-run queue.pop myqueue all salt\-run queue.pop myqueue 6 backend=sqlite salt\-run queue.pop myqueue all backend=sqlite .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.queue.process_queue(queue, quantity=1, backend=\(aqsqlite\(aq, is_runner=False) Pop items off a queue and create an event on the Salt event bus to be processed by a Reactor. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run queue.process_queue myqueue salt\-run queue.process_queue myqueue 6 salt\-run queue.process_queue myqueue all backend=sqlite .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.queue.process_runner(quantity=1, queue=None, backend=None) Process queued runners .INDENT 7.0 .TP .B quantity number of runners to process .TP .B queue queue to insert the runner reference into .TP .B backend backend that to use for the queue .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run queue.process_runner salt\-run queue.process_runner 5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.reactor .sp A convenience system to manage reactors .sp Beginning in the 2017.7 release, the reactor runner requires that the reactor system is running. This is accomplished one of two ways, either by having reactors configured or by including \fBreactor\fP in the engine configuration for the Salt master. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B engines: .INDENT 7.0 .IP \(bu 2 reactor .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.reactor.add(event, reactors, saltenv=\(aqbase\(aq, test=None) Add a new reactor .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run reactor.add \(aqsalt/cloud/*/destroyed\(aq reactors=\(aq/srv/reactor/destroy/*.sls\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.reactor.delete(event, saltenv=\(aqbase\(aq, test=None) Delete a reactor .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run reactor.delete \(aqsalt/cloud/*/destroyed\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.reactor.is_leader() Return whether the running reactor is acting as a leader (responding to events). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run reactor.is_leader .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.reactor.list_(saltenv=\(aqbase\(aq, test=None) List currently configured reactors .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run reactor.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.reactor.set_leader(value=True) Set the current reactor to act as a leader (responding to events). Defaults to True .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run reactor.set_leader True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.salt .sp This runner makes Salt\(aqs execution modules available on the salt master. .sp New in version 2016.11.0. .sp Salt\(aqs execution modules are normally available on the salt minion. Use this runner to call execution modules on the salt master. Salt \fI\%execution modules\fP are the functions called by the \fBsalt\fP command. .sp Execution modules can be called with \fBsalt\-run\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run salt.cmd test.ping # call functions with arguments and keyword arguments salt\-run salt.cmd test.arg 1 2 3 key=value a=1 .ft P .fi .UNINDENT .UNINDENT .sp Execution modules are also available to salt runners: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __salt__[\(aqsalt.cmd\(aq](fun=fun, args=args, kwargs=kwargs) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.salt.cmd(fun, *args, **kwargs) Changed in version 2018.3.0: Added \fBwith_pillar\fP argument .sp Execute \fBfun\fP with the given \fBargs\fP and \fBkwargs\fP\&. Parameter \fBfun\fP should be the string \fI\%name\fP of the execution module to call. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Execution modules will be loaded \fIevery time\fP this function is called. Additionally, keep in mind that since runners execute on the master, custom execution modules will need to be synced to the master using \fI\%salt\-run saltutil.sync_modules\fP, otherwise they will not be available. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B with_pillar False If \fBTrue\fP, pillar data will be compiled for the master .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To target the master in the pillar top file, keep in mind that the default \fBid\fP for the master is \fB<hostname>_master\fP\&. This can be overridden by setting an \fBid\fP configuration parameter in the master config file. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run salt.cmd test.ping # call functions with arguments and keyword arguments salt\-run salt.cmd test.arg 1 2 3 a=1 salt\-run salt.cmd mymod.myfunc with_pillar=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.salt.execute(tgt, fun, arg=(), timeout=None, tgt_type=\(aqglob\(aq, ret=\(aq\(aq, jid=\(aq\(aq, kwarg=None, **kwargs) New in version 2017.7.0. .sp Execute \fBfun\fP on all minions matched by \fBtgt\fP and \fBtgt_type\fP\&. Parameter \fBfun\fP is the name of execution module function to call. .sp This function should mainly be used as a helper for runner modules, in order to avoid redundant code. For example, when inside a runner one needs to execute a certain function on arbitrary groups of minions, only has to: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ret1 = __salt__[\(aqsalt.execute\(aq](\(aq*\(aq, \(aqmod.fun\(aq) ret2 = __salt__[\(aqsalt.execute\(aq](\(aqmy_nodegroup\(aq, \(aqmod2.fun2\(aq, tgt_type=\(aqnodegroup\(aq) .ft P .fi .UNINDENT .UNINDENT .sp It can also be used to schedule jobs directly on the master, for example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C schedule: collect_bgp_stats: function: salt.execute args: \- edge\-routers \- bgp.neighbors kwargs: tgt_type: nodegroup days: 1 returner: redis .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.saltutil .sp The Saltutil runner is used to sync custom types to the Master. See the \fI\%saltutil module\fP for documentation on managing updates to minions. .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.runners.saltutil.sync_all(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync all custom types .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None dictionary of modules to sync based on type .TP .B extmod_blacklist None dictionary of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_all salt\-run saltutil.sync_all extmod_whitelist={\(aqrunners\(aq: [\(aqcustom_runner\(aq], \(aqgrains\(aq: []} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_cache(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) New in version 2017.7.0. .sp Sync cache modules from \fBsalt://_cache\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_cache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_clouds(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) New in version 2017.7.0. .sp Sync cloud modules from \fBsalt://_clouds\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_clouds .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_eauth_tokens(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) New in version 2018.3.0. .sp Sync eauth token modules from \fBsalt://_tokens\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_eauth_tokens .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_engines(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync engines from \fBsalt://_engines\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_engines .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_executors(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) New in version 3000. .sp Sync executor modules from \fBsalt://_executors\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-seperated list of modules to sync .TP .B extmod_blacklist None comma\-seperated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_executors .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_fileserver(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) New in version 2018.3.0. .sp Sync fileserver modules from \fBsalt://_fileserver\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_fileserver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_grains(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync grains modules from \fBsalt://_grains\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_grains .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_modules(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync execution modules from \fBsalt://_modules\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_modules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_output(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync output modules from \fBsalt://_output\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_output .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_pillar(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync pillar modules from \fBsalt://_pillar\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_pillar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_proxymodules(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync proxy modules from \fBsalt://_proxy\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_proxymodules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_queues(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync queue modules from \fBsalt://_queues\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_queues .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_renderers(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync renderer modules from from \fBsalt://_renderers\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_renderers .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_returners(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync returner modules from \fBsalt://_returners\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_returners .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_roster(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) New in version 2017.7.0. .sp Sync roster modules from \fBsalt://_roster\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_roster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_runners(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync runners from \fBsalt://_runners\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_runners .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_sdb(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) New in version 2017.7.0. .sp Sync sdb modules from \fBsalt://_sdb\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_sdb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_serializers(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) New in version 2019.2.0. .sp Sync serializer modules from \fBsalt://_serializers\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-seperated list of modules to sync .TP .B extmod_blacklist None comma\-seperated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_utils .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_states(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync state modules from \fBsalt://_states\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_states .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_thorium(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) New in version 2018.3.0. .sp Sync Thorium from \fBsalt://_thorium\fP to the master .INDENT 7.0 .TP .B saltenv: \fBbase\fP The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist comma\-separated list of modules to sync .TP .B extmod_blacklist comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_thorium .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_tops(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) New in version 2016.3.7,2016.11.4,2017.7.0. .sp Sync master_tops modules from \fBsalt://_tops\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_tops .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_utils(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) New in version 2016.11.0. .sp Sync utils modules from \fBsalt://_utils\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_utils .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_wheel(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) Sync wheel modules from \fBsalt://_wheel\fP to the master .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-separated list of modules to sync .TP .B extmod_blacklist None comma\-separated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_wheel .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.saltutil.sync_wrapper(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) New in version 3007.0. .sp Sync salt\-ssh wrapper modules from \fBsalt://_wrapper\fP to the master. .INDENT 7.0 .TP .B saltenv base The fileserver environment from which to sync. To sync from more than one environment, pass a comma\-separated list. .TP .B extmod_whitelist None comma\-seperated list of modules to sync .TP .B extmod_blacklist None comma\-seperated list of modules to blacklist based on type .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run saltutil.sync_wrapper .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.sdb .sp Runner for setting and querying data via the sdb API on the master .INDENT 0.0 .TP .B salt.runners.sdb.delete(uri) Delete a value from a db, using a uri in the form of \fBsdb://<profile>/<key>\fP\&. If the uri provided does not start with \fBsdb://\fP or the value is not successfully deleted, return \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run sdb.delete sdb://mymemcached/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.sdb.get(uri) Get a value from a db, using a uri in the form of sdb://<profile>/<key>. If the uri provided does not start with sdb://, then it will be returned as\-is. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run sdb.get sdb://mymemcached/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.sdb.get_or_set_hash(uri, length=8, chars=\(aqabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(\-_=+)\(aq) Perform a one\-time generation of a hash and write it to sdb. If that value has already been set return the value instead. .sp This is useful for generating passwords or keys that are specific to multiple minions that need to be stored somewhere centrally. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run sdb.get_or_set_hash \(aqSECRET_KEY\(aq 50 .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This function could return strings which may contain characters which are reserved as directives by the YAML parser, such as strings beginning with \fB%\fP\&. To avoid issues when using the output of this function in an SLS file containing YAML+Jinja, surround the call with single quotes. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.sdb.set_(uri, value) Set a value in a db, using a uri in the form of \fBsdb://<profile>/<key>\fP\&. If the uri provided does not start with \fBsdb://\fP or the value is not successfully set, return \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run sdb.set sdb://mymemcached/foo bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.smartos_vmadm .sp Runner for SmartOS minions control vmadm .INDENT 0.0 .TP .B salt.runners.smartos_vmadm.get(search, one=True) Return information for vms .INDENT 7.0 .TP .B search string filter vms, see the execution module. .TP .B one boolean return only one vm .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the search parameter does not contain an equal (=) symbol it will be assumed it will be tried as uuid, hostname, and alias. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vmadm.get 91244bba\-1146\-e4ec\-c07e\-e825e0223aa9 salt\-run vmadm.get search=\(aqalias=saskia\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.smartos_vmadm.is_running(search) Return true if vm is running .INDENT 7.0 .TP .B search string filter vms, see the execution module. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the search parameter does not contain an equal (=) symbol it will be assumed it will be tried as uuid, hostname, and alias. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If multiple vms are matched, the result will be true of ALL vms are running .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vmadm.is_running 91244bba\-1146\-e4ec\-c07e\-e825e0223aa9 salt\-run vmadm.is_running search=\(aqalias=julia\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.smartos_vmadm.list_vms(search=None, verbose=False) List all vms .INDENT 7.0 .TP .B search string filter vms, see the execution module .TP .B verbose boolean print additional information about the vm .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vmadm.list salt\-run vmadm.list search=\(aqtype=KVM\(aq salt\-run vmadm.list verbose=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.smartos_vmadm.nodes(verbose=False) List all compute nodes .INDENT 7.0 .TP .B verbose boolean print additional information about the node e.g. platform version, hvm capable, ... .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vmadm.nodes salt\-run vmadm.nodes verbose=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.smartos_vmadm.reboot(search, one=True, force=False) Reboot one or more vms .INDENT 7.0 .TP .B search string filter vms, see the execution module. .TP .B one boolean reboot only one vm .TP .B force boolean force reboot, faster but no graceful shutdown .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the search parameter does not contain an equal (=) symbol it will be assumed it will be tried as uuid, hostname, and alias. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vmadm.reboot 91244bba\-1146\-e4ec\-c07e\-e825e0223aa9 salt\-run vmadm.reboot search=\(aqalias=marije\(aq salt\-run vmadm.reboot search=\(aqtype=KVM\(aq one=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.smartos_vmadm.start(search, one=True) Start one or more vms .INDENT 7.0 .TP .B search string filter vms, see the execution module. .TP .B one boolean start only one vm .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the search parameter does not contain an equal (=) symbol it will be assumed it will be tried as uuid, hostname, and alias. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vmadm.start 91244bba\-1146\-e4ec\-c07e\-e825e0223aa9 salt\-run vmadm.start search=\(aqalias=jiska\(aq salt\-run vmadm.start search=\(aqtype=KVM\(aq one=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.smartos_vmadm.stop(search, one=True) Stop one or more vms .INDENT 7.0 .TP .B search string filter vms, see the execution module. .TP .B one boolean stop only one vm .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the search parameter does not contain an equal (=) symbol it will be assumed it will be tried as uuid, hostname, and alias. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vmadm.stop 91244bba\-1146\-e4ec\-c07e\-e825e0223aa9 salt\-run vmadm.stop search=\(aqalias=jody\(aq salt\-run vmadm.stop search=\(aqtype=KVM\(aq one=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.spacewalk .SS Spacewalk Runner .sp New in version 2016.3.0. .sp Runner to interact with Spacewalk using Spacewalk API .INDENT 0.0 .TP .B codeauthor Nitin Madhok <\fI\%nmadhok@g.clemson.edu\fP>, Joachim Werner <\fI\%joe@suse.com\fP>, Benedikt Werner <\fI\%1benediktwerner@gmail.com\fP> .TP .B maintainer Benedikt Werner <\fI\%1benediktwerner@gmail.com\fP> .UNINDENT .sp To use this runner, set up the Spacewalk URL, username and password in the master configuration at \fB/etc/salt/master\fP or \fB/etc/salt/master.d/spacewalk.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C spacewalk: spacewalk01.domain.com: username: \(aqtestuser\(aq password: \(aqverybadpass\(aq spacewalk02.domain.com: username: \(aqtestuser\(aq password: \(aqverybadpass\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Optionally, \fBprotocol\fP can be specified if the spacewalk server is not using the defaults. Default is \fBprotocol: https\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.spacewalk.addGroupsToKey(server, activation_key, groups) Add server groups to a activation key .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run spacewalk.addGroupsToKey spacewalk01.domain.com 1\-my\-key \(aq[group1, group2]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.spacewalk.api(server, command, *args, **kwargs) Call the Spacewalk xmlrpc api. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run spacewalk.api spacewalk01.domain.com systemgroup.create MyGroup Description salt\-run spacewalk.api spacewalk01.domain.com systemgroup.create arguments=\(aq[\(dqMyGroup\(dq, \(dqDescription\(dq]\(aq .ft P .fi .UNINDENT .UNINDENT .sp State Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C create_group: salt.runner: \- name: spacewalk.api \- server: spacewalk01.domain.com \- command: systemgroup.create \- arguments: \- MyGroup \- Description .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.spacewalk.deleteAllActivationKeys(server) Delete all activation keys from Spacewalk .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run spacewalk.deleteAllActivationKeys spacewalk01.domain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.spacewalk.deleteAllGroups(server) Delete all server groups from Spacewalk .UNINDENT .INDENT 0.0 .TP .B salt.runners.spacewalk.deleteAllSystems(server) Delete all systems from Spacewalk .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run spacewalk.deleteAllSystems spacewalk01.domain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.spacewalk.unregister(name, server_url) Unregister specified server from Spacewalk .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run spacewalk.unregister my\-test\-vm spacewalk01.domain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.ssh .sp A Runner module interface on top of the salt\-ssh Python API. .sp This allows for programmatic use from salt\-api, the Reactor, Orchestrate, etc. .INDENT 0.0 .TP .B salt.runners.ssh.cmd(tgt, fun, arg=(), timeout=None, tgt_type=\(aqglob\(aq, kwarg=None) New in version 2015.5.0. .sp Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Execute a single command via the salt\-ssh subsystem and return all routines at once .sp A wrapper around the \fI\%SSHClient.cmd\fP method. .UNINDENT .SS salt.runners.state .sp Execute orchestration functions .INDENT 0.0 .TP .B salt.runners.state.event(tagmatch=\(aq*\(aq, count=\-1, quiet=False, sock_dir=None, pretty=False, node=\(aqmaster\(aq) Watch Salt\(aqs event bus and block until the given tag is matched .sp New in version 2014.7.0. .sp Changed in version 2019.2.0: \fBtagmatch\fP can now be either a glob or regular expression. .sp This is useful for utilizing Salt\(aqs event bus from shell scripts or for taking simple actions directly from the CLI. .sp Enable debug logging to see ignored events. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtagmatch\fP \-\- the event is written to stdout for each tag that matches this glob or regular expression. .IP \(bu 2 \fBcount\fP \-\- this number is decremented for each event that matches the \fBtagmatch\fP parameter; pass \fB\-1\fP to listen forever. .IP \(bu 2 \fBquiet\fP \-\- do not print to stdout; just block .IP \(bu 2 \fBsock_dir\fP \-\- path to the Salt master\(aqs event socket file. .IP \(bu 2 \fBpretty\fP \-\- Output the JSON all on a single line if \fBFalse\fP (useful for shell tools); pretty\-print the JSON output if \fBTrue\fP\&. .IP \(bu 2 \fBnode\fP \-\- Watch the minion\-side or master\-side event bus. \&.. versionadded:: 2016.3.0 .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Reboot a minion and run highstate when it comes back online salt \(aqjerry\(aq system.reboot && \e\e salt\-run state.event \(aqsalt/minion/jerry/start\(aq count=1 quiet=True && \e\e salt \(aqjerry\(aq state.highstate # Reboot multiple minions and run highstate when all are back online salt \-L \(aqkevin,stewart,dave\(aq system.reboot && \e\e salt\-run state.event \(aqsalt/minion/*/start\(aq count=3 quiet=True && \e\e salt \-L \(aqkevin,stewart,dave\(aq state.highstate # Watch the event bus forever in a shell while\-loop. salt\-run state.event | while read \-r tag data; do echo $tag echo $data | jq \-\-color\-output . done .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 See \fI\%tests/eventlisten.sh\fP for an example of usage within a shell script. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.state.orch(mods, saltenv=\(aqbase\(aq, test=None, exclude=None, pillar=None, pillarenv=None, pillar_enc=None, orchestration_jid=None) This function is an alias of \fBorchestrate\fP\&. .INDENT 7.0 .INDENT 3.5 New in version 0.17.0. .sp Execute a state run from the master, used as a powerful orchestration system. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 More Orchestrate documentation .INDENT 0.0 .IP \(bu 2 \fI\%Full Orchestrate Tutorial\fP .IP \(bu 2 \fI\%Docs for the master\-side state module\fP .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate webserver salt\-run state.orchestrate webserver saltenv=dev test=True salt\-run state.orchestrate webserver saltenv=dev pillarenv=aws .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.1.1: Runner renamed from \fBstate.sls\fP to \fBstate.orchestrate\fP .sp Changed in version 2014.7.0: Runner uses the pillar variable .sp Changed in version 2017.5.0: Runner uses the pillar_enc variable that allows renderers to render the pillar. This is usable when supplying the contents of a file as pillar, and the file contains gpg\-encrypted entries. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 GPG renderer documentation .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate webserver pillar_enc=gpg pillar=\(dq$(cat somefile.json)\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.state.orch_show_sls(mods, saltenv=\(aqbase\(aq, test=None, queue=False, pillar=None, pillarenv=None, pillar_enc=None) This function is an alias of \fBorchestrate_show_sls\fP\&. .INDENT 7.0 .INDENT 3.5 Display the state data from a specific sls, or list of sls files, after being render using the master minion. .sp Note, the master minion adds a \(dq_master\(dq suffix to its minion id. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 The state.show_sls module function .UNINDENT .UNINDENT .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orch_show_sls my\-orch\-formula.my\-orch\-state \(aqpillar={ nodegroup: ng1 }\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.state.orchestrate(mods, saltenv=\(aqbase\(aq, test=None, exclude=None, pillar=None, pillarenv=None, pillar_enc=None, orchestration_jid=None) New in version 0.17.0. .sp Execute a state run from the master, used as a powerful orchestration system. .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 More Orchestrate documentation .INDENT 0.0 .IP \(bu 2 \fI\%Full Orchestrate Tutorial\fP .IP \(bu 2 \fI\%Docs for the master\-side state module\fP .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate webserver salt\-run state.orchestrate webserver saltenv=dev test=True salt\-run state.orchestrate webserver saltenv=dev pillarenv=aws .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.1.1: Runner renamed from \fBstate.sls\fP to \fBstate.orchestrate\fP .sp Changed in version 2014.7.0: Runner uses the pillar variable .sp Changed in version 2017.5.0: Runner uses the pillar_enc variable that allows renderers to render the pillar. This is usable when supplying the contents of a file as pillar, and the file contains gpg\-encrypted entries. .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 GPG renderer documentation .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate webserver pillar_enc=gpg pillar=\(dq$(cat somefile.json)\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.state.orchestrate_high(data, test=None, queue=False, pillar=None, **kwargs) Execute a single state orchestration routine .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate_high \(aq{ stage_one: {salt.state: [{tgt: \(dqdb*\(dq}, {sls: postgres_setup}]}, stage_two: {salt.state: [{tgt: \(dqweb*\(dq}, {sls: apache_setup}, { require: [{salt: stage_one}], }]}, }\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.state.orchestrate_show_sls(mods, saltenv=\(aqbase\(aq, test=None, queue=False, pillar=None, pillarenv=None, pillar_enc=None) Display the state data from a specific sls, or list of sls files, after being render using the master minion. .sp Note, the master minion adds a \(dq_master\(dq suffix to its minion id. .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 The state.show_sls module function .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orch_show_sls my\-orch\-formula.my\-orch\-state \(aqpillar={ nodegroup: ng1 }\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.state.orchestrate_single(fun, name, test=None, queue=False, pillar=None, **kwargs) Execute a single state orchestration routine .sp New in version 2015.5.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate_single fun=salt.wheel name=key.list_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.state.pause(jid, state_id=None, duration=None) Set up a state id pause, this instructs a running state to pause at a given state id. This needs to pass in the jid of the running state and can optionally pass in a duration in seconds. .UNINDENT .INDENT 0.0 .TP .B salt.runners.state.resume(jid, state_id=None) Remove a pause from a jid, allowing it to continue .UNINDENT .INDENT 0.0 .TP .B salt.runners.state.rm_pause(jid, state_id=None) This function is an alias of \fBresume\fP\&. .INDENT 7.0 .INDENT 3.5 Remove a pause from a jid, allowing it to continue .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.state.set_pause(jid, state_id=None, duration=None) This function is an alias of \fBpause\fP\&. .INDENT 7.0 .INDENT 3.5 Set up a state id pause, this instructs a running state to pause at a given state id. This needs to pass in the jid of the running state and can optionally pass in a duration in seconds. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.state.sls(mods, saltenv=\(aqbase\(aq, test=None, exclude=None, pillar=None, pillarenv=None, pillar_enc=None, orchestration_jid=None) This function is an alias of \fBorchestrate\fP\&. .INDENT 7.0 .INDENT 3.5 New in version 0.17.0. .sp Execute a state run from the master, used as a powerful orchestration system. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 More Orchestrate documentation .INDENT 0.0 .IP \(bu 2 \fI\%Full Orchestrate Tutorial\fP .IP \(bu 2 \fI\%Docs for the master\-side state module\fP .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate webserver salt\-run state.orchestrate webserver saltenv=dev test=True salt\-run state.orchestrate webserver saltenv=dev pillarenv=aws .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.1.1: Runner renamed from \fBstate.sls\fP to \fBstate.orchestrate\fP .sp Changed in version 2014.7.0: Runner uses the pillar variable .sp Changed in version 2017.5.0: Runner uses the pillar_enc variable that allows renderers to render the pillar. This is usable when supplying the contents of a file as pillar, and the file contains gpg\-encrypted entries. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 GPG renderer documentation .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate webserver pillar_enc=gpg pillar=\(dq$(cat somefile.json)\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.state.soft_kill(jid, state_id=None) Set up a state run to die before executing the given state id, this instructs a running state to safely exit at a given state id. This needs to pass in the jid of the running state. If a state_id is not passed then the jid referenced will be safely exited at the beginning of the next state run. .UNINDENT .SS salt.runners.survey .sp A general map/reduce style salt runner for aggregating results returned by several different minions. .sp New in version 2014.7.0. .sp Aggregated results are sorted by the size of the minion pools which returned matching results. .sp Useful for playing the game: \fI\(dqsome of these things are not like the others...\(dq\fP when identifying discrepancies in a large infrastructure managed by salt. .INDENT 0.0 .TP .B salt.runners.survey.diff(*args, **kwargs) Return the DIFFERENCE of the result sets returned by each matching minion pool .sp New in version 2014.7.0. .sp These pools are determined from the aggregated and sorted results of a salt command. .sp This command displays the \(dqdiffs\(dq as a series of 2\-way differences \-\- namely the difference between the FIRST displayed minion pool (according to sort order) and EACH SUBSEQUENT minion pool result set. .sp Differences are displayed according to the Python \fBdifflib.unified_diff()\fP as in the case of the salt execution module \fBfile.get_diff\fP\&. .sp This command is submitted via a salt runner using the general form: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run survey.diff [survey_sort=up/down] <target> <salt\-execution\-module> <salt\-execution\-module parameters> .ft P .fi .UNINDENT .UNINDENT .sp Optionally accept a \fBsurvey_sort=\fP parameter. Default: \fBsurvey_sort=down\fP .sp CLI Example #1: (Example to display the \(dqdifferences of files\(dq) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run survey.diff survey_sort=up \(dq*\(dq cp.get_file_str file:///etc/hosts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.survey.hash(*args, **kwargs) Return the MATCHING minion pools from the aggregated and sorted results of a salt command .sp New in version 2014.7.0. .sp This command is submitted via a salt runner using the general form: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run survey.hash [survey_sort=up/down] <target> <salt\-execution\-module> <salt\-execution\-module parameters> .ft P .fi .UNINDENT .UNINDENT .sp Optionally accept a \fBsurvey_sort=\fP parameter. Default: \fBsurvey_sort=down\fP .sp CLI Example #1: (functionally equivalent to \fBsalt\-run manage.up\fP) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run survey.hash \(dq*\(dq test.ping .ft P .fi .UNINDENT .UNINDENT .sp CLI Example #2: (find an \(dqoutlier\(dq minion config file) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run survey.hash \(dq*\(dq file.get_hash /etc/salt/minion survey_sort=up .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.test .sp This runner is used only for test purposes and serves no production purpose .INDENT 0.0 .TP .B salt.runners.test.arg(*args, **kwargs) Output the given args and kwargs .sp Kwargs will be filtered for \(aqprivate\(aq keynames. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run test.arg foo bar=baz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.test.get_opts() New in version 2018.3.0. .sp Return the configuration options of the master. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run test.get_opts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.test.metasyntactic(locality=\(aqus\(aq) Return common metasyntactic variables for the given locality .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run test.metasyntactic locality=uk .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.test.raw_arg(*args, **kwargs) Output the given args and kwargs .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run test.arg foo __bar=baz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.test.sleep(s_time=10) Sleep t seconds, then return True .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run test.sleep s_time=5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.test.stdout_print() Print \(aqfoo\(aq and return \(aqbar\(aq .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run test.stdout_print .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.test.stream() Fire a stream of 100 test events, then return True .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run test.stream .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.thin .sp The thin runner is used to manage the salt thin systems. .sp Salt Thin is a transport\-less version of Salt that can be used to run routines in a standalone way. This runner has tools which generate the standalone salt system for easy consumption. .INDENT 0.0 .TP .B salt.runners.thin.generate(extra_mods=\(aq\(aq, overwrite=False, so_mods=\(aq\(aq, absonly=True, compress=\(aqgzip\(aq) Generate the salt\-thin tarball and print the location of the tarball Optional additional mods to include (e.g. mako) can be supplied as a comma delimited string. Permits forcing an overwrite of the output file as well. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run thin.generate salt\-run thin.generate mako salt\-run thin.generate mako,wempy 1 salt\-run thin.generate overwrite=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.thin.generate_min(extra_mods=\(aq\(aq, overwrite=False, so_mods=\(aq\(aq) Generate the salt\-thin tarball and print the location of the tarball Optional additional mods to include (e.g. mako) can be supplied as a comma delimited string. Permits forcing an overwrite of the output file as well. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run thin.generate_min .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.vault .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%vault Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Runner functions supporting the Vault modules. Configuration instructions are documented in the \fI\%execution module docs\fP\&. .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity new .TP .B platform all .UNINDENT .INDENT 0.0 .TP .B class salt.runners.vault.LazyPillar(opts, grains, minion_id, extra_minion_data=None) Simulates a pillar dictionary. Only compiles the pillar once an item is requested. .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.cleanup_auth() New in version 3007.0. .sp Removes AppRoles and entities associated with unknown minion IDs. Can only clean up entities if the AppRole still exists. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Make absolutely sure that the configured minion approle issue mount is exclusively dedicated to the Salt master, otherwise you might lose data by using this function! (config: \fBvault:issue:approle:mount\fP) .sp This detects unknown existing AppRoles by listing all roles on the configured minion AppRole mount and deducting known minions from the returned list. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vault.cleanup_auth .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.clear_cache(master=True, minions=True) New in version 3007.0. .sp Clears master cache of Vault\-specific data. This can include: \- AppRole metadata \- rendered policies \- cached authentication credentials for impersonated minions \- cached KV metadata for impersonated minions .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vault.clear_cache salt\-run vault.clear_cache minions=false salt\-run vault.clear_cache master=false minions=\(aq[minion1, minion2]\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B master Clear cached data for the master context. Includes cached master authentication data and KV metadata. Defaults to true. .TP .B minions Clear cached data for minions on the master. Can include cached authentication credentials and KV metadata for pillar compilation as well as AppRole metadata and rendered policies for credential issuance. Defaults to true. Set this to a list of minion IDs to only clear cached data pertaining to thse minions. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.generate_new_token(minion_id, signature, impersonated_by_master=False, issue_params=None) New in version 3007.0. .sp Generate a Vault token for minion <minion_id>. .INDENT 7.0 .TP .B minion_id The ID of the minion that requests a token. .TP .B signature Cryptographic signature which validates that the request is indeed sent by the minion (or the master, see impersonated_by_master). .TP .B impersonated_by_master If the master needs to create a token on behalf of the minion, this is True. This happens when the master generates minion pillars. .TP .B issue_params Dictionary of parameters for the generated tokens. See master configuration \fBvault:issue:token:params\fP for possible values. Requires \fBvault:issue:allow_minion_override_params\fP master configuration setting to be effective. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.generate_secret_id(minion_id, signature, impersonated_by_master=False, issue_params=None) New in version 3007.0. .sp Generate a Vault secret ID for minion <minion_id>. Requires the master to be configured to generate AppRoles for minions (configuration: \fBvault:issue:type\fP). .INDENT 7.0 .TP .B minion_id The ID of the minion that requests a secret ID. .TP .B signature Cryptographic signature which validates that the request is indeed sent by the minion (or the master, see impersonated_by_master). .TP .B impersonated_by_master If the master needs to create a token on behalf of the minion, this is True. This happens when the master generates minion pillars. .TP .B issue_params Dictionary of configuration values for the generated AppRole. See master configuration vault:issue:approle:params for possible values. Requires \fBvault:issue:allow_minion_override_params\fP master configuration setting to be effective. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.generate_token(minion_id, signature, impersonated_by_master=False, ttl=None, uses=None, upgrade_request=False) Deprecated since version 3007.0. .sp Generate a Vault token for minion <minion_id>. .INDENT 7.0 .TP .B minion_id The ID of the minion that requests a token. .TP .B signature Cryptographic signature which validates that the request is indeed sent by the minion (or the master, see impersonated_by_master). .TP .B impersonated_by_master If the master needs to create a token on behalf of the minion, this is True. This happens when the master generates minion pillars. .TP .B ttl Ticket time to live in seconds, 1m minutes, or 2h hrs .TP .B uses Number of times a token can be used .TP .B upgrade_request In case the new runner endpoints have not been whitelisted for peer running, this endpoint serves as a gateway to \fBvault.get_config\fP\&. Defaults to False. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.get_config(minion_id, signature, impersonated_by_master=False, issue_params=None, config_only=False) New in version 3007.0. .sp Return Vault configuration for minion <minion_id>. .INDENT 7.0 .TP .B minion_id The ID of the minion that requests the configuration. .TP .B signature Cryptographic signature which validates that the request is indeed sent by the minion (or the master, see impersonated_by_master). .TP .B impersonated_by_master If the master needs to contact the Vault server on behalf of the minion, this is True. This happens when the master generates minion pillars. .TP .B issue_params Parameters for credential issuance. Requires \fBvault:issue:allow_minion_override_params\fP master configuration setting to be effective. .TP .B config_only In case the master is configured to issue tokens, do not include a new token in the response. This is used for configuration update checks. Defaults to false. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.get_role_id(minion_id, signature, impersonated_by_master=False, issue_params=None) New in version 3007.0. .sp Return the Vault role\-id for minion <minion_id>. Requires the master to be configured to generate AppRoles for minions (configuration: \fBvault:issue:type\fP). .INDENT 7.0 .TP .B minion_id The ID of the minion that requests a role\-id. .TP .B signature Cryptographic signature which validates that the request is indeed sent by the minion (or the master, see impersonated_by_master). .TP .B impersonated_by_master If the master needs to create a token on behalf of the minion, this is True. This happens when the master generates minion pillars. .TP .B issue_params Dictionary of configuration values for the generated AppRole. See master configuration vault:issue:approle:params for possible values. Requires \fBvault:issue:allow_minion_override_params\fP master configuration setting to be effective. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.list_approles() New in version 3007.0. .sp List all AppRoles that have been created by the Salt master. They are named after the minions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vault.list_approles .ft P .fi .UNINDENT .UNINDENT .sp Required policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C path \(dqauth/<mount>/role\(dq { capabilities = [\(dqlist\(dq] } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.list_entities() New in version 3007.0. .sp List all entities that have been created by the Salt master. They are named \fIsalt_minion_{minion_id}\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vault.list_entities .ft P .fi .UNINDENT .UNINDENT .sp Required policy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C path \(dqidentity/entity/name\(dq { capabilities = [\(dqlist\(dq] } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.show_approle(minion_id) New in version 3007.0. .sp Show AppRole configuration for <minion_id>. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vault.show_approle db1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.show_entity(minion_id) New in version 3007.0. .sp Show entity metadata for <minion_id>. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vault.show_entity db1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.show_policies(minion_id, refresh_pillar=<Constant.NOT_SET>, expire=None) Show the Vault policies that are applied to tokens for the given minion. .INDENT 7.0 .TP .B minion_id The ID of the minion to show policies for. .TP .B refresh_pillar Whether to refresh the pillar data when rendering templated policies. None will only refresh when the cached data is unavailable, boolean values force one behavior always. Defaults to config value \fBvault:policies:refresh_pillar\fP or None. .TP .B expire Policy computation can be heavy in case pillar data is used in templated policies and it has not been cached. Therefore, a short\-lived cache specifically for rendered policies is used. This specifies the expiration timeout in seconds. Defaults to config value \fBvault:policies:cache_time\fP or 60. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When issuing AppRoles to minions, the shown policies are read from Vault configuration for the minion\(aqs AppRole and thus refresh_pillar/expire will not be honored. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vault.show_policies myminion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.sync_approles(minions=None, up=False, down=False) New in version 3007.0. .sp Sync minion AppRole parameters with current settings, including associated token policies. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Only updates existing AppRoles. They are issued during the first request for one by the minion. Running this will reset minion overrides, which are reapplied automatically during the next request for authentication details. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Unlike when issuing tokens, AppRole\-associated policies are not regularly refreshed automatically. It is advised to schedule regular runs of this function. .UNINDENT .UNINDENT .sp If no parameter is specified, will try to sync AppRoles for all known minions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vault.sync_approles salt\-run vault.sync_approles ecorp .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B minions (List of) ID(s) of the minion(s) to update the AppRole for. Defaults to None. .TP .B up Find all minions that are up and update their AppRoles. Defaults to False. .TP .B down Find all minions that are down and update their AppRoles. Defaults to False. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.sync_entities(minions=None, up=False, down=False) New in version 3007.0. .sp Sync minion entities with current settings. Only updates entities for minions with existing AppRoles. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This updates associated metadata only. Entities are created only when issuing AppRoles to minions (\fBvault:issue:type\fP == \fBapprole\fP). .UNINDENT .UNINDENT .sp If no parameter is specified, will try to sync entities for all known minions. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vault.sync_entities .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B minions (List of) ID(s) of the minion(s) to update the entity for. Defaults to None. .TP .B up Find all minions that are up and update their associated entities. Defaults to False. .TP .B down Find all minions that are down and update their associated entities. Defaults to False. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vault.unseal() Unseal Vault server .sp This function uses the \(aqkeys\(aq from the \(aqvault\(aq configuration to unseal vault server .INDENT 7.0 .TP .B vault: .INDENT 7.0 .TP .B keys: .INDENT 7.0 .IP \(bu 2 n63/TbrQuL3xaIW7ZZpuXj/tIfnK1/MbVxO4vT3wYD2A .IP \(bu 2 S9OwCvMRhErEA4NVVELYBs6w/Me6+urgUr24xGK44Uy3 .IP \(bu 2 F1j4b7JKq850NS6Kboiy5laJ0xY8dWJvB3fcwA+SraYl .IP \(bu 2 1cYtvjKJNDVam9c7HNqJUfINk4PYyAXIpjkpN/sIuzPv .IP \(bu 2 3pPK5X6vGtwLhNOFv1U2elahECz3HpRUfNXJFYLw6lid .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vault.unseal .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.venafiapi .sp Support for Venafi .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 vcert Python module .UNINDENT .TP .B configuration In order to connect to Venafi services you need to specify it in Salt master configuration. Example for Venafi Cloud (using env variables): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B venafi: api_key: \(dqsdb://osenv/CLOUDAPIKEY\(dq .UNINDENT .sp Example for Venafi Platform (using env variables): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B venafi: base_url: \(dq\fI\%https://tpp.example.com/\fP\(dq tpp_user: admin tpp_password: \(dqsdb://osenv/TPP_PASSWORD\(dq trust_bundle: \(dq/opt/venafi/bundle.pem\(dq .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.venafiapi.del_cached_domain(domains) Delete cached domains from the master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run venafi.del_cached_domain domain1.example.com,domain2.example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.venafiapi.list_domain_cache() List domains that have been cached .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run venafi.list_domain_cache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.venafiapi.renew(minion_id, dns_name=None, zone=None, country=None, state=None, loc=None, org=None, org_unit=None, key_password=None, csr_path=None, pkey_path=None) Request a new certificate .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run venafi.request <minion_id> <dns_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.venafiapi.request(minion_id, dns_name=None, zone=None, country=None, state=None, loc=None, org=None, org_unit=None, key_password=None, csr_path=None, pkey_path=None) Request a new certificate .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run venafi.request <minion_id> <dns_name> .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.venafiapi.show_cert(dns_name) Show issued certificate for domain .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run venafi.show_cert example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.virt .sp Control virtual machines via Salt .INDENT 0.0 .TP .B salt.runners.virt.force_off(name) Force power down the named virtual machine .UNINDENT .INDENT 0.0 .TP .B salt.runners.virt.host_info(host=None) Return information about the host connected to this master .UNINDENT .INDENT 0.0 .TP .B salt.runners.virt.init(name, cpu, mem, image, hypervisor=\(aqkvm\(aq, host=None, seed=True, nic=\(aqdefault\(aq, install=True, start=True, disk=\(aqdefault\(aq, saltenv=\(aqbase\(aq, enable_vnc=False, seed_cmd=\(aqseed.apply\(aq, enable_qcow=False, serial_type=\(aqNone\(aq) This routine is used to create a new virtual machine. This routines takes a number of options to determine what the newly created virtual machine will look like. .INDENT 7.0 .TP .B name The mandatory name of the new virtual machine. The name option is also the minion id, all minions must have an id. .TP .B cpu The number of cpus to allocate to this new virtual machine. .TP .B mem The amount of memory to allocate to this virtual machine. The number is interpreted in megabytes. .TP .B image The network location of the virtual machine image, commonly a location on the salt fileserver, but http, https and ftp can also be used. .TP .B hypervisor The hypervisor to use for the new virtual machine. Default is \fIkvm\fP\&. .TP .B host The host to use for the new virtual machine, if this is omitted Salt will automatically detect what host to use. .TP .B seed Set to \fIFalse\fP to prevent Salt from seeding the new virtual machine. .TP .B nic The nic profile to use, defaults to the \(dqdefault\(dq nic profile which assumes a single network interface per VM associated with the \(dqbr0\(dq bridge on the master. .TP .B install Set to False to prevent Salt from installing a minion on the new VM before it spins up. .TP .B disk The disk profile to use .TP .B saltenv The Salt environment to use .TP .B enable_vnc Whether a VNC screen is attached to resulting VM. Default is \fIFalse\fP\&. .TP .B seed_cmd If seed is \fITrue\fP, use this execution module function to seed new VM. Default is \fIseed.apply\fP\&. .TP .B enable_qcow Clone disk image as a copy\-on\-write qcow2 image, using downloaded \fIimage\fP as backing file. .TP .B serial_type Enable serial console. Set to \(aqpty\(aq for serial console or \(aqtcp\(aq for telnet. Default is \(aqNone\(aq .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.virt.list(host=None, quiet=False, hyper=None) List the virtual machines on each host, this is a simplified query, showing only the virtual machine names belonging to each host. A single host can be passed in to specify an individual host to list. .UNINDENT .INDENT 0.0 .TP .B salt.runners.virt.migrate(name, target=\(aq\(aq) Migrate a VM from one host to another. This routine will just start the migration and display information on how to look up the progress. .UNINDENT .INDENT 0.0 .TP .B salt.runners.virt.next_host() Return the host to use for the next autodeployed VM. This queries the available host and executes some math the determine the most \(dqavailable\(dq next host. .UNINDENT .INDENT 0.0 .TP .B salt.runners.virt.pause(name) Pause the named VM .UNINDENT .INDENT 0.0 .TP .B salt.runners.virt.purge(name, delete_key=True) Destroy the named VM .UNINDENT .INDENT 0.0 .TP .B salt.runners.virt.query(host=None, quiet=False) Query the virtual machines. When called without options all hosts are detected and a full query is returned. A single host can be passed in to specify an individual host to query. .UNINDENT .INDENT 0.0 .TP .B salt.runners.virt.reset(name) Force power down and restart an existing VM .UNINDENT .INDENT 0.0 .TP .B salt.runners.virt.resume(name) Resume a paused VM .UNINDENT .INDENT 0.0 .TP .B salt.runners.virt.start(name) Start a named virtual machine .UNINDENT .INDENT 0.0 .TP .B salt.runners.virt.vm_info(name, quiet=False) Return the information on the named VM .UNINDENT .SS salt.runners.vistara .sp Vistara Runner .sp Runner to interact with the Vistara (\fI\%http://www.vistarait.com/\fP) REST API .INDENT 0.0 .TP .B codeauthor Brad Thurber <\fI\%brad.thurber@gmail.com\fP> .UNINDENT .sp To use this runner, the Vistara client_id and Vistara oauth2 client_key and client_secret must be set in the master config. .sp For example \fB/etc/salt/master.d/_vistara.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vistara: client_id: client_012345 client_key: N0tReallyaR3alKeyButShouldB12345 client_secret: ThisI5AreallyLongsecretKeyIwonderwhyTheyMakethemSoBigTheseDays00 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.vistara.delete_device(name, safety_on=True) Deletes a device from Vistara based on DNS name or partial name. By default, delete_device will only perform the delete if a single host is returned. Set safety_on=False to delete all matches (up to default API search page size) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run vistara.delete_device \(aqhostname\-101.mycompany.com\(aq salt\-run vistara.delete_device \(aqhostname\-101\(aq salt\-run vistara.delete_device \(aqhostname\-1\(aq safety_on=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.runners.winrepo .sp Runner to manage Windows software repo .INDENT 0.0 .TP .B salt.runners.winrepo.genrepo(opts=None, fire_event=True) Generate winrepo_cachefile based on sls files in the winrepo_dir .INDENT 7.0 .TP .B opts Specify an alternate opts dict. Should not be used unless this function is imported into an execution module. .TP .B fire_event True Fire an event on failure. Only supported on the master. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run winrepo.genrepo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.runners.winrepo.update_git_repos(opts=None, clean=False, masterless=False) Checkout git repos containing Windows Software Package Definitions .INDENT 7.0 .TP .B opts Specify an alternate opts dict. Should not be used unless this function is imported into an execution module. .TP .B clean False Clean repo cachedirs which are not configured under \fI\%winrepo_remotes\fP\&. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This argument should not be set to \fBTrue\fP if a mix of git and non\-git repo definitions are being used, as it will result in the non\-git repo definitions being removed. .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-run winrepo.update_git_repos salt\-run winrepo.update_git_repos clean=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS sdb modules .TS center; |l|l|. _ T{ \fI\%cache\fP T} T{ cache Module T} _ T{ \fI\%confidant\fP T} T{ An SDB module for getting credentials from confidant. T} _ T{ \fI\%consul\fP T} T{ Consul sdb Module T} _ T{ \fI\%couchdb\fP T} T{ CouchDB sdb Module T} _ T{ \fI\%env\fP T} T{ Environment sdb Module T} _ T{ \fI\%etcd_db\fP T} T{ etcd Database Module T} _ T{ \fI\%keyring_db\fP T} T{ Keyring Database Module T} _ T{ \fI\%memcached\fP T} T{ Memcached sdb Module T} _ T{ \fI\%redis_sdb\fP T} T{ Redis SDB module T} _ T{ \fI\%rest\fP T} T{ Generic REST API SDB Module T} _ T{ \fI\%sqlite3\fP T} T{ SQLite sdb Module T} _ T{ \fI\%tism\fP T} T{ tISM \- the Immutable Secrets Manager SDB Module T} _ T{ \fI\%vault\fP T} T{ Vault SDB Module T} _ T{ \fI\%yaml\fP T} T{ Pull sdb values from a YAML file T} _ .TE .SS salt.sdb.cache .sp cache Module .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity New .TP .B platform all .UNINDENT .sp New in version 2017.7.0. .sp This module provides access to Salt\(aqs cache subsystem. .sp Like all sdb modules, the cache module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. In the example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mastercloudcache: driver: cache bank: cloud/active/ec2/my\-ec2\-conf/saltmaster cachedir: /var/cache/salt .ft P .fi .UNINDENT .UNINDENT .sp The \fBdriver\fP refers to the cache module, \fBbank\fP refers to the cache bank that contains the data and \fBcachedir\fP (optional), if used, points to an alternate directory for cache data storage. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_ip: sdb://mastercloudcache/public_ips .ft P .fi .UNINDENT .UNINDENT .sp It is also possible to override both the \fBbank\fP and \fBcachedir\fP options inside the SDB URI: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_ip: sdb://mastercloudcache/public_ips?cachedir=/var/cache/salt .ft P .fi .UNINDENT .UNINDENT .sp For this reason, both the \fBbank\fP and the \fBcachedir\fP options can be omitted from the SDB profile. However, if the \fBbank\fP option is omitted, it must be specified in the URI: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_ip: sdb://mastercloudcache/public_ips?bank=cloud/active/ec2/my\-ec2\-conf/saltmaster .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.sdb.cache.delete(key, service=None, profile=None) Get a value from the cache service .UNINDENT .INDENT 0.0 .TP .B salt.sdb.cache.get(key, service=None, profile=None) Get a value from the cache service .UNINDENT .INDENT 0.0 .TP .B salt.sdb.cache.set_(key, value, service=None, profile=None) Set a key/value pair in the cache service .UNINDENT .SS salt.sdb.confidant .sp An SDB module for getting credentials from confidant. .SS Configuring the Confidant module .sp The module can be configured via sdb in the minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C confidant: driver: confidant # The URL of the confidant web service url: \(aqhttps://confidant\-production.example.com\(aq # The context to use for KMS authentication auth_context: from: example\-production\-iad to: confidant\-production\-iad user_type: service # The KMS master key to use for authentication auth_key: \(dqalias/authnz\(dq # Cache file for KMS auth token token_cache_file: /run/confidant/confidant_token # The duration of the validity of a token, in minutes token_duration: 60 # key, keyid and region can be defined in the profile, but it\(aqs generally # best to use IAM roles or environment variables for AWS auth. keyid: 98nh9h9h908h09kjjk key: jhf908gyeghehe0he0g8h9u0j0n0n09hj09h0 region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends confidant\-common, confidant\-client .UNINDENT .SS Module Documentation .INDENT 0.0 .TP .B salt.sdb.confidant.get(key, profile=None) Read pillar data from Confidant via its API. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion sdb.get \(aqsdb://confidant/credentials\(aq .ft P .fi .UNINDENT .UNINDENT .sp Valid keys are: credentials, credentials_metadata, result. credentials returns a dict of joined credential_pairs, credentials_metadata returns a dict of metadata relevant to the credentials mapped to the confidant service, and result returns a bool that can be used to determine if the sdb call succeeded or failed to fetch credentials from confidant (or from local cache). If result is false, the data in credentials or credentials_metadata can\(aqt be trusted. .UNINDENT .SS salt.sdb.consul .sp Consul sdb Module .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity New .TP .B platform all .UNINDENT .sp This module allows access to Consul using an \fBsdb://\fP URI .sp Like all sdb modules, the Consul module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myconsul: driver: consul host: 127.0.0.1 port: 8500 token: b6376760\-a8bb\-edd5\-fcda\-33bc13bfc556 scheme: http consistency: default dc: dev verify: True .ft P .fi .UNINDENT .UNINDENT .sp The \fBdriver\fP refers to the Consul module, all other options are optional. For option details see: \fI\%https://python\-consul.readthedocs.io/en/latest/#consul\fP .INDENT 0.0 .TP .B salt.sdb.consul.get(key, profile=None) .UNINDENT .INDENT 0.0 .TP .B salt.sdb.consul.get_conn(profile) Return a client object for accessing consul .UNINDENT .INDENT 0.0 .TP .B salt.sdb.consul.set_(key, value, profile=None) .UNINDENT .SS salt.sdb.couchdb .sp CouchDB sdb Module .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity New .TP .B depends python2\-couchdb .TP .B platform all .UNINDENT .sp This allow interaction between Salt and a CouchDB [couchdb.apache.org] database. It uses salt\(aqs \fIsdb\fP system to allow for inserts and retrevals using the \fIsdb://\fP prefix in salt configuration files. .sp To use the couchbase sdb module, it must first be configured in the salt master or minion config. The following arguments are required: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C couchdb_sdb: driver: couchdb host: localhost port: 5984 database: salt_sdb .ft P .fi .UNINDENT .UNINDENT .sp One could then query the CouchDB instance via an \fIsdb://\fP URI such as the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C password: sdb://couchdb_sdb/mykey .ft P .fi .UNINDENT .UNINDENT .sp To use this interface, you must track IDs on your own or have another source to do the map\-reduce logic necessary to calculate the ID you wish to fetch. .sp Additional contributions to build true map\-reduce functionality into this module would be welcome. .INDENT 0.0 .TP .B salt.sdb.couchdb.get(key, profile=None) Get a value from couchdb by id .UNINDENT .INDENT 0.0 .TP .B salt.sdb.couchdb.set_(key, value, profile=None) Set a key/value pair in couchdb .UNINDENT .SS salt.sdb.env .sp Environment sdb Module .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity New .TP .B depends None .TP .B platform all .UNINDENT .sp This module allows access to environment variables using an \fBsdb://\fP URI. .sp Example configuration for this module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C osenv: driver: env .ft P .fi .UNINDENT .UNINDENT .SS WARNING: .sp OS environment variables will be available to read via SDB. Please make sure you don\(aqt have any sensitive data in your environment variables!! .sp Example usage of sdb env module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C set some env var: cmd.run: \- name: echo {{ salt[\(aqsdb.set\(aq](\(aqsdb://osenv/foo\(aq, \(aqbar\(aq) }} \- order: 1 {% if salt[\(aqsdb.get\(aq](\(aqsdb://osenv/foo\(aq) == \(aqbar\(aq %} always\-changes\-and\-succeeds: test.succeed_with_changes: \- name: foo {% else %} always\-changes\-and\-fails: test.fail_with_changes: \- name: foo {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp The above example will return success. .sp The \fBenv\fP sdb module can also be used with salt cloud. Assuming you have exported the environment variable named \fBcompute\fP (and have \fBosenv\fP defined). The example below will look for the salt cloud config key \fBcompute_name\fP in the environment: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-openstack\-config: compute_name: sdb://osenv/compute ..snip .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.sdb.env.get(key, profile=None) Get a value .UNINDENT .INDENT 0.0 .TP .B salt.sdb.env.set_(key, value, profile=None) Set a key/value pair .UNINDENT .SS salt.sdb.etcd_db .sp etcd Database Module .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity New .TP .B depends python\-etcd or etcd3\-py .TP .B platform all .UNINDENT .sp New in version 2015.5.0. .sp This module allows access to the etcd database using an \fBsdb://\fP URI. This package is located at \fBhttps://pypi.python.org/pypi/python\-etcd\fP\&. .sp Like all sdb modules, the etcd module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. In the example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myetcd: driver: etcd etcd.host: 127.0.0.1 etcd.port: 2379 .ft P .fi .UNINDENT .UNINDENT .sp The \fBdriver\fP refers to the etcd module, \fBetcd.host\fP refers to the host that is hosting the etcd database and \fBetcd.port\fP refers to the port on that host. .sp In order to choose whether to use etcd API v2 or v3, you can put the following configuration option in the same place as your etcd configuration. This option defaults to true, meaning you will use v2 unless you specify otherwise. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.require_v2: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C password: sdb://myetcd/mypassword .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.sdb.etcd_db.delete(key, service=None, profile=None) Get a value from the etcd service .UNINDENT .INDENT 0.0 .TP .B salt.sdb.etcd_db.get(key, service=None, profile=None) Get a value from the etcd service .UNINDENT .INDENT 0.0 .TP .B salt.sdb.etcd_db.set_(key, value, service=None, profile=None) Set a key/value pair in the etcd service .UNINDENT .SS salt.sdb.keyring_db .sp Keyring Database Module .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity New .TP .B depends keyring .TP .B platform all .UNINDENT .sp This module allows access to the keyring package using an \fBsdb://\fP URI. This package is located at \fBhttps://pypi.python.org/pypi/keyring\fP\&. .sp Care must be taken when using keyring. Not all keyend backends are supported on all operating systems. Also, many backends require an agent to be running in order to work. For instance, the \(dqSecret Service\(dq backend requires a compatible agent such as \fBgnome\-keyring\-daemon\fP or \fBkwallet\fP to be running. The keyczar backend does not seem to enjoy the benefits of an agent, and so using it will require either that the password is typed in manually (which is unreasonable for the salt\-minion and salt\-master daemons, especially in production) or an agent is written for it. .sp Like all sdb modules, the keyring module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. In the example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mykeyring: driver: keyring service: system .ft P .fi .UNINDENT .UNINDENT .sp The \fBdriver\fP refers to the keyring module, \fBservice\fP refers to the service that will be used inside of keyring (which may be likened unto a database table) and \fBmykeyring\fP refers to the name that will appear in the URI: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C password: sdb://mykeyring/mypassword .ft P .fi .UNINDENT .UNINDENT .sp The underlying backend configuration must be configured via keyring itself. For examples and documentation, see keyring: .sp \fI\%https://pypi.python.org/pypi/keyring\fP .sp New in version 2014.1.4. .INDENT 0.0 .TP .B salt.sdb.keyring_db.get(key, service=None, profile=None) Get a value from a keyring service .UNINDENT .INDENT 0.0 .TP .B salt.sdb.keyring_db.set_(key, value, service=None, profile=None) Set a key/value pair in a keyring service .UNINDENT .SS salt.sdb.memcached .sp Memcached sdb Module .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity New .TP .B depends python\-memcached .TP .B platform all .UNINDENT .sp This module allows access to memcached using an \fBsdb://\fP URI. This package is located at \fBhttps://pypi.python.org/pypi/python\-memcached\fP\&. .sp Like all sdb modules, the memcached module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. In the example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mymemcache: driver: memcached memcached.host: localhost memcached.port: 11211 .ft P .fi .UNINDENT .UNINDENT .sp The \fBdriver\fP refers to the memcached module, \fBhost\fP and \fBport\fP the memcached server to connect to (defaults to \fBlocalhost\fP and \fB11211\fP, and \fBmymemcached\fP refers to the name that will appear in the URI: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C password: sdb://mymemcached/mykey .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.sdb.memcached.get(key, profile=None) Get a value from memcached .UNINDENT .INDENT 0.0 .TP .B salt.sdb.memcached.set_(key, value, profile=None) Set a key/value pair in memcached .UNINDENT .SS salt.sdb.redis_sdb .SS Redis SDB module .INDENT 0.0 .INDENT 3.5 New in version 2019.2.0. .UNINDENT .UNINDENT .sp This module allows access to Redis using an \fBsdb://\fP URI. .sp Like all SDB modules, the Redis module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sdb_redis: driver: redis host: 127.0.0.1 port: 6379 password: pass db: 1 .ft P .fi .UNINDENT .UNINDENT .sp The \fBdriver\fP refers to the Redis module, all other options are optional. For option details see: \fI\%https://redis\-py.readthedocs.io/en/latest/\fP\&. .INDENT 0.0 .TP .B salt.sdb.redis_sdb.delete(key, profile=None) Delete a key from the Redis SDB. .UNINDENT .INDENT 0.0 .TP .B salt.sdb.redis_sdb.get(key, profile=None) Get a value from the Redis SDB. .UNINDENT .INDENT 0.0 .TP .B salt.sdb.redis_sdb.set_(key, value, profile=None) Set a value into the Redis SDB. .UNINDENT .SS salt.sdb.rest .sp Generic REST API SDB Module .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity New .TP .B platform all .UNINDENT .sp New in version 2015.8.0. .sp This module allows access to a REST interface using an \fBsdb://\fP URI. .sp Like all REST modules, the REST module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. In the example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-rest\-api: driver: rest urls: url: https://api.github.com/ keys: url: https://api.github.com/users/{{user}}/keys backend: requests .ft P .fi .UNINDENT .UNINDENT .sp The \fBdriver\fP refers to the REST module, and must be set to \fBrest\fP in order to use this driver. Each of the other items inside this block refers to a separate set of HTTP items, including a URL and any options associated with it. The options used here should match the options available in \fBsalt.utils.http.query()\fP\&. .sp In order to call the \fBurls\fP item in the example, the following reference can be made inside a configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C github_urls: sdb://my\-rest\-api/urls .ft P .fi .UNINDENT .UNINDENT .sp Key/Value pairs may also be used with this driver, and merged into the URL using the configured renderer (\fBjinja\fP, by default). For instance, in order to use the \fBkeys\fP item in the example, the following reference can be made: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C github_urls: sdb://my\-rest\-api/keys?user=myuser .ft P .fi .UNINDENT .UNINDENT .sp This will cause the following URL to actually be called: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C https://api.github.com/users/myuser/keys .ft P .fi .UNINDENT .UNINDENT .sp Key/Value pairs will NOT be passed through as GET data. If GET data needs to be sent to the URL, then it should be configured in the SDB configuration block. For instance: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C another\-rest\-api: driver: rest user_data: url: https://api.example.com/users/ params: user: myuser .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.sdb.rest.get(key, service=None, profile=None) Get a value from the REST interface .UNINDENT .INDENT 0.0 .TP .B salt.sdb.rest.query(key, value=None, service=None, profile=None) Get a value from the REST interface .UNINDENT .INDENT 0.0 .TP .B salt.sdb.rest.set_(key, value, service=None, profile=None) Set a key/value pair in the REST interface .UNINDENT .SS salt.sdb.sqlite3 .sp SQLite sdb Module .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity New .TP .B platform all .UNINDENT .sp This module allows access to sqlite3 using an \fBsdb://\fP URI .sp Like all sdb modules, the sqlite3 module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysqlite: driver: sqlite3 database: /tmp/sdb.sqlite table: sdb create_table: True .ft P .fi .UNINDENT .UNINDENT .sp The \fBdriver\fP refers to the sqlite3 module, \fBdatabase\fP refers to the sqlite3 database file. \fBtable\fP is the table within the db that will hold keys and values (defaults to \fBsdb\fP). The database and table will be created if they do not exist. .SS Advanced Usage: .sp Instead of a table name, it is possible to provide custom SQL statements to create the table(s) and get and set values. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myadvanced driver: sqlite3 database: /tmp/sdb\-advanced.sqlite create_statements: \- \(dqCREATE TABLE advanced (a text, b text, c blob, d blob)\(dq \- \(dqCREATE INDEX myidx ON advanced (a)\(dq get_query: \(dqSELECT d FROM advanced WHERE a=:key\(dq set_query: \(dqINSERT OR REPLACE INTO advanced (a, d) VALUES (:key, :value)\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.sdb.sqlite3.get(key, profile=None) Get a value from sqlite3 .UNINDENT .INDENT 0.0 .TP .B salt.sdb.sqlite3.set_(key, value, profile=None) Set a key/value pair in sqlite3 .UNINDENT .SS salt.sdb.tism .sp tISM \- the Immutable Secrets Manager SDB Module .INDENT 0.0 .TP .B maintainer tISM .TP .B maturity New .TP .B platform all .UNINDENT .sp New in version 2017.7.0. .sp This module will decrypt PGP encrypted secrets against a tISM server. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sdb://<profile>/<encrypted secret> sdb://tism/hQEMAzJ+GfdAB3KqAQf9E3cyvrPEWR1sf1tMvH0nrJ0bZa9kDFLPxvtwAOqlRiNp0F7IpiiVRF+h+sW5Mb4ffB1TElMzQ+/G5ptd6CjmgBfBsuGeajWmvLEi4lC6/9v1rYGjjLeOCCcN4Dl5AHlxUUaSrxB8akTDvSAnPvGhtRTZqDlltl5UEHsyYXM8RaeCrBw5Or1yvC9Ctx2saVp3xmALQvyhzkUv5pTb1mH0I9Z7E0ian07ZUOD+pVacDAf1oQcPpqkeNVTQQ15EP0fDuvnW+a0vxeLhkbFLfnwqhqEsvFxVFLHVLcs2ffE5cceeOMtVo7DS9fCtkdZr5hR7a+86n4hdKfwDMFXiBwSIPMkmY980N/H30L/r50+CBkuI/u4M2pXDcMYsvvt4ajCbJn91qaQ7BDI= .ft P .fi .UNINDENT .UNINDENT .sp A profile must be setup in the minion configuration or pillar. If you want to use sdb in a runner or pillar you must also place a profile in the master configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tism: driver: tism url: https://my.tismd:8080/decrypt token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6MSwiZXhwIjoxNTg1MTExNDYwLCJqdGkiOiI3NnA5cWNiMWdtdmw4Iiwia2V5cyI6WyJBTEwiXX0.RtAhG6Uorf5xnSf4Ya_GwJnoHkCsql4r1_hiOeDSLzo .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.sdb.tism.get(key, service=None, profile=None) Get a decrypted secret from the tISMd API .UNINDENT .SS salt.sdb.vault .sp Vault SDB Module .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity New .TP .B platform all .UNINDENT .sp New in version 2016.11.0. .sp This module allows access to Hashicorp Vault using an \fBsdb://\fP URI. .sp Base configuration instructions are documented in the \fI\%execution module docs\fP\&. Below are noted extra configuration required for the sdb module, but the base configuration must also be completed. .sp Like all sdb modules, the vault module requires a configuration profile to be configured in either the minion configuration file or a pillar. This profile requires only setting the \fBdriver\fP parameter to \fBvault\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myvault: driver: vault .ft P .fi .UNINDENT .UNINDENT .sp Once configured you can access data using a URL such as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C password: sdb://myvault/secret/passwords/mypassword .ft P .fi .UNINDENT .UNINDENT .sp In this URL, \fBmyvault\fP refers to the configuration profile, \fBsecret/passwords\fP is the path where the data resides, and \fBmypassword\fP is the key of the data to return. .sp The above URI is analogous to running the following vault command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ vault read \-field=mypassword secret/passwords .ft P .fi .UNINDENT .UNINDENT .SS Further configuration .sp The following options can be set in the profile: .INDENT 0.0 .TP .B patch When writing data, partially update the secret instead of overwriting it completely. This is usually the expected behavior, since without this option, each secret path can only contain a single mapping key safely. Defaults to \fBFalse\fP for backwards\-compatibility reasons. .sp New in version 3007.0. .UNINDENT .INDENT 0.0 .TP .B salt.sdb.vault.get(key, profile=None) Get a value from the vault service .UNINDENT .INDENT 0.0 .TP .B salt.sdb.vault.set_(key, value, profile=None) Set a key/value pair in the vault service .UNINDENT .SS salt.sdb.yaml .sp Pull sdb values from a YAML file .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity New .TP .B platform all .UNINDENT .sp New in version 2017.7.0. .sp Configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-yaml\-file: driver: yaml files: \- /path/to/foo.yaml \- /path/to/bar.yaml .ft P .fi .UNINDENT .UNINDENT .sp The files are merged together and the result is searched using the same mechanism Salt uses for searching Grains and Pillar data structures. .sp Optional configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-yaml\-file: driver: yaml files: \- /path/to/foo.yaml \- /path/to/bar.yaml merge: strategy: smart merge_list: false gpg: true .ft P .fi .UNINDENT .UNINDENT .sp New in version 2018.3.0. .sp Setting the \fBgpg\fP option to \fBtrue\fP (default is \fBfalse\fP) will decrypt embedded GPG\-encrypted data using the \fI\%GPG renderer\fP\&. .INDENT 0.0 .TP .B salt.sdb.yaml.get(key, profile=None) Get a value from the dictionary .UNINDENT .INDENT 0.0 .TP .B salt.sdb.yaml.set_(*args, **kwargs) Setting a value is not supported; edit the YAML files directly .UNINDENT .SS serializer modules .SS salt.serializers .sp This module implements all the serializers needed by salt. Each serializer offers the same functions and attributes: .INDENT 0.0 .TP .B deserialize function for deserializing string or stream .TP .B serialize function for serializing a Python object .TP .B available flag that tells if the serializer is available (all dependencies are met etc.) .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.DeserializationError(message, line_num=None, buf=\(aq\(aq, marker=\(aq <======================\(aq, trace=None) Raised when stream of string failed to be deserialized .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.SerializationError(message=\(aq\(aq) Raised when stream of string failed to be serialized .UNINDENT .TS center; |l|l|. _ T{ \fI\%configparser\fP T} T{ salt.serializers.configparser T} _ T{ \fI\%json\fP T} T{ salt.serializers.json T} _ T{ \fI\%keyvalue\fP T} T{ salt.serializers.keyvalue New in version 3006.0. T} _ T{ \fI\%msgpack\fP T} T{ salt.serializers.msgpack T} _ T{ \fI\%plist\fP T} T{ salt.serializers.plist New in version 3001. T} _ T{ \fI\%python\fP T} T{ salt.serializers.python T} _ T{ \fI\%tomlmod\fP T} T{ salt.serializers.tomlmod T} _ T{ \fByaml\fP T} T{ salt.serializers.yaml T} _ T{ \fByamlex\fP T} T{ salt.serializers.yamlex T} _ .TE .SS salt.serializers.configparser .SS salt.serializers.configparser .sp New in version 2016.3.0. .sp Implements a configparser serializer. .INDENT 0.0 .TP .B exception salt.serializers.configparser.DeserializationError(message, line_num=None, buf=\(aq\(aq, marker=\(aq <======================\(aq, trace=None) Raised when stream of string failed to be deserialized .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.configparser.SerializationError(message=\(aq\(aq) Raised when stream of string failed to be serialized .UNINDENT .INDENT 0.0 .TP .B salt.serializers.configparser.deserialize(stream_or_string, **options) Deserialize any string or stream like object into a Python data structure. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstream_or_string\fP \-\- stream or string to deserialize. .IP \(bu 2 \fBoptions\fP \-\- options given to lower configparser module. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.serializers.configparser.serialize(obj, **options) Serialize Python data to a configparser formatted string or file. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- the data structure to serialize .IP \(bu 2 \fBoptions\fP \-\- options given to lower configparser module. .UNINDENT .UNINDENT .UNINDENT .SS salt.serializers.json .SS salt.serializers.json .sp Implements JSON serializer. .sp It\(aqs just a wrapper around json (or simplejson if available). .INDENT 0.0 .TP .B exception salt.serializers.json.DeserializationError(message, line_num=None, buf=\(aq\(aq, marker=\(aq <======================\(aq, trace=None) Raised when stream of string failed to be deserialized .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.json.SerializationError(message=\(aq\(aq) Raised when stream of string failed to be serialized .UNINDENT .INDENT 0.0 .TP .B salt.serializers.json.deserialize(stream_or_string, **options) Deserialize any string or stream like object into a Python data structure. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstream_or_string\fP \-\- stream or string to deserialize. .IP \(bu 2 \fBoptions\fP \-\- options given to lower json/simplejson module. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.serializers.json.serialize(obj, **options) Serialize Python data to JSON. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- the data structure to serialize .IP \(bu 2 \fBoptions\fP \-\- options given to lower json/simplejson module. .UNINDENT .UNINDENT .UNINDENT .SS salt.serializers.keyvalue .SS salt.serializers.keyvalue .sp New in version 3006.0. .sp Implements keyvalue serializer which can be used for serializing or deserializing any file which defines keys and values separated by a common set of characters, such environment files, which are in \(dqKEY=value\(dq format. .sp Options: .INDENT 0.0 .TP .B param line_ending String representation of LF or CRLF to be used for serialization to a file. Defaults to \fB\er\en\fP on Windows and \fB\en\fP on other operating systems. .TP .B param quoting Boolean flag to determine if values should be quoted (\fBTrue\fP) during serialization or dequoted (\fBFalse\fP) during deserialization. Defaults to \fBNone\fP (no action). .TP .B param separator String representing the character(s) used when concatenating or reading key/value pairs. Defaults to \fB=\fP\&. .UNINDENT .sp A dataset such as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo: bar wang: chung .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- [foo, bar] \- [wang, chung] .ft P .fi .UNINDENT .UNINDENT .sp can be represented as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo=bar wang=chung .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.keyvalue.DeserializationError(message, line_num=None, buf=\(aq\(aq, marker=\(aq <======================\(aq, trace=None) Raised when stream of string failed to be deserialized .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.keyvalue.SerializationError(message=\(aq\(aq) Raised when stream of string failed to be serialized .UNINDENT .INDENT 0.0 .TP .B salt.serializers.keyvalue.dequote(value) Remove extra quotes around a string. .UNINDENT .INDENT 0.0 .TP .B salt.serializers.keyvalue.deserialize(stream_or_string, **options) Deserialize any string or stream like object into a Python data structure. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstream_or_string\fP \-\- stream or string to deserialize. .IP \(bu 2 \fBoptions\fP \-\- options given to the function .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.serializers.keyvalue.quote(txt) Wraps a text around quotes. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set my_text = \(aqmy_text\(aq %} {{ my_text | quote }} .ft P .fi .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \(aqmy_text\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.serializers.keyvalue.serialize(obj, **options) Serialize Python data to environment file. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- the data structure to serialize .IP \(bu 2 \fBoptions\fP \-\- options given to the function .UNINDENT .UNINDENT .UNINDENT .SS salt.serializers.msgpack .SS salt.serializers.msgpack .sp Implements MsgPack serializer. .INDENT 0.0 .TP .B exception salt.serializers.msgpack.DeserializationError(message, line_num=None, buf=\(aq\(aq, marker=\(aq <======================\(aq, trace=None) Raised when stream of string failed to be deserialized .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.msgpack.SerializationError(message=\(aq\(aq) Raised when stream of string failed to be serialized .UNINDENT .INDENT 0.0 .TP .B salt.serializers.msgpack.deserialize(stream_or_string, **options) Deserialize any string of stream like object into a Python data structure. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstream_or_string\fP \-\- stream or string to deserialize. .IP \(bu 2 \fBoptions\fP \-\- options given to lower msgpack module. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.serializers.msgpack.serialize(obj, **options) Serialize Python data to MsgPack. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- the data structure to serialize .IP \(bu 2 \fBoptions\fP \-\- options given to lower msgpack module. .UNINDENT .UNINDENT .UNINDENT .SS salt.serializers.plist .SS salt.serializers.plist .sp New in version 3001. .sp Implements plist serializer. .sp Wrapper around plistlib. .INDENT 0.0 .TP .B exception salt.serializers.plist.DeserializationError(message, line_num=None, buf=\(aq\(aq, marker=\(aq <======================\(aq, trace=None) Raised when stream of string failed to be deserialized .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.plist.SerializationError(message=\(aq\(aq) Raised when stream of string failed to be serialized .UNINDENT .INDENT 0.0 .TP .B salt.serializers.plist.deserialize(stream_or_string, **options) Deserialize any string or stream like object into a Python data structure. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstream_or_string\fP \-\- stream or string to deserialize. .IP \(bu 2 \fBoptions\fP \-\- options given to lower plist module. .UNINDENT .TP .B Returns Deserialized data structure. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.serializers.plist.serialize(value, **options) Serialize Python data to plist. To create a binary plist pass \fBfmt: FMT_BINARY\fP as an option. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- the data structure to serialize .IP \(bu 2 \fBoptions\fP \-\- options given to lower plist module. .UNINDENT .TP .B Returns bytes of serialized plist. .UNINDENT .UNINDENT .SS salt.serializers.python .SS salt.serializers.python .sp New in version 2016.3.0. .sp Implements a Python serializer (via pprint.format) .INDENT 0.0 .TP .B salt.serializers.python.serialize(obj, **options) Serialize Python data to a Python string representation (via pprint.format) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- the data structure to serialize .IP \(bu 2 \fBoptions\fP \-\- options given to pprint.format .UNINDENT .UNINDENT .UNINDENT .SS salt.serializers.toml .SS salt.serializers.tomlmod .sp Implements TOML serializer. .sp It\(aqs just a wrapper around the python toml module. .INDENT 0.0 .TP .B exception salt.serializers.tomlmod.DeserializationError(message, line_num=None, buf=\(aq\(aq, marker=\(aq <======================\(aq, trace=None) Raised when stream of string failed to be deserialized .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.tomlmod.SerializationError(message=\(aq\(aq) Raised when stream of string failed to be serialized .UNINDENT .INDENT 0.0 .TP .B salt.serializers.tomlmod.deserialize(stream_or_string, **options) Deserialize from TOML into Python data structure. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstream_or_string\fP \-\- toml stream or string to deserialize. .IP \(bu 2 \fBoptions\fP \-\- options given to the python toml module. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.serializers.tomlmod.serialize(obj, **options) Serialize Python data to TOML. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- the data structure to serialize. .IP \(bu 2 \fBoptions\fP \-\- options given to the python toml module. .UNINDENT .UNINDENT .UNINDENT .SS salt.serializers.yaml .SS salt.serializers.yaml .sp Implements YAML serializer. .sp Underneath, it is based on pyyaml and use the safe dumper and loader. It also use C bindings if they are available. .INDENT 0.0 .TP .B salt.serializers.yaml.BaseDumper alias of \fBCSafeDumper\fP .UNINDENT .INDENT 0.0 .TP .B salt.serializers.yaml.BaseLoader alias of \fBCSafeLoader\fP .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.yaml.ConstructorError(context=None, context_mark=None, problem=None, problem_mark=None, note=None) .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.yaml.DeserializationError(message, line_num=None, buf=\(aq\(aq, marker=\(aq <======================\(aq, trace=None) Raised when stream of string failed to be deserialized .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yaml.Dumper(stream, default_style=None, default_flow_style=False, canonical=None, indent=None, width=None, allow_unicode=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None, sort_keys=True) Overwrites Dumper as not for pollute legacy Dumper .INDENT 7.0 .TP .B yaml_multi_representers = {<class \(aqsalt.serializers.yaml.EncryptedString\(aq>: <function EncryptedString.yaml_dumper>, <class \(aqNoneType\(aq>: <function SafeRepresenter.represent_none>, <class \(aqstr\(aq>: <function SafeRepresenter.represent_str>, <class \(aqbool\(aq>: <function SafeRepresenter.represent_bool>, <class \(aqint\(aq>: <function SafeRepresenter.represent_int>, <class \(aqfloat\(aq>: <function SafeRepresenter.represent_float>, <class \(aqlist\(aq>: <function SafeRepresenter.represent_list>, <class \(aqtuple\(aq>: <function SafeRepresenter.represent_list>, <class \(aqdict\(aq>: <function SafeRepresenter.represent_dict>, <class \(aqset\(aq>: <function SafeRepresenter.represent_set>, <class \(aqdatetime.date\(aq>: <function SafeRepresenter.represent_date>, <class \(aqdatetime.datetime\(aq>: <function SafeRepresenter.represent_datetime>, None: <function SafeRepresenter.represent_undefined>, <class \(aqcollections.OrderedDict\(aq>: <function SafeRepresenter.represent_dict>} .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yaml.EncryptedString .INDENT 7.0 .TP .B static yaml_constructor(loader, tag, node) .UNINDENT .INDENT 7.0 .TP .B static yaml_dumper(dumper, data) .UNINDENT .INDENT 7.0 .TP .B yaml_tag = \(aq!encrypted\(aq .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yaml.Loader(stream) Overwrites Loader as not for pollute legacy Loader .INDENT 7.0 .TP .B yaml_multi_constructors = {\(aq!encrypted\(aq: <function EncryptedString.yaml_constructor>, \(aqtag:yaml.org,2002:binary\(aq: <function SafeConstructor.construct_yaml_binary>, \(aqtag:yaml.org,2002:bool\(aq: <function SafeConstructor.construct_yaml_bool>, \(aqtag:yaml.org,2002:float\(aq: <function SafeConstructor.construct_yaml_float>, \(aqtag:yaml.org,2002:int\(aq: <function SafeConstructor.construct_yaml_int>, \(aqtag:yaml.org,2002:map\(aq: <function SafeConstructor.construct_yaml_map>, \(aqtag:yaml.org,2002:null\(aq: <function SafeConstructor.construct_yaml_null>, \(aqtag:yaml.org,2002:omap\(aq: <function SafeConstructor.construct_yaml_omap>, \(aqtag:yaml.org,2002:pairs\(aq: <function SafeConstructor.construct_yaml_pairs>, \(aqtag:yaml.org,2002:seq\(aq: <function SafeConstructor.construct_yaml_seq>, \(aqtag:yaml.org,2002:set\(aq: <function SafeConstructor.construct_yaml_set>, \(aqtag:yaml.org,2002:str\(aq: <function SafeConstructor.construct_yaml_str>, \(aqtag:yaml.org,2002:timestamp\(aq: <function SafeConstructor.construct_yaml_timestamp>} .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yaml.OrderedDict Dictionary that remembers insertion order .INDENT 7.0 .TP .B clear() -> None. Remove all items from od. .UNINDENT .INDENT 7.0 .TP .B copy() -> a shallow copy of od .UNINDENT .INDENT 7.0 .TP .B fromkeys(value=None) Create a new ordered dictionary with keys from iterable and values set to value. .UNINDENT .INDENT 7.0 .TP .B items() -> a set\-like object providing a view on D\(aqs items .UNINDENT .INDENT 7.0 .TP .B keys() -> a set\-like object providing a view on D\(aqs keys .UNINDENT .INDENT 7.0 .TP .B move_to_end(key, last=True) Move an existing element to the end (or beginning if last is false). .sp Raise KeyError if the element does not exist. .UNINDENT .INDENT 7.0 .TP .B pop(key[, default]) -> v, remove specified key and return the corresponding value. If the key is not found, return the default if given; otherwise, raise a KeyError. .UNINDENT .INDENT 7.0 .TP .B popitem(last=True) Remove and return a (key, value) pair from the dictionary. .sp Pairs are returned in LIFO order if last is true or FIFO order if false. .UNINDENT .INDENT 7.0 .TP .B setdefault(key, default=None) Insert key with a value of default if key is not in the dictionary. .sp Return the value for key if key is in the dictionary, else default. .UNINDENT .INDENT 7.0 .TP .B update([E], **F) -> None. Update D from dict/iterable E and F. If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k] .UNINDENT .INDENT 7.0 .TP .B values() -> an object providing a view on D\(aqs values .UNINDENT .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.yaml.ScannerError(context=None, context_mark=None, problem=None, problem_mark=None, note=None) .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.yaml.SerializationError(message=\(aq\(aq) Raised when stream of string failed to be serialized .UNINDENT .INDENT 0.0 .TP .B salt.serializers.yaml.deserialize(stream_or_string, **options) Deserialize any string of stream like object into a Python data structure. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstream_or_string\fP \-\- stream or string to deserialize. .IP \(bu 2 \fBoptions\fP \-\- options given to lower yaml module. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.serializers.yaml.serialize(obj, **options) Serialize Python data to YAML. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- the data structure to serialize .IP \(bu 2 \fBoptions\fP \-\- options given to lower yaml module. .UNINDENT .UNINDENT .UNINDENT .SS salt.serializers.yamlex .SS salt.serializers.yamlex .sp YAMLEX is a format that allows for things like sls files to be more intuitive. .sp It\(aqs an extension of YAML that implements all the salt magic: \- it implies omap for any dict like. \- it implies that string like data are str, not unicode \- ... .sp For example, the file \fIstates.sls\fP has this contents: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo: bar: 42 baz: [1, 2, 3] .ft P .fi .UNINDENT .UNINDENT .sp The file can be parsed into Python like this .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from salt.serializers import yamlex with open(\(aqstate.sls\(aq, \(aqr\(aq) as stream: obj = yamlex.deserialize(stream) .ft P .fi .UNINDENT .UNINDENT .sp Check that \fBobj\fP is an OrderedDict .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from salt.utils.odict import OrderedDict assert isinstance(obj, dict) assert isinstance(obj, OrderedDict) .ft P .fi .UNINDENT .UNINDENT .sp yamlex \fI__repr__\fP and \fI__str__\fP objects\(aq methods render YAML understandable string. It means that they are template friendly. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C print \(aq{0}\(aq.format(obj) .ft P .fi .UNINDENT .UNINDENT .sp returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {foo: {bar: 42, baz: [1, 2, 3]}} .ft P .fi .UNINDENT .UNINDENT .sp and they are still valid YAML: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from salt.serializers import yaml yml_obj = yaml.deserialize(str(obj)) assert yml_obj == obj .ft P .fi .UNINDENT .UNINDENT .sp yamlex implements also custom tags: .sp !aggregate .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 this tag allows structures aggregation. .UNINDENT .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C placeholder: !aggregate foo placeholder: !aggregate bar placeholder: !aggregate baz .ft P .fi .UNINDENT .UNINDENT .sp is rendered as .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C placeholder: [foo, bar, baz] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp !reset .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 this tag flushes the computing value. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C placeholder: {!aggregate foo: {foo: 42}} placeholder: {!aggregate foo: {bar: null}} !reset placeholder: {!aggregate foo: {baz: inga}} .ft P .fi .UNINDENT .UNINDENT .sp is roughly equivalent to .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C placeholder: {!aggregate foo: {baz: inga}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Document is defacto an aggregate mapping. .INDENT 0.0 .TP .B class salt.serializers.yamlex.AggregatedMap .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yamlex.AggregatedSequence(iterable=(), /) .UNINDENT .INDENT 0.0 .TP .B salt.serializers.yamlex.BaseDumper alias of \fBSafeDumper\fP .UNINDENT .INDENT 0.0 .TP .B salt.serializers.yamlex.BaseLoader alias of \fBCSafeLoader\fP .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.yamlex.ConstructorError(context=None, context_mark=None, problem=None, problem_mark=None, note=None) .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.yamlex.DeserializationError(message, line_num=None, buf=\(aq\(aq, marker=\(aq <======================\(aq, trace=None) Raised when stream of string failed to be deserialized .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yamlex.Dumper(stream, default_style=None, default_flow_style=False, canonical=None, indent=None, width=None, allow_unicode=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None, sort_keys=True) sls dumper. .INDENT 7.0 .TP .B represent_odict(data) .UNINDENT .INDENT 7.0 .TP .B yaml_multi_representers = {<class \(aqNoneType\(aq>: <function SafeRepresenter.represent_none>, <class \(aqbytes\(aq>: <function SafeRepresenter.represent_binary>, <class \(aqstr\(aq>: <function SafeRepresenter.represent_str>, <class \(aqbool\(aq>: <function SafeRepresenter.represent_bool>, <class \(aqint\(aq>: <function SafeRepresenter.represent_int>, <class \(aqfloat\(aq>: <function SafeRepresenter.represent_float>, <class \(aqlist\(aq>: <function SafeRepresenter.represent_list>, <class \(aqtuple\(aq>: <function SafeRepresenter.represent_list>, <class \(aqdict\(aq>: <function Dumper.represent_odict>, <class \(aqset\(aq>: <function SafeRepresenter.represent_set>, <class \(aqdatetime.date\(aq>: <function SafeRepresenter.represent_date>, <class \(aqdatetime.datetime\(aq>: <function SafeRepresenter.represent_datetime>, None: <function SafeRepresenter.represent_undefined>} .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yamlex.Loader(stream) Create a custom YAML loader that uses the custom constructor. This allows for the YAML loading defaults to be manipulated based on needs within salt to make things like sls file more intuitive. .INDENT 7.0 .TP .B DEFAULT_MAPPING_TAG = \(aqtag:yaml.org,2002:omap\(aq .UNINDENT .INDENT 7.0 .TP .B DEFAULT_SCALAR_TAG = \(aqtag:yaml.org,2002:str\(aq .UNINDENT .INDENT 7.0 .TP .B DEFAULT_SEQUENCE_TAG = \(aqtag:yaml.org,2002:seq\(aq .UNINDENT .INDENT 7.0 .TP .B compose_document() .UNINDENT .INDENT 7.0 .TP .B construct_sls_aggregate(node) .UNINDENT .INDENT 7.0 .TP .B construct_sls_int(node) Verify integers and pass them in correctly is they are declared as octal .UNINDENT .INDENT 7.0 .TP .B construct_sls_reset(node) .UNINDENT .INDENT 7.0 .TP .B construct_sls_str(node) Build the SLSString. .UNINDENT .INDENT 7.0 .TP .B construct_yaml_omap(node) Build the SLSMap .UNINDENT .INDENT 7.0 .TP .B resolve_sls_tag(node) .UNINDENT .INDENT 7.0 .TP .B yaml_constructors = {\(aqtag:yaml.org,2002:null\(aq: <function SafeConstructor.construct_yaml_null>, \(aqtag:yaml.org,2002:bool\(aq: <function SafeConstructor.construct_yaml_bool>, \(aqtag:yaml.org,2002:int\(aq: <function Loader.construct_sls_int>, \(aqtag:yaml.org,2002:float\(aq: <function SafeConstructor.construct_yaml_float>, \(aqtag:yaml.org,2002:binary\(aq: <function SafeConstructor.construct_yaml_binary>, \(aqtag:yaml.org,2002:timestamp\(aq: <function SafeConstructor.construct_yaml_timestamp>, \(aqtag:yaml.org,2002:omap\(aq: <function Loader.construct_yaml_omap>, \(aqtag:yaml.org,2002:pairs\(aq: <function SafeConstructor.construct_yaml_pairs>, \(aqtag:yaml.org,2002:set\(aq: <function SafeConstructor.construct_yaml_set>, \(aqtag:yaml.org,2002:str\(aq: <function Loader.construct_sls_str>, \(aqtag:yaml.org,2002:seq\(aq: <function SafeConstructor.construct_yaml_seq>, \(aqtag:yaml.org,2002:map\(aq: <function SafeConstructor.construct_yaml_map>, None: <function SafeConstructor.construct_undefined>, \(aq!aggregate\(aq: <function Loader.construct_sls_aggregate>, \(aq!reset\(aq: <function Loader.construct_sls_reset>} .UNINDENT .INDENT 7.0 .TP .B yaml_multi_constructors = {\(aqtag:yaml.org,2002:binary\(aq: <function SafeConstructor.construct_yaml_binary>, \(aqtag:yaml.org,2002:bool\(aq: <function SafeConstructor.construct_yaml_bool>, \(aqtag:yaml.org,2002:float\(aq: <function SafeConstructor.construct_yaml_float>, \(aqtag:yaml.org,2002:map\(aq: <function SafeConstructor.construct_yaml_map>, \(aqtag:yaml.org,2002:null\(aq: <function SafeConstructor.construct_yaml_null>, \(aqtag:yaml.org,2002:pairs\(aq: <function SafeConstructor.construct_yaml_pairs>, \(aqtag:yaml.org,2002:seq\(aq: <function SafeConstructor.construct_yaml_seq>, \(aqtag:yaml.org,2002:set\(aq: <function SafeConstructor.construct_yaml_set>, \(aqtag:yaml.org,2002:timestamp\(aq: <function SafeConstructor.construct_yaml_timestamp>} .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yamlex.Map Map aggregation. .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yamlex.MappingNode(tag, value, start_mark=None, end_mark=None, flow_style=None) .INDENT 7.0 .TP .B id = \(aqmapping\(aq .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yamlex.OrderedDict Dictionary that remembers insertion order .INDENT 7.0 .TP .B clear() -> None. Remove all items from od. .UNINDENT .INDENT 7.0 .TP .B copy() -> a shallow copy of od .UNINDENT .INDENT 7.0 .TP .B fromkeys(value=None) Create a new ordered dictionary with keys from iterable and values set to value. .UNINDENT .INDENT 7.0 .TP .B items() -> a set\-like object providing a view on D\(aqs items .UNINDENT .INDENT 7.0 .TP .B keys() -> a set\-like object providing a view on D\(aqs keys .UNINDENT .INDENT 7.0 .TP .B move_to_end(key, last=True) Move an existing element to the end (or beginning if last is false). .sp Raise KeyError if the element does not exist. .UNINDENT .INDENT 7.0 .TP .B pop(key[, default]) -> v, remove specified key and return the corresponding value. If the key is not found, return the default if given; otherwise, raise a KeyError. .UNINDENT .INDENT 7.0 .TP .B popitem(last=True) Remove and return a (key, value) pair from the dictionary. .sp Pairs are returned in LIFO order if last is true or FIFO order if false. .UNINDENT .INDENT 7.0 .TP .B setdefault(key, default=None) Insert key with a value of default if key is not in the dictionary. .sp Return the value for key if key is in the dictionary, else default. .UNINDENT .INDENT 7.0 .TP .B update([E], **F) -> None. Update D from dict/iterable E and F. If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k] .UNINDENT .INDENT 7.0 .TP .B values() -> an object providing a view on D\(aqs values .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yamlex.SLSMap Ensures that dict str() and repr() are YAML friendly. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C >>> mapping = OrderedDict([(\(aqa\(aq, \(aqb\(aq), (\(aqc\(aq, None)]) >>> print mapping OrderedDict([(\(aqa\(aq, \(aqb\(aq), (\(aqc\(aq, None)]) >>> sls_map = SLSMap(mapping) >>> print sls_map.__str__() {a: b, c: null} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yamlex.SLSString Ensures that str str() and repr() are YAML friendly. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C >>> scalar = str(\(aqfoo\(aq) >>> print \(aqfoo\(aq foo >>> sls_scalar = SLSString(scalar) >>> print sls_scalar \(dqfoo\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.yamlex.ScannerError(context=None, context_mark=None, problem=None, problem_mark=None, note=None) .UNINDENT .INDENT 0.0 .TP .B class salt.serializers.yamlex.Sequence(iterable=(), /) Sequence aggregation. .UNINDENT .INDENT 0.0 .TP .B exception salt.serializers.yamlex.SerializationError(message=\(aq\(aq) Raised when stream of string failed to be serialized .UNINDENT .INDENT 0.0 .TP .B salt.serializers.yamlex.aggregate(obj_a, obj_b, level=False, map_class=<class \(aqsalt.utils.aggregation.Map\(aq>, sequence_class=<class \(aqsalt.utils.aggregation.Sequence\(aq>) Merge obj_b into obj_a. .sp .nf .ft C >>> aggregate(\(aqfirst\(aq, \(aqsecond\(aq, True) == [\(aqfirst\(aq, \(aqsecond\(aq] True .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.serializers.yamlex.deserialize(stream_or_string, **options) Deserialize any string of stream like object into a Python data structure. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstream_or_string\fP \-\- stream or string to deserialize. .IP \(bu 2 \fBoptions\fP \-\- options given to lower yaml module. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.serializers.yamlex.merge_recursive(obj_a, obj_b, level=False) Merge obj_b into obj_a. .UNINDENT .INDENT 0.0 .TP .B salt.serializers.yamlex.serialize(obj, **options) Serialize Python data to YAML. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobj\fP \-\- the data structure to serialize .IP \(bu 2 \fBoptions\fP \-\- options given to lower yaml module. .UNINDENT .UNINDENT .UNINDENT .SS state modules .TS center; |l|l|. _ T{ \fI\%acme\fP T} T{ ACME / Let\(aqs Encrypt certificate management state T} _ T{ \fI\%alias\fP T} T{ Configuration of email aliases T} _ T{ \fI\%alternatives\fP T} T{ Configuration of the alternatives system T} _ T{ \fI\%ansiblegate\fP T} T{ Execution of Ansible modules from within states T} _ T{ \fI\%apache\fP T} T{ T} _ T{ \fI\%apache_conf\fP T} T{ T} _ T{ \fI\%apache_module\fP T} T{ T} _ T{ \fI\%apache_site\fP T} T{ T} _ T{ \fI\%aptpkg\fP T} T{ Package management operations specific to APT\- and DEB\-based systems T} _ T{ \fI\%archive\fP T} T{ Extract an archive T} _ T{ \fI\%artifactory\fP T} T{ This state downloads artifacts from artifactory. T} _ T{ \fI\%at\fP T} T{ Configuration disposable regularly scheduled tasks for at. T} _ T{ \fI\%augeas\fP T} T{ Configuration management using Augeas T} _ T{ \fI\%aws_sqs\fP T} T{ Manage SQS Queues T} _ T{ \fI\%beacon\fP T} T{ Management of the Salt beacons T} _ T{ \fI\%bigip\fP T} T{ A state module designed to enforce load\-balancing configurations for F5 Big\-IP entities. T} _ T{ \fI\%blockdev\fP T} T{ Management of Block Devices T} _ T{ \fI\%boto3_elasticache\fP T} T{ Manage Elasticache with boto3 T} _ T{ \fI\%boto3_elasticsearch\fP T} T{ Manage Elasticsearch Service T} _ T{ \fI\%boto3_route53\fP T} T{ Manage Route53 records with Boto 3 T} _ T{ \fI\%boto3_sns\fP T} T{ Manage SNS Topics T} _ T{ \fI\%boto_apigateway\fP T} T{ Manage Apigateway Rest APIs T} _ T{ \fI\%boto_asg\fP T} T{ Manage Autoscale Groups T} _ T{ \fI\%boto_cfn\fP T} T{ Connection module for Amazon Cloud Formation T} _ T{ \fI\%boto_cloudfront\fP T} T{ Manage CloudFront distributions T} _ T{ \fI\%boto_cloudtrail\fP T} T{ Manage CloudTrail Objects T} _ T{ \fI\%boto_cloudwatch_alarm\fP T} T{ Manage Cloudwatch alarms T} _ T{ \fI\%boto_cloudwatch_event\fP T} T{ Manage CloudTrail Objects T} _ T{ \fI\%boto_cognitoidentity\fP T} T{ Manage CognitoIdentity Functions T} _ T{ \fI\%boto_datapipeline\fP T} T{ Manage Data Pipelines T} _ T{ \fI\%boto_dynamodb\fP T} T{ Manage DynamoDB Tables T} _ T{ \fI\%boto_ec2\fP T} T{ Manage EC2 T} _ T{ \fI\%boto_elasticache\fP T} T{ Manage Elasticache T} _ T{ \fI\%boto_elasticsearch_domain\fP T} T{ Manage Elasticsearch Domains T} _ T{ \fI\%boto_elb\fP T} T{ Manage ELBs T} _ T{ \fI\%boto_elbv2\fP T} T{ Manage AWS Application Load Balancer T} _ T{ \fI\%boto_iam\fP T} T{ Manage IAM objects T} _ T{ \fI\%boto_iam_role\fP T} T{ Manage IAM roles T} _ T{ \fI\%boto_iot\fP T} T{ Manage IoT Objects T} _ T{ \fI\%boto_kinesis\fP T} T{ Manage Kinesis Streams T} _ T{ \fI\%boto_kms\fP T} T{ Manage KMS keys, key policies and grants. T} _ T{ \fI\%boto_lambda\fP T} T{ Manage Lambda Functions T} _ T{ \fI\%boto_lc\fP T} T{ Manage Launch Configurations T} _ T{ \fI\%boto_rds\fP T} T{ Manage RDSs T} _ T{ \fI\%boto_route53\fP T} T{ Manage Route53 records T} _ T{ \fI\%boto_s3\fP T} T{ Manage S3 Resources T} _ T{ \fI\%boto_s3_bucket\fP T} T{ Manage S3 Buckets T} _ T{ \fI\%boto_secgroup\fP T} T{ Manage Security Groups T} _ T{ \fI\%boto_sns\fP T} T{ Manage SNS Topics T} _ T{ \fI\%boto_sqs\fP T} T{ Manage SQS Queues T} _ T{ \fI\%boto_vpc\fP T} T{ Manage VPCs T} _ T{ \fI\%bower\fP T} T{ Installation of Bower Packages T} _ T{ \fI\%btrfs\fP T} T{ Manage BTRFS file systems. T} _ T{ \fI\%cabal\fP T} T{ Installation of Cabal Packages T} _ T{ \fI\%ceph\fP T} T{ Manage ceph with salt. T} _ T{ \fI\%chef\fP T} T{ Execute Chef client runs T} _ T{ \fI\%chocolatey\fP T} T{ Manage Windows Packages using Chocolatey . T} _ T{ \fI\%chronos_job\fP T} T{ Configure Chronos jobs via a salt proxy. T} _ T{ \fI\%cimc\fP T} T{ A state module to manage Cisco UCS chassis devices. T} _ T{ \fI\%cisconso\fP T} T{ State module for Cisco NSO Proxy minions T} _ T{ \fI\%cloud\fP T} T{ Using states instead of maps to deploy clouds T} _ T{ \fI\%cmd\fP T} T{ Execution of arbitrary commands T} _ T{ \fI\%composer\fP T} T{ Installation of Composer Packages T} _ T{ \fI\%consul\fP T} T{ Consul Management T} _ T{ \fI\%cron\fP T} T{ Management of cron, the Unix command scheduler T} _ T{ \fI\%cryptdev\fP T} T{ Opening of Encrypted Devices T} _ T{ \fI\%csf\fP T} T{ CSF Ip tables management T} _ T{ \fI\%cyg\fP T} T{ Installation of Cygwin packages. T} _ T{ \fI\%ddns\fP T} T{ Dynamic DNS updates T} _ T{ \fI\%debconfmod\fP T} T{ Management of debconf selections T} _ T{ \fI\%dellchassis\fP T} T{ Manage chassis via Salt Proxies. T} _ T{ \fI\%disk\fP T} T{ Disk monitoring state T} _ T{ \fI\%docker_container\fP T} T{ T} _ T{ \fI\%docker_image\fP T} T{ T} _ T{ \fI\%docker_network\fP T} T{ T} _ T{ \fI\%docker_volume\fP T} T{ T} _ T{ \fI\%drac\fP T} T{ Management of Dell DRAC T} _ T{ \fI\%dvs\fP T} T{ Manage VMware distributed virtual switches (DVSs) and their distributed virtual portgroups (DVportgroups). T} _ T{ \fI\%elasticsearch\fP T} T{ State module to manage Elasticsearch. T} _ T{ \fI\%elasticsearch_index\fP T} T{ State module to manage Elasticsearch indices T} _ T{ \fI\%elasticsearch_index_template\fP T} T{ State module to manage Elasticsearch index templates T} _ T{ \fI\%environ\fP T} T{ Support for getting and setting the environment variables of the current salt process. T} _ T{ \fI\%eselect\fP T} T{ Management of Gentoo configuration using eselect T} _ T{ \fI\%esxcluster\fP T} T{ Manage VMware ESXi Clusters. T} _ T{ \fI\%esxdatacenter\fP T} T{ Salt states to create and manage VMware vSphere datacenters (datacenters). T} _ T{ \fI\%esxi\fP T} T{ Manage VMware ESXi Hosts. T} _ T{ \fI\%esxvm\fP T} T{ Salt state to create, update VMware ESXi Virtual Machines. T} _ T{ \fI\%etcd_mod\fP T} T{ Manage etcd Keys T} _ T{ \fI\%ethtool\fP T} T{ Configuration of network device T} _ T{ \fI\%event\fP T} T{ Send events through Salt\(aqs event system during state runs T} _ T{ \fI\%file\fP T} T{ Operations on regular files, special files, directories, and symlinks T} _ T{ \fI\%firewall\fP T} T{ State to check firewall configurations T} _ T{ \fI\%firewalld\fP T} T{ Management of firewalld T} _ T{ \fI\%gem\fP T} T{ Installation of Ruby modules packaged as gems T} _ T{ \fI\%git\fP T} T{ States to manage git repositories and git configuration T} _ T{ \fI\%github\fP T} T{ Github User State Module T} _ T{ \fI\%glance_image\fP T} T{ Management of OpenStack Glance Images T} _ T{ \fI\%glassfish\fP T} T{ Manage Glassfish/Payara server . T} _ T{ \fI\%glusterfs\fP T} T{ Manage GlusterFS pool. T} _ T{ \fI\%gnomedesktop\fP T} T{ Configuration of the GNOME desktop T} _ T{ \fI\%gpg\fP T} T{ Manage GPG keychains T} _ T{ \fI\%grafana\fP T} T{ Manage Grafana Dashboards T} _ T{ \fI\%grafana4_dashboard\fP T} T{ Manage Grafana v4.0 Dashboards T} _ T{ \fI\%grafana4_datasource\fP T} T{ Manage Grafana v4.0 data sources T} _ T{ \fI\%grafana4_org\fP T} T{ Manage Grafana v4.0 orgs T} _ T{ \fI\%grafana4_user\fP T} T{ Manage Grafana v4.0 users T} _ T{ \fI\%grafana_dashboard\fP T} T{ Manage Grafana v2.0 Dashboards T} _ T{ \fI\%grafana_datasource\fP T} T{ Manage Grafana v2.0 data sources T} _ T{ \fI\%grains\fP T} T{ Manage grains on the minion T} _ T{ \fI\%group\fP T} T{ Management of user groups T} _ T{ \fI\%heat\fP T} T{ Management of Heat T} _ T{ \fI\%helm\fP T} T{ T} _ T{ \fI\%hg\fP T} T{ Interaction with Mercurial repositories T} _ T{ \fI\%highstate_doc\fP T} T{ To be used with processors in module \fIhighstate_doc\fP\&. T} _ T{ \fI\%host\fP T} T{ Management of addresses and names in hosts file T} _ T{ \fI\%http\fP T} T{ HTTP monitoring states T} _ T{ \fI\%icinga2\fP T} T{ Icinga2 state T} _ T{ \fI\%idem\fP T} T{ Idem Support T} _ T{ \fI\%ifttt\fP T} T{ Trigger an event in IFTTT T} _ T{ \fI\%incron\fP T} T{ Management of incron, the inotify cron T} _ T{ \fI\%influxdb08_database\fP T} T{ Management of Influxdb 0.8 databases T} _ T{ \fI\%influxdb08_user\fP T} T{ Management of InfluxDB 0.8 users T} _ T{ \fI\%influxdb_continuous_query\fP T} T{ Management of Influxdb continuous queries T} _ T{ \fI\%influxdb_database\fP T} T{ Management of Influxdb databases T} _ T{ \fI\%influxdb_retention_policy\fP T} T{ Management of Influxdb retention policies T} _ T{ \fI\%influxdb_user\fP T} T{ Management of InfluxDB users T} _ T{ \fI\%infoblox_a\fP T} T{ Infoblox A record management. T} _ T{ \fI\%infoblox_cname\fP T} T{ Infoblox CNAME management. T} _ T{ \fI\%infoblox_host_record\fP T} T{ Infoblox host record management. T} _ T{ \fI\%infoblox_range\fP T} T{ Infoblox host record management. T} _ T{ \fI\%ini_manage\fP T} T{ Manage ini files T} _ T{ \fI\%ipmi\fP T} T{ Manage IPMI devices over LAN T} _ T{ \fI\%ipset\fP T} T{ Management of ipsets T} _ T{ \fI\%iptables\fP T} T{ Management of iptables T} _ T{ \fI\%jboss7\fP T} T{ Manage JBoss 7 Application Server via CLI interface T} _ T{ \fI\%jenkins\fP T} T{ Management of Jenkins T} _ T{ \fI\%junos\fP T} T{ State modules to interact with Junos devices. T} _ T{ \fI\%kapacitor\fP T} T{ Kapacitor state module. T} _ T{ \fI\%kernelpkg\fP T} T{ Manage kernel packages and active kernel version T} _ T{ \fI\%keyboard\fP T} T{ Management of keyboard layouts T} _ T{ \fI\%keystone\fP T} T{ Management of Keystone users T} _ T{ \fI\%keystone_domain\fP T} T{ Management of OpenStack Keystone Domains T} _ T{ \fI\%keystone_endpoint\fP T} T{ Management of OpenStack Keystone Endpoints T} _ T{ \fI\%keystone_group\fP T} T{ Management of OpenStack Keystone Groups T} _ T{ \fI\%keystone_project\fP T} T{ Management of OpenStack Keystone Projects T} _ T{ \fI\%keystone_role\fP T} T{ Management of OpenStack Keystone Roles T} _ T{ \fI\%keystone_role_grant\fP T} T{ Management of OpenStack Keystone Role Grants T} _ T{ \fI\%keystone_service\fP T} T{ Management of OpenStack Keystone Services T} _ T{ \fI\%keystone_user\fP T} T{ Management of OpenStack Keystone Users T} _ T{ \fI\%keystore\fP T} T{ State management of a java keystore T} _ T{ \fI\%kmod\fP T} T{ Loading and unloading of kernel modules T} _ T{ \fI\%kubernetes\fP T} T{ T} _ T{ \fI\%layman\fP T} T{ Management of Gentoo Overlays using layman T} _ T{ \fI\%ldap\fP T} T{ Manage entries in an LDAP database T} _ T{ \fI\%libcloud_dns\fP T} T{ Manage DNS records and zones using libcloud T} _ T{ \fI\%libcloud_loadbalancer\fP T} T{ Apache Libcloud Load Balancer State T} _ T{ \fI\%libcloud_storage\fP T} T{ Apache Libcloud Storage State T} _ T{ \fI\%linux_acl\fP T} T{ Linux File Access Control Lists T} _ T{ \fI\%locale\fP T} T{ Management of languages/locales T} _ T{ \fI\%logadm\fP T} T{ Management of logs using Solaris logadm. T} _ T{ \fI\%logrotate\fP T} T{ Module for managing logrotate. T} _ T{ \fI\%loop\fP T} T{ Loop state T} _ T{ \fI\%lvm\fP T} T{ Management of Linux logical volumes T} _ T{ \fI\%lvs_server\fP T} T{ Management of LVS (Linux Virtual Server) Real Server T} _ T{ \fI\%lvs_service\fP T} T{ Management of LVS (Linux Virtual Server) Service T} _ T{ \fI\%lxc\fP T} T{ Manage Linux Containers T} _ T{ \fI\%lxd\fP T} T{ Manage LXD profiles. T} _ T{ \fI\%lxd_container\fP T} T{ Manage LXD containers. T} _ T{ \fI\%lxd_image\fP T} T{ Manage LXD images. T} _ T{ \fI\%lxd_profile\fP T} T{ Manage LXD profiles. T} _ T{ \fI\%mac_assistive\fP T} T{ Allows you to manage assistive access on macOS minions with 10.9+ T} _ T{ \fI\%mac_keychain\fP T} T{ Installing of certificates to the keychain T} _ T{ \fI\%mac_xattr\fP T} T{ Allows you to manage extended attributes on files or directories T} _ T{ \fI\%macdefaults\fP T} T{ Writing/reading defaults from a macOS minion T} _ T{ \fI\%macpackage\fP T} T{ Installing of mac pkg files T} _ T{ \fI\%makeconf\fP T} T{ Management of Gentoo make.conf T} _ T{ \fI\%marathon_app\fP T} T{ Configure Marathon apps via a salt proxy. T} _ T{ \fI\%mdadm_raid\fP T} T{ Managing software RAID with mdadm T} _ T{ \fI\%memcached\fP T} T{ States for Management of Memcached Keys T} _ T{ \fI\%modjk\fP T} T{ State to control Apache modjk T} _ T{ \fI\%modjk_worker\fP T} T{ Manage modjk workers T} _ T{ \fI\%module\fP T} T{ Execution of Salt modules from within states T} _ T{ \fI\%mongodb_database\fP T} T{ Management of MongoDB Databases T} _ T{ \fI\%mongodb_user\fP T} T{ Management of MongoDB Users T} _ T{ \fI\%monit\fP T} T{ Monit state T} _ T{ \fI\%mount\fP T} T{ Mounting of filesystems T} _ T{ \fI\%mssql_database\fP T} T{ Management of Microsoft SQLServer Databases T} _ T{ \fI\%mssql_login\fP T} T{ Management of Microsoft SQLServer Logins T} _ T{ \fI\%mssql_role\fP T} T{ Management of Microsoft SQLServer Databases T} _ T{ \fI\%mssql_user\fP T} T{ Management of Microsoft SQLServer Users T} _ T{ \fI\%msteams\fP T} T{ Send a message card to Microsoft Teams T} _ T{ \fI\%mysql_database\fP T} T{ Management of MySQL databases (schemas) T} _ T{ \fI\%mysql_grants\fP T} T{ Management of MySQL grants (user permissions) T} _ T{ \fI\%mysql_query\fP T} T{ Execution of MySQL queries T} _ T{ \fI\%mysql_user\fP T} T{ Management of MySQL users T} _ T{ \fI\%net_napalm_yang\fP T} T{ NAPALM YANG state T} _ T{ \fI\%netacl\fP T} T{ Network ACL T} _ T{ \fI\%netconfig\fP T} T{ Network Config T} _ T{ \fI\%netntp\fP T} T{ Network NTP T} _ T{ \fI\%netsnmp\fP T} T{ Network SNMP T} _ T{ \fI\%netusers\fP T} T{ Network Users T} _ T{ \fI\%network\fP T} T{ Configuration of network interfaces T} _ T{ \fI\%neutron_network\fP T} T{ Management of OpenStack Neutron Networks T} _ T{ \fI\%neutron_secgroup\fP T} T{ Management of OpenStack Neutron Security Groups T} _ T{ \fI\%neutron_secgroup_rule\fP T} T{ Management of OpenStack Neutron Security Group Rules T} _ T{ \fI\%neutron_subnet\fP T} T{ Management of OpenStack Neutron Subnets T} _ T{ \fI\%nexus\fP T} T{ This state downloads artifacts from Nexus 3.x. T} _ T{ \fI\%nfs_export\fP T} T{ Management of NFS exports T} _ T{ \fI\%nftables\fP T} T{ Management of nftables T} _ T{ \fI\%npm\fP T} T{ Installation of NPM Packages T} _ T{ \fI\%ntp\fP T} T{ Management of NTP servers T} _ T{ \fI\%nxos\fP T} T{ State module for Cisco NX\-OS Switch Proxy and Native minions T} _ T{ \fI\%nxos_upgrade\fP T} T{ Manage NX\-OS System Image Upgrades. T} _ T{ \fI\%openstack_config\fP T} T{ Manage OpenStack configuration file settings. T} _ T{ \fI\%openvswitch_bridge\fP T} T{ Management of Open vSwitch bridges. T} _ T{ \fI\%openvswitch_db\fP T} T{ Management of Open vSwitch database records. T} _ T{ \fI\%openvswitch_port\fP T} T{ Management of Open vSwitch ports. T} _ T{ \fI\%opsgenie\fP T} T{ Create/Close an alert in OpsGenie T} _ T{ \fI\%pagerduty\fP T} T{ Create an Event in PagerDuty T} _ T{ \fI\%pagerduty_escalation_policy\fP T} T{ Manage PagerDuty escalation policies. T} _ T{ \fI\%pagerduty_schedule\fP T} T{ Manage PagerDuty schedules. T} _ T{ \fI\%pagerduty_service\fP T} T{ Manage PagerDuty services T} _ T{ \fI\%pagerduty_user\fP T} T{ Manage PagerDuty users. T} _ T{ \fI\%panos\fP T} T{ A state module to manage Palo Alto network devices. T} _ T{ \fI\%pbm\fP T} T{ Manages VMware storage policies (called pbm because the vCenter endpoint is /pbm) T} _ T{ \fI\%pcs\fP T} T{ Management of Pacemaker/Corosync clusters with PCS T} _ T{ \fI\%pdbedit\fP T} T{ Manage accounts in Samba\(aqs passdb using pdbedit T} _ T{ \fI\%pecl\fP T} T{ Installation of PHP Extensions Using pecl T} _ T{ \fI\%pip_state\fP T} T{ Installation of Python Packages Using pip T} _ T{ \fI\%pkg\fP T} T{ Installation of packages using OS package managers such as yum or apt\-get T} _ T{ \fI\%pkgbuild\fP T} T{ The pkgbuild state is the front of Salt package building backend. T} _ T{ \fI\%pkgng\fP T} T{ Manage package remote repo using FreeBSD pkgng T} _ T{ \fI\%pkgrepo\fP T} T{ Management of APT/DNF/YUM/Zypper package repos T} _ T{ \fI\%portage_config\fP T} T{ Management of Portage package configuration on Gentoo T} _ T{ \fI\%ports\fP T} T{ Manage software from FreeBSD ports T} _ T{ \fI\%postgres_cluster\fP T} T{ Management of PostgreSQL clusters T} _ T{ \fI\%postgres_database\fP T} T{ Management of PostgreSQL databases T} _ T{ \fI\%postgres_extension\fP T} T{ Management of PostgreSQL extensions T} _ T{ \fI\%postgres_group\fP T} T{ Management of PostgreSQL groups (roles) T} _ T{ \fI\%postgres_initdb\fP T} T{ Initialization of PostgreSQL data directory T} _ T{ \fI\%postgres_language\fP T} T{ Management of PostgreSQL languages T} _ T{ \fI\%postgres_privileges\fP T} T{ Management of PostgreSQL Privileges T} _ T{ \fI\%postgres_schema\fP T} T{ Management of PostgreSQL schemas T} _ T{ \fI\%postgres_tablespace\fP T} T{ Management of PostgreSQL tablespace T} _ T{ \fI\%postgres_user\fP T} T{ Management of PostgreSQL users (roles) T} _ T{ \fI\%powerpath\fP T} T{ Powerpath configuration support T} _ T{ \fI\%probes\fP T} T{ Network Probes T} _ T{ \fI\%process\fP T} T{ Process Management T} _ T{ \fI\%proxy\fP T} T{ Allows you to manage proxy settings on minions T} _ T{ \fI\%pushover\fP T} T{ T} _ T{ \fI\%pyenv\fP T} T{ Managing python installations with pyenv T} _ T{ \fI\%pyrax_queues\fP T} T{ Manage Rackspace Queues T} _ T{ \fI\%quota\fP T} T{ Management of POSIX Quotas T} _ T{ \fI\%rabbitmq_cluster\fP T} T{ Manage RabbitMQ Clusters T} _ T{ \fI\%rabbitmq_plugin\fP T} T{ Manage RabbitMQ Plugins T} _ T{ \fI\%rabbitmq_policy\fP T} T{ Manage RabbitMQ Policies T} _ T{ \fI\%rabbitmq_upstream\fP T} T{ Manage RabbitMQ Upstreams T} _ T{ \fI\%rabbitmq_user\fP T} T{ Manage RabbitMQ Users T} _ T{ \fI\%rabbitmq_vhost\fP T} T{ Manage RabbitMQ Virtual Hosts T} _ T{ \fI\%rbac_solaris\fP T} T{ Management of Solaris RBAC T} _ T{ \fI\%rbenv\fP T} T{ Managing Ruby installations with rbenv T} _ T{ \fI\%rdp\fP T} T{ Manage RDP Service on Windows servers T} _ T{ \fI\%redismod\fP T} T{ Management of Redis server T} _ T{ \fI\%reg\fP T} T{ Manage the Windows registry T} _ T{ \fI\%restconf\fP T} T{ RESTCONF State module for Proxy minions T} _ T{ \fI\%rsync\fP T} T{ State to synchronize files and directories with rsync. T} _ T{ \fI\%rvm\fP T} T{ Managing Ruby installations and gemsets with Ruby Version Manager (RVM) T} _ T{ \fI\%salt_proxy\fP T} T{ Salt proxy state T} _ T{ \fI\%saltmod\fP T} T{ Control the Salt command interface T} _ T{ \fI\%saltutil\fP T} T{ Saltutil State T} _ T{ \fI\%schedule\fP T} T{ Management of the Salt scheduler T} _ T{ \fI\%selinux\fP T} T{ Management of SELinux rules T} _ T{ \fI\%serverdensity_device\fP T} T{ Monitor Server with Server Density T} _ T{ \fI\%service\fP T} T{ Starting or restarting of services and daemons T} _ T{ \fI\%slack\fP T} T{ Send a message to Slack T} _ T{ \fI\%smartos\fP T} T{ Management of SmartOS Standalone Compute Nodes T} _ T{ \fI\%smtp\fP T} T{ Sending Messages via SMTP T} _ T{ \fI\%snapper\fP T} T{ Managing implicit state and baselines using snapshots T} _ T{ \fI\%solrcloud\fP T} T{ States for solrcloud alias and collection configuration T} _ T{ \fI\%splunk\fP T} T{ Splunk User State Module T} _ T{ \fI\%splunk_search\fP T} T{ Splunk Search State Module T} _ T{ \fI\%sqlite3\fP T} T{ Management of SQLite3 databases T} _ T{ \fI\%ssh_auth\fP T} T{ Control of entries in SSH authorized_key files T} _ T{ \fI\%ssh_known_hosts\fP T} T{ Control of SSH known_hosts entries T} _ T{ \fI\%stateconf\fP T} T{ Stateconf System T} _ T{ \fI\%status\fP T} T{ Minion status monitoring T} _ T{ \fI\%statuspage\fP T} T{ StatusPage T} _ T{ \fI\%supervisord\fP T} T{ Interaction with the Supervisor daemon T} _ T{ \fI\%svn\fP T} T{ Manage SVN repositories T} _ T{ \fI\%sysctl\fP T} T{ Configuration of the kernel using sysctl T} _ T{ \fI\%sysfs\fP T} T{ Configuration of the kernel using sysfs T} _ T{ \fI\%syslog_ng\fP T} T{ State module for syslog_ng T} _ T{ \fI\%sysrc\fP T} T{ State to work with sysrc T} _ T{ \fI\%telemetry_alert\fP T} T{ Manage Telemetry alert configurations T} _ T{ \fI\%test\fP T} T{ Test States T} _ T{ \fI\%testinframod\fP T} T{ T} _ T{ \fI\%timezone\fP T} T{ Management of timezones T} _ T{ \fI\%tls\fP T} T{ Enforce state for SSL/TLS T} _ T{ \fI\%tomcat\fP T} T{ Manage Apache Tomcat web applications T} _ T{ \fI\%trafficserver\fP T} T{ Control Apache Traffic Server T} _ T{ \fI\%tuned\fP T} T{ Interface to Red Hat tuned\-adm module T} _ T{ \fI\%uptime\fP T} T{ Monitor Web Server with Uptime T} _ T{ \fI\%user\fP T} T{ Management of user accounts. T} _ T{ \fI\%vagrant\fP T} T{ Manage Vagrant VMs T} _ T{ \fI\%vault\fP T} T{ T} _ T{ \fI\%vbox_guest\fP T} T{ VirtualBox Guest Additions installer state T} _ T{ \fI\%victorops\fP T} T{ Create an Event in VictorOps T} _ T{ \fI\%virt\fP T} T{ Manage virt T} _ T{ \fI\%virtualenv_mod\fP T} T{ Setup of Python virtualenv sandboxes. T} _ T{ \fI\%webutil\fP T} T{ Support for htpasswd module. T} _ T{ \fI\%win_appx\fP T} T{ Manage Microsoft Store apps on Windows. T} _ T{ \fI\%win_certutil\fP T} T{ Installing of certificates to the Windows Certificate Manager T} _ T{ \fI\%win_dacl\fP T} T{ Windows Object Access Control Lists T} _ T{ \fI\%win_dism\fP T} T{ Installing of Windows features using DISM T} _ T{ \fI\%win_dns_client\fP T} T{ Module for configuring DNS Client on Windows systems T} _ T{ \fI\%win_firewall\fP T} T{ State for configuring Windows Firewall T} _ T{ \fI\%win_iis\fP T} T{ Microsoft IIS site management T} _ T{ \fI\%win_lgpo\fP T} T{ Manage Windows Local Group Policy T} _ T{ \fI\%win_lgpo_reg\fP T} T{ LGPO \- Registry.pol T} _ T{ \fI\%win_license\fP T} T{ Installation and activation of windows licenses T} _ T{ \fI\%win_network\fP T} T{ Configuration of network interfaces on Windows hosts T} _ T{ \fI\%win_path\fP T} T{ Manage the Windows System PATH T} _ T{ \fI\%win_pki\fP T} T{ Microsoft certificate management via the Pki PowerShell module. T} _ T{ \fI\%win_powercfg\fP T} T{ This module allows you to control the power settings of a windows minion via powercfg. T} _ T{ \fI\%win_servermanager\fP T} T{ Manage Windows features via the ServerManager powershell module. T} _ T{ \fI\%win_shortcut\fP T} T{ State module for creating shortcuts on Windows. T} _ T{ \fI\%win_smtp_server\fP T} T{ Module for managing IIS SMTP server configuration on Windows servers. T} _ T{ \fI\%win_snmp\fP T} T{ Module for managing SNMP service settings on Windows servers. T} _ T{ \fI\%win_system\fP T} T{ Management of Windows system information T} _ T{ \fI\%win_task\fP T} T{ State module for adding and removing scheduled tasks using the Windows Task Scheduler. T} _ T{ \fI\%win_wua\fP T} T{ Installation of Windows Updates using the Windows Update Agent T} _ T{ \fI\%win_wusa\fP T} T{ Microsoft Updates (KB) Management T} _ T{ \fI\%winrepo\fP T} T{ Manage Windows Package Repository T} _ T{ \fI\%wordpress\fP T} T{ This state module is used to manage Wordpress installations T} _ T{ \fI\%x509\fP T} T{ Manage X509 Certificates T} _ T{ \fI\%x509_v2\fP T} T{ Manage X.509 certificates T} _ T{ \fI\%xml\fP T} T{ XML Manager T} _ T{ \fI\%xmpp\fP T} T{ Sending Messages over XMPP T} _ T{ \fI\%zabbix_action\fP T} T{ T} _ T{ \fI\%zabbix_host\fP T} T{ T} _ T{ \fI\%zabbix_hostgroup\fP T} T{ T} _ T{ \fI\%zabbix_mediatype\fP T} T{ T} _ T{ \fI\%zabbix_template\fP T} T{ T} _ T{ \fI\%zabbix_user\fP T} T{ T} _ T{ \fI\%zabbix_usergroup\fP T} T{ T} _ T{ \fI\%zabbix_usermacro\fP T} T{ T} _ T{ \fI\%zabbix_valuemap\fP T} T{ T} _ T{ \fI\%zcbuildout\fP T} T{ Management of zc.buildout T} _ T{ \fI\%zenoss\fP T} T{ State to manage monitoring in Zenoss. T} _ T{ \fI\%zfs\fP T} T{ States for managing zfs datasets T} _ T{ \fI\%zk_concurrency\fP T} T{ Control concurrency of steps within state execution using zookeeper T} _ T{ \fI\%zone\fP T} T{ Management of Solaris Zones T} _ T{ \fI\%zookeeper\fP T} T{ Zookeeper State T} _ T{ \fI\%zpool\fP T} T{ States for managing zpools T} _ .TE .SS salt.states.acme .SS ACME / Let\(aqs Encrypt certificate management state .sp New in version 2016.3.0. .sp See also the module documentation .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reload\-gitlab: cmd.run: \- name: gitlab\-ctl hup dev.example.com: acme.cert: \- aliases: \- gitlab.example.com \- email: acmemaster@example.com \- webroot: /opt/gitlab/embedded/service/gitlab\-rails/public \- renew: 14 \- fire_event: acme/dev.example.com \- onchanges_in: \- cmd: reload\-gitlab .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.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, manual_auth_hook=None, manual_cleanup_hook=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 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) .IP \(bu 2 \fBdns_plugin_credentials\fP \-\- Path to the credentials file if required by the specified DNS plugin .IP \(bu 2 \fBmanual_auth_hook\fP \-\- Path to the authentication hook script. .IP \(bu 2 \fBmanual_cleanup_hook\fP \-\- Path to the cleanup or post\-authentication hook script. .UNINDENT .UNINDENT .UNINDENT .SS salt.states.alias .sp Configuration of email aliases .sp The mail aliases file can be managed to contain definitions for specific email aliases: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C username: alias.present: \- target: user@example.com .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C thomas: alias.present: \- target: thomas@example.com .ft P .fi .UNINDENT .UNINDENT .sp The default alias file is set to \fB/etc/aliases\fP, as defined in Salt\(aqs \fI\%config execution module\fP\&. To change the alias file from the default location, set the following in your minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C aliases.file: /my/alias/file .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.alias.absent(name) Ensure that the named alias is absent .INDENT 7.0 .TP .B name The alias to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.alias.present(name, target) Ensures that the named alias is present with the given target or list of targets. If the alias exists but the target differs from the previous entry, the target(s) will be overwritten. If the alias does not exist, the alias will be created. .INDENT 7.0 .TP .B name The local user/address to assign an alias to .TP .B target The forwarding address .UNINDENT .UNINDENT .SS salt.states.alternatives .sp Configuration of the alternatives system .sp Control the alternatives system .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set my_hadoop_conf = \(aq/opt/hadoop/conf\(aq %} {{ my_hadoop_conf }}: file.directory hadoop\-0.20\-conf: alternatives.install: \- name: hadoop\-0.20\-conf \- link: /etc/hadoop\-0.20/conf \- path: {{ my_hadoop_conf }} \- priority: 30 \- require: \- file: {{ my_hadoop_conf }} hadoop\-0.20\-conf: alternatives.remove: \- name: hadoop\-0.20\-conf \- path: {{ my_hadoop_conf }} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.alternatives.auto(name) New in version 0.17.0. .sp Instruct alternatives to use the highest priority path for <name> .INDENT 7.0 .TP .B name is the master name for this link group (e.g. pager) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.alternatives.install(name, link, path, priority) Install new alternative for defined <name> .INDENT 7.0 .TP .B name is the master name for this link group (e.g. pager) .TP .B link is the symlink pointing to /etc/alternatives/<name>. (e.g. /usr/bin/pager) .TP .B path is the location of the new alternative target. NB: This file / directory must already exist. (e.g. /usr/bin/less) .TP .B priority is an integer; options with higher numbers have higher priority in automatic mode. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.alternatives.remove(name, path) Removes installed alternative for defined <name> and <path> or fallback to default alternative, if some defined before. .INDENT 7.0 .TP .B name is the master name for this link group (e.g. pager) .TP .B path is the location of one of the alternative target files. (e.g. /usr/bin/less) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.alternatives.set_(name, path) New in version 0.17.0. .sp Sets alternative for <name> to <path>, if <path> is defined as an alternative for <name>. .INDENT 7.0 .TP .B name is the master name for this link group (e.g. pager) .TP .B path is the location of one of the alternative target files. (e.g. /usr/bin/less) .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: alternatives.set: \- path: /usr/bin/foo\-2.0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.ansiblegate .SS Execution of Ansible modules from within states .sp With \fIansible.call\fP these states allow individual Ansible module calls to be made via states. To call an Ansible module function use a \fBmodule.run\fP state: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C some_set_of_tasks: ansible: \- system.ping \- packaging.os.zypper \- name: emacs \- state: installed .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.states.ansiblegate.AnsibleState Ansible state caller. .INDENT 7.0 .TP .B get_args(argset) Get args and kwargs from the argset. .INDENT 7.0 .TP .B Parameters \fBargset\fP \-\- .TP .B Returns .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ansiblegate.playbooks(name, rundir=None, git_repo=None, git_kwargs=None, ansible_kwargs=None) Run Ansible Playbooks .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- path to playbook. This can be relative to rundir or the git repo .IP \(bu 2 \fBrundir\fP \-\- location to run ansible\-playbook from. .IP \(bu 2 \fBgit_repo\fP \-\- git repository to clone for ansible playbooks. This is cloned using the \fIgit.latest\fP state, and is cloned to the \fIrundir\fP if specified, otherwise it is clone to the \fIcache_dir\fP .IP \(bu 2 \fBgit_kwargs\fP \-\- extra kwargs to pass to \fIgit.latest\fP state module besides the \fIname\fP and \fItarget\fP .IP \(bu 2 \fBansible_kwargs\fP \-\- extra kwargs to pass to \fIansible.playbooks\fP execution module besides the \fIname\fP and \fItarget\fP .UNINDENT .TP .B Returns Ansible playbook output. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C run nginx install: ansible.playbooks: \- name: install.yml \- git_repo: git://github.com/gituser/playbook.git \- git_kwargs: rev: master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.apache .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%apache Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Apache state .sp New in version 2014.7.0. .sp Allows for inputting a yaml dictionary into a file for apache configuration files. .sp The variable \fBthis\fP is special and signifies what should be included with the above word between angle brackets (<>). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/httpd/conf.d/website.com.conf: apache.configfile: \- config: \- VirtualHost: this: \(aq*:80\(aq ServerName: \- website.com ServerAlias: \- www.website.com \- dev.website.com ErrorLog: logs/website.com\-error_log CustomLog: logs/website.com\-access_log combined DocumentRoot: /var/www/vhosts/website.com Directory: this: /var/www/vhosts/website.com Order: Deny,Allow Deny from: all Allow from: \- 127.0.0.1 \- 192.168.100.0/24 Options: \- Indexes \- FollowSymlinks AllowOverride: All .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2018.3.0. .sp Allows having the same section container multiple times (e.g. <Directory /path/to/dir>). .sp YAML structure stays the same only replace dictionary with a list. .sp When a section container does not have mandatory attribute, such as <Else>, it still needs keyword \fBthis\fP with empty string (or \(dq\(dq if nicer output is required \- without space). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/httpd/conf.d/website.com.conf: apache.configfile: \- config: \- VirtualHost: \- this: \(aq*:80\(aq \- ServerName: \- website.com \- DocumentRoot: /var/www/vhosts/website.com \- Directory: this: /var/www/vhosts/website.com Order: Deny,Allow Deny from: all Allow from: \- 127.0.0.1 \- 192.168.100.0/24 Options: \- Indexes \- FollowSymlinks AllowOverride: All \- Directory: \- this: /var/www/vhosts/website.com/private \- Order: Deny,Allow \- Deny from: all \- Allow from: \- 127.0.0.1 \- 192.168.100.0/24 \- If: this: some condition do: something \- Else: this: do: something else \- Else: this: \(dq\(dq do: another thing .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.apache.configfile(name, config) .UNINDENT .SS salt.states.apache_conf .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%apache Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Manage Apache Confs .sp New in version 2016.3.0. .sp Enable and disable apache confs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Enable security conf: apache_conf.enabled: \- name: security Disable security conf: apache_conf.disabled: \- name: security .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.apache_conf.disabled(name) Ensure an Apache conf is disabled. .INDENT 7.0 .TP .B name Name of the Apache conf .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.apache_conf.enabled(name) Ensure an Apache conf is enabled. .INDENT 7.0 .TP .B name Name of the Apache conf .UNINDENT .UNINDENT .SS salt.states.apache_module .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%apache Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Manage Apache Modules .sp New in version 2014.7.0. .sp Enable and disable apache modules. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Enable cgi module: apache_module.enabled: \- name: cgi Disable cgi module: apache_module.disabled: \- name: cgi .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.apache_module.disabled(name) Ensure an Apache module is disabled. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name Name of the Apache module .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.apache_module.enabled(name) Ensure an Apache module is enabled. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name Name of the Apache module .UNINDENT .UNINDENT .SS salt.states.apache_site .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%apache Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Manage Apache Sites .sp New in version 2016.3.0. .sp Enable and disable apache sites. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Enable default site: apache_site.enabled: \- name: default Disable default site: apache_site.disabled: \- name: default .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.apache_site.disabled(name) Ensure an Apache site is disabled. .INDENT 7.0 .TP .B name Name of the Apache site .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.apache_site.enabled(name) Ensure an Apache site is enabled. .INDENT 7.0 .TP .B name Name of the Apache site .UNINDENT .UNINDENT .SS salt.states.aptpkg .SS Package management operations specific to APT\- and DEB\-based systems .INDENT 0.0 .TP .B salt.states.aptpkg.held(name) 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 .UNINDENT .UNINDENT .SS salt.states.archive .sp Extract an archive .sp New in version 2014.1.0. .INDENT 0.0 .TP .B salt.states.archive.extracted(name, source, source_hash=None, source_hash_name=None, source_hash_update=False, skip_files_list_verify=False, skip_verify=False, password=None, options=None, list_options=None, force=False, overwrite=False, clean=False, clean_parent=False, user=None, group=None, if_missing=None, trim_output=False, use_cmd_unzip=None, extract_perms=True, enforce_toplevel=True, enforce_ownership_on=None, archive_format=None, use_etag=False, signature=None, source_hash_sig=None, signed_by_any=None, signed_by_all=None, keyring=None, gnupghome=None, **kwargs) New in version 2014.1.0. .sp Changed in version 2016.11.0,3005: This state has been rewritten. Some arguments are new to this release and will not be available in the 2016.3 release cycle (and earlier). Additionally, the \fBZIP Archive Handling\fP section below applies specifically to the 2016.11.0 release (and newer). .sp Ensure that an archive is extracted to a specific directory. .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 \fBChanges for 2016.11.0\fP .sp In earlier releases, this state would rely on the \fBif_missing\fP argument to determine whether or not the archive needed to be extracted. When this argument was not passed, then the state would just assume \fBif_missing\fP is the same as the \fBname\fP argument (i.e. the parent directory into which the archive would be extracted). .sp This caused a number of annoyances. One such annoyance was the need to know beforehand a path that would result from the extraction of the archive, and setting \fBif_missing\fP to that directory, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C extract_myapp: archive.extracted: \- name: /var/www \- source: salt://apps/src/myapp\-16.2.4.tar.gz \- user: www \- group: www \- if_missing: /var/www/myapp\-16.2.4 .ft P .fi .UNINDENT .UNINDENT .sp If \fB/var/www\fP already existed, this would effectively make \fBif_missing\fP a required argument, just to get Salt to extract the archive. .sp Some users worked around this by adding the top\-level directory of the archive to the end of the \fBname\fP argument, and then used \fB\-\-strip\fP or \fB\-\-strip\-components\fP to remove that top\-level dir when extracting: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C extract_myapp: archive.extracted: \- name: /var/www/myapp\-16.2.4 \- source: salt://apps/src/myapp\-16.2.4.tar.gz \- user: www \- group: www .ft P .fi .UNINDENT .UNINDENT .sp With the rewrite for 2016.11.0, these workarounds are no longer necessary. \fBif_missing\fP is still a supported argument, but it is no longer required. The equivalent SLS in 2016.11.0 would be: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C extract_myapp: archive.extracted: \- name: /var/www \- source: salt://apps/src/myapp\-16.2.4.tar.gz \- user: www \- group: www .ft P .fi .UNINDENT .UNINDENT .sp Salt now uses a function called \fBarchive.list\fP to get a list of files/directories in the archive. Using this information, the state can now check the minion to see if any paths are missing, and know whether or not the archive needs to be extracted. This makes the \fBif_missing\fP argument unnecessary in most use cases. .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 \fBZIP Archive Handling\fP .sp \fINote: this information applies to 2016.11.0 and later.\fP .sp Salt has two different functions for extracting ZIP archives: .INDENT 0.0 .IP 1. 3 \fI\%archive.unzip\fP, which uses Python\(aqs \fI\%zipfile\fP module to extract ZIP files. .IP 2. 3 \fI\%archive.cmd_unzip\fP, which uses the \fBunzip\fP CLI command to extract ZIP files. .UNINDENT .sp Salt will prefer the use of \fI\%archive.cmd_unzip\fP when CLI options are specified (via the \fBoptions\fP argument), and will otherwise prefer the \fI\%archive.unzip\fP function. Use of \fI\%archive.cmd_unzip\fP can be forced however by setting the \fBuse_cmd_unzip\fP argument to \fBTrue\fP\&. By contrast, setting this argument to \fBFalse\fP will force usage of \fI\%archive.unzip\fP\&. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /var/www: archive.extracted: \- source: salt://foo/bar/myapp.zip \- use_cmd_unzip: True .ft P .fi .UNINDENT .UNINDENT .sp When \fBuse_cmd_unzip\fP is omitted, Salt will choose which extraction function to use based on the source archive and the arguments passed to the state. When in doubt, simply do not set this argument; it is provided as a means of overriding the logic Salt uses to decide which function to use. .sp There are differences in the features available in both extraction functions. These are detailed below. .INDENT 0.0 .IP \(bu 2 \fICommand\-line options\fP (only supported by \fI\%archive.cmd_unzip\fP) \- When the \fBoptions\fP argument is used, \fI\%archive.cmd_unzip\fP is the only function that can be used to extract the archive. Therefore, if \fBuse_cmd_unzip\fP is specified and set to \fBFalse\fP, and \fBoptions\fP is also set, the state will not proceed. .IP \(bu 2 \fIPermissions\fP \- Due to an \fI\%upstream bug in Python\fP, permissions are not preserved when the \fI\%zipfile\fP module is used to extract an archive. As of the 2016.11.0 release, \fI\%archive.unzip\fP (as well as this state) has an \fBextract_perms\fP argument which, when set to \fBTrue\fP (the default), will attempt to match the permissions of the extracted files/directories to those defined within the archive. To disable this functionality and have the state not attempt to preserve the permissions from the ZIP archive, set \fBextract_perms\fP to \fBFalse\fP: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C /var/www: archive.extracted: \- source: salt://foo/bar/myapp.zip \- extract_perms: False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Directory into which the archive should be extracted .TP .B source Archive to be extracted .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument uses the same syntax as its counterpart in the \fI\%file.managed\fP state. .UNINDENT .UNINDENT .TP .B source_hash Hash of source file, or file with list of hash\-to\-file mappings .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument uses the same syntax as its counterpart in the \fI\%file.managed\fP state. .UNINDENT .UNINDENT .sp Changed in version 2016.11.0: If this argument specifies the hash itself, instead of a URI to a file containing hashes, the hash type can now be omitted and Salt will determine the hash type based on the length of the hash. For example, both of the below states are now valid, while before only the second one would be: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo_app: archive.extracted: \- name: /var/www \- source: https://mydomain.tld/foo.tar.gz \- source_hash: 3360db35e682f1c5f9c58aa307de16d41361618c bar_app: archive.extracted: \- name: /var/www \- source: https://mydomain.tld/bar.tar.gz \- source_hash: sha1=5edb7d584b82ddcbf76e311601f5d4442974aaa5 .ft P .fi .UNINDENT .UNINDENT .TP .B source_hash_name When \fBsource_hash\fP refers to a hash file, Salt will try to find the correct hash by matching the filename part of the \fBsource\fP URI. When managing a file with a \fBsource\fP of \fBsalt://files/foo.tar.gz\fP, then the following line in a hash file would match: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C acbd18db4cc2f85cedef654fccc4a4d8 foo.tar.gz .ft P .fi .UNINDENT .UNINDENT .sp This line would also match: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C acbd18db4cc2f85cedef654fccc4a4d8 ./dir1/foo.tar.gz .ft P .fi .UNINDENT .UNINDENT .sp However, sometimes a hash file will include multiple similar paths: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C 37b51d194a7513e45b56f6524f2d51f2 ./dir1/foo.txt acbd18db4cc2f85cedef654fccc4a4d8 ./dir2/foo.txt 73feffa4b7f6bb68e44cf984c85f6e88 ./dir3/foo.txt .ft P .fi .UNINDENT .UNINDENT .sp In cases like this, Salt may match the incorrect hash. This argument can be used to tell Salt which filename to match, to ensure that the correct hash is identified. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /var/www: archive.extracted: \- source: https://mydomain.tld/dir2/foo.tar.gz \- source_hash: https://mydomain.tld/hashes \- source_hash_name: ./dir2/foo.tar.gz .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument must contain the full filename entry from the checksum file, as this argument is meant to disambiguate matches for multiple files that have the same basename. So, in the example above, simply using \fBfoo.txt\fP would not match. .UNINDENT .UNINDENT .sp New in version 2016.11.0. .TP .B source_hash_update False Set this to \fBTrue\fP if archive should be extracted if source_hash has changed and there is a difference between the archive and the local files. This would extract regardless of the \fBif_missing\fP parameter. .sp Note that this is only checked if the \fBsource\fP value has not changed. If it has (e.g. to increment a version number in the path) then the archive will not be extracted even if the hash has changed. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Setting this to \fBTrue\fP along with \fBkeep_source\fP set to \fBFalse\fP will result the \fBsource\fP re\-download to do a archive file list check. If it\(aqs not desirable please consider the \fBskip_files_list_verify\fP argument. .UNINDENT .UNINDENT .sp New in version 2016.3.0. .TP .B skip_files_list_verify False Set this to \fBTrue\fP if archive should be extracted if \fBsource_hash\fP has changed but only checksums of the archive will be checked to determine if the extraction is required. .sp It will try to find a local cache of the \fBsource\fP and check its hash against the \fBsource_hash\fP\&. If there is no local cache available, for example if you set the \fBkeep_source\fP to \fBFalse\fP, it will try to find a cached source hash file in the Minion archives cache directory. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The current limitation of this logic is that you have to set minions \fBhash_type\fP config option to the same one that you\(aqre going to pass via \fBsource_hash\fP argument. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 With this argument set to \fBTrue\fP Salt will only check for the \fBsource_hash\fP against the local hash of the \fBsourse\fP\&. So if you, for example, remove extracted files without clearing the Salt Minion cache next time you execute the state Salt will not notice that extraction is required if the hashes are still match. .UNINDENT .UNINDENT .sp New in version 3000. .TP .B skip_verify False If \fBTrue\fP, hash verification of remote file sources (\fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP) will be skipped, and the \fBsource_hash\fP argument will be ignored. .sp New in version 2016.3.4. .TP .B keep_source True For \fBsource\fP archives not local to the minion (i.e. from the Salt fileserver or a remote source such as \fBhttp(s)\fP or \fBftp\fP), Salt will need to download the archive to the minion cache before they can be extracted. To remove the downloaded archive after extraction, set this argument to \fBFalse\fP\&. .sp New in version 2017.7.3. .TP .B keep True Same as \fBkeep_source\fP, kept for backward\-compatibility. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If both \fBkeep_source\fP and \fBkeep\fP are used, \fBkeep\fP will be ignored. .UNINDENT .UNINDENT .TP .B password \fBFor ZIP archives only.\fP Password used for extraction. .sp New in version 2016.3.0. .sp Changed in version 2016.11.0: The newly\-added \fI\%archive.is_encrypted\fP function will be used to determine if the archive is password\-protected. If it is, then the \fBpassword\fP argument will be required for the state to proceed. .TP .B options \fBFor tar and zip archives only.\fP This option can be used to specify a string of additional arguments to pass to the tar/zip command. .sp If this argument is not used, then the minion will attempt to use Python\(aqs native \fI\%tarfile\fP/\fI\%zipfile\fP support to extract it. For zip archives, this argument is mostly used to overwrite existing files with \fBo\fP\&. .sp Using this argument means that the \fBtar\fP or \fBunzip\fP command will be used, which is less platform\-independent, so keep this in mind when using this option; the CLI options must be valid options for the \fBtar\fP/\fBunzip\fP implementation on the minion\(aqs OS. .sp New in version 2016.11.0. .sp Changed in version 2015.8.11,2016.3.2: XZ\-compressed tar archives no longer require \fBJ\fP to manually be set in the \fBoptions\fP, they are now detected automatically and decompressed using the \fI\%xz\fP CLI command and extracted using \fBtar xvf\fP\&. This is a more platform\-independent solution, as not all tar implementations support the \fBJ\fP argument for extracting archives. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For tar archives, main operators like \fB\-x\fP, \fB\-\-extract\fP, \fB\-\-get\fP, \fB\-c\fP and \fB\-f\fP/\fB\-\-file\fP should \fInot\fP be used here. .UNINDENT .UNINDENT .TP .B list_options \fBFor tar archives only.\fP This state uses \fI\%archive.list\fP to discover the contents of the source archive so that it knows which file paths should exist on the minion if the archive has already been extracted. For the vast majority of tar archives, \fI\%archive.list\fP \(dqjust works\(dq. Archives compressed using gzip, bzip2, and xz/lzma (with the help of the \fI\%xz\fP CLI command) are supported automatically. However, for archives compressed using other compression types, CLI options must be passed to \fI\%archive.list\fP\&. .sp This argument will be passed through to \fI\%archive.list\fP as its \fBoptions\fP argument, to allow it to successfully list the archive\(aqs contents. For the vast majority of archives, this argument should not need to be used, it should only be needed in cases where the state fails with an error stating that the archive\(aqs contents could not be listed. .sp New in version 2016.11.0. .TP .B force False If a path that should be occupied by a file in the extracted result is instead a directory (or vice\-versa), the state will fail. Set this argument to \fBTrue\fP to force these paths to be removed in order to allow the archive to be extracted. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Use this option \fIvery\fP carefully. .UNINDENT .UNINDENT .sp New in version 2016.11.0. .TP .B overwrite False Set this to \fBTrue\fP to force the archive to be extracted. This is useful for cases where the filenames/directories have not changed, but the content of the files have. .sp New in version 2016.11.1. .TP .B clean False Set this to \fBTrue\fP to remove any top\-level files and recursively remove any top\-level directory paths before extracting. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Files will only be cleaned first if extracting the archive is deemed necessary, either by paths missing on the minion, or if \fBoverwrite\fP is set to \fBTrue\fP\&. .UNINDENT .UNINDENT .sp New in version 2016.11.1. .TP .B clean_parent False If \fBTrue\fP, and the archive is extracted, delete the parent directory (i.e. the directory into which the archive is extracted), and then re\-create that directory before extracting. Note that \fBclean\fP and \fBclean_parent\fP are mutually exclusive. .sp New in version 3000. .TP .B user The user to own each extracted file. Not available on Windows. .sp New in version 2015.8.0. .sp Changed in version 2016.3.0: When used in combination with \fBif_missing\fP, ownership will only be enforced if \fBif_missing\fP is a directory. .sp Changed in version 2016.11.0: Ownership will be enforced only on the file/directory paths found by running \fI\%archive.list\fP on the source archive. An alternative root directory on which to enforce ownership can be specified using the \fBenforce_ownership_on\fP argument. .TP .B group The group to own each extracted file. Not available on Windows. .sp New in version 2015.8.0. .sp Changed in version 2016.3.0: When used in combination with \fBif_missing\fP, ownership will only be enforced if \fBif_missing\fP is a directory. .sp Changed in version 2016.11.0: Ownership will be enforced only on the file/directory paths found by running \fI\%archive.list\fP on the source archive. An alternative root directory on which to enforce ownership can be specified using the \fBenforce_ownership_on\fP argument. .TP .B if_missing If specified, this path will be checked, and if it exists then the archive will not be extracted. This path can be either a directory or a file, so this option can also be used to check for a semaphore file and conditionally skip extraction. .sp Changed in version 2016.3.0: When used in combination with either \fBuser\fP or \fBgroup\fP, ownership will only be enforced when \fBif_missing\fP is a directory. .sp Changed in version 2016.11.0: Ownership enforcement is no longer tied to this argument, it is simply checked for existence and extraction will be skipped if if is present. .TP .B trim_output False Useful for archives with many files in them. This can either be set to \fBTrue\fP (in which case only the first 100 files extracted will be in the state results), or it can be set to an integer for more exact control over the max number of files to include in the state results. .sp New in version 2016.3.0. .TP .B use_cmd_unzip False Set to \fBTrue\fP for zip files to force usage of the \fI\%archive.cmd_unzip\fP function to extract. .sp New in version 2016.11.0. .TP .B extract_perms True \fBFor ZIP archives only.\fP When using \fI\%archive.unzip\fP to extract ZIP archives, Salt works around an \fI\%upstream bug in Python\fP to set the permissions on extracted files/directories to match those encoded into the ZIP archive. Set this argument to \fBFalse\fP to skip this workaround. .sp New in version 2016.11.0. .TP .B enforce_toplevel True This option will enforce a single directory at the top level of the source archive, to prevent extracting a \(aqtar\-bomb\(aq. Set this argument to \fBFalse\fP to allow archives with files (or multiple directories) at the top level to be extracted. .sp New in version 2016.11.0. .TP .B enforce_ownership_on When \fBuser\fP or \fBgroup\fP is specified, Salt will default to enforcing permissions on the file/directory paths detected by running \fI\%archive.list\fP on the source archive. Use this argument to specify an alternate directory on which ownership should be enforced. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This path must be within the path specified by the \fBname\fP argument. .UNINDENT .UNINDENT .sp New in version 2016.11.0. .TP .B archive_format One of \fBtar\fP, \fBzip\fP, or \fBrar\fP\&. .sp Changed in version 2016.11.0: If omitted, the archive format will be guessed based on the value of the \fBsource\fP argument. If the minion is running a release older than 2016.11.0, this option is required. .UNINDENT .INDENT 7.0 .TP .B use_etag If \fBTrue\fP, remote http/https file sources will attempt to use the ETag header to determine if the remote file needs to be downloaded. This provides a lightweight mechanism for promptly refreshing files changed on a web server without requiring a full hash comparison via the \fBsource_hash\fP parameter. .sp New in version 3005. .TP .B signature Ensure a valid GPG signature exists on the selected \fBsource\fP file. This needs to be a file URI retrievable by \fI:py:func:\(gacp.cache_file <salt.modules.cp.cache_file>\fP which identifies a detached signature. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A signature is only enforced directly after caching the file, before it is extracted to its final destination. Existing files at the target will never be modified. .sp It will be enforced regardless of source type. .UNINDENT .UNINDENT .sp New in version 3007.0. .TP .B source_hash_sig When \fBsource\fP is a remote file source, \fBsource_hash\fP is a file, \fBskip_verify\fP is not true and \fBuse_etag\fP is not true, ensure a valid GPG signature exists on the source hash file. Set this to \fBtrue\fP for an inline (clearsigned) signature, or to a file URI retrievable by \fI:py:func:\(gacp.cache_file <salt.modules.cp.cache_file>\fP for a detached one. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A signature on the \fBsource_hash\fP file is enforced regardless of changes since its contents are used to check if an existing file is in the correct state \- but only for remote sources! As for \fBsignature\fP, existing target files will not be modified, only the cached source_hash and source_hash_sig files will be removed. .UNINDENT .UNINDENT .sp New in version 3007.0. .TP .B signed_by_any When verifying signatures either on the managed file or its source hash file, require at least one valid signature from one of a list of key fingerprints. This is passed to \fI\%gpg.verify\fP\&. .sp New in version 3007.0. .TP .B signed_by_all When verifying signatures either on the managed file or its source hash file, require a valid signature from each of the key fingerprints in this list. This is passed to \fI\%gpg.verify\fP\&. .sp New in version 3007.0. .TP .B keyring When verifying signatures, use this keyring. .sp New in version 3007.0. .TP .B gnupghome When verifying signatures, use this GnuPG home. .sp New in version 3007.0. .UNINDENT .sp \fBExamples\fP .INDENT 7.0 .IP 1. 3 tar with lmza (i.e. xz) compression: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C graylog2\-server: archive.extracted: \- name: /opt/ \- source: https://github.com/downloads/Graylog2/graylog2\-server/graylog2\-server\-0.9.6p1.tar.lzma \- source_hash: md5=499ae16dcae71eeb7c3a30c75ea7a1a6 .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 tar archive with flag for verbose output, and enforcement of user/group ownership: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C graylog2\-server: archive.extracted: \- name: /opt/ \- source: https://github.com/downloads/Graylog2/graylog2\-server/graylog2\-server\-0.9.6p1.tar.gz \- source_hash: md5=499ae16dcae71eeb7c3a30c75ea7a1a6 \- options: v \- user: foo \- group: foo .ft P .fi .UNINDENT .UNINDENT .IP 3. 3 tar archive, with \fBsource_hash_update\fP set to \fBTrue\fP to prevent state from attempting extraction unless the \fBsource_hash\fP differs from the previous time the archive was extracted: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C graylog2\-server: archive.extracted: \- name: /opt/ \- source: https://github.com/downloads/Graylog2/graylog2\-server/graylog2\-server\-0.9.6p1.tar.lzma \- source_hash: md5=499ae16dcae71eeb7c3a30c75ea7a1a6 \- source_hash_update: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.states.artifactory .sp This state downloads artifacts from artifactory. .INDENT 0.0 .TP .B salt.states.artifactory.downloaded(name, artifact, target_dir=\(aq/tmp\(aq, target_file=None, use_literal_group_id=False) Ensures that the artifact from artifactory exists at given location. If it doesn\(aqt exist, then it will be downloaded. If it already exists then the checksum of existing file is checked against checksum in artifactory. If it is different then the step will fail. .INDENT 7.0 .TP .B artifact Details of the artifact to be downloaded from artifactory. Various options are: .INDENT 7.0 .IP \(bu 2 artifactory_url: URL of the artifactory instance .IP \(bu 2 repository: Repository in artifactory .IP \(bu 2 artifact_id: Artifact ID .IP \(bu 2 group_id: Group ID .IP \(bu 2 packaging: Packaging .IP \(bu 2 classifier: Classifier \&.. versionadded:: 2015.8.0 .IP \(bu 2 .INDENT 2.0 .TP .B version: Version One of the following: \- Version to download \- \fBlatest\fP \- Download the latest release of this artifact \- \fBlatest_snapshot\fP \- Download the latest snapshot for this artifact .UNINDENT .IP \(bu 2 username: Artifactory username \&.. versionadded:: 2015.8.0 .IP \(bu 2 password: Artifactory password \&.. versionadded:: 2015.8.0 .UNINDENT .TP .B target_dir Directory where the artifact should be downloaded. By default it is downloaded to /tmp directory. .TP .B target_file Target file to download artifact to. By default file name is resolved by artifactory. .UNINDENT .sp An example to download an artifact to a specific file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C jboss_module_downloaded: artifactory.downloaded: \- artifact: artifactory_url: http://artifactory.intranet.example.com/artifactory repository: \(aqlibs\-release\-local\(aq artifact_id: \(aqmodule\(aq group_id: \(aqcom.company.module\(aq packaging: \(aqjar\(aq classifier: \(aqsources\(aq version: \(aq1.0\(aq \- target_file: /opt/jboss7/modules/com/company/lib/module.jar .ft P .fi .UNINDENT .UNINDENT .sp Download artifact to the folder (automatically resolves file name): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C jboss_module_downloaded: artifactory.downloaded: \- artifact: artifactory_url: http://artifactory.intranet.example.com/artifactory repository: \(aqlibs\-release\-local\(aq artifact_id: \(aqmodule\(aq group_id: \(aqcom.company.module\(aq packaging: \(aqjar\(aq classifier: \(aqsources\(aq version: \(aq1.0\(aq \- target_dir: /opt/jboss7/modules/com/company/lib .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.at .SS Configuration disposable regularly scheduled tasks for at. .sp The at state can be add disposable regularly scheduled tasks for your system. .INDENT 0.0 .TP .B salt.states.at.absent(name, jobid=None, **kwargs) Changed in version 2017.7.0. .sp Remove a job from queue .INDENT 7.0 .TP .B jobid: string|int Specific jobid to remove .TP .B tag string Job\(aqs tag .TP .B runas string Runs user\-specified jobs .TP .B kwargs Addition kwargs can be provided to filter jobs. See output of \fIat.jobcheck\fP for more. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C example1: at.absent: .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 this will remove all jobs! .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C example2: at.absent: \- year: 13 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C example3: at.absent: \- tag: rose .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C example4: at.absent: \- tag: rose \- day: 13 \- hour: 16 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C example5: at.absent: \- jobid: 4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.at.mod_watch(name, **kwargs) The at watcher, called to invoke the watch command. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBwatch\fP \fI\%requisite\fP\&. It should not be called directly. .sp Parameters for this function should be set by the state being triggered. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the atjob .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.at.present(name, timespec, tag=None, user=None, job=None, unique_tag=False) Changed in version 2017.7.0. .sp Add a job to queue. .INDENT 7.0 .TP .B job string Command to run. .TP .B timespec string The \(aqtimespec\(aq follows the format documented in the at(1) manpage. .TP .B tag string Make a tag for the job. .TP .B user string The user to run the at job \&.. versionadded:: 2014.1.4 .TP .B unique_tag boolean If set to True job will not be added if a job with the tag exists. \&.. versionadded:: 2017.7.0 .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C rose: at.present: \- job: \(aqecho \(dqI love saltstack\(dq > love\(aq \- timespec: \(aq9:09 11/09/13\(aq \- tag: love \- user: jam .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.at.watch(name, timespec, tag=None, user=None, job=None, unique_tag=False) New in version 2017.7.0. .sp Add an at job if trigger by watch .INDENT 7.0 .TP .B job string Command to run. .TP .B timespec string The \(aqtimespec\(aq follows the format documented in the at(1) manpage. .TP .B tag string Make a tag for the job. .TP .B user string The user to run the at job \&.. versionadded:: 2014.1.4 .TP .B unique_tag boolean If set to True job will not be added if a job with the tag exists. \&.. versionadded:: 2017.7.0 .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C minion_restart: at.watch: \- job: \(aqsalt\-call \-\-local service.restart salt\-minion\(aq \- timespec: \(aqnow +1 min\(aq \- tag: minion_restart \- unique_tag: trye \- watch: \- file: /etc/salt/minion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.augeas .sp Configuration management using Augeas .sp New in version 0.17.0. .sp This state requires the \fBaugeas\fP Python module. .sp \fI\%Augeas\fP can be used to manage configuration files. .INDENT 0.0 .TP .B salt.states.augeas.change(name, context=None, changes=None, lens=None, load_path=None, **kwargs) New in version 2014.7.0. .sp This state replaces \fBsetvalue()\fP\&. .sp Issue changes to Augeas, optionally for a specific context, with a specific lens. .INDENT 7.0 .TP .B name State name .TP .B context A file path, prefixed by \fB/files\fP\&. Should resolve to an actual file (not an arbitrary augeas path). This is used to avoid duplicating the file name for each item in the changes list (for example, \fBset bind 0.0.0.0\fP in the example below operates on the file specified by \fBcontext\fP). If \fBcontext\fP is not specified, a file path prefixed by \fB/files\fP should be included with the \fBset\fP command. .sp The file path is examined to determine if the specified changes are already present. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C redis\-conf: augeas.change: \- context: /files/etc/redis/redis.conf \- changes: \- set bind 0.0.0.0 \- set maxmemory 1G .ft P .fi .UNINDENT .UNINDENT .TP .B changes List of changes that are issued to Augeas. Available commands are \fBset\fP, \fBsetm\fP, \fBmv\fP/\fBmove\fP, \fBins\fP/\fBinsert\fP, and \fBrm\fP/\fBremove\fP\&. .TP .B lens The lens to use, needs to be suffixed with \fI\&.lns\fP, e.g.: \fINginx.lns\fP\&. See the \fI\%list of stock lenses\fP shipped with Augeas. .UNINDENT .sp New in version 2016.3.0. .INDENT 7.0 .TP .B load_path A 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 .sp Usage examples: .sp Set the \fBbind\fP parameter in \fB/etc/redis/redis.conf\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C redis\-conf: augeas.change: \- changes: \- set /files/etc/redis/redis.conf/bind 0.0.0.0 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Use the \fBcontext\fP parameter to specify the file you want to manipulate. This way you don\(aqt have to include this in the changes every time: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C redis\-conf: augeas.change: \- context: /files/etc/redis/redis.conf \- changes: \- set bind 0.0.0.0 \- set databases 4 \- set maxmemory 1G .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Augeas is aware of a lot of common configuration files and their syntax. It knows the difference between for example ini and yaml files, but also files with very specific syntax, like the hosts file. This is done with \fIlenses\fP, which provide mappings between the Augeas tree and the file. .sp There are many \fI\%preconfigured lenses\fP that come with Augeas by default, and they specify the common locations for configuration files. So most of the time Augeas will know how to manipulate a file. In the event that you need to manipulate a file that Augeas doesn\(aqt know about, you can specify the lens to use like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C redis\-conf: augeas.change: \- lens: redis.lns \- context: /files/etc/redis/redis.conf \- changes: \- set bind 0.0.0.0 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Even though Augeas knows that \fB/etc/redis/redis.conf\fP is a Redis configuration file and knows how to parse it, it is recommended to specify the lens anyway. This is because by default, Augeas loads all known lenses and their associated file paths. All these files are parsed when Augeas is loaded, which can take some time. When specifying a lens, Augeas is loaded with only that lens, which speeds things up quite a bit. .UNINDENT .UNINDENT .sp A more complex example, this adds an entry to the services file for Zabbix, and removes an obsolete service: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C zabbix\-service: augeas.change: \- lens: services.lns \- context: /files/etc/services \- changes: \- ins service\-name after service\-name[last()] \- set service\-name[last()] \(dqzabbix\-agent\(dq \- set \(dqservice\-name[. = \(aqzabbix\-agent\(aq]/port\(dq 10050 \- set \(dqservice\-name[. = \(aqzabbix\-agent\(aq]/protocol\(dq tcp \- set \(dqservice\-name[. = \(aqzabbix\-agent\(aq]/#comment\(dq \(dqZabbix Agent service\(dq \- rm \(dqservice\-name[. = \(aqim\-obsolete\(aq]\(dq \- unless: grep \(aq^zabbix\-agent\es\(aq /etc/services .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Don\(aqt forget the \fBunless\fP here, otherwise it will fail on next runs because the service is already defined. Additionally you have to quote lines containing \fBservice\-name[. = \(aqzabbix\-agent\(aq]\fP otherwise \fI\%augeas_cfg\fP execute will fail because it will receive more parameters than expected. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Order is important when defining a service with Augeas, in this case it\(aqs \fBport\fP, \fBprotocol\fP and \fB#comment\fP\&. For more info about the lens check \fI\%services lens documentation\fP\&. .UNINDENT .UNINDENT .sp \fI\%http://augeas.net/docs/references/lenses/files/services\-aug.html#Services.record\fP .UNINDENT .SS salt.states.aws_sqs .sp Manage SQS Queues .sp Create and destroy SQS queues. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses the awscli tool provided by Amazon. This can be downloaded from pip. Also check the documentation for awscli for configuration information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myqueue: aws_sqs.exists: \- region: eu\-west\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.aws_sqs.absent(name, region, user=None, opts=False) Remove the named SQS queue if it exists. .INDENT 7.0 .TP .B name Name of the SQS queue. .TP .B region Region to remove the queue from .TP .B user Name of the user performing the SQS operations .TP .B opts Include additional arguments and options to the aws command line .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.aws_sqs.exists(name, region, user=None, opts=False) Ensure the SQS queue exists. .INDENT 7.0 .TP .B name Name of the SQS queue. .TP .B region Region to create the queue .TP .B user Name of the user performing the SQS operations .TP .B opts Include additional arguments and options to the aws command line .UNINDENT .UNINDENT .SS salt.states.beacon .SS Management of the Salt beacons .sp New in version 2015.8.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ps: beacon.present: \- save: True \- enable: False \- services: salt\-master: running apache2: stopped sh: beacon.present: [] load: beacon.present: \- averages: 1m: \- 0.0 \- 2.0 5m: \- 0.0 \- 1.5 15m: \- 0.1 \- 1.0 \&.. versionadded:: 3000 Beginning in the 3000 release, multiple copies of a beacon can be configured using the \(ga\(gabeacon_module\(ga\(ga parameter. inotify_infs: beacon.present: \- save: True \- enable: True \- files: /etc/infs.conf: mask: \- create \- delete \- modify recurse: True auto_add: True \- interval: 10 \- beacon_module: inotify \- disable_during_state_run: True inotify_ntp: beacon.present: \- save: True \- enable: True \- files: /etc/ntp.conf: mask: \- create \- delete \- modify recurse: True auto_add: True \- interval: 10 \- beacon_module: inotify \- disable_during_state_run: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.beacon.absent(name, save=False, **kwargs) Ensure beacon is absent. .INDENT 7.0 .TP .B name The name of the beacon that is ensured absent. .TP .B save True/False, if True the beacons.conf file be updated too. Default is False. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C remove_beacon: beacon.absent: \- name: ps \- save: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.beacon.disabled(name, **kwargs) Disable a beacon. .INDENT 7.0 .TP .B name The name of the beacon to disable. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C disable_beacon: beacon.disabled: \- name: psp .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.beacon.enabled(name, **kwargs) Enable a beacon. .INDENT 7.0 .TP .B name The name of the beacon to enable. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C enable_beacon: beacon.enabled: \- name: ps .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.beacon.present(name, save=False, **kwargs) Ensure beacon is configured with the included beacon data. .INDENT 7.0 .TP .B name The name of the beacon to ensure is configured. .TP .B save True/False, if True the beacons.conf file be updated too. Default is False. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ps_beacon: beacon.present: \- name: ps \- save: True \- enable: False \- services: salt\-master: running apache2: stopped .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.bigip .INDENT 0.0 .TP .B A state module designed to enforce load\-balancing configurations for F5 Big\-IP entities. .INDENT 7.0 .TP .B maturity develop .TP .B platform f5_bigip_11.6 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.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 member to add to the pool .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.create_monitor(hostname, username, password, monitor_type, name, **kwargs) A function to connect to a bigip device and create a monitor. .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 monitor_type The type of monitor to create .TP .B name The name of the monitor to create .TP .B kwargs [ arg=val ] ... .sp Consult F5 BIGIP user guide for specific options for each monitor type. Typically, tmsh arg names are used. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.create_node(hostname, username, password, name, address) Create a new node if it does not already exist. .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 node to create .TP .B address The address of the node .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.create_pool(hostname, username, password, name, members=None, allow_nat=None, allow_snat=None, description=None, gateway_failsafe_device=None, ignore_persisted_weight=None, ip_tos_to_client=None, ip_tos_to_server=None, link_qos_to_client=None, link_qos_to_server=None, load_balancing_mode=None, min_active_members=None, min_up_members=None, min_up_members_action=None, min_up_members_checking=None, monitor=None, profiles=None, queue_depth_limit=None, queue_on_connection_limit=None, queue_time_limit=None, reselect_tries=None, service_down_action=None, slow_ramp_time=None) Create a new node if it does not already exist. .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 create .TP .B members List of members to be added to the pool .TP .B allow_nat [yes | no] .TP .B allow_snat [yes | no] .TP .B description [string] .TP .B gateway_failsafe_device [string] .TP .B ignore_persisted_weight [enabled | disabled] .TP .B ip_tos_to_client [pass\-through | [integer]] .TP .B ip_tos_to_server [pass\-through | [integer]] .TP .B link_qos_to_client [pass\-through | [integer]] .TP .B link_qos_to_server [pass\-through | [integer]] .TP .B load_balancing_mode [dynamic\-ratio\-member | dynamic\-ratio\-node | fastest\-app\-response | fastest\-node | least\-connections\-members | least\-connections\-node | least\-sessions | observed\-member | observed\-node | predictive\-member | predictive\-node | ratio\-least\-connections\-member | ratio\-least\-connections\-node | ratio\-member | ratio\-node | ratio\-session | round\-robin | weighted\-least\-connections\-member | weighted\-least\-connections\-node] .TP .B min_active_members [integer] .TP .B min_up_members [integer] .TP .B min_up_members_action [failover | reboot | restart\-all] .TP .B min_up_members_checking [enabled | disabled] .TP .B monitor [name] .TP .B profiles [none | profile_name] .TP .B queue_depth_limit [integer] .TP .B queue_on_connection_limit [enabled | disabled] .TP .B queue_time_limit [integer] .TP .B reselect_tries [integer] .TP .B service_down_action [drop | none | reselect | reset] .TP .B slow_ramp_time [integer] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.create_profile(hostname, username, password, profile_type, name, **kwargs) A function to connect to a bigip device and create a profile. .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 profile_type The type of profile to create .TP .B name The name of the profile to create .TP .B kwargs [ arg=val ] ... .sp Consult F5 BIGIP user guide for specific options for each profile type. Typically, tmsh arg names are used. .UNINDENT .sp Special Characters \fB|\fP, \fB,\fP and \fB:\fP must be escaped using \fB\e\fP when used within strings. .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.create_virtual(hostname, username, password, name, destination, pool=None, address_status=None, auto_lasthop=None, bwc_policy=None, cmp_enabled=None, connection_limit=None, dhcp_relay=None, description=None, fallback_persistence=None, flow_eviction_policy=None, gtm_score=None, ip_forward=None, ip_protocol=None, internal=None, twelve_forward=None, last_hop_pool=None, mask=None, mirror=None, nat64=None, persist=None, profiles=None, policies=None, rate_class=None, rate_limit=None, rate_limit_mode=None, rate_limit_dst=None, rate_limit_src=None, rules=None, related_rules=None, reject=None, source=None, source_address_translation=None, source_port=None, virtual_state=None, traffic_classes=None, translate_address=None, translate_port=None, vlans=None) A function to connect to a bigip device and create a virtual server if it does not already exists. .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 virtual to create .TP .B destination [ [virtual_address_name:port] | [ipv4:port] | [ipv6.port] ] .TP .B pool [ [pool_name] | none] .TP .B address_status [yes | no] .TP .B auto_lasthop [default | enabled | disabled ] .TP .B bwc_policy [none] | string] .TP .B cmp_enabled [yes | no] .TP .B dhcp_relay [yes | no} .TP .B connection_limit [integer] .TP .B description [string] .TP .B state [disabled | enabled] .TP .B fallback_persistence [none | [profile name] ] .TP .B flow_eviction_policy [none | [eviction policy name] ] .TP .B gtm_score [integer] .TP .B ip_forward [yes | no] .TP .B ip_protocol [any | protocol] .TP .B internal [yes | no] .TP .B twelve_forward(12\-forward) [yes | no] .TP .B last_hop\-pool [ [pool_name] | none] .TP .B mask { [ipv4] | [ipv6] } .TP .B mirror { [disabled | enabled | none] } .TP .B nat64 [enabled | disabled] .TP .B persist [list] .TP .B profiles [none | default | list ] .TP .B policies [none | default | list ] .TP .B rate_class [name] .TP .B rate_limit [integer] .TP .B rate_limit\-mode [destination | object | object\-destination | object\-source | object\-source\-destination | source | source\-destination] .TP .B rate_limit\-dst [integer] .TP .B rate_limit\-src [integer] .TP .B rules [none | list ] .TP .B related_rules [none | list ] .TP .B reject [yes | no] .TP .B source { [ipv4[/prefixlen]] | [ipv6[/prefixlen]] } .TP .B source_address_translation [none | snat:pool_name | lsn | automap | dictionary ] .TP .B source_port [change | preserve | preserve\-strict] .TP .B state [enabled | disabled] .TP .B traffic_classes [none | default | list ] .TP .B translate_address [enabled | disabled] .TP .B translate_port [enabled | disabled] .TP .B vlans [none | default | dictionary] .INDENT 7.0 .TP .B vlan_ids [ list] .TP .B enabled [ true | false ] .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.delete_monitor(hostname, username, password, monitor_type, name) Modify an existing monitor. If it does exists, only the parameters specified will be enforced. .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 monitor_type The type of monitor to create .TP .B name The name of the monitor to create .TP .B kwargs [ arg=val ] ... .sp Consult F5 BIGIP user guide for specific options for each monitor type. Typically, tmsh arg names are used. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.delete_node(hostname, username, password, name) Delete an existing node. .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 node which will be deleted. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.delete_pool(hostname, username, password, name) Delete 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 which will be deleted .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.delete_pool_member(hostname, username, password, name, member) Delete an existing pool member. .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 be modified .TP .B member The name of the member to delete from the pool .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.delete_profile(hostname, username, password, profile_type, name) Modify an existing profile. If it does exists, only the parameters specified will be enforced. .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 profile_type The type of profile to create .TP .B name The name of the profile to create .TP .B kwargs [ arg=val ] ... .sp Consult F5 BIGIP user guide for specific options for each profile type. Typically, tmsh arg names are used. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.delete_virtual(hostname, username, password, name) Delete an existing virtual. .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 virtual which will be deleted .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.list_monitor(hostname, username, password, monitor_type, name) A function to list an existing monitor. .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 monitor_type The type of monitor to list .TP .B name The name of the monitor to list .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.list_node(hostname, username, password, name) A function to connect to a bigip device and list a specific node. .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 node to list. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.list_pool(hostname, username, password, name) A function to connect to a bigip device and list a specific 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 list. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.list_profile(hostname, username, password, profile_type, name) A function to list an existing profile. .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 profile_type The type of profile to list .TP .B name The name of the profile to list .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.list_virtual(hostname, username, password, name) A function to list a specific virtual. .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 virtual to list .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.manage_monitor(hostname, username, password, monitor_type, name, **kwargs) Create a new monitor if a monitor of this type and name does not already exists. If it does exists, only the parameters specified will be enforced. .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 monitor_type The type of monitor to create .TP .B name The name of the monitor to create .TP .B kwargs [ arg=val ] ... .sp Consult F5 BIGIP user guide for specific options for each monitor type. Typically, tmsh arg names are used. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.manage_node(hostname, username, password, name, address, connection_limit=None, description=None, dynamic_ratio=None, logging=None, monitor=None, rate_limit=None, ratio=None, session=None, node_state=None) Manages a node of a given bigip device. If the node does not exist it will be created, otherwise, only the properties which are different than the existing will be updated. .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 node to manage. .TP .B address The address of the node .TP .B connection_limit [integer] .TP .B description [string] .TP .B dynam c_ratio: [integer] .TP .B logging [enabled | disabled] .TP .B monitor [[name] | none | default] .TP .B rate_limit [integer] .TP .B ratio [integer] .TP .B session [user\-enabled | user\-disabled] .TP .B node_state (state) [user\-down | user\-up ] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.manage_pool(hostname, username, password, name, allow_nat=None, allow_snat=None, description=None, gateway_failsafe_device=None, ignore_persisted_weight=None, ip_tos_to_client=None, ip_tos_to_server=None, link_qos_to_client=None, link_qos_to_server=None, load_balancing_mode=None, min_active_members=None, min_up_members=None, min_up_members_action=None, min_up_members_checking=None, monitor=None, profiles=None, queue_depth_limit=None, queue_on_connection_limit=None, queue_time_limit=None, reselect_tries=None, service_down_action=None, slow_ramp_time=None) Create a new pool if it does not already exist. Pool members are managed separately. Only the parameters specified are enforced. .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 create .TP .B allow_nat [yes | no] .TP .B allow_snat [yes | no] .TP .B description [string] .TP .B gateway_failsafe_device [string] .TP .B ignore_persisted_weight [enabled | disabled] .TP .B ip_tos_to_client [pass\-through | [integer]] .TP .B ip_tos_to_server [pass\-through | [integer]] .TP .B link_qos_to_client [pass\-through | [integer]] .TP .B link_qos_to_server [pass\-through | [integer]] .TP .B load_balancing_mode [dynamic\-ratio\-member | dynamic\-ratio\-node | fastest\-app\-response | fastest\-node | least\-connections\-members | least\-connections\-node | least\-sessions | observed\-member | observed\-node | predictive\-member | predictive\-node | ratio\-least\-connections\-member | ratio\-least\-connections\-node | ratio\-member | ratio\-node | ratio\-session | round\-robin | weighted\-least\-connections\-member | weighted\-least\-connections\-node] .TP .B min_active_members [integer] .TP .B min_up_members [integer] .TP .B min_up_members_action [failover | reboot | restart\-all] .TP .B min_up_members_checking [enabled | disabled] .TP .B monitor [name] .TP .B profiles [none | profile_name] .TP .B queue_depth_limit [integer] .TP .B queue_on_connection_limit [enabled | disabled] .TP .B queue_time_limit [integer] .TP .B reselect_tries [integer] .TP .B service_down_action [drop | none | reselect | reset] .TP .B slow_ramp_time [integer] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.manage_pool_members(hostname, username, password, name, members) Manage the members of an existing pool. This function replaces all current pool members. Only the parameters specified are enforced. .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 members list of pool members to manage. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.manage_profile(hostname, username, password, profile_type, name, **kwargs) Create a new profile if a monitor of this type and name does not already exists. If it does exists, only the parameters specified will be enforced. .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 profile_type The type of profile to create .TP .B name The name of the profile to create .TP .B kwargs [ arg=val ] ... .sp Consult F5 BIGIP user guide for specific options for each profile type. Typically, tmsh arg names are used. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.manage_virtual(hostname, username, password, name, destination, pool=None, address_status=None, auto_lasthop=None, bwc_policy=None, cmp_enabled=None, connection_limit=None, dhcp_relay=None, description=None, fallback_persistence=None, flow_eviction_policy=None, gtm_score=None, ip_forward=None, ip_protocol=None, internal=None, twelve_forward=None, last_hop_pool=None, mask=None, mirror=None, nat64=None, persist=None, profiles=None, policies=None, rate_class=None, rate_limit=None, rate_limit_mode=None, rate_limit_dst=None, rate_limit_src=None, rules=None, related_rules=None, reject=None, source=None, source_address_translation=None, source_port=None, virtual_state=None, traffic_classes=None, translate_address=None, translate_port=None, vlans=None) Manage a virtual server. If a virtual does not exists it will be created, otherwise only the parameters specified will be enforced. .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 virtual to create .TP .B destination [ [virtual_address_name:port] | [ipv4:port] | [ipv6.port] ] .TP .B pool [ [pool_name] | none] .TP .B address_status [yes | no] .TP .B auto_lasthop [default | enabled | disabled ] .TP .B bwc_policy [none] | string] .TP .B cmp_enabled [yes | no] .TP .B dhcp_relay [yes | no} .TP .B connection_limit [integer] .TP .B description [string] .TP .B state [disabled | enabled] .TP .B fallback_persistence [none | [profile name] ] .TP .B flow_eviction_policy [none | [eviction policy name] ] .TP .B gtm_score [integer] .TP .B ip_forward [yes | no] .TP .B ip_protocol [any | protocol] .TP .B internal [yes | no] .TP .B twelve_forward(12\-forward) [yes | no] .TP .B last_hop\-pool [ [pool_name] | none] .TP .B mask { [ipv4] | [ipv6] } .TP .B mirror { [disabled | enabled | none] } .TP .B nat64 [enabled | disabled] .TP .B persist [list] .TP .B profiles [none | default | list ] .TP .B policies [none | default | list ] .TP .B rate_class [name] .TP .B rate_limit [integer] .TP .B rate_limit\-mode [destination | object | object\-destination | object\-source | object\-source\-destination | source | source\-destination] .TP .B rate_limit\-dst [integer] .TP .B rate_limit\-src [integer] .TP .B rules [none | list ] .TP .B related_rules [none | list ] .TP .B reject [yes | no] .TP .B source { [ipv4[/prefixlen]] | [ipv6[/prefixlen]] } .TP .B source_address_translation [none | snat:pool_name | lsn | automap | dictionary ] .TP .B source_port [change | preserve | preserve\-strict] .TP .B state [enabled | disabled] .TP .B traffic_classes [none | default | list ] .TP .B translate_address [enabled | disabled] .TP .B translate_port [enabled | disabled] .TP .B vlans [none | default | dictionary] .INDENT 7.0 .TP .B vlan_ids [ list] .TP .B enabled [ true | false ] .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.modify_monitor(hostname, username, password, monitor_type, name, **kwargs) Modify an existing monitor. If it does exists, only the parameters specified will be enforced. .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 monitor_type The type of monitor to create .TP .B name The name of the monitor to create .TP .B kwargs [ arg=val ] ... .sp Consult F5 BIGIP user guide for specific options for each monitor type. Typically, tmsh arg names are used. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.modify_node(hostname, username, password, name, connection_limit=None, description=None, dynamic_ratio=None, logging=None, monitor=None, rate_limit=None, ratio=None, session=None, node_state=None) Modify an existing node. Only a node which already exists will be modified and only the parameters specified will be enforced. .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 node to modify .TP .B connection_limit [integer] .TP .B description [string] .TP .B dynamic_ratio [integer] .TP .B logging [enabled | disabled] .TP .B monitor [[name] | none | default] .TP .B rate_limit [integer] .TP .B ratio [integer] .TP .B session [user\-enabled | user\-disabled] .TP .B node_state (state) [user\-down | user\-up ] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.modify_pool(hostname, username, password, name, allow_nat=None, allow_snat=None, description=None, gateway_failsafe_device=None, ignore_persisted_weight=None, ip_tos_to_client=None, ip_tos_to_server=None, link_qos_to_client=None, link_qos_to_server=None, load_balancing_mode=None, min_active_members=None, min_up_members=None, min_up_members_action=None, min_up_members_checking=None, monitor=None, profiles=None, queue_depth_limit=None, queue_on_connection_limit=None, queue_time_limit=None, reselect_tries=None, service_down_action=None, slow_ramp_time=None) Modify an existing pool. Pool members are managed separately. Only the parameters specified are enforced. .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 create .TP .B allow_nat [yes | no] .TP .B allow_snat [yes | no] .TP .B description [string] .TP .B gateway_failsafe_device [string] .TP .B ignore_persisted_weight [enabled | disabled] .TP .B ip_tos_to_client [pass\-through | [integer]] .TP .B ip_tos_to_server [pass\-through | [integer]] .TP .B link_qos_to_client [pass\-through | [integer]] .TP .B link_qos_to_server [pass\-through | [integer]] .TP .B load_balancing_mode [dynamic\-ratio\-member | dynamic\-ratio\-node | fastest\-app\-response | fastest\-node | least\-connections\-members | least\-connections\-node | least\-sessions | observed\-member | observed\-node | predictive\-member | predictive\-node | ratio\-least\-connections\-member | ratio\-least\-connections\-node | ratio\-member | ratio\-node | ratio\-session | round\-robin | weighted\-least\-connections\-member | weighted\-least\-connections\-node] .TP .B min_active_members [integer] .TP .B min_up_members [integer] .TP .B min_up_members_action [failover | reboot | restart\-all] .TP .B min_up_members_checking [enabled | disabled] .TP .B monitor [name] .TP .B profiles [none | profile_name] .TP .B queue_depth_limit [integer] .TP .B queue_on_connection_limit [enabled | disabled] .TP .B queue_time_limit [integer] .TP .B reselect_tries [integer] .TP .B service_down_action [drop | none | reselect | reset] .TP .B slow_ramp_time [integer] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.modify_pool_member(hostname, username, password, name, member, connection_limit=None, description=None, dynamic_ratio=None, inherit_profile=None, logging=None, monitor=None, priority_group=None, profiles=None, rate_limit=None, ratio=None, session=None, member_state=None) A function to connect to a bigip device and modify a member of 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 member modify .TP .B connection_limit [integer] .TP .B description [string] .TP .B dynamic_ratio [integer] .TP .B inherit_profile [enabled | disabled] .TP .B logging [enabled | disabled] .TP .B monitor [name] .TP .B priority_group [integer] .TP .B profiles [none | profile_name] .TP .B rate_limit [integer] .TP .B ratio [integer] .TP .B session [user\-enabled | user\-disabled] .TP .B member_state (state) [ user\-up | user\-down ] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.modify_profile(hostname, username, password, profile_type, name, **kwargs) Modify an existing profile. If it does exists, only the parameters specified will be enforced. .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 profile_type The type of profile to create .TP .B name The name of the profile to create .TP .B kwargs [ arg=val ] ... .sp Consult F5 BIGIP user guide for specific options for each monitor type. Typically, tmsh arg names are used. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bigip.modify_virtual(hostname, username, password, name, destination, pool=None, address_status=None, auto_lasthop=None, bwc_policy=None, cmp_enabled=None, connection_limit=None, dhcp_relay=None, description=None, fallback_persistence=None, flow_eviction_policy=None, gtm_score=None, ip_forward=None, ip_protocol=None, internal=None, twelve_forward=None, last_hop_pool=None, mask=None, mirror=None, nat64=None, persist=None, profiles=None, policies=None, rate_class=None, rate_limit=None, rate_limit_mode=None, rate_limit_dst=None, rate_limit_src=None, rules=None, related_rules=None, reject=None, source=None, source_address_translation=None, source_port=None, virtual_state=None, traffic_classes=None, translate_address=None, translate_port=None, vlans=None) Modify an virtual server. modify an existing virtual. Only parameters specified will be enforced. .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 virtual to create .TP .B destination [ [virtual_address_name:port] | [ipv4:port] | [ipv6.port] ] .TP .B pool [ [pool_name] | none] .TP .B address_status [yes | no] .TP .B auto_lasthop [default | enabled | disabled ] .TP .B bwc_policy [none] | string] .TP .B cmp_enabled [yes | no] .TP .B dhcp_relay [yes | no} .TP .B connection_limit [integer] .TP .B description [string] .TP .B state [disabled | enabled] .TP .B fallback_persistence [none | [profile name] ] .TP .B flow_eviction_policy [none | [eviction policy name] ] .TP .B gtm_score [integer] .TP .B ip_forward [yes | no] .TP .B ip_protocol [any | protocol] .TP .B internal [yes | no] .TP .B twelve_forward(12\-forward) [yes | no] .TP .B last_hop\-pool [ [pool_name] | none] .TP .B mask { [ipv4] | [ipv6] } .TP .B mirror { [disabled | enabled | none] } .TP .B nat64 [enabled | disabled] .TP .B persist [list] .TP .B profiles [none | default | list ] .TP .B policies [none | default | list ] .TP .B rate_class [name] .TP .B rate_limit [integer] .TP .B rate_limit\-mode [destination | object | object\-destination | object\-source | object\-source\-destination | source | source\-destination] .TP .B rate_limit_dst [integer] .TP .B rate_limit_src [integer] .TP .B rules [none | list ] .TP .B related_rules [none | list ] .TP .B reject [yes | no] .TP .B source { [ipv4[/prefixlen]] | [ipv6[/prefixlen]] } .TP .B source_address_translation [none | snat:pool_name | lsn | automap | dictionary ] .TP .B source_port [change | preserve | preserve\-strict] .TP .B state [enabled | disabled] .TP .B traffic_classes [none | default | list ] .TP .B translate_address [enabled | disabled] .TP .B translate_port [enabled | disabled] .TP .B vlans [none | default | dictionary ] .INDENT 7.0 .TP .B vlan_ids [ list] .TP .B enabled [ true | false ] .UNINDENT .UNINDENT .UNINDENT .SS salt.states.blockdev .sp Management of Block Devices .sp A state module to manage blockdevices .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /dev/sda: blockdev.tuned: \- read\-only: True master\-data: blockdev.tuned: \- name: /dev/vg/master\-data \- read\-only: True \- read\-ahead: 1024 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2014.7.0. .INDENT 0.0 .TP .B salt.states.blockdev.formatted(name, fs_type=\(aqext4\(aq, force=False, **kwargs) Manage filesystems of partitions. .INDENT 7.0 .TP .B name The name of the block device .TP .B fs_type The filesystem it should be formatted as .TP .B force Force mke2fs to create a filesystem, even if the specified device is not a partition on a block special device. This option is only enabled for ext and xfs filesystems .sp This option is dangerous, use it with caution. .sp New in version 2016.11.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.blockdev.tuned(name, **kwargs) Manage options of block device .INDENT 7.0 .TP .B name The name of the block device .TP .B opts: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B read\-ahead Read\-ahead buffer size .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B filesystem\-read\-ahead Filesystem Read\-ahead buffer size .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B read\-only Set Read\-Only .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B read\-write Set Read\-Write .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.states.boto3_elasticache .SS Manage Elasticache with boto3 .sp New in version 2017.7.0. .sp Create, destroy and update Elasticache clusters. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses boto3 behind the scenes \- as a result it inherits any limitations it boto3\(aqs implementation of the AWS API. It is also designed to as directly as possible leverage boto3\(aqs parameter naming and semantics. This allows one to use \fI\%http://boto3.readthedocs.io/en/latest/reference/services/elasticache.html\fP as an excellent source for details too involved to reiterate here. .sp Note: This module is designed to be transparent (\(dqintentionally ignorant\(dq is the phrase I used to describe it to my boss) to new AWS / boto options \- since all AWS API params are passed directly through both the state and executions modules, any new args to existing functions which become available after this documentation is written should work immediately. .sp Brand new API calls, of course, would still require new functions to be added :) .sp This module accepts explicit elasticache credentials but 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 is available \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C elasticache.keyid: GKTADJGHEIQSXMKKRBJ08H elasticache.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure myelasticache exists: boto3_elasticache.present: \- name: myelasticache \- engine: redis \- cache_node_type: cache.t1.micro \- num_cache_nodes: 1 \- notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Using a profile from pillars Ensure myelasticache exists: boto3_elasticache.present: \- name: myelasticache \- engine: redis \- cache_node_type: cache.t1.micro \- num_cache_nodes: 1 \- notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic \- region: us\-east\-1 \- profile: myprofile .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Passing in a profile Ensure myelasticache exists: boto3_elasticache.present: \- name: myelasticache \- engine: redis \- cache_node_type: cache.t1.micro \- num_cache_nodes: 1 \- notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic \- region: us\-east\-1 \- profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_elasticache.cache_cluster_absent(name, wait=600, region=None, key=None, keyid=None, profile=None, **args) Ensure a given cache cluster is deleted. .INDENT 7.0 .TP .B name Name of the cache cluster. .TP .B wait Integer describing how long, in seconds, to wait for confirmation from AWS that the resource is in the desired state. Zero meaning to return success or failure immediately of course. Note that waiting for the cluster to become available is generally the better course, as failure to do so will often lead to subsequent failures when managing dependent resources. .TP .B CacheClusterId The node group (shard) identifier. Note: In general this parameter is not needed, as \(aqname\(aq is used if it\(aqs not provided. .TP .B FinalSnapshotIdentifier The user\-supplied name of a final cache cluster snapshot. This is the unique name that identifies the snapshot. ElastiCache creates the snapshot, and then deletes the cache cluster immediately afterward. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_elasticache.cache_cluster_present(name, wait=900, security_groups=None, region=None, key=None, keyid=None, profile=None, **args) Ensure a given cache cluster exists. .INDENT 7.0 .TP .B name Name of the cache cluster (cache cluster id). .TP .B wait Integer describing how long, in seconds, to wait for confirmation from AWS that the resource is in the desired state. Zero meaning to return success or failure immediately of course. Note that waiting for the cluster to become available is generally the better course, as failure to do so will often lead to subsequent failures when managing dependent resources. .TP .B security_groups One or more VPC security groups (names and/or IDs) associated with the cache cluster. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is additive with any sec groups provided via the SecurityGroupIds parameter below. Use this parameter ONLY when you are creating a cluster in a VPC. .UNINDENT .UNINDENT .TP .B CacheClusterId The node group (shard) identifier. This parameter is stored as a lowercase string. .sp Constraints: .INDENT 7.0 .IP \(bu 2 A name must contain from 1 to 20 alphanumeric characters or hyphens. .IP \(bu 2 The first character must be a letter. .IP \(bu 2 A name cannot end with a hyphen or contain two consecutive hyphens. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 In general this parameter is not needed, as \(aqname\(aq is used if it\(aqs not provided. .UNINDENT .UNINDENT .TP .B ReplicationGroupId The ID of the replication group to which this cache cluster should belong. If this parameter is specified, the cache cluster is added to the specified replication group as a read replica; otherwise, the cache cluster is a standalone primary that is not part of any replication group. If the specified replication group is Multi\-AZ enabled and the Availability Zone is not specified, the cache cluster is created in Availability Zones that provide the best spread of read replicas across Availability Zones. .TP .B AZMode Specifies whether the nodes in this Memcached cluster are created in a single Availability Zone or created across multiple Availability Zones in the cluster\(aqs region. If the AZMode and PreferredAvailabilityZones are not specified, ElastiCache assumes single\-az mode. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This parameter is ONLY supported for Memcached cache clusters. .UNINDENT .UNINDENT .TP .B PreferredAvailabilityZone The EC2 Availability Zone in which the cache cluster is created. All nodes belonging to this Memcached cache cluster are placed in the preferred Availability Zone. If you want to create your nodes across multiple Availability Zones, use PreferredAvailabilityZones. .sp Default: System chosen Availability Zone. .TP .B PreferredAvailabilityZones A list of the Availability Zones in which cache nodes are created. The order of the zones in the list is not important. The number of Availability Zones listed must equal the value of NumCacheNodes. If you want all the nodes in the same Availability Zone, use PreferredAvailabilityZone instead, or repeat the Availability Zone multiple times in the list. .sp Default: System chosen Availability Zones. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is ONLY supported on Memcached. .sp If you are creating your cache cluster in an Amazon VPC (recommended) you can only locate nodes in Availability Zones that are associated with the subnets in the selected subnet group. .UNINDENT .UNINDENT .TP .B NumCacheNodes The initial (integer) number of cache nodes that the cache cluster has. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For clusters running Redis, this value must be 1. .sp For clusters running Memcached, this value must be between 1 and 20. .UNINDENT .UNINDENT .TP .B CacheNodeType The compute and memory capacity of the nodes in the node group (shard). Valid node types (and pricing for them) are exhaustively described at \fI\%https://aws.amazon.com/elasticache/pricing/\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 All T2 instances must be created in a VPC .UNINDENT .UNINDENT .sp Redis backup/restore is not supported for Redis (cluster mode disabled) T1 and T2 instances. Backup/restore is supported on Redis (cluster mode enabled) T2 instances. .sp Redis Append\-only files (AOF) functionality is not supported for T1 or T2 instances. .UNINDENT .UNINDENT .TP .B Engine The name of the cache engine to be used for this cache cluster. Valid values for this parameter are: memcached | redis .TP .B EngineVersion The version number of the cache engine to be used for this cache cluster. To view the supported cache engine versions, use the DescribeCacheEngineVersions operation. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 You can upgrade to a newer engine version but you cannot downgrade to an earlier engine version. If you want to use an earlier engine version, you must delete the existing cache cluster or replication group and create it anew with the earlier engine version. .UNINDENT .UNINDENT .TP .B CacheParameterGroupName The name of the parameter group to associate with this cache cluster. If this argument is omitted, the default parameter group for the specified engine is used. You cannot use any parameter group which has cluster\-enabled=\(aqyes\(aq when creating a cluster. .TP .B CacheSubnetGroupName The name of the Cache Subnet Group to be used for the cache cluster. Use this parameter ONLY when you are creating a cache cluster within a VPC. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you\(aqre going to launch your cluster in an Amazon VPC, you need to create a subnet group before you start creating a cluster. .UNINDENT .UNINDENT .TP .B CacheSecurityGroupNames A list of Cache Security Group names to associate with this cache cluster. Use this parameter ONLY when you are creating a cache cluster outside of a VPC. .TP .B SecurityGroupIds One or more VPC security groups associated with the cache cluster. Use this parameter ONLY when you are creating a cache cluster within a VPC. .TP .B Tags A list of tags to be added to this resource. Note that due to shortcomings in the AWS API for Elasticache, these can only be set during resource creation \- later modification is not (currently) supported. .TP .B SnapshotArns A single\-element string list containing an Amazon Resource Name (ARN) that uniquely identifies a Redis RDB snapshot file stored in Amazon S3. The snapshot file is used to populate the node group (shard). The Amazon S3 object name in the ARN cannot contain any commas. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This parameter is ONLY valid if the Engine parameter is redis. .UNINDENT .UNINDENT .TP .B SnapshotName The name of a Redis snapshot from which to restore data into the new node group (shard). The snapshot status changes to restoring while the new node group (shard) is being created. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This parameter is ONLY valid if the Engine parameter is redis. .UNINDENT .UNINDENT .TP .B PreferredMaintenanceWindow Specifies the weekly time range during which maintenance on the cache cluster is permitted. It is specified as a range in the format ddd:hh24:mi\-ddd:hh24:mi (24H Clock UTC). The minimum maintenance window is a 60 minute period. Valid values for ddd are: sun, mon, tue, wed, thu, fri, sat .sp Example: sun:23:00\-mon:01:30 .TP .B Port The port number on which each of the cache nodes accepts connections. .sp Default: 6379 .TP .B NotificationTopicArn The Amazon Resource Name (ARN) of the Amazon Simple Notification Service (SNS) topic to which notifications are sent. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The Amazon SNS topic owner must be the same as the cache cluster owner. .UNINDENT .UNINDENT .TP .B AutoMinorVersionUpgrade This (boolean) parameter is currently disabled. .TP .B SnapshotRetentionLimit The number of days for which ElastiCache retains automatic snapshots before deleting them. .sp Default: 0 (i.e., automatic backups are disabled for this cache cluster). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This parameter is ONLY valid if the Engine parameter is redis. .UNINDENT .UNINDENT .TP .B SnapshotWindow The daily time range (in UTC) during which ElastiCache begins taking a daily snapshot of your node group (shard). If you do not specify this parameter, ElastiCache automatically chooses an appropriate time range. .sp Example: 05:00\-09:00 .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This parameter is ONLY valid if the Engine parameter is redis. .UNINDENT .UNINDENT .TP .B AuthToken The password used to access a password protected server. .sp Password constraints: .INDENT 7.0 .IP \(bu 2 Must be only printable ASCII characters. .IP \(bu 2 Must be at least 16 characters and no more than 128 characters in length. .IP \(bu 2 Cannot contain any of the following characters: \(aq/\(aq, \(aq\(dq\(aq, or \(dq@\(dq. .UNINDENT .TP .B CacheNodeIdsToRemove A list of cache node IDs to be removed. A node ID is a numeric identifier (0001, 0002, etc.). This parameter is only valid when NumCacheNodes is less than the existing number of cache nodes. The number of cache node IDs supplied in this parameter must match the difference between the existing number of cache nodes in the cluster or pending cache nodes, whichever is greater, and the value of NumCacheNodes in the request. .TP .B NewAvailabilityZones The list of Availability Zones where the new Memcached cache nodes are created. This parameter is only valid when NumCacheNodes in the request is greater than the sum of the number of active cache nodes and the number of cache nodes pending creation (which may be zero). The number of Availability Zones supplied in this list must match the cache nodes being added in this request. Note: This option is only supported on Memcached clusters. .TP .B NotificationTopicStatus The status of the SNS notification topic. Notifications are sent only if the status is active. .sp Valid values: active | inactive .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_elasticache.cache_subnet_group_absent(name, region=None, key=None, keyid=None, profile=None, **args) Ensure a given cache subnet group is deleted. .INDENT 7.0 .TP .B name Name of the cache subnet group. .TP .B CacheSubnetGroupName A name for the cache subnet group. Note: In general this parameter is not needed, as \(aqname\(aq is used if it\(aqs not provided. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_elasticache.cache_subnet_group_present(name, subnets=None, region=None, key=None, keyid=None, profile=None, **args) Ensure cache subnet group exists. .INDENT 7.0 .TP .B name A name for the cache subnet group. This value is stored as a lowercase string. Constraints: Must contain no more than 255 alphanumeric characters or hyphens. .TP .B subnets A list of VPC subnets (IDs, Names, or a mix) for the cache subnet group. .TP .B CacheSubnetGroupName A name for the cache subnet group. This value is stored as a lowercase string. Constraints: Must contain no more than 255 alphanumeric characters or hyphens. Note: In general this parameter is not needed, as \(aqname\(aq is used if it\(aqs not provided. .TP .B CacheSubnetGroupDescription A description for the cache subnet group. .TP .B SubnetIds A list of VPC subnet IDs for the cache subnet group. This is ADDITIVE with \(aqsubnets\(aq above. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_elasticache.replication_group_absent(name, wait=600, region=None, key=None, keyid=None, profile=None, **args) Ensure a given replication group is deleted. .INDENT 7.0 .TP .B name Name of the replication group. .TP .B wait Integer describing how long, in seconds, to wait for confirmation from AWS that the resource is in the desired state. Zero meaning to return success or failure immediately of course. Note that waiting for the cluster to become available is generally the better course, as failure to do so will often lead to subsequent failures when managing dependent resources. .TP .B ReplicationGroupId The replication group identifier. Note: In general this parameter is not needed, as \(aqname\(aq is used if it\(aqs not provided. .TP .B RetainPrimaryCluster If set to true, all of the read replicas are deleted, but the primary node is retained. .TP .B FinalSnapshotIdentifier The name of a final node group (shard) snapshot. ElastiCache creates the snapshot from the primary node in the cluster, rather than one of the replicas; this is to ensure that it captures the freshest data. After the final snapshot is taken, the replication group is immediately deleted. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_elasticache.replication_group_present(name, wait=900, security_groups=None, region=None, key=None, keyid=None, profile=None, **args) Ensure a replication group exists and is in the given state. .INDENT 7.0 .TP .B name Name of replication group .TP .B wait Integer describing how long, in seconds, to wait for confirmation from AWS that the resource is in the desired state. Zero meaning to return success or failure immediately of course. Note that waiting for the cluster to become available is generally the better course, as failure to do so will often lead to subsequent failures when managing dependent resources. .TP .B security_groups One or more VPC security groups (names and/or IDs) associated with the cache cluster. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is additive with any sec groups provided via the SecurityGroupIds parameter below. Use this parameter ONLY when you are creating a cluster in a VPC. .UNINDENT .UNINDENT .TP .B ReplicationGroupId The replication group identifier. This parameter is stored as a lowercase string. .sp Constraints: .INDENT 7.0 .IP \(bu 2 A name must contain from 1 to 20 alphanumeric characters or hyphens. .IP \(bu 2 The first character must be a letter. .IP \(bu 2 A name cannot end with a hyphen or contain two consecutive hyphens. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 In general this parameter is not needed, as \(aqname\(aq is used if it\(aqs not provided. .UNINDENT .UNINDENT .TP .B ReplicationGroupDescription A user\-created description for the replication group. .TP .B PrimaryClusterId The identifier of the cache cluster that serves as the primary for this replication group. This cache cluster must already exist and have a status of available. This parameter is not required if NumCacheClusters, NumNodeGroups, or ReplicasPerNodeGroup is specified. .TP .B AutomaticFailoverEnabled Specifies whether a read\-only replica is automatically promoted to read/write primary if the existing primary fails. If true, Multi\-AZ is enabled for this replication group. If false, Multi\-AZ is disabled for this replication group. .sp Default: False .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 AutomaticFailoverEnabled must be enabled for Redis (cluster mode enabled) replication groups. .sp ElastiCache Multi\-AZ replication groups is not supported on: .INDENT 0.0 .IP \(bu 2 Redis versions earlier than 2.8.6. .IP \(bu 2 Redis (cluster mode disabled): T1 and T2 node types. .IP \(bu 2 Redis (cluster mode enabled): T2 node types. .UNINDENT .UNINDENT .UNINDENT .TP .B NumCacheClusters The number of clusters this replication group initially has. This parameter is not used if there is more than one node group (shard). You should use ReplicasPerNodeGroup instead. If Multi\-AZ is enabled , the value of this parameter must be at least 2. The maximum permitted value for NumCacheClusters is 6 (primary plus 5 replicas). .TP .B PreferredCacheClusterAZs A list of EC2 Availability Zones in which the replication group\(aqs cache clusters are created. The order of the Availability Zones in the list is the order in which clusters are allocated. The primary cluster is created in the first AZ in the list. This parameter is not used if there is more than one node group (shard). You should use NodeGroupConfiguration instead. The number of Availability Zones listed must equal the value of NumCacheClusters. .sp Default: System chosen Availability Zones. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you are creating your replication group in an Amazon VPC (recommended), you can only locate cache clusters in Availability Zones associated with the subnets in the selected subnet group. .UNINDENT .UNINDENT .TP .B NumNodeGroups An optional parameter that specifies the number of node groups (shards) for this Redis (cluster mode enabled) replication group. For Redis (cluster mode disabled) either omit this parameter or set it to 1. .sp Default: 1 .TP .B ReplicasPerNodeGroup An optional parameter that specifies the number of replica nodes in each node group (shard). Valid values are: 0 to 5 .TP .B NodeGroupConfiguration A list of node group (shard) configuration options. Each node group (shard) configuration has the following: Slots, PrimaryAvailabilityZone, ReplicaAvailabilityZones, ReplicaCount. If you\(aqre creating a Redis (cluster mode disabled) or a Redis (cluster mode enabled) replication group, you can use this parameter to configure one node group (shard) or you can omit this parameter. For fiddly details of the expected data layout of this param, see \fI\%http://boto3.readthedocs.io/en/latest/reference/services/elasticache.html\fP?#ElastiCache.Client.create_replication_group .TP .B CacheNodeType The compute and memory capacity of the nodes in the node group (shard). See \fI\%https://aws.amazon.com/elasticache/pricing/\fP for current sizing, prices, and constraints. .TP .B Engine The name of the cache engine to be used for the cache clusters in this replication group. .TP .B EngineVersion The version number of the cache engine to be used for the cache clusters in this replication group. To view the supported cache engine versions, use the DescribeCacheEngineVersions operation. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 You can upgrade to a newer engine version but you cannot downgrade to an earlier engine version. If you want to use an earlier engine version, you must delete the existing cache cluster or replication group and create it anew with the earlier engine version. .UNINDENT .UNINDENT .TP .B CacheParameterGroupName The name of the parameter group to associate with this replication group. If this argument is omitted, the default cache parameter group for the specified engine is used. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you are running Redis version 3.2.4 or later, only one node group (shard), and want to use a default parameter group, we recommend that you specify the parameter group by name. .sp To create a Redis (cluster mode disabled) replication group, use CacheParameterGroupName=default.redis3.2 .sp To create a Redis (cluster mode enabled) replication group, use CacheParameterGroupName=default.redis3.2.cluster.on .UNINDENT .UNINDENT .TP .B CacheSubnetGroupName The name of the cache subnet group to be used for the replication group. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you\(aqre going to launch your cluster in an Amazon VPC, you need to create a s group before you start creating a cluster. For more information, see Subnets and Subnet Groups. .UNINDENT .UNINDENT .TP .B CacheSecurityGroupNames A list of cache security group names to associate with this replication group. .TP .B SecurityGroupIds One or more Amazon VPC security groups associated with this replication group. Use this parameter only when you are creating a replication group in an VPC. .TP .B Tags A list of tags to be added to this resource. Note that due to shortcomings in the AWS API for Elasticache, these can only be set during resource creation \- later modification is not (currently) supported. .TP .B SnapshotArns A list of ARNs that uniquely identify the Redis RDB snapshot files stored in Amazon S3. These snapshot files are used to populate the replication group. The Amazon S3 object name in the ARN cannot contain any commas. The list must match the number of node groups (shards) in the replication group, which means you cannot repartition. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This parameter is only valid if the Engine parameter is redis. .UNINDENT .UNINDENT .TP .B SnapshotName The name of a snapshot from which to restore data into the new replication group. The snapshot status changes to restoring while the new replication group is being created. Note: This parameter is only valid if the Engine parameter is redis. .TP .B PreferredMaintenanceWindow Specifies the weekly time range during which maintenance on the cluster is performed. It is specified as a range in the format ddd:hh24:mi\-ddd:hh24:mi (24H Clock UTC). The minimum maintenance window is a 60 minute period. Valid values for ddd are: sun, mon, tue, wed, thu, fri, sat .sp Example: sun:23:00\-mon:01:30 .TP .B Port The port number on which each member of the replication group accepts connections. .TP .B NotificationTopicArn The ARN of an SNS topic to which notifications are sent. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The SNS topic owner must be the same as the cache cluster owner. .UNINDENT .UNINDENT .TP .B AutoMinorVersionUpgrade This parameter is currently disabled. .TP .B SnapshotRetentionLimit The number of days for which ElastiCache will retain automatic snapshots before deleting them. .sp Default: 0 (that is, automatic backups are disabled for this cache cluster). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This parameter is only valid if the Engine parameter is redis. .UNINDENT .UNINDENT .TP .B SnapshotWindow The daily time range (in UTC) during which ElastiCache begins taking a daily snapshot of your node group (shard). If you do not specify this parameter, ElastiCache automatically chooses an appropriate time range. .sp Example: 05:00\-09:00 .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This parameter is only valid if the Engine parameter is redis. .UNINDENT .UNINDENT .TP .B AuthToken The password used to access a password protected server. Password constraints: .INDENT 7.0 .IP \(bu 2 Must be only printable ASCII characters. .IP \(bu 2 Must be at least 16 characters and no more than 128 characters in length. .IP \(bu 2 Cannot contain any of the following characters: \(aq/\(aq, \(aq\(dq\(aq, or \(dq@\(dq. .UNINDENT .TP .B SnapshottingClusterId The cache cluster ID that is used as the daily snapshot source for the replication group. .TP .B NotificationTopicStatus The status of the SNS notification topic. Notifications are sent only if the status is active. Valid values: active | inactive .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto3_elasticsearch .SS Manage Elasticsearch Service .sp New in version 3001. .INDENT 0.0 .TP .B configuration This module accepts explicit AWS credentials but can also utilize IAM roles assigned to the instance trough Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at: .INDENT 7.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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C es.keyid: GKTADJGHEIQSXMKKRBJ08H es.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C es.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, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .TP .B codeauthor Herbert Buurman <\fI\%herbert.buurman@ogd.nl\fP> .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_elasticsearch.absent(name, blocking=True, region=None, keyid=None, key=None, profile=None) Ensure the Elasticsearch Domain specified does not exist. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the Elasticsearch domain to be made absent. .IP \(bu 2 \fBblocking\fP (\fI\%bool\fP) \-\- Whether or not the state should wait for the deletion to be completed. Default: \fBTrue\fP .UNINDENT .UNINDENT .sp New in version 3001. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Remove Elasticsearch Domain: boto3_elasticsearch.absent: \- name: my_domain \- region: eu\-west\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_elasticsearch.latest(name, minor_only=True, region=None, keyid=None, key=None, profile=None) Ensures the Elasticsearch domain specifies runs on the latest compatible version of elasticsearch, upgrading it if it is not. .sp Note that this operation is blocking until the upgrade is complete. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the Elasticsearch domain to upgrade. .IP \(bu 2 \fBminor_only\fP (\fI\%bool\fP) \-\- Only upgrade to the latest minor version. .UNINDENT .UNINDENT .sp New in version 3001. .sp Example: .sp The following example will ensure the elasticsearch domain \fBmy_domain\fP is upgraded to the latest minor version. So if it is currently 5.1 it will be upgraded to 5.6. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Upgrade Elasticsearch Domain: boto3_elasticsearch.latest: \- name: my_domain \- minor_only: True \- region: eu\-west\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_elasticsearch.present(name, elasticsearch_version=None, elasticsearch_cluster_config=None, ebs_options=None, access_policies=None, snapshot_options=None, vpc_options=None, cognito_options=None, encryption_at_rest_options=None, node_to_node_encryption_options=None, advanced_options=None, log_publishing_options=None, blocking=True, tags=None, region=None, keyid=None, key=None, profile=None) Ensure an Elasticsearch Domain exists. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the Elasticsearch domain that you are creating. Domain names are unique across the domains owned by an account within an AWS region. Domain names must start with a letter or number and can contain the following characters: a\-z (lowercase), 0\-9, and \- (hyphen). .IP \(bu 2 \fBelasticsearch_version\fP (\fI\%str\fP) \-\- String of format X.Y to specify version for the Elasticsearch domain eg. \(dq1.5\(dq or \(dq2.3\(dq. .IP \(bu 2 \fBelasticsearch_cluster_config\fP (\fI\%dict\fP) \-\- .sp Dict specifying the configuration options for an Elasticsearch domain. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 InstanceType (str): The instance type for an Elasticsearch cluster. .IP \(bu 2 InstanceCount (int): The instance type for an Elasticsearch cluster. .IP \(bu 2 DedicatedMasterEnabled (bool): Indicate whether a dedicated master node is enabled. .IP \(bu 2 ZoneAwarenessEnabled (bool): Indicate whether zone awareness is enabled. .IP \(bu 2 ZoneAwarenessConfig (dict): Specifies the zone awareness configuration for a domain when zone awareness is enabled. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 AvailabilityZoneCount (int): An integer value to indicate the number of availability zones for a domain when zone awareness is enabled. This should be equal to number of subnets if VPC endpoints is enabled. .UNINDENT .IP \(bu 2 DedicatedMasterType (str): The instance type for a dedicated master node. .IP \(bu 2 DedicatedMasterCount (int): Total number of dedicated master nodes, active and on standby, for the cluster. .UNINDENT .IP \(bu 2 \fBebs_options\fP (\fI\%dict\fP) \-\- .sp Dict specifying the options to enable or disable and specifying the type and size of EBS storage volumes. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 EBSEnabled (bool): Specifies whether EBS\-based storage is enabled. .IP \(bu 2 VolumeType (str): Specifies the volume type for EBS\-based storage. .IP \(bu 2 VolumeSize (int): Integer to specify the size of an EBS volume. .IP \(bu 2 Iops (int): Specifies the IOPD for a Provisioned IOPS EBS volume (SSD). .UNINDENT .IP \(bu 2 \fBaccess_policies\fP (\fI\%str\fP\fI or \fP\fI\%dict\fP) \-\- Dict or JSON string with the IAM access policy. .IP \(bu 2 \fBsnapshot_options\fP (\fI\%dict\fP) \-\- .sp Dict specifying the snapshot options. Keys (case senstive) in here are: .INDENT 2.0 .IP \(bu 2 AutomatedSnapshotStartHour (int): Specifies the time, in UTC format, when the service takes a daily automated snapshot of the specified Elasticsearch domain. Default value is 0 hours. .UNINDENT .IP \(bu 2 \fBvpc_options\fP (\fI\%dict\fP) \-\- .sp Dict with the options to specify the subnets and security groups for the VPC endpoint. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 SubnetIds (list): The list of subnets for the VPC endpoint. .IP \(bu 2 SecurityGroupIds (list): The list of security groups for the VPC endpoint. .UNINDENT .IP \(bu 2 \fBcognito_options\fP (\fI\%dict\fP) \-\- .sp Dict with options to specify the cognito user and identity pools for Kibana authentication. Keys (case senstive) in here are: .INDENT 2.0 .IP \(bu 2 Enabled (bool): Specifies the option to enable Cognito for Kibana authentication. .IP \(bu 2 UserPoolId (str): Specifies the Cognito user pool ID for Kibana authentication. .IP \(bu 2 IdentityPoolId (str): Specifies the Cognito identity pool ID for Kibana authentication. .IP \(bu 2 RoleArn (str): Specifies the role ARN that provides Elasticsearch permissions for accessing Cognito resources. .UNINDENT .IP \(bu 2 \fBencryption_at_rest_options\fP (\fI\%dict\fP) \-\- .sp Dict specifying the encryption at rest options. This option can only be used for the creation of a new Elasticsearch domain. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 Enabled (bool): Specifies the option to enable Encryption At Rest. .IP \(bu 2 KmsKeyId (str): Specifies the KMS Key ID for Encryption At Rest options. .UNINDENT .IP \(bu 2 \fBnode_to_node_encryption_options\fP (\fI\%dict\fP) \-\- .sp Dict specifying the node to node encryption options. This option can only be used for the creation of a new Elasticsearch domain. Keys (case sensitive) in here are: .INDENT 2.0 .IP \(bu 2 Enabled (bool): Specify True to enable node\-to\-node encryption. .UNINDENT .IP \(bu 2 \fBadvanced_options\fP (\fI\%dict\fP) \-\- Dict with option to allow references to indices in an HTTP request body. Must be False when configuring access to individual sub\-resources. By default, the value is True. See \fI\%http://docs.aws.amazon.com/elasticsearch\-service/latest/developerguide\fP /es\-createupdatedomains.html#es\-createdomain\-configure\-advanced\-options for more information. .IP \(bu 2 \fBlog_publishing_options\fP (\fI\%dict\fP) \-\- .sp Dict with options for various type of logs. The keys denote the type of log file and can be one of the following: .INDENT 2.0 .IP \(bu 2 INDEX_SLOW_LOGS .IP \(bu 2 SEARCH_SLOW_LOGS .IP \(bu 2 ES_APPLICATION_LOGS .UNINDENT .sp The value assigned to each key is a dict with the following case sensitive keys: .INDENT 2.0 .IP \(bu 2 CloudWatchLogsLogGroupArn (str): The ARN of the Cloudwatch log group to which the log needs to be published. .IP \(bu 2 Enabled (bool): Specifies whether given log publishing option is enabled or not. .UNINDENT .IP \(bu 2 \fBblocking\fP (\fI\%bool\fP) \-\- Whether or not the state should wait for all operations (create/update/upgrade) to be completed. Default: \fBTrue\fP .IP \(bu 2 \fBtags\fP (\fI\%dict\fP) \-\- Dict of tags to ensure are present on the Elasticsearch domain. .UNINDENT .UNINDENT .sp New in version 3001. .sp Example: .sp This will create an elasticsearch domain consisting of a single t2.small instance in the eu\-west\-1 region (Ireland) and will wait until the instance is available before returning from the state. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Create new domain: boto3_elasticsearch.present: \- name: my_domain \- elasticsearch_version: \(aq5.1\(aq \- elasticsearch_cluster_config: InstanceType: t2.small.elasticsearch InstanceCount: 1 DedicatedMasterEnabled: False ZoneAwarenessEnabled: False \- ebs_options: EBSEnabled: True VolumeType: gp2 VolumeSize: 10 \- snapshot_options: AutomatedSnapshotStartHour: 3 \- vpc_options: SubnetIds: \- subnet\-12345678 SecurityGroupIds: \- sg\-12345678 \- node_to_node_encryption_options: Enabled: False \- region: eu\-west\-1 \- tags: foo: bar baz: qux .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_elasticsearch.tagged(name, tags=None, replace=False, region=None, keyid=None, key=None, profile=None) Ensures the Elasticsearch domain has the tags provided. Adds tags to the domain unless \fBreplace\fP is set to \fBTrue\fP, in which case all existing tags will be replaced with the tags provided in \fBtags\fP\&. (This will remove all tags if \fBreplace\fP is \fBTrue\fP and \fBtags\fP is empty). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The Elasticsearch domain to work with. .IP \(bu 2 \fBtags\fP (\fI\%dict\fP) \-\- The tags to add to/replace on the Elasticsearch domain. .IP \(bu 2 \fBreplace\fP (\fI\%bool\fP) \-\- Whether or not to replace (\fBTrue\fP) all existing tags on the Elasticsearch domain, or add (\fBFalse\fP) tags to the ES domain. .UNINDENT .UNINDENT .sp New in version 3001. .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_elasticsearch.upgraded(name, elasticsearch_version, blocking=True, region=None, keyid=None, key=None, profile=None) Ensures the Elasticsearch domain specified runs on the specified version of elasticsearch. Only upgrades are possible as downgrades require a manual snapshot and an S3 bucket to store them in. .sp Note that this operation is blocking until the upgrade is complete. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the Elasticsearch domain to upgrade. .IP \(bu 2 \fBelasticsearch_version\fP (\fI\%str\fP) \-\- String of format X.Y to specify version for the Elasticsearch domain eg. \(dq1.5\(dq or \(dq2.3\(dq. .UNINDENT .UNINDENT .sp New in version 3001. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Upgrade Elasticsearch Domain: boto3_elasticsearch.upgraded: \- name: my_domain \- elasticsearch_version: \(aq7.2\(aq \- region: eu\-west\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.boto3_route53 .sp Manage Route53 records with Boto 3 .sp New in version 2017.7.0. .sp Create and delete Route53 records. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto3\fP, which can be installed via package, or pip. .sp This module accepts explicit route53 credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C route53.keyid: GKTADJGHEIQSXMKKRBJ08H route53.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C An exciting new AWS Route 53 Hosted Zone: boto_route53.hosted_zone_present: \- Name: example.com. \- PrivateZone: true \- VPCs: \- VPCName: MyLittleVPC VPCRegion: us\-east\-1 \- VPCId: vpc\-12345678 \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs mycnamerecord: boto_route53.rr_present: \- Name: test.example.com. \- ResourceRecords: \- my\-elb.us\-east\-1.elb.amazonaws.com. \- DomainName: example.com. \- TTL: 60 \- Type: CNAME \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_route53.hosted_zone_absent(name, Name=None, PrivateZone=False, region=None, key=None, keyid=None, profile=None) Ensure the Route53 Hostes Zone described is absent .INDENT 7.0 .TP .B name The name of the state definition. .TP .B Name The name of the domain. This should be a fully\-specified domain, and should terminate with a period. If not provided, the value of name will be used. .TP .B PrivateZone Set True if deleting a private hosted zone. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_route53.hosted_zone_present(name, Name=None, PrivateZone=False, CallerReference=None, Comment=None, VPCs=None, region=None, key=None, keyid=None, profile=None) Ensure a hosted zone exists with the given attributes. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B Name The name of the domain. This should be a fully\-specified domain, and should terminate with a period. This is the name you have registered with your DNS registrar. It is also the name you will delegate from your registrar to the Amazon Route 53 delegation servers returned in response to this request. If not provided, the value of name will be used. .TP .B PrivateZone Set True if creating a private hosted zone. If true, then \(aqVPCs\(aq is also required. .TP .B Comment Any comments you want to include about the hosted zone. .TP .B CallerReference A unique string that identifies the request and that allows create_hosted_zone() calls to be retried without the risk of executing the operation twice. This helps ensure idempotency across state calls, but can cause issues if a zone is deleted and then an attempt is made to recreate it with the same CallerReference. If not provided, a unique UUID will be generated at each state run, which can potentially lead to duplicate zones being created if the state is run again while the previous zone creation is still in PENDING status (which can occasionally take several minutes to clear). Maximum length of 128. .TP .B VPCs A list of dicts, each dict composed of a VPCRegion, and either a VPCId or a VPCName. Note that this param is ONLY used if PrivateZone == True .INDENT 7.0 .TP .B VPCId When creating a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with VPCName. .TP .B VPCName When creating a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with VPCId. .TP .B VPCRegion When creating a private hosted zone, the region of the associated VPC is required. If not provided, an effort will be made to determine it from VPCId or VPCName, if possible. This will fail if a given VPCName exists in multiple regions visible to the bound account, in which case you\(aqll need to provide an explicit value for VPCRegion. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_route53.rr_absent(name, HostedZoneId=None, DomainName=None, PrivateZone=False, Name=None, Type=None, SetIdentifier=None, region=None, key=None, keyid=None, profile=None) Ensure the Route53 record is deleted. .INDENT 7.0 .TP .B name The name of the state definition. This will be used for Name if the latter is not provided. .TP .B HostedZoneId The ID of the zone to delete the record from. Exclusive with DomainName. .TP .B DomainName The domain name of the zone to delete the record from. Exclusive with HostedZoneId. .TP .B PrivateZone Set to True if the RR to be removed is in a private zone, False if public. .TP .B Name Name of the resource record. .TP .B Type The record type (A, NS, MX, TXT, etc.) .TP .B SetIdentifier Valid for Weighted, Latency, Geolocation, and Failover resource record sets only. An identifier that differentiates among multiple resource record sets that have the same combination of DNS name and type. The value of SetIdentifier must be unique for each resource record set that has the same combination of DNS name and type. Omit SetIdentifier for any other types of record sets. .TP .B region The region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile Dict, or pillar key pointing to a dict, containing AWS region/key/keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_route53.rr_present(name, HostedZoneId=None, DomainName=None, PrivateZone=False, Name=None, Type=None, SetIdentifier=None, Weight=None, Region=None, GeoLocation=None, Failover=None, TTL=None, ResourceRecords=None, AliasTarget=None, HealthCheckId=None, TrafficPolicyInstanceId=None, region=None, key=None, keyid=None, profile=None) Ensure the Route53 record is present. .INDENT 7.0 .TP .B name The name of the state definition. This will be used for Name if the latter is not provided. .TP .B HostedZoneId The ID of a zone to create the record in. Exclusive with DomainName. .TP .B DomainName The domain name of a zone to create the record in. Exclusive with HostedZoneId. .TP .B PrivateZone Set to True if the resource record should be in a private zone, False if public. .TP .B Name Name of the Route 53 resource record being managed. .TP .B Type The record type (A, NS, MX, TXT, etc.) .TP .B SetIdentifier Valid for Weighted, Latency, Geolocation, and Failover resource record sets only. An identifier that differentiates among multiple resource record sets that have the same combination of DNS name and type. The value of SetIdentifier must be unique for each resource record set that has the same combination of DNS name and type. Omit SetIdentifier for any other types of record sets. .TP .B Weight Valid for Weighted resource record sets only. Among resource record sets that have the same combination of DNS name and type, a value that determines the proportion of DNS queries that Amazon Route 53 responds to using the current resource record set. Amazon Route 53 calculates the sum of the weights for the resource record sets that have the same combination of DNS name and type. Amazon Route 53 then responds to queries based on the ratio of a resource\(aqs weight to the total. .sp Note the following: .INDENT 7.0 .IP \(bu 2 You must specify a value for the Weight element for every weighted resource record set. .IP \(bu 2 You can only specify one ResourceRecord per weighted resource record set. .IP \(bu 2 You can\(aqt create latency, failover, or geolocation resource record sets that have the same values for the Name and Type elements as weighted resource record sets. .IP \(bu 2 You can create a maximum of 100 weighted resource record sets that have the same values for the Name and Type elements. .IP \(bu 2 For weighted (but not weighted alias) resource record sets, if you set Weight to 0 for a resource record set, Amazon Route 53 never responds to queries with the applicable value for that resource record set. However, if you set Weight to 0 for all resource record sets that have the same combination of DNS name and type, traffic is routed to all resources with equal probability. The effect of setting Weight to 0 is different when you associate health checks with weighted resource record sets. For more information, see \fI\%Options for Configuring Amazon Route 53 Active\-Active and Active\-Passive Failover\fP in the Amazon Route 53 Developer Guide. .UNINDENT .TP .B Region Valid for Latency\-based resource record sets only. The Amazon EC2 Region where the resource that is specified in this resource record set resides. The resource typically is an AWS resource, such as an EC2 instance or an ELB load balancer, and is referred to by an IP address or a DNS domain name, depending on the record type. .TP .B GeoLocation Geo location resource record sets only. A dict that lets you control how Route 53 responds to DNS queries based on the geographic origin of the query. For example, if you want all queries from Africa to be routed to a web server with an IP address of 192.0.2.111, create a resource record set with a Type of A and a ContinentCode of AF. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ContinentCode The two\-letter code for the continent. Valid values: AF | AN | AS | EU | OC | NA | SA Constraint: Specifying ContinentCode with either CountryCode or SubdivisionCode returns an InvalidInput error. CountryCode The two\-letter code for the country. SubdivisionCode The code for the subdivision, for example, a state in the United States or a province in Canada. .ft P .fi .UNINDENT .UNINDENT .sp Notes .INDENT 7.0 .IP \(bu 2 Creating geolocation and geolocation alias resource record sets in private hosted zones is not supported. .IP \(bu 2 If you create separate resource record sets for overlapping geographic regions (for example, one resource record set for a continent and one for a country on the same continent), priority goes to the smallest geographic region. This allows you to route most queries for a continent to one resource and to route queries for a country on that continent to a different resource. .IP \(bu 2 You can\(aqt create two geolocation resource record sets that specify the same geographic location. .IP \(bu 2 The value \fB*\fP in the CountryCode element matches all geographic locations that aren\(aqt specified in other geolocation resource record sets that have the same values for the Name and Type elements. .IP \(bu 2 Geolocation works by mapping IP addresses to locations. However, some IP addresses aren\(aqt mapped to geographic locations, so even if you create geolocation resource record sets that cover all seven continents, Amazon Route 53 will receive some DNS queries from locations that it can\(aqt identify. We recommend that you create a resource record set for which the value of CountryCode is \fB*\fP, which handles both queries that come from locations for which you haven\(aqt created geolocation resource record sets and queries from IP addresses that aren\(aqt mapped to a location. If you don\(aqt create a \fB*\fP resource record set, Amazon Route 53 returns a \(dqno answer\(dq response for queries from those locations. .IP \(bu 2 You can\(aqt create non\-geolocation resource record sets that have the same values for the Name and Type elements as geolocation resource record sets. .UNINDENT .TP .B TTL The resource record cache time to live (TTL), in seconds. Note the following: .INDENT 7.0 .IP \(bu 2 If you\(aqre creating an alias resource record set, omit TTL. Amazon Route 53 uses the value of TTL for the alias target. .IP \(bu 2 If you\(aqre associating this resource record set with a health check (if you\(aqre adding a HealthCheckId element), we recommend that you specify a TTL of 60 seconds or less so clients respond quickly to changes in health status. .IP \(bu 2 All of the resource record sets in a group of weighted, latency, geolocation, or failover resource record sets must have the same value for TTL. .IP \(bu 2 If a group of weighted resource record sets includes one or more weighted alias resource record sets for which the alias target is an ELB load balancer, we recommend that you specify a TTL of 60 seconds for all of the non\-alias weighted resource record sets that have the same name and type. Values other than 60 seconds (the TTL for load balancers) will change the effect of the values that you specify for Weight. .UNINDENT .TP .B ResourceRecords A list, containing one or more values for the resource record. No single value can exceed 4,000 characters. For details on how to format values for different record types, see \fI\%Supported DNS Resource Record Types\fP in the Amazon Route 53 Developer Guide. .sp Note: You can specify more than one value for all record types except CNAME and SOA. .sp It is also possible to pass \(dqmagic\(dq strings as resource record values. This functionality can easily be extended, but for the moment supports the following: .INDENT 7.0 .INDENT 3.5 \(aqmagic:ec2_instance_tag:some_tag_name:some_string:some_instance_attr\(aq .UNINDENT .UNINDENT .sp This tells salt to lookup an EC2 instance with a tag \(aqsome_tag_name\(aq which has the value \(aqsome_string\(aq and substitute the \(aqsome_instance_attr\(aq attribute of that instance as the resource record value being evaluated. .sp This should work generally for any EC2 instance tags, as long as the instance attribute being fetched is available to getattr(instance, \(aqattribute\(aq) as seen in the code below. Anything else will most likely require this function to be extended to handle it. .sp The canonical use\-case for this (at least at our site) is to query the Name tag (which we always populate with the host\(aqs FQDN) to lookup the public or private IPs bound to the instance, so we can then automgically create Route 53 records for them. .TP .B AliasTarget The rules governing how to define an AliasTarget for the various supported use\-cases are obtuse beyond reason and attempting to paraphrase them (or even worse, cut\-and\-paste them in their entirety) would be silly and counterproductive. If you need this feature, then Read The Fine Materials at the \fI\%Boto 3 Route 53 page\fP and/or the \fI\%AWS Route 53 docs\fP and suss them for yourself \- I sure won\(aqt claim to understand them partcularly well. .TP .B region The region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile Dict, or pillar key pointing to a dict, containing AWS region/key/keyid. .UNINDENT .UNINDENT .SS salt.states.boto3_sns .SS Manage SNS Topics .sp Create and destroy SNS topics. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit AWS credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sns.keyid: GKTADJGHEIQSXMKKRBJ08H sns.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mytopic: boto3_sns.topic_present: \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .SS Using a profile from pillars .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mytopic: boto3_sns.topic_present: \- region: us\-east\-1 \- profile: mysnsprofile .ft P .fi .UNINDENT .UNINDENT .SS Passing in a profile .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mytopic: boto3_sns.topic_present: \- region: us\-east\-1 \- profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_sns.topic_absent(name, unsubscribe=False, region=None, key=None, keyid=None, profile=None) Ensure the named sns topic is deleted. .INDENT 7.0 .TP .B name Name of the SNS topic. .TP .B unsubscribe If True, unsubscribe all subcriptions to the SNS topic before deleting the SNS topic .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto3_sns.topic_present(name, subscriptions=None, attributes=None, region=None, key=None, keyid=None, profile=None) Ensure the SNS topic exists. .INDENT 7.0 .TP .B name Name of the SNS topic. .TP .B subscriptions List of SNS subscriptions. .sp Each subscription is a dictionary with a protocol and endpoint key: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C subscriptions: \- Protocol: https Endpoint: https://www.example.com/sns\-endpoint \- Protocol: sqs Endpoint: arn:aws:sqs:us\-west\-2:123456789012:MyQueue .ft P .fi .UNINDENT .UNINDENT .TP .B attributes Dictionary of attributes to set on the SNS topic Valid attribute keys are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Policy: the JSON serialization of the topic\(aqs access control policy .IP \(bu 2 .INDENT 2.0 .TP .B DisplayName: the human\-readable name used in the \(dqFrom\(dq field for notifications to email and email\-json endpoints .UNINDENT .IP \(bu 2 DeliveryPolicy: the JSON serialization of the topic\(aqs delivery policy .UNINDENT .UNINDENT .UNINDENT .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_apigateway .SS Manage Apigateway Rest APIs .sp New in version 2016.11.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 boto >= 2.8.0 .IP \(bu 2 boto3 >= 1.2.1 .IP \(bu 2 botocore >= 1.4.49 .UNINDENT .UNINDENT .sp Create and destroy rest apis depending on a swagger version 2 definition file. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto3\fP, which can be installed via package, or pip. .sp This module accepts explicit vpc credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vpc.keyid: GKTADJGHEIQSXMKKRBJ08H vpc.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure Apigateway API exists: boto_apigateway.present: \- name: myfunction \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_apigateway.absent(name, api_name, stage_name, nuke_api=False, region=None, key=None, keyid=None, profile=None) Ensure the stage_name associated with the given api_name deployed by boto_apigateway\(aqs present state is removed. If the currently associated deployment to the given stage_name has no other stages associated with it, the deployment will also be removed. .INDENT 7.0 .TP .B name Name of the swagger file in YAML format .TP .B api_name Name of the rest api on AWS ApiGateway to ensure is absent. .TP .B stage_name Name of the stage to be removed irrespective of the swagger file content. If the current deployment associated with the stage_name has no other stages associated with it, the deployment will also be removed. .TP .B nuke_api If True, removes the API itself only if there are no other stages associated with any other deployments once the given stage_name is removed. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_apigateway.present(name, api_name, swagger_file, stage_name, api_key_required, lambda_integration_role, lambda_region=None, stage_variables=None, region=None, key=None, keyid=None, profile=None, lambda_funcname_format=\(aq{stage}_{api}_{resource}_{method}\(aq, authorization_type=\(aqNONE\(aq, error_response_template=None, response_template=None) Ensure the spcified api_name with the corresponding swaggerfile is deployed to the given stage_name in AWS ApiGateway. .sp this state currently only supports ApiGateway integration with AWS Lambda, and CORS support is handled through a Mock integration. .sp There may be multiple deployments for the API object, each deployment is tagged with a description (i.e. unique label) in pretty printed json format consisting of the following key/values. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(dqapi_name\(dq: api_name, \(dqswagger_file\(dq: basename_of_swagger_file \(dqswagger_file_md5sum\(dq: md5sum_of_swagger_file, \(dqswagger_info_object\(dq: info_object_content_in_swagger_file } .ft P .fi .UNINDENT .UNINDENT .sp Please note that the name of the lambda function to be integrated will be derived via the provided lambda_funcname_format parameters: .INDENT 7.0 .IP \(bu 2 the default lambda_funcname_format is a string with the following substitutable keys: \(dq{stage}_{api}_{resource}_{method}\(dq. The user can choose to reorder the known keys. .IP \(bu 2 the stage key corresponds to the stage_name passed in. .IP \(bu 2 the api key corresponds to the api_name passed in. .IP \(bu 2 the resource corresponds to the resource path defined in the passed swagger file. .IP \(bu 2 the method corresponds to the method for a resource path defined in the passed swagger file. .UNINDENT .sp For the default lambda_funcname_format, given the following input: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C api_name = \(aq Test Service\(aq stage_name = \(aqalpha\(aq basePath = \(aq/api\(aq path = \(aq/a/{b}/c\(aq method = \(aqPOST\(aq .ft P .fi .UNINDENT .UNINDENT .sp We will end up with the following Lambda Function Name that will be looked up: \(aqtest_service_alpha_a_b_c_post\(aq .sp The canconicalization of these input parameters is done in the following order: .INDENT 7.0 .IP 1. 3 lambda_funcname_format is formatted with the input parameters as passed, .IP 2. 3 resulting string is stripped for leading/trailing spaces, .IP 3. 3 path parameter\(aqs curly braces are removed from the resource path, .IP 4. 3 consecutive spaces and forward slashes in the paths are replaced with \(aq_\(aq .IP 5. 3 consecutive \(aq_\(aq are replaced with \(aq_\(aq .UNINDENT .sp Please note that for error response handling, the swagger file must have an error response model with the following schema. The lambda functions should throw exceptions for any non successful responses. An optional pattern field can be specified in errorMessage field to aid the response mapping from Lambda to the proper error return status codes. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Error: type: object properties: stackTrace: type: array items: type: array items: type: string description: call stack errorType: type: string description: error type errorMessage: type: string description: | Error message, will be matched based on pattern. If no pattern is specified, the default pattern used for response mapping will be +*. .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the state definition .TP .B api_name The name of the rest api that we want to ensure exists in AWS API Gateway .TP .B swagger_file Name of the location of the swagger rest api definition file in YAML format. .TP .B stage_name Name of the stage we want to be associated with the given api_name and swagger_file definition .TP .B api_key_required True or False \- whether the API Key is required to call API methods .TP .B lambda_integration_role The name or ARN of the IAM role that the AWS ApiGateway assumes when it executes your lambda function to handle incoming requests .TP .B lambda_region The region where we expect to find the lambda functions. This is used to determine the region where we should look for the Lambda Function for integration purposes. The region determination is based on the following priority: .INDENT 7.0 .IP 1. 3 lambda_region as passed in (is not None) .IP 2. 3 if lambda_region is None, use the region as if a boto_lambda function were executed without explicitly specifying lambda region. .IP 3. 3 if region determined in (2) is different than the region used by boto_apigateway functions, a final lookup will be attempted using the boto_apigateway region. .UNINDENT .TP .B stage_variables A dict with variables and their values, or a pillar key (string) that contains a dict with variables and their values. key and values in the dict must be strings. {\(aqstring\(aq: \(aqstring\(aq} .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B lambda_funcname_format Please review the earlier example for the usage. The only substituable keys in the funcname format are {stage}, {api}, {resource}, {method}. Any other keys or positional substitution parameters will be flagged as an invalid input. .TP .B authorization_type This field can be either \(aqNONE\(aq, or \(aqAWS_IAM\(aq. This will be applied to all methods in the given swagger spec file. Default is set to \(aqNONE\(aq .TP .B error_response_template String value that defines the response template mapping that should be applied in cases error occurs. Refer to AWS documentation for details: \fI\%http://docs.aws.amazon.com/apigateway/latest/developerguide/api\-gateway\-mapping\-template\-reference.html\fP .sp If set to None, the following default value is used: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \(aq#set($inputRoot = $input.path(\(aq$\(aq))\en\(aq \(aq{\en\(aq \(aq \(dqerrorMessage\(dq : \(dq$inputRoot.errorMessage\(dq,\en\(aq \(aq \(dqerrorType\(dq : \(dq$inputRoot.errorType\(dq,\en\(aq \(aq \(dqstackTrace\(dq : [\en\(aq \(aq#foreach($stackTrace in $inputRoot.stackTrace)\en\(aq \(aq [\en\(aq \(aq#foreach($elem in $stackTrace)\en\(aq \(aq \(dq$elem\(dq\en\(aq \(aq#if($foreach.hasNext),#end\en\(aq \(aq#end\en\(aq \(aq ]\en\(aq \(aq#if($foreach.hasNext),#end\en\(aq \(aq#end\en\(aq \(aq ]\en\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.0. .TP .B response_template String value that defines the response template mapping applied in case of success (including OPTIONS method) If set to None, empty ({}) template is assumed, which will transfer response from the lambda function as is. .sp New in version 2017.7.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_apigateway.usage_plan_absent(name, plan_name, region=None, key=None, keyid=None, profile=None) Ensures usage plan identified by name is no longer present .sp New in version 2017.7.0. .INDENT 7.0 .TP .B name name of the state .TP .B plan_name name of the plan to remove .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C usage plan absent: boto_apigateway.usage_plan_absent: \- plan_name: my_usage_plan \- profile: my_profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_apigateway.usage_plan_association_absent(name, plan_name, api_stages, region=None, key=None, keyid=None, profile=None) Ensures usage plan identified by name is removed from provided api_stages If a plan is associated to stages not listed in api_stages parameter, those associations remain intact. .sp New in version 2017.7.0. .INDENT 7.0 .TP .B name name of the state .TP .B plan_name name of the plan to use .TP .B api_stages list of dictionaries, where each dictionary consists of the following keys: .INDENT 7.0 .TP .B apiId apiId of the api to detach usage plan from .TP .B stage stage name of the api to detach usage plan from .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C UsagePlanAssociationAbsent: boto_apigateway.usage_plan_association_absent: \- plan_name: my_plan \- api_stages: \- apiId: 9kb0404ec0 stage: my_stage \- apiId: l9v7o2aj90 stage: my_stage \- profile: my_profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_apigateway.usage_plan_association_present(name, plan_name, api_stages, region=None, key=None, keyid=None, profile=None) Ensures usage plan identified by name is added to provided api_stages .sp New in version 2017.7.0. .INDENT 7.0 .TP .B name name of the state .TP .B plan_name name of the plan to use .TP .B api_stages list of dictionaries, where each dictionary consists of the following keys: .INDENT 7.0 .TP .B apiId apiId of the api to attach usage plan to .TP .B stage stage name of the api to attach usage plan to .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C UsagePlanAssociationPresent: boto_apigateway.usage_plan_association_present: \- plan_name: my_plan \- api_stages: \- apiId: 9kb0404ec0 stage: my_stage \- apiId: l9v7o2aj90 stage: my_stage \- profile: my_profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_apigateway.usage_plan_present(name, plan_name, description=None, throttle=None, quota=None, region=None, key=None, keyid=None, profile=None) Ensure the spcifieda usage plan with the corresponding metrics is deployed .sp New in version 2017.7.0. .INDENT 7.0 .TP .B name name of the state .TP .B plan_name [Required] name of the usage plan .TP .B throttle [Optional] throttling parameters expressed as a dictionary. If provided, at least one of the throttling parameters must be present .INDENT 7.0 .TP .B rateLimit rate per second at which capacity bucket is populated .TP .B burstLimit maximum rate allowed .UNINDENT .TP .B quota [Optional] quota on the number of api calls permitted by the plan. If provided, limit and period must be present .INDENT 7.0 .TP .B limit [Required] number of calls permitted per quota period .TP .B offset [Optional] number of calls to be subtracted from the limit at the beginning of the period .TP .B period [Required] period to which quota applies. Must be DAY, WEEK or MONTH .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C UsagePlanPresent: boto_apigateway.usage_plan_present: \- plan_name: my_usage_plan \- throttle: rateLimit: 70 burstLimit: 100 \- quota: limit: 1000 offset: 0 period: DAY \- profile: my_profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.boto_asg .SS Manage Autoscale Groups .sp New in version 2014.7.0. .sp Create and destroy autoscale groups. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses boto, which can be installed via package, or pip. .sp This module accepts explicit autoscale credentials but 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 used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C asg.keyid: GKTADJGHEIQSXMKKRBJ08H asg.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify key, keyid and region via a profile, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure myasg exists: boto_asg.present: \- name: myasg \- launch_config_name: mylc \- availability_zones: \- us\-east\-1a \- us\-east\-1b \- min_size: 1 \- max_size: 1 \- desired_capacity: 1 \- load_balancers: \- myelb \- suspended_processes: \- AddToLoadBalancer \- AlarmNotification \- scaling_policies \- adjustment_type: ChangeInCapacity \- as_name: api\-production\-iad \- cooldown: 1800 \- min_adjustment_step: None \- name: ScaleDown \- scaling_adjustment: \-1 \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs # Using a profile from pillars. Ensure myasg exists: boto_asg.present: \- name: myasg \- launch_config_name: mylc \- availability_zones: \- us\-east\-1a \- us\-east\-1b \- min_size: 1 \- max_size: 1 \- desired_capacity: 1 \- load_balancers: \- myelb \- profile: myprofile # Passing in a profile. Ensure myasg exists: boto_asg.present: \- name: myasg \- launch_config_name: mylc \- availability_zones: \- us\-east\-1a \- us\-east\-1b \- min_size: 1 \- max_size: 1 \- desired_capacity: 1 \- load_balancers: \- myelb \- profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 # Deleting an autoscale group with running instances. Ensure myasg is deleted: boto_asg.absent: \- name: myasg # If instances exist, we must force the deletion of the asg. \- force: True .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs possible to specify cloudwatch alarms that will be setup along with the ASG. Note the alarm name will be the name attribute defined, plus the ASG resource name. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure myasg exists: boto_asg.present: \- name: myasg \- launch_config_name: mylc \- availability_zones: \- us\-east\-1a \- us\-east\-1b \- min_size: 1 \- max_size: 1 \- desired_capacity: 1 \- load_balancers: \- myelb \- profile: myprofile \- alarms: CPU: name: \(aqASG CPU **MANAGED BY SALT**\(aq attributes: metric: CPUUtilization namespace: AWS/EC2 statistic: Average comparison: \(aq>=\(aq threshold: 65.0 period: 60 evaluation_periods: 30 unit: null description: \(aqASG CPU\(aq alarm_actions: [ \(aqarn:aws:sns:us\-east\-1:12345:myalarm\(aq ] insufficient_data_actions: [] ok_actions: [ \(aqarn:aws:sns:us\-east\-1:12345:myalarm\(aq ] .ft P .fi .UNINDENT .UNINDENT .sp You can also use alarms from pillars, and override values from the pillar alarms by setting overrides on the resource. Note that \(aqboto_asg_alarms\(aq will be used as a default value for all resources, if defined and can be used to ensure alarms are always set for an ASG resource. .sp Setting the alarms in a pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_asg_alarm: CPU: name: \(aqASG CPU **MANAGED BY SALT**\(aq attributes: metric: CPUUtilization namespace: AWS/EC2 statistic: Average comparison: \(aq>=\(aq threshold: 65.0 period: 60 evaluation_periods: 30 unit: null description: \(aqASG CPU\(aq alarm_actions: [ \(aqarn:aws:sns:us\-east\-1:12345:myalarm\(aq ] insufficient_data_actions: [] ok_actions: [ \(aqarn:aws:sns:us\-east\-1:12345:myalarm\(aq ] .ft P .fi .UNINDENT .UNINDENT .sp Overriding the alarm values on the resource: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure myasg exists: boto_asg.present: \- name: myasg \- launch_config_name: mylc \- availability_zones: \- us\-east\-1a \- us\-east\-1b \- min_size: 1 \- max_size: 1 \- desired_capacity: 1 \- load_balancers: \- myelb \- profile: myprofile \- alarms_from_pillar: my_asg_alarm # override CPU:attributes:threshold \- alarms: CPU: attributes: threshold: 50.0 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_asg.absent(name, force=False, region=None, key=None, keyid=None, profile=None, remove_lc=False) Ensure the named autoscale group is deleted. .INDENT 7.0 .TP .B name Name of the autoscale group. .TP .B force Force deletion of autoscale group. .TP .B remove_lc Delete the launch config as well. .TP .B region The region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_asg.present(name, launch_config_name, availability_zones, min_size, max_size, launch_config=None, desired_capacity=None, load_balancers=None, default_cooldown=None, health_check_type=None, health_check_period=None, placement_group=None, vpc_zone_identifier=None, subnet_names=None, tags=None, termination_policies=None, termination_policies_from_pillar=\(aqboto_asg_termination_policies\(aq, suspended_processes=None, scaling_policies=None, scaling_policies_from_pillar=\(aqboto_asg_scaling_policies\(aq, scheduled_actions=None, scheduled_actions_from_pillar=\(aqboto_asg_scheduled_actions\(aq, alarms=None, alarms_from_pillar=\(aqboto_asg_alarms\(aq, region=None, key=None, keyid=None, profile=None, notification_arn=None, notification_arn_from_pillar=\(aqboto_asg_notification_arn\(aq, notification_types=None, notification_types_from_pillar=\(aqboto_asg_notification_types\(aq) Ensure the autoscale group exists. .INDENT 7.0 .TP .B name Name of the autoscale group. .TP .B launch_config_name Name of the launch config to use for the group. Or, if \fBlaunch_config\fP is specified, this will be the launch config name\(aqs prefix. (see below) .TP .B launch_config A dictionary of launch config attributes. If specified, a launch config will be used or created, matching this set of attributes, and the autoscale group will be set to use that launch config. The launch config name will be the \fBlaunch_config_name\fP followed by a hyphen followed by a hash of the \fBlaunch_config\fP dict contents. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my_asg: boto_asg.present: \- launch_config: \- ebs_optimized: false \- instance_profile_name: my_iam_profile \- kernel_id: \(aq\(aq \- ramdisk_id: \(aq\(aq \- key_name: my_ssh_key \- image_name: aws2015091\-hvm \- instance_type: c3.xlarge \- instance_monitoring: false \- security_groups: \- my_sec_group_01 \- my_sec_group_02 .ft P .fi .UNINDENT .UNINDENT .TP .B availability_zones List of availability zones for the group. .TP .B min_size Minimum size of the group. .TP .B max_size Maximum size of the group. .TP .B desired_capacity The desired capacity of the group. .TP .B load_balancers List of load balancers for the group. Once set this can not be updated (Amazon restriction). .TP .B default_cooldown Number of seconds after a Scaling Activity completes before any further scaling activities can start. .TP .B health_check_type The service you want the health status from, Amazon EC2 or Elastic Load Balancer (EC2 or ELB). .TP .B health_check_period Length of time in seconds after a new EC2 instance comes into service that Auto Scaling starts checking its health. .TP .B placement_group Physical location of your cluster placement group created in Amazon EC2. Once set this can not be updated (Amazon restriction). .TP .B vpc_zone_identifier A list of the subnet identifiers of the Virtual Private Cloud. .TP .B subnet_names For VPC, a list of subnet names (NOT subnet IDs) to deploy into. Exclusive with vpc_zone_identifier. .TP .B tags A list of tags. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- key: \(aqkey\(aq value: \(aqvalue\(aq propagate_at_launch: true .ft P .fi .UNINDENT .UNINDENT .TP .B termination_policies A list of termination policies. Valid values are: .INDENT 7.0 .IP \(bu 2 \fBOldestInstance\fP .IP \(bu 2 \fBNewestInstance\fP .IP \(bu 2 \fBOldestLaunchConfiguration\fP .IP \(bu 2 \fBClosestToNextInstanceHour\fP .IP \(bu 2 \fBDefault\fP .UNINDENT .sp If no value is specified, the \fBDefault\fP value is used. .TP .B termination_policies_from_pillar: name of pillar dict that contains termination policy settings. Termination policies defined for this specific state will override those from pillar. .TP .B suspended_processes List of processes to be suspended. see \fI\%http://docs.aws.amazon.com/AutoScaling/latest/DeveloperGuide/US_SuspendResume.html\fP .TP .B scaling_policies List of scaling policies. Each policy is a dict of key\-values described by \fI\%https://boto.readthedocs.io/en/latest/ref/autoscale.html#boto.ec2.autoscale.policy.ScalingPolicy\fP .TP .B scaling_policies_from_pillar: name of pillar dict that contains scaling policy settings. Scaling policies defined for this specific state will override those from pillar. .TP .B scheduled_actions: a dictionary of scheduled actions. Each key is the name of scheduled action and each value is dictionary of options. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- scheduled_actions: scale_up_at_10: desired_capacity: 4 min_size: 3 max_size: 5 recurrence: \(dq0 9 * * 1\-5\(dq scale_down_at_7: desired_capacity: 1 min_size: 1 max_size: 1 recurrence: \(dq0 19 * * 1\-5\(dq .ft P .fi .UNINDENT .UNINDENT .TP .B scheduled_actions_from_pillar: name of pillar dict that contains scheduled_actions settings. Scheduled actions for this specific state will override those from pillar. .TP .B alarms: a dictionary of name\->boto_cloudwatch_alarm sections to be associated with this ASG. All attributes should be specified except for dimension which will be automatically set to this ASG. .sp See the \fI\%salt.states.boto_cloudwatch_alarm\fP state for information about these attributes. .sp If any alarm actions include \(dq:self:\(dq this will be replaced with the asg name. For example, alarm_actions reading \(dq[\(aqscaling_policy:self:ScaleUp\(aq]\(dq will map to the arn for this asg\(aqs scaling policy named \(dqScaleUp\(dq. In addition, any alarms that have only scaling_policy as actions will be ignored if min_size is equal to max_size for this ASG. .TP .B alarms_from_pillar: name of pillar dict that contains alarm settings. Alarms defined for this specific state will override those from pillar. .TP .B region The region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B notification_arn The AWS arn that notifications will be sent to .TP .B notification_arn_from_pillar name of the pillar dict that contains \fBnotifcation_arn\fP settings. A \fBnotification_arn\fP defined for this specific state will override the one from pillar. .TP .B notification_types A list of event names that will trigger a notification. The list of valid notification types is: .INDENT 7.0 .IP \(bu 2 \fBautoscaling:EC2_INSTANCE_LAUNCH\fP .IP \(bu 2 \fBautoscaling:EC2_INSTANCE_LAUNCH_ERROR\fP .IP \(bu 2 \fBautoscaling:EC2_INSTANCE_TERMINATE\fP .IP \(bu 2 \fBautoscaling:EC2_INSTANCE_TERMINATE_ERROR\fP .IP \(bu 2 \fBautoscaling:TEST_NOTIFICATION\fP .UNINDENT .TP .B notification_types_from_pillar name of the pillar dict that contains \fBnotifcation_types\fP settings. \fBnotification_types\fP defined for this specific state will override those from the pillar. .UNINDENT .UNINDENT .SS salt.states.boto_cfn .sp Connection module for Amazon Cloud Formation .sp New in version 2015.8.0. .INDENT 0.0 .TP .B depends boto .TP .B configuration This module accepts explicit AWS credentials but 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 \fI\%http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html\fP .sp If IAM roles are not used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C stack\-present: boto_cfn.present: \- name: mystack \- template_body: salt://base/mytemplate.json \- disable_rollback: true \- region: eu\-west\-1 \- keyid: \(aqAKIAJHTMIQ2ASDFLASDF\(aq \- key: \(aqfdkjsafkljsASSADFalkfjasdf\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C stack\-absent: boto_cfn.absent: \- name: mystack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_cfn.absent(name, region=None, key=None, keyid=None, profile=None) Ensure cloud formation stack is absent. .sp name (string) – The name of the stack to delete. .sp region (string) \- Region to connect to. .sp key (string) \- Secret key to be used. .sp keyid (string) \- Access key to be used. .sp profile (dict) \- A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_cfn.present(name, template_body=None, template_url=None, parameters=None, notification_arns=None, disable_rollback=None, timeout_in_minutes=None, capabilities=None, tags=None, on_failure=None, stack_policy_body=None, stack_policy_url=None, use_previous_template=None, stack_policy_during_update_body=None, stack_policy_during_update_url=None, region=None, key=None, keyid=None, profile=None) Ensure cloud formation stack is present. .sp name (string) \- Name of the stack. .sp template_body (string) – Structure containing the template body. Can also be loaded from a file by using salt://. .sp template_url (string) – Location of file containing the template body. The URL must point to a template located in an S3 bucket in the same region as the stack. .sp parameters (list) – A list of key/value tuples that specify input parameters for the stack. A 3\-tuple (key, value, bool) may be used to specify the UsePreviousValue option. .sp notification_arns (list) – The Simple Notification Service (SNS) topic ARNs to publish stack related events. You can find your SNS topic ARNs using the \fI\%SNS_console\fP or your Command Line Interface (CLI). .sp disable_rollback (bool) – Indicates whether or not to rollback on failure. .sp timeout_in_minutes (integer) – The amount of time that can pass before the stack status becomes CREATE_FAILED; if DisableRollback is not set or is set to False, the stack will be rolled back. .sp capabilities (list) – The list of capabilities you want to allow in the stack. Currently, the only valid capability is ‘CAPABILITY_IAM’. .sp tags (dict) – A set of user\-defined Tags to associate with this stack, represented by key/value pairs. Tags defined for the stack are propagated to EC2 resources that are created as part of the stack. A maximum number of 10 tags can be specified. .sp on_failure (string) – Determines what action will be taken if stack creation fails. This must be one of: DO_NOTHING, ROLLBACK, or DELETE. You can specify either OnFailure or DisableRollback, but not both. .sp stack_policy_body (string) – Structure containing the stack policy body. Can also be loaded from a file by using salt://. .sp stack_policy_url (string) – Location of a file containing the stack policy. The URL must point to a policy (max size: 16KB) located in an S3 bucket in the same region as the stack.If you pass StackPolicyBody and StackPolicyURL, only StackPolicyBody is used. .sp use_previous_template (boolean) – Used only when templates are not the same. Set to True to use the previous template instead of uploading a new one via TemplateBody or TemplateURL. .sp stack_policy_during_update_body (string) – Used only when templates are not the same. Structure containing the temporary overriding stack policy body. If you pass StackPolicyDuringUpdateBody and StackPolicyDuringUpdateURL, only StackPolicyDuringUpdateBody is used. Can also be loaded from a file by using salt://. .sp stack_policy_during_update_url (string) – Used only when templates are not the same. Location of a file containing the temporary overriding stack policy. The URL must point to a policy (max size: 16KB) located in an S3 bucket in the same region as the stack. If you pass StackPolicyDuringUpdateBody and StackPolicyDuringUpdateURL, only StackPolicyDuringUpdateBody is used. .sp region (string) \- Region to connect to. .sp key (string) \- Secret key to be used. .sp keyid (string) \- Access key to be used. .sp profile (dict) \- A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .SS salt.states.boto_cloudfront .sp Manage CloudFront distributions .sp New in version 2018.3.0. .sp Create, update and destroy CloudFront distributions. .sp This module accepts explicit AWS credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them, either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cloudfront.keyid: GKTADJGHEIQSXMKKRBJ08H cloudfront.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP, and \fBregion\fP via a profile, either passed in as a dict, or a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C aws: region: us\-east\-1: profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_cloudfront.present(name, config, tags, region=None, key=None, keyid=None, profile=None) Ensure the CloudFront distribution is present. .INDENT 7.0 .TP .B name (string) Name of the CloudFront distribution .TP .B config (dict) Configuration for the distribution .TP .B tags (dict) Tags to associate with the distribution .TP .B region (string) Region to connect to .TP .B key (string) Secret key to use .TP .B keyid (string) Access key to use .TP .B profile (dict or string) A dict with region, key, and keyid, or a pillar key (string) that contains such a dict. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Manage my_distribution CloudFront distribution: boto_cloudfront.present: \- name: my_distribution \- config: Comment: \(aqpartial config shown, most parameters elided\(aq Enabled: True \- tags: testing_key: testing_value .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.boto_cloudtrail .SS Manage CloudTrail Objects .sp New in version 2016.3.0. .sp Create and destroy CloudTrail objects. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 boto .IP \(bu 2 boto3 .UNINDENT .UNINDENT .sp The dependencies listed above can be installed via package or pip. .sp This module accepts explicit vpc credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vpc.keyid: GKTADJGHEIQSXMKKRBJ08H vpc.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure trail exists: boto_cloudtrail.present: \- Name: mytrail \- S3BucketName: mybucket \- S3KeyPrefix: prefix \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_cloudtrail.absent(name, Name, region=None, key=None, keyid=None, profile=None) Ensure trail with passed properties is absent. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B Name Name of the trail. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_cloudtrail.present(name, Name, S3BucketName, S3KeyPrefix=None, SnsTopicName=None, IncludeGlobalServiceEvents=True, IsMultiRegionTrail=None, EnableLogFileValidation=False, CloudWatchLogsLogGroupArn=None, CloudWatchLogsRoleArn=None, KmsKeyId=None, LoggingEnabled=True, Tags=None, region=None, key=None, keyid=None, profile=None) Ensure trail exists. .INDENT 7.0 .TP .B name The name of the state definition .TP .B Name Name of the trail. .TP .B S3BucketName Specifies the name of the Amazon S3 bucket designated for publishing log files. .TP .B S3KeyPrefix Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for log file delivery. .TP .B SnsTopicName Specifies the name of the Amazon SNS topic defined for notification of log file delivery. The maximum length is 256 characters. .TP .B IncludeGlobalServiceEvents Specifies whether the trail is publishing events from global services such as IAM to the log files. .TP .B EnableLogFileValidation Specifies whether log file integrity validation is enabled. The default is false. .TP .B CloudWatchLogsLogGroupArn Specifies a log group name using an Amazon Resource Name (ARN), a unique identifier that represents the log group to which CloudTrail logs will be delivered. Not required unless you specify CloudWatchLogsRoleArn. .TP .B CloudWatchLogsRoleArn Specifies the role for the CloudWatch Logs endpoint to assume to write to a user\(aqs log group. .TP .B KmsKeyId Specifies the KMS key ID to use to encrypt the logs delivered by CloudTrail. The value can be a an alias name prefixed by \(dqalias/\(dq, a fully specified ARN to an alias, a fully specified ARN to a key, or a globally unique identifier. .TP .B LoggingEnabled Whether logging should be enabled for the trail .TP .B Tags A dictionary of tags that should be set on the trail .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_cloudwatch_alarm .sp Manage Cloudwatch alarms .sp New in version 2014.7.0. .sp Create and destroy cloudwatch alarms. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses boto, which can be installed via package, or pip. .sp This module accepts explicit credentials but 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: .sp \fI\%http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html\fP .sp If IAM roles are not used you need to specify them either in a pillar or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cloudwatch.keyid: GKTADJGHEIQSXMKKRBJ08H cloudwatch.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify key, keyid and region via a profile, either as a passed in dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my test alarm: boto_cloudwatch_alarm.present: \- name: my test alarm \- attributes: metric: ApproximateNumberOfMessagesVisible namespace: AWS/SQS statistic: Average comparison: \(dq>=\(dq threshold: 20000.0 period: 60 evaluation_periods: 1 description: test alarm via salt dimensions: QueueName: \- the\-sqs\-queue\-name alarm_actions: \- arn:aws:sns:us\-east\-1:1111111:myalerting\-action .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_cloudwatch_alarm.absent(name, region=None, key=None, keyid=None, profile=None) Ensure the named cloudwatch alarm is deleted. .INDENT 7.0 .TP .B name Name of the alarm. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_cloudwatch_alarm.present(name, attributes, region=None, key=None, keyid=None, profile=None) Ensure the cloudwatch alarm exists. .INDENT 7.0 .TP .B name Name of the alarm .TP .B attributes A dict of key/value cloudwatch alarm attributes. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_cloudwatch_event .SS Manage CloudTrail Objects .sp New in version 2016.11.0. .sp Create and destroy CloudWatch event rules. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto3\fP, which can be installed via package, or pip. .sp This module accepts explicit vpc credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cloudwatch_event.keyid: GKTADJGHEIQSXMKKRBJ08H cloudwatch_event.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure event rule exists: boto_cloudwatch_event.present: \- Name: mytrail \- ScheduleExpression: \(aqrate(120 minutes)\(aq \- State: \(aqDISABLED\(aq \- Targets: \- Id: \(dqtarget1\(dq Arn: \(dqarn:aws:lambda:us\-west\-1:124456715622:function:my_function\(dq Input: \(aq{\(dqarbitrary\(dq: \(dqjson\(dq}\(aq \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_cloudwatch_event.absent(name, Name=None, region=None, key=None, keyid=None, profile=None) Ensure CloudWatch event rule with passed properties is absent. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B Name Name of the event rule. Defaults to the value of the \(aqname\(aq param if not provided. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_cloudwatch_event.present(name, Name=None, ScheduleExpression=None, EventPattern=None, Description=None, RoleArn=None, State=None, Targets=None, region=None, key=None, keyid=None, profile=None) Ensure trail exists. .INDENT 7.0 .TP .B name The name of the state definition .TP .B Name Name of the event rule. Defaults to the value of the \(aqname\(aq param if not provided. .TP .B ScheduleExpression The scheduling expression. For example, \fBcron(0 20 * * ? *)\fP, \(dqrate(5 minutes)\(dq .TP .B EventPattern The event pattern. .TP .B Description A description of the rule .TP .B State Indicates whether the rule is ENABLED or DISABLED. .TP .B RoleArn The Amazon Resource Name (ARN) of the IAM role associated with the rule. .TP .B Targets A list of rresources to be invoked when the rule is triggered. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_cognitoidentity .SS Manage CognitoIdentity Functions .sp New in version 2016.11.0. .sp Create and destroy CognitoIdentity identity pools. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto3\fP, which can be installed via package, or pip. .sp This module accepts explicit vpc credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vpc.keyid: GKTADJGHEIQSXMKKRBJ08H vpc.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure function exists: boto_cognitoidentity.pool_present: \- PoolName: my_identity_pool \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_cognitoidentity.pool_absent(name, IdentityPoolName, RemoveAllMatched=False, region=None, key=None, keyid=None, profile=None) Ensure cognito identity pool with passed properties is absent. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B IdentityPoolName Name of the Cognito Identity Pool. Please note that this may match multiple pools with the same given name, in which case, all will be removed. .TP .B RemoveAllMatched If True, all identity pools with the matching IdentityPoolName will be removed. If False and there are more than one identity pool with the matching IdentityPoolName, no action will be taken. If False and there is only one identity pool with the matching IdentityPoolName, the identity pool will be removed. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_cognitoidentity.pool_present(name, IdentityPoolName, AuthenticatedRole, AllowUnauthenticatedIdentities=False, UnauthenticatedRole=None, SupportedLoginProviders=None, DeveloperProviderName=None, OpenIdConnectProviderARNs=None, region=None, key=None, keyid=None, profile=None) Ensure Cognito Identity Pool exists. .INDENT 7.0 .TP .B name The name of the state definition .TP .B IdentityPoolName Name of the Cognito Identity Pool .TP .B AuthenticatedRole An IAM role name or ARN that will be associated with temporary AWS credentials for an authenticated cognito identity. .TP .B AllowUnauthenticatedIdentities Whether to allow anonymous user identities .TP .B UnauthenticatedRole An IAM role name or ARN that will be associated with anonymous user identities .TP .B SupportedLoginProviders A dictionary or pillar that contains key:value pairs mapping provider names to provider app IDs. .TP .B DeveloperProviderName A string which is the domain by which Cognito will refer to your users. This name acts as a placeholder that allows your backend and the Cognito service to communicate about the developer provider. Once you have set a developer provider name, you cannot change it. Please take care in setting this parameter. .TP .B OpenIdConnectProviderARNs A list or pillar name that contains a list of OpenID Connect provider ARNs. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_datapipeline .sp Manage Data Pipelines .sp New in version 2016.3.0. .sp Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto3\fP, which can be installed via package, or pip. .sp This module accepts explicit AWS credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C datapipeline.keyid: GKTADJGHEIQSXMKKRBJ08H datapipeline.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure daily data pipeline exists: boto_datapipeline.present: \- name: my\-datapipeline \- pipeline_objects: DefaultSchedule: name: Every 1 day fields: period: 1 Day type: Schedule startAt: FIRST_ACTIVATION_DATE_TIME \- parameter_values: myDDBTableName: my\-dynamo\-table .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_datapipeline.absent(name, region=None, key=None, keyid=None, profile=None) Ensure a pipeline with the service_name does not exist .INDENT 7.0 .TP .B name Name of the service to ensure a data pipeline does not exist for. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_datapipeline.present(name, pipeline_objects=None, pipeline_objects_from_pillars=\(aqboto_datapipeline_pipeline_objects\(aq, parameter_objects=None, parameter_objects_from_pillars=\(aqboto_datapipeline_parameter_objects\(aq, parameter_values=None, parameter_values_from_pillars=\(aqboto_datapipeline_parameter_values\(aq, region=None, key=None, keyid=None, profile=None) Ensure the data pipeline exists with matching definition. .INDENT 7.0 .TP .B name Name of the service to ensure a data pipeline exists for. .TP .B pipeline_objects Pipeline objects to use. Will override objects read from pillars. .TP .B pipeline_objects_from_pillars The pillar key to use for lookup. .TP .B parameter_objects Parameter objects to use. Will override objects read from pillars. .TP .B parameter_objects_from_pillars The pillar key to use for lookup. .TP .B parameter_values Parameter values to use. Will override values read from pillars. .TP .B parameter_values_from_pillars The pillar key to use for lookup. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_dynamodb .SS Manage DynamoDB Tables .sp New in version 2015.5.0. .sp Create and destroy DynamoDB tables. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit DynamoDB credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure DynamoDB table does not exist: boto_dynamodb.absent: \- table_name: new_table \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs \- region: us\-east\-1 Ensure DynamoDB table exists: boto_dynamodb.present: \- table_name: new_table \- read_capacity_units: 1 \- write_capacity_units: 2 \- hash_key: primary_id \- hash_key_data_type: N \- range_key: start_timestamp \- range_key_data_type: N \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs \- region: us\-east\-1 \- local_indexes: \- index: \- name: \(dqprimary_id_end_timestamp_index\(dq \- hash_key: primary_id \- hash_key_data_type: N \- range_key: end_timestamp \- range_key_data_type: N \- global_indexes: \- index: \- name: \(dqname_end_timestamp_index\(dq \- hash_key: name \- hash_key_data_type: S \- range_key: end_timestamp \- range_key_data_type: N \- read_capacity_units: 3 \- write_capacity_units: 4 .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs possible to specify cloudwatch alarms that will be setup along with the DynamoDB table. Note the alarm name will be defined by the name attribute provided, plus the DynamoDB resource name. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure DynamoDB table exists: boto_dynamodb.present: \- name: new_table \- read_capacity_units: 1 \- write_capacity_units: 2 \- hash_key: primary_id \- hash_key_data_type: N \- range_key: start_timestamp \- range_key_data_type: N \- alarms: ConsumedWriteCapacityUnits: name: \(aqDynamoDB ConsumedWriteCapacityUnits **MANAGED BY SALT**\(aq attributes: metric: ConsumedWriteCapacityUnits namespace: AWS/DynamoDB statistic: Sum comparison: \(aq>=\(aq # threshold_percent is used to calculate the actual threshold # based on the provisioned capacity for the table. threshold_percent: 0.75 period: 300 evaluation_periods: 2 unit: Count description: \(aqDynamoDB ConsumedWriteCapacityUnits\(aq alarm_actions: [ \(aqarn:aws:sns:us\-east\-1:1234:my\-alarm\(aq ] insufficient_data_actions: [] ok_actions: [ \(aqarn:aws:sns:us\-east\-1:1234:my\-alarm\(aq ] \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs \- region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp You can also use alarms from pillars, and override values from the pillar alarms by setting overrides on the resource. Note that \(aqboto_dynamodb_alarms\(aq will be used as a default value for all resources, if defined and can be used to ensure alarms are always set for a resource. .sp Setting the alarms in a pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C boto_dynamodb_alarms: ConsumedWriteCapacityUnits: name: \(aqDynamoDB ConsumedWriteCapacityUnits **MANAGED BY SALT**\(aq attributes: metric: ConsumedWriteCapacityUnits namespace: AWS/DynamoDB statistic: Sum comparison: \(aq>=\(aq # threshold_percent is used to calculate the actual threshold # based on the provisioned capacity for the table. threshold_percent: 0.75 period: 300 evaluation_periods: 2 unit: Count description: \(aqDynamoDB ConsumedWriteCapacityUnits\(aq alarm_actions: [ \(aqarn:aws:sns:us\-east\-1:1234:my\-alarm\(aq ] insufficient_data_actions: [] ok_actions: [ \(aqarn:aws:sns:us\-east\-1:1234:my\-alarm\(aq ] Ensure DynamoDB table exists: boto_dynamodb.present: \- name: new_table \- read_capacity_units: 1 \- write_capacity_units: 2 \- hash_key: primary_id \- hash_key_data_type: N \- range_key: start_timestamp \- range_key_data_type: N \- alarms: ConsumedWriteCapacityUnits: attributes: threshold_percent: 0.90 period: 900 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B exception salt.states.boto_dynamodb.GsiNotUpdatableError Raised when a global secondary index cannot be updated. .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_dynamodb.absent(name, region=None, key=None, keyid=None, profile=None) Ensure the DynamoDB table does not exist. .INDENT 7.0 .TP .B name Name of the DynamoDB table. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_dynamodb.present(name=None, table_name=None, region=None, key=None, keyid=None, profile=None, read_capacity_units=None, write_capacity_units=None, alarms=None, alarms_from_pillar=\(aqboto_dynamodb_alarms\(aq, hash_key=None, hash_key_data_type=None, range_key=None, range_key_data_type=None, local_indexes=None, global_indexes=None, backup_configs_from_pillars=\(aqboto_dynamodb_backup_configs\(aq) Ensure the DynamoDB table exists. Table throughput can be updated after table creation. .sp Global secondary indexes (GSIs) are managed with some exceptions: .INDENT 7.0 .IP \(bu 2 If a GSI deletion is detected, a failure will occur (deletes should be done manually in the AWS console). .IP \(bu 2 If multiple GSIs are added in a single Salt call, a failure will occur (boto supports one creation at a time). Note that this only applies after table creation; multiple GSIs can be created during table creation. .IP \(bu 2 Updates to existing GSIs are limited to read/write capacity only (DynamoDB limitation). .UNINDENT .INDENT 7.0 .TP .B name Name of the DynamoDB table .TP .B table_name Name of the DynamoDB table (deprecated) .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B read_capacity_units The read throughput for this table .TP .B write_capacity_units The write throughput for this table .TP .B hash_key The name of the attribute that will be used as the hash key for this table .TP .B hash_key_data_type The DynamoDB datatype of the hash key .TP .B range_key The name of the attribute that will be used as the range key for this table .TP .B range_key_data_type The DynamoDB datatype of the range key .TP .B local_indexes The local indexes you would like to create .TP .B global_indexes The global indexes you would like to create .TP .B backup_configs_from_pillars Pillars to use to configure DataPipeline backups .UNINDENT .UNINDENT .SS salt.states.boto_ec2 .sp Manage EC2 .sp New in version 2015.8.0. .sp This module provides an interface to the Elastic Compute Cloud (EC2) service from AWS. .sp The below code creates a key pair: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create\-key\-pair: boto_ec2.key_present: \- name: mykeypair \- save_private: /root/ \- region: eu\-west\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import\-key\-pair: boto_ec2.key_present: \- name: mykeypair \- upload_public: \(aqssh\-rsa AAAA\(aq \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp You can also use salt:// in order to define the public key. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import\-key\-pair: boto_ec2.key_present: \- name: mykeypair \- upload_public: salt://mybase/public_key.pub \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp The below code deletes a key pair: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C delete\-key\-pair: boto_ec2.key_absent: \- name: mykeypair \- region: eu\-west\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_ec2.eni_absent(name, release_eip=False, region=None, key=None, keyid=None, profile=None) Ensure the EC2 ENI is absent. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name Name tag associated with the ENI. .TP .B release_eip True/False \- release any EIP associated with the ENI .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_ec2.eni_present(name, subnet_id=None, subnet_name=None, private_ip_address=None, description=None, groups=None, source_dest_check=True, allocate_eip=None, arecords=None, region=None, key=None, keyid=None, profile=None) Ensure the EC2 ENI exists. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name Name tag associated with the ENI. .TP .B subnet_id The VPC subnet ID the ENI will exist within. .TP .B subnet_name The VPC subnet name the ENI will exist within. .TP .B private_ip_address The private ip address to use for this ENI. If this is not specified AWS will automatically assign a private IP address to the ENI. Must be specified at creation time; will be ignored afterward. .TP .B description Description of the key. .TP .B groups A list of security groups to apply to the ENI. .TP .B source_dest_check Boolean specifying whether source/destination checking is enabled on the ENI. .TP .B allocate_eip allocate and associate an EIP to the ENI. Could be \(aqstandard\(aq to allocate Elastic IP to EC2 region or \(aqvpc\(aq to get it for a particular VPC .sp Changed in version 2016.11.0. .TP .B arecords A list of arecord dicts with attributes needed for the DNS add_record state. By default the boto_route53.add_record state will be used, which requires: name, zone, ttl, and identifier. See the boto_route53 state for information about these attributes. Other DNS modules can be called by specifying the provider keyword. By default, the private ENI IP address will be used, set \(aqpublic: True\(aq in the arecord dict to use the ENI\(aqs public IP address .sp New in version 2016.3.0. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_ec2.instance_absent(name, instance_name=None, instance_id=None, release_eip=False, region=None, key=None, keyid=None, profile=None, filters=None) Ensure an EC2 instance does not exist (is stopped and removed). .sp Changed in version 2016.11.0. .INDENT 7.0 .TP .B name (string) \- The name of the state definition. .TP .B instance_name (string) \- The name of the instance. .TP .B instance_id (string) \- The ID of the instance. .TP .B release_eip (bool) \- Release any associated EIPs during termination. .TP .B region (string) \- Region to connect to. .TP .B key (string) \- Secret key to be used. .TP .B keyid (string) \- Access key to be used. .TP .B profile (variable) \- A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B filters (dict) \- A dict of additional filters to use in matching the instance to delete. .UNINDENT .sp YAML example fragment: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- filters: vpc\-id: vpc\-abcdef12 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_ec2.instance_present(name, instance_name=None, instance_id=None, image_id=None, image_name=None, tags=None, key_name=None, security_groups=None, user_data=None, instance_type=None, placement=None, kernel_id=None, ramdisk_id=None, vpc_id=None, vpc_name=None, monitoring_enabled=None, subnet_id=None, subnet_name=None, private_ip_address=None, block_device_map=None, disable_api_termination=None, instance_initiated_shutdown_behavior=None, placement_group=None, client_token=None, security_group_ids=None, security_group_names=None, additional_info=None, tenancy=None, instance_profile_arn=None, instance_profile_name=None, ebs_optimized=None, network_interfaces=None, network_interface_name=None, network_interface_id=None, attributes=None, target_state=None, public_ip=None, allocation_id=None, allocate_eip=False, region=None, key=None, keyid=None, profile=None) Ensure an EC2 instance is running with the given attributes and state. .INDENT 7.0 .TP .B name (string) \- The name of the state definition. Recommended that this match the instance_name attribute (generally the FQDN of the instance). .TP .B instance_name (string) \- The name of the instance, generally its FQDN. Exclusive with \(aqinstance_id\(aq. .TP .B instance_id (string) \- The ID of the instance (if known). Exclusive with \(aqinstance_name\(aq. .TP .B image_id (string) – The ID of the AMI image to run. .TP .B image_name (string) – The name of the AMI image to run. .TP .B tags (dict) \- Tags to apply to the instance. .TP .B key_name (string) – The name of the key pair with which to launch instances. .TP .B security_groups (list of strings) – The names of the EC2 classic security groups with which to associate instances .TP .B user_data (string) – The Base64\-encoded MIME user data to be made available to the instance(s) in this reservation. .TP .B instance_type (string) – The EC2 instance size/type. Note that only certain types are compatible with HVM based AMIs. .TP .B placement (string) – The Availability Zone to launch the instance into. .TP .B kernel_id (string) – The ID of the kernel with which to launch the instances. .TP .B ramdisk_id (string) – The ID of the RAM disk with which to launch the instances. .TP .B vpc_id (string) \- The ID of a VPC to attach the instance to. .TP .B vpc_name (string) \- The name of a VPC to attach the instance to. .TP .B monitoring_enabled (bool) – Enable detailed CloudWatch monitoring on the instance. .TP .B subnet_id (string) – The ID of the subnet within which to launch the instances for VPC. .TP .B subnet_name (string) – The name of the subnet within which to launch the instances for VPC. .TP .B private_ip_address (string) – If you’re using VPC, you can optionally use this parameter to assign the instance a specific available IP address from the subnet (e.g., 10.0.0.25). .TP .B block_device_map (boto.ec2.blockdevicemapping.BlockDeviceMapping) – A BlockDeviceMapping data structure describing the EBS volumes associated with the Image. .TP .B disable_api_termination (bool) – If True, the instances will be locked and will not be able to be terminated via the API. .TP .B instance_initiated_shutdown_behavior (string) – Specifies whether the instance stops or terminates on instance\-initiated shutdown. Valid values are: .INDENT 7.0 .IP \(bu 2 \(aqstop\(aq .IP \(bu 2 \(aqterminate\(aq .UNINDENT .TP .B placement_group (string) – If specified, this is the name of the placement group in which the instance(s) will be launched. .TP .B client_token (string) – Unique, case\-sensitive identifier you provide to ensure idempotency of the request. Maximum 64 ASCII characters. .TP .B security_group_ids (list of strings) – The IDs of the VPC security groups with which to associate instances. .TP .B security_group_names (list of strings) – The names of the VPC security groups with which to associate instances. .TP .B additional_info (string) – Specifies additional information to make available to the instance(s). .TP .B tenancy (string) – The tenancy of the instance you want to launch. An instance with a tenancy of ‘dedicated’ runs on single\-tenant hardware and can only be launched into a VPC. Valid values are:”default” or “dedicated”. NOTE: To use dedicated tenancy you MUST specify a VPC subnet\-ID as well. .TP .B instance_profile_arn (string) – The Amazon resource name (ARN) of the IAM Instance Profile (IIP) to associate with the instances. .TP .B instance_profile_name (string) – The name of the IAM Instance Profile (IIP) to associate with the instances. .TP .B ebs_optimized (bool) – Whether the instance is optimized for EBS I/O. This optimization provides dedicated throughput to Amazon EBS and a tuned configuration stack to provide optimal EBS I/O performance. This optimization isn’t available with all instance types. .TP .B network_interfaces (boto.ec2.networkinterface.NetworkInterfaceCollection) – A NetworkInterfaceCollection data structure containing the ENI specifications for the instance. .TP .B network_interface_name .INDENT 7.0 .INDENT 3.5 (string) \- The name of Elastic Network Interface to attach .UNINDENT .UNINDENT .sp New in version 2016.11.0. .TP .B network_interface_id .INDENT 7.0 .INDENT 3.5 (string) \- The id of Elastic Network Interface to attach .UNINDENT .UNINDENT .sp New in version 2016.11.0. .TP .B attributes (dict) \- Instance attributes and value to be applied to the instance. Available options are: .INDENT 7.0 .IP \(bu 2 instanceType \- A valid instance type (m1.small) .IP \(bu 2 kernel \- Kernel ID (None) .IP \(bu 2 ramdisk \- Ramdisk ID (None) .IP \(bu 2 userData \- Base64 encoded String (None) .IP \(bu 2 disableApiTermination \- Boolean (true) .IP \(bu 2 instanceInitiatedShutdownBehavior \- stop|terminate .IP \(bu 2 blockDeviceMapping \- List of strings \- ie: [‘/dev/sda=false’] .IP \(bu 2 sourceDestCheck \- Boolean (true) .IP \(bu 2 groupSet \- Set of Security Groups or IDs .IP \(bu 2 ebsOptimized \- Boolean (false) .IP \(bu 2 sriovNetSupport \- String \- ie: ‘simple’ .UNINDENT .TP .B target_state (string) \- The desired target state of the instance. Available options are: .INDENT 7.0 .IP \(bu 2 running .IP \(bu 2 stopped .UNINDENT .sp Note that this option is currently UNIMPLEMENTED. .TP .B public_ip: (string) \- The IP of a previously allocated EIP address, which will be attached to the instance. EC2 Classic instances ONLY \- for VCP pass in an allocation_id instead. .TP .B allocation_id: (string) \- The ID of a previously allocated EIP address, which will be attached to the instance. VPC instances ONLY \- for Classic pass in a public_ip instead. .TP .B allocate_eip: (bool) \- Allocate and attach an EIP on\-the\-fly for this instance. Note you\(aqll want to release this address when terminating the instance, either manually or via the \(aqrelease_eip\(aq flag to \(aqinstance_absent\(aq. .TP .B region (string) \- Region to connect to. .TP .B key (string) \- Secret key to be used. .TP .B keyid (string) \- Access key to be used. .TP .B profile (variable) \- A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_ec2.key_absent(name, region=None, key=None, keyid=None, profile=None) Deletes a key pair .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_ec2.key_present(name, save_private=None, upload_public=None, region=None, key=None, keyid=None, profile=None) Ensure key pair is present. .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_ec2.private_ips_absent(name, network_interface_name=None, network_interface_id=None, private_ip_addresses=None, region=None, key=None, keyid=None, profile=None) Ensure an ENI does not have secondary private ip addresses associated with it .INDENT 7.0 .TP .B name (String) \- State definition name .TP .B network_interface_id (String) \- The EC2 network interface id, example eni\-123456789 .TP .B private_ip_addresses (List or String) \- The secondary private ip address(es) that should be absent on the ENI. .TP .B region (string) \- Region to connect to. .TP .B key (string) \- Secret key to be used. .TP .B keyid (string) \- Access key to be used. .TP .B profile (variable) \- A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_ec2.private_ips_present(name, network_interface_name=None, network_interface_id=None, private_ip_addresses=None, allow_reassignment=False, region=None, key=None, keyid=None, profile=None) Ensure an ENI has secondary private ip addresses associated with it .INDENT 7.0 .TP .B name (String) \- State definition name .TP .B network_interface_id (String) \- The EC2 network interface id, example eni\-123456789 .TP .B private_ip_addresses (List or String) \- The secondary private ip address(es) that should be present on the ENI. .TP .B allow_reassignment (Boolean) \- If true, will reassign a secondary private ip address associated with another ENI. If false, state will fail if the secondary private ip address is associated with another ENI. .TP .B region (string) \- Region to connect to. .TP .B key (string) \- Secret key to be used. .TP .B keyid (string) \- Access key to be used. .TP .B profile (variable) \- A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_ec2.snapshot_created(name, ami_name, instance_name, wait_until_available=True, wait_timeout_seconds=300, **kwargs) Create a snapshot from the given instance .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_ec2.volume_absent(name, volume_name=None, volume_id=None, instance_name=None, instance_id=None, device=None, region=None, key=None, keyid=None, profile=None) Ensure the EC2 volume is detached and absent. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B name State definition name. .TP .B volume_name Name tag associated with the volume. For safety, if this matches more than one volume, the state will refuse to apply. .TP .B volume_id Resource ID of the volume. .TP .B instance_name Only remove volume if it is attached to instance with this Name tag. Exclusive with \(aqinstance_id\(aq. Requires \(aqdevice\(aq. .TP .B instance_id Only remove volume if it is attached to this instance. Exclusive with \(aqinstance_name\(aq. Requires \(aqdevice\(aq. .TP .B device Match by device rather than ID. Requires one of \(aqinstance_name\(aq or \(aqinstance_id\(aq. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_ec2.volume_present(name, volume_name=None, volume_id=None, instance_name=None, instance_id=None, device=None, size=None, snapshot_id=None, volume_type=None, iops=None, encrypted=False, kms_key_id=None, region=None, key=None, keyid=None, profile=None) Ensure the EC2 volume is present and attached. .INDENT 7.0 .TP .B name State definition name. .TP .B volume_name The Name tag value for the volume. If no volume with that matching name tag is found, a new volume will be created. If multiple volumes are matched, the state will fail. .TP .B volume_id Resource ID of the volume. Exclusive with \(aqvolume_name\(aq. .TP .B instance_name Attach volume to instance with this Name tag. Exclusive with \(aqinstance_id\(aq. .TP .B instance_id Attach volume to instance with this ID. Exclusive with \(aqinstance_name\(aq. .TP .B device The device on the instance through which the volume is exposed (e.g. /dev/sdh) .TP .B size The size of the new volume, in GiB. If you\(aqre creating the volume from a snapshot and don\(aqt specify a volume size, the default is the snapshot size. Optionally specified at volume creation time; will be ignored afterward. Requires \(aqvolume_name\(aq. .TP .B snapshot_id The snapshot ID from which the new Volume will be created. Optionally specified at volume creation time; will be ignored afterward. Requires \(aqvolume_name\(aq. .TP .B volume_type The type of the volume. Optionally specified at volume creation time; will be ignored afterward. Requires \(aqvolume_name\(aq. Valid volume types for AWS can be found here: \fI\%http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html\fP .TP .B iops The provisioned IOPS you want to associate with this volume. Optionally specified at volume creation time; will be ignored afterward. Requires \(aqvolume_name\(aq. .TP .B encrypted Specifies whether the volume should be encrypted. Optionally specified at volume creation time; will be ignored afterward. Requires \(aqvolume_name\(aq. .TP .B kms_key_id If encrypted is True, this KMS Key ID may be specified to encrypt volume with this key. Optionally specified at volume creation time; will be ignored afterward. Requires \(aqvolume_name\(aq. e.g.: arn:aws:kms:us\-east\-1:012345678910:key/abcd1234\-a123\-456a\-a12b\-a123b4cd56ef .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_ec2.volumes_tagged(name, tag_maps, authoritative=False, region=None, key=None, keyid=None, profile=None) Ensure EC2 volume(s) matching the given filters have the defined tags. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B name State definition name. .TP .B tag_maps List of dicts of filters and tags, where \(aqfilters\(aq is a dict suitable for passing to the \(aqfilters\(aq argument of boto_ec2.get_all_volumes(), and \(aqtags\(aq is a dict of tags to be set on volumes as matched by the given filters. The filter syntax is extended to permit passing either a list of volume_ids or an instance_name (with instance_name being the Name tag of the instance to which the desired volumes are mapped). Each mapping in the list is applied separately, so multiple sets of volumes can be all tagged differently with one call to this function. .UNINDENT .sp YAML example fragment: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- filters: attachment.instance_id: i\-abcdef12 tags: Name: dev\-int\-abcdef12.aws\-foo.com \- filters: attachment.device: /dev/sdf tags: ManagedSnapshots: true BillingGroup: bubba.hotep@aws\-foo.com \- filters: instance_name: prd\-foo\-01.aws\-foo.com tags: Name: prd\-foo\-01.aws\-foo.com BillingGroup: infra\-team@aws\-foo.com \- filters: volume_ids: [ vol\-12345689, vol\-abcdef12 ] tags: BillingGroup: infra\-team@aws\-foo.com .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B authoritative Should un\-declared tags currently set on matched volumes be deleted? Boolean. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_elasticache .SS Manage Elasticache .sp New in version 2014.7.0. .sp Create, destroy and update Elasticache clusters. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp Note: This module currently only supports creation and deletion of elasticache resources and will not modify clusters when their configuration changes in your state files. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit elasticache credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C elasticache.keyid: GKTADJGHEIQSXMKKRBJ08H elasticache.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure myelasticache exists: boto_elasticache.present: \- name: myelasticache \- engine: redis \- cache_node_type: cache.t1.micro \- num_cache_nodes: 1 \- notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs # Using a profile from pillars Ensure myelasticache exists: boto_elasticache.present: \- name: myelasticache \- engine: redis \- cache_node_type: cache.t1.micro \- num_cache_nodes: 1 \- notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic \- region: us\-east\-1 \- profile: myprofile # Passing in a profile Ensure myelasticache exists: boto_elasticache.present: \- name: myelasticache \- engine: redis \- cache_node_type: cache.t1.micro \- num_cache_nodes: 1 \- notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic \- region: us\-east\-1 \- profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elasticache.absent(name, wait=True, region=None, key=None, keyid=None, profile=None) Ensure the named elasticache cluster is deleted. .INDENT 7.0 .TP .B name Name of the cache cluster. .TP .B wait Boolean. Wait for confirmation from boto that the cluster is in the deleting state. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elasticache.cache_cluster_absent(*args, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elasticache.cache_cluster_present(*args, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elasticache.creategroup(name, primary_cluster_id, replication_group_description, wait=None, region=None, key=None, keyid=None, profile=None) Ensure the a replication group is create. .INDENT 7.0 .TP .B name Name of replication group .TP .B wait Waits for the group to be available .TP .B primary_cluster_id Name of the master cache node .TP .B replication_group_description Description for the group .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elasticache.present(name, engine=None, cache_node_type=None, num_cache_nodes=None, preferred_availability_zone=None, port=None, cache_parameter_group_name=None, cache_security_group_names=None, replication_group_id=None, auto_minor_version_upgrade=True, security_group_ids=None, cache_subnet_group_name=None, engine_version=None, notification_topic_arn=None, preferred_maintenance_window=None, wait=None, region=None, key=None, keyid=None, profile=None) Ensure the cache cluster exists. .INDENT 7.0 .TP .B name Name of the cache cluster (cache cluster id). .TP .B engine The name of the cache engine to be used for this cache cluster. Valid values are memcached or redis. .TP .B cache_node_type The compute and memory capacity of the nodes in the cache cluster. cache.t1.micro, cache.m1.small, etc. See: \fI\%https://boto.readthedocs.io/en/latest/ref/elasticache.html#boto.elasticache.layer1.ElastiCacheConnection.create_cache_cluster\fP .TP .B num_cache_nodes The number of cache nodes that the cache cluster will have. .TP .B preferred_availability_zone The EC2 Availability Zone in which the cache cluster will be created. All cache nodes belonging to a cache cluster are placed in the preferred availability zone. .TP .B port The port number on which each of the cache nodes will accept connections. .TP .B cache_parameter_group_name The name of the cache parameter group to associate with this cache cluster. If this argument is omitted, the default cache parameter group for the specified engine will be used. .TP .B cache_security_group_names A list of cache security group names to associate with this cache cluster. Use this parameter only when you are creating a cluster outside of a VPC. .TP .B replication_group_id The replication group to which this cache cluster should belong. If this parameter is specified, the cache cluster will be added to the specified replication group as a read replica; otherwise, the cache cluster will be a standalone primary that is not part of any replication group. .TP .B auto_minor_version_upgrade Determines whether minor engine upgrades will be applied automatically to the cache cluster during the maintenance window. A value of True allows these upgrades to occur; False disables automatic upgrades. .TP .B security_group_ids One or more VPC security groups associated with the cache cluster. Use this parameter only when you are creating a cluster in a VPC. .TP .B cache_subnet_group_name The name of the cache subnet group to be used for the cache cluster. Use this parameter only when you are creating a cluster in a VPC. .TP .B engine_version The version number of the cache engine to be used for this cluster. .TP .B notification_topic_arn The Amazon Resource Name (ARN) of the Amazon Simple Notification Service (SNS) topic to which notifications will be sent. The Amazon SNS topic owner must be the same as the cache cluster owner. .TP .B preferred_maintenance_window The weekly time range (in UTC) during which system maintenance can occur. Example: sun:05:00\-sun:09:00 .TP .B wait Boolean. Wait for confirmation from boto that the cluster is in the available state. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elasticache.replication_group_absent(name, tags=None, region=None, key=None, keyid=None, profile=None) .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elasticache.replication_group_present(*args, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elasticache.subnet_group_absent(name, tags=None, region=None, key=None, keyid=None, profile=None) .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elasticache.subnet_group_present(name, subnet_ids=None, subnet_names=None, description=None, tags=None, region=None, key=None, keyid=None, profile=None) Ensure ElastiCache subnet group exists. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B name The name for the ElastiCache subnet group. This value is stored as a lowercase string. .TP .B subnet_ids A list of VPC subnet IDs for the cache subnet group. Exclusive with subnet_names. .TP .B subnet_names A list of VPC subnet names for the cache subnet group. Exclusive with subnet_ids. .TP .B description Subnet group description. .TP .B tags A list of tags. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_elasticsearch_domain .SS Manage Elasticsearch Domains .sp New in version 2016.11.0. .sp Create and destroy Elasticsearch domains. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto3\fP, which can be installed via package, or pip. .sp This module accepts explicit vpc credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vpc.keyid: GKTADJGHEIQSXMKKRBJ08H vpc.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure domain exists: boto_elasticsearch_domain.present: \- DomainName: mydomain \- profile=\(aquser\-credentials\(aq \- ElasticsearchVersion: \(dq2.3\(dq \- ElasticsearchClusterConfig: InstanceType\(dq: \(dqt2.micro.elasticsearch\(dq InstanceCount: 1 DedicatedMasterEnabled: False ZoneAwarenessEnabled: False \- EBSOptions: EBSEnabled: True VolumeType: \(dqgp2\(dq VolumeSize: 10 Iops: 0 \- AccessPolicies: Version: \(dq2012\-10\-17\(dq Statement: \- Effect: \(dqAllow\(dq \- Principal: AWS: \(dq*\(dq \- Action: \- \(dqes:*\(dq \- Resource: \(dqarn:aws:es:*:111111111111:domain/mydomain/*\(dq \- Condition: IpAddress: \(dqaws:SourceIp\(dq: \- \(dq127.0.0.1\(dq \- \(dq127.0.0.2\(dq \- SnapshotOptions: AutomatedSnapshotStartHour: 0 \- AdvancedOptions: rest.action.multi.allow_explicit_index\(dq: \(dqtrue\(dq \- Tags: a: \(dqb\(dq \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elasticsearch_domain.absent(name, DomainName, region=None, key=None, keyid=None, profile=None) Ensure domain with passed properties is absent. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B DomainName Name of the domain. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elasticsearch_domain.present(name, DomainName, ElasticsearchClusterConfig=None, EBSOptions=None, AccessPolicies=None, SnapshotOptions=None, AdvancedOptions=None, Tags=None, region=None, key=None, keyid=None, profile=None, ElasticsearchVersion=\(aq1.5\(aq) Ensure domain exists. .INDENT 7.0 .TP .B name The name of the state definition .TP .B DomainName Name of the domain. .TP .B ElasticsearchClusterConfig Configuration options for an Elasticsearch domain. Specifies the instance type and number of instances in the domain cluster. .sp InstanceType (string) \-\- The instance type for an Elasticsearch cluster. .sp InstanceCount (integer) \-\- The number of instances in the specified domain cluster. .sp DedicatedMasterEnabled (boolean) \-\- A boolean value to indicate whether a dedicated master node is enabled. See About Dedicated Master Nodes for more information. .sp ZoneAwarenessEnabled (boolean) \-\- A boolean value to indicate whether zone awareness is enabled. See About Zone Awareness for more information. .sp DedicatedMasterType (string) \-\- The instance type for a dedicated master node. .sp DedicatedMasterCount (integer) \-\- Total number of dedicated master nodes, active and on standby, for the cluster. .TP .B EBSOptions Options to enable, disable and specify the type and size of EBS storage volumes. .sp EBSEnabled (boolean) \-\- Specifies whether EBS\-based storage is enabled. .sp VolumeType (string) \-\- Specifies the volume type for EBS\-based storage. .sp VolumeSize (integer) \-\- Integer to specify the size of an EBS volume. .sp Iops (integer) \-\- Specifies the IOPD for a Provisioned IOPS EBS volume (SSD). .TP .B AccessPolicies IAM access policy .TP .B SnapshotOptions Option to set time, in UTC format, of the daily automated snapshot. Default value is 0 hours. .sp AutomatedSnapshotStartHour (integer) \-\- Specifies the time, in UTC format, when the service takes a daily automated snapshot of the specified Elasticsearch domain. Default value is 0 hours. .TP .B AdvancedOptions Option to allow references to indices in an HTTP request body. Must be false when configuring access to individual sub\-resources. By default, the value is true . .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B ElasticsearchVersion String of format X.Y to specify version for the Elasticsearch domain eg. \(dq1.5\(dq or \(dq2.3\(dq. .UNINDENT .UNINDENT .SS salt.states.boto_elb .sp Manage ELBs .sp New in version 2014.7.0. .sp Create and destroy ELBs. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit elb credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C elb.keyid: GKTADJGHEIQSXMKKRBJ08H elb.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure myelb ELB exists: boto_elb.present: \- name: myelb \- region: us\-east\-1 \- availability_zones: \- us\-east\-1a \- us\-east\-1c \- us\-east\-1d \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs \- listeners: \- elb_port: 443 instance_port: 80 elb_protocol: HTTPS instance_protocol: HTTP certificate: \(aqarn:aws:iam::1111111:server\-certificate/mycert\(aq policies: \- my\-ssl\-policy \- cookie\-policy \- elb_port: 8210 instance_port: 8210 elb_protocol: TCP \- backends: \- instance_port: 80 policies: \- enable\-proxy\-protocol \- health_check: target: \(aqHTTP:80/\(aq \- attributes: cross_zone_load_balancing: enabled: true access_log: enabled: true s3_bucket_name: \(aqmybucket\(aq s3_bucket_prefix: \(aqmy\-logs\(aq emit_interval: 5 connecting_settings: idle_timeout: 60 \- cnames: \- name: mycname.example.com. zone: example.com. ttl: 60 \- name: myothercname.example.com. zone: example.com. \- security_groups: \- my\-security\-group \- policies: \- policy_name: my\-ssl\-policy policy_type: SSLNegotiationPolicyType policy: Protocol\-TLSv1.2: true Protocol\-SSLv3: false Server\-Defined\-Cipher\-Order: true ECDHE\-ECDSA\-AES128\-GCM\-SHA256: true \- policy_name: cookie\-policy policy_type: LBCookieStickinessPolicyType policy: {} # no policy means this is a session cookie \- policy_name: enable\-proxy\-protocol policy_type: ProxyProtocolPolicyType policy: ProxyProtocol: true # Using a profile from pillars Ensure myelb ELB exists: boto_elb.present: \- name: myelb \- region: us\-east\-1 \- profile: myelbprofile # Passing in a profile Ensure myelb ELB exists: boto_elb.present: \- name: myelb \- region: us\-east\-1 \- profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs possible to specify attributes from pillars by specifying a pillar. You can override the values defined in the pillard by setting the attributes on the resource. The module will use the default pillar key \(aqboto_elb_attributes\(aq, which allows you to set default attributes for all ELB resources. .sp Setting the attributes pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_elb_attributes: cross_zone_load_balancing: enabled: true connection_draining: enabled: true timeout: 20 access_log: enabled: true s3_bucket_name: \(aqmybucket\(aq s3_bucket_prefix: \(aqmy\-logs\(aq emit_interval: 5 .ft P .fi .UNINDENT .UNINDENT .sp Overriding the attribute values on the resource: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure myelb ELB exists: boto_elb.present: \- name: myelb \- region: us\-east\-1 \- attributes_from_pillar: my_elb_attributes # override cross_zone_load_balancing:enabled \- attributes: cross_zone_load_balancing: enabled: false \- profile: myelbprofile .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs possible to specify cloudwatch alarms that will be setup along with the ELB. Note the alarm name will be defined by the name attribute provided, plus the ELB resource name. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure myelb ELB exists: boto_elb.present: \- name: myelb \- region: us\-east\-1 \- profile: myelbprofile \- alarms: UnHealthyHostCount: name: \(aqELB UnHealthyHostCount **MANAGED BY SALT**\(aq attributes: metric: UnHealthyHostCount namespace: AWS/ELB statistic: Average comparison: \(aq>=\(aq threshold: 1.0 period: 600 evaluation_periods: 6 unit: null description: ELB UnHealthyHostCount alarm_actions: [\(aqarn:aws:sns:us\-east\-1:12345:myalarm\(aq] insufficient_data_actions: [] ok_actions: [\(aqarn:aws:sns:us\-east\-1:12345:myalarm\(aq] .ft P .fi .UNINDENT .UNINDENT .sp You can also use alarms from pillars, and override values from the pillar alarms by setting overrides on the resource. Note that \(aqboto_elb_alarms\(aq will be used as a default value for all resources, if defined and can be used to ensure alarms are always set for a resource. .sp Setting the alarms in a pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_elb_alarm: UnHealthyHostCount: name: \(aqELB UnHealthyHostCount **MANAGED BY SALT**\(aq attributes: metric: UnHealthyHostCount namespace: AWS/ELB statistic: Average comparison: \(aq>=\(aq threshold: 1.0 period: 600 evaluation_periods: 6 unit: null description: ELB UnHealthyHostCount alarm_actions: [\(aqarn:aws:sns:us\-east\-1:12345:myalarm\(aq] insufficient_data_actions: [] ok_actions: [\(aqarn:aws:sns:us\-east\-1:12345:myalarm\(aq] .ft P .fi .UNINDENT .UNINDENT .sp Overriding the alarm values on the resource: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure myelb ELB exists: boto_elb.present: \- name: myelb \- region: us\-east\-1 \- profile: myelbprofile \- alarms_from_pillar: my_elb_alarm # override UnHealthyHostCount:attributes:threshold \- alarms: UnHealthyHostCount: attributes: threshold: 2.0 .ft P .fi .UNINDENT .UNINDENT .sp Tags can also be set: .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure myelb ELB exists: boto_elb.present: \- name: myelb \- region: us\-east\-1 \- profile: myelbprofile \- tags: MyTag: \(aqMy Tag Value\(aq OtherTag: \(aqMy Other Value\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elb.absent(name, region=None, key=None, keyid=None, profile=None) Ensure an ELB does not exist .INDENT 7.0 .TP .B name name of the ELB .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elb.present(name, listeners, availability_zones=None, subnets=None, subnet_names=None, security_groups=None, scheme=\(aqinternet\-facing\(aq, health_check=None, attributes=None, attributes_from_pillar=\(aqboto_elb_attributes\(aq, cnames=None, alarms=None, alarms_from_pillar=\(aqboto_elb_alarms\(aq, policies=None, policies_from_pillar=\(aqboto_elb_policies\(aq, backends=None, region=None, key=None, keyid=None, profile=None, wait_for_sync=True, tags=None, instance_ids=None, instance_names=None) Ensure the ELB exists. .INDENT 7.0 .TP .B name Name of the ELB. .TP .B availability_zones A list of availability zones for this ELB. .TP .B listeners A list of listener lists; example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ [\(aq443\(aq, \(aqHTTPS\(aq, \(aqarn:aws:iam::1111111:server\-certificate/mycert\(aq], [\(aq8443\(aq, \(aq80\(aq, \(aqHTTPS\(aq, \(aqHTTP\(aq, \(aqarn:aws:iam::1111111:server\-certificate/mycert\(aq] ] .ft P .fi .UNINDENT .UNINDENT .TP .B subnets A list of subnet IDs in your VPC to attach to your LoadBalancer. .TP .B subnet_names A list of subnet names in your VPC to attach to your LoadBalancer. .TP .B security_groups The security groups assigned to your LoadBalancer within your VPC. Must be passed either as a list or a comma\-separated string. .sp For example, a list: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- security_groups: \- secgroup\-one \- secgroup\-two .ft P .fi .UNINDENT .UNINDENT .sp Or as a comma\-separated string: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- security_groups: secgroup\-one,secgroup\-two .ft P .fi .UNINDENT .UNINDENT .TP .B scheme The type of a LoadBalancer, \fBinternet\-facing\fP or \fBinternal\fP\&. Once set, can not be modified. .TP .B health_check A dict defining the health check for this ELB. .TP .B attributes A dict defining the attributes to set on this ELB. Unknown keys will be silently ignored. .sp See the \fI\%salt.modules.boto_elb.set_attributes\fP function for recognized attributes. .TP .B attributes_from_pillar name of pillar dict that contains attributes. Attributes defined for this specific state will override those from pillar. .TP .B cnames A list of cname dicts with attributes needed for the DNS add_record state. By default the boto_route53.add_record state will be used, which requires: name, zone, ttl, and identifier. See the boto_route53 state for information about these attributes. Other DNS modules can be called by specifying the provider keyword. the cnames dict will be passed to the state as kwargs. .sp See the \fI\%salt.states.boto_route53\fP state for information about these attributes. .TP .B alarms: a dictionary of name\->boto_cloudwatch_alarm sections to be associated with this ELB. All attributes should be specified except for dimension which will be automatically set to this ELB. .sp See the \fI\%salt.states.boto_cloudwatch_alarm\fP state for information about these attributes. .TP .B alarms_from_pillar: name of pillar dict that contains alarm settings. Alarms defined for this specific state will override those from pillar. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B wait_for_sync Wait for an INSYNC change status from Route53. .TP .B tags dict of tags .TP .B instance_ids list of instance ids. The state will ensure that these, and ONLY these, instances are registered with the ELB. This is additive with instance_names. .TP .B instance_names list of instance names. The state will ensure that these, and ONLY these, instances are registered with the ELB. This is additive with instance_ids. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elb.register_instances(name, instances, region=None, key=None, keyid=None, profile=None) Add EC2 instance(s) to an Elastic Load Balancer. Removing an instance from the \fBinstances\fP list does not remove it from the ELB. .INDENT 7.0 .TP .B name The name of the Elastic Load Balancer to add EC2 instances to. .TP .B instances A list of EC2 instance IDs that this Elastic Load Balancer should distribute traffic to. This state will only ever append new instances to the ELB. EC2 instances already associated with this ELB will not be removed if they are not in the \fBinstances\fP list. .UNINDENT .sp New in version 2015.8.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C add\-instances: boto_elb.register_instances: \- name: myloadbalancer \- instances: \- instance\-id1 \- instance\-id2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.boto_elbv2 .sp Manage AWS Application Load Balancer .sp New in version 2017.7.0. .sp Add and remove targets from an ALB target group. .sp This module uses \fBboto3\fP, which can be installed via package, or pip. .sp This module accepts explicit alb credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C elbv2.keyid: GKTADJGHEIQSXMKKRBJ08H elbv2.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs elbv2.region: us\-west\-2 .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elbv2.create_target_group(name, protocol, port, vpc_id, region=None, key=None, keyid=None, profile=None, health_check_protocol=\(aqHTTP\(aq, health_check_port=\(aqtraffic\-port\(aq, health_check_path=\(aq/\(aq, health_check_interval_seconds=30, health_check_timeout_seconds=5, healthy_threshold_count=5, unhealthy_threshold_count=2, **kwargs) New in version 2017.11.0. .sp Create target group if not present. .INDENT 7.0 .TP .B name (string) \- The name of the target group. .TP .B protocol (string) \- The protocol to use for routing traffic to the targets .TP .B port (int) \- The port on which the targets receive traffic. This port is used unless you specify a port override when registering the traffic. .TP .B vpc_id (string) \- The identifier of the virtual private cloud (VPC). .TP .B health_check_protocol (string) \- The protocol the load balancer uses when performing health check on targets. The default is the HTTP protocol. .TP .B health_check_port (string) \- The port the load balancer uses when performing health checks on targets. The default is \(aqtraffic\-port\(aq, which indicates the port on which each target receives traffic from the load balancer. .TP .B health_check_path (string) \- The ping path that is the destination on the targets for health checks. The default is /. .TP .B health_check_interval_seconds (integer) \- The approximate amount of time, in seconds, between health checks of an individual target. The default is 30 seconds. .TP .B health_check_timeout_seconds (integer) \- The amount of time, in seconds, during which no response from a target means a failed health check. The default is 5 seconds. .TP .B healthy_threshold_count (integer) \- The number of consecutive health checks successes required before considering an unhealthy target healthy. The default is 5. .TP .B unhealthy_threshold_count (integer) \- The number of consecutive health check failures required before considering a target unhealthy. The default is 2. .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C create\-target: boto_elb2.create_targets_group: \- name: myALB \- protocol: https \- port: 443 \- vpc_id: myVPC .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elbv2.delete_target_group(name, region=None, key=None, keyid=None, profile=None) Delete target group. .INDENT 7.0 .TP .B name (string) \- The Amazon Resource Name (ARN) of the resource. .TP .B returns (bool) \- True on success, False on failure. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check\-target: boto_elb2.delete_targets_group: \- name: myALB \- protocol: https \- port: 443 \- vpc_id: myVPC .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elbv2.targets_deregistered(name, targets, region=None, key=None, keyid=None, profile=None, **kwargs) Remove targets to an Application Load Balancer target group. .INDENT 7.0 .TP .B name The ARN of the Application Load Balancer Target Group to remove targets from. .TP .B targets A list of target IDs or a string of a single target registered to the target group to be removed .UNINDENT .sp New in version 2017.7.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C remove\-targets: boto_elb.targets_deregistered: \- name: arn:myloadbalancer \- targets: \- instance\-id1 \- instance\-id2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_elbv2.targets_registered(name, targets, region=None, key=None, keyid=None, profile=None, **kwargs) New in version 2017.7.0. .sp Add targets to an Application Load Balancer target group. This state will not remove targets. .INDENT 7.0 .TP .B name The ARN of the Application Load Balancer Target Group to add targets to. .TP .B targets A list of target IDs or a string of a single target that this target group should distribute traffic to. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C add\-targets: boto_elb.targets_registered: \- name: arn:myloadbalancer \- targets: \- instance\-id1 \- instance\-id2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.boto_iam .SS Manage IAM objects .sp New in version 2015.8.0. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit IAM credentials but 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 \fI\%here\fP\&. .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C delete\-user: boto_iam.user_absent: \- name: myuser \- delete_keys: true .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C delete\-keys: boto_iam.keys_absent: \- access_keys: \- \(aqAKIAJHTMIQ2ASDFLASDF\(aq \- \(aqPQIAJHTMIQ2ASRTLASFR\(aq \- user_name: myuser .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create\-user: boto_iam.user_present: \- name: myuser \- policies: mypolicy: | { \(dqVersion\(dq: \(dq2012\-10\-17\(dq, \(dqStatement\(dq: [{ \(dqEffect\(dq: \(dqAllow\(dq, \(dqAction\(dq: \(dq*\(dq, \(dqResource\(dq: \(dq*\(dq}] } \- password: NewPassword$$1 \- region: eu\-west\-1 \- keyid: \(aqAKIAJHTMIQ2ASDFLASDF\(aq \- key: \(aqfdkjsafkljsASSADFalkfjasdf\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create\-group: boto_iam.group_present: \- name: mygroup \- users: \- myuser \- myuser1 \- policies: mypolicy: | { \(dqVersion\(dq: \(dq2012\-10\-17\(dq, \(dqStatement\(dq: [{ \(dqEffect\(dq: \(dqAllow\(dq, \(dqAction\(dq: \(dq*\(dq, \(dqResource\(dq: \(dq*\(dq}] } \- region: eu\-west\-1 \- keyid: \(aqAKIAJHTMIQ2ASDFLASDF\(aq \- key: \(aqsafsdfsal;fdkjsafkljsASSADFalkfj\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C change\-policy: boto_iam.account_policy: \- change_password: True \- region: eu\-west\-1 \- keyid: \(aqAKIAJHTMIQ2ASDFLASDF\(aq \- key: \(aqsafsdfsal;fdkjsafkljsASSADFalkfj\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create server certificate: boto_iam.server_cert_present: \- name: mycert \- public_key: salt://base/mycert.crt \- private_key: salt://base/mycert.key \- cert_chain: salt://base/mycert_chain.crt \- region: eu\-west\-1 \- keyid: \(aqAKIAJHTMIQ2ASDFLASDF\(aq \- key: \(aqfdkjsafkljsASSADFalkfjasdf\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C delete server certificate: boto_iam.server_cert_absent: \- name: mycert .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create keys for user: boto_iam.keys_present: \- name: myusername \- number: 2 \- save_dir: /root \- region: eu\-west\-1 \- keyid: \(aqAKIAJHTMIQ2ASDFLASDF\(aq \- key: \(aqfdkjsafkljsASSADFalkfjasdf\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create policy: boto_iam.policy_present: \- name: myname \- policy_document: \(aq{\(dqMyPolicy\(dq: \(dqStatement\(dq: [{\(dqAction\(dq: [\(dqsqs:*\(dq], \(dqEffect\(dq: \(dqAllow\(dq, \(dqResource\(dq: [\(dqarn:aws:sqs:*:*:*\(dq], \(dqSid\(dq: \(dqMyPolicySqs1\(dq}]}\(aq \- region: eu\-west\-1 \- keyid: \(aqAKIAJHTMIQ2ASDFLASDF\(aq \- key: \(aqfdkjsafkljsASSADFalkfjasdf\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C add\-saml\-provider: boto_iam.saml_provider_present: \- name: my_saml_provider \- saml_metadata_document: salt://base/files/provider.xml \- keyid: \(aqAKIAJHTMIQ2ASDFLASDF\(aq \- key: \(aqsafsdfsal;fdkjsafkljsASSADFalkfj\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.account_policy(name=None, allow_users_to_change_password=None, hard_expiry=None, max_password_age=None, minimum_password_length=None, password_reuse_prevention=None, require_lowercase_characters=None, require_numbers=None, require_symbols=None, require_uppercase_characters=None, region=None, key=None, keyid=None, profile=None) Change account policy. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B name (string) The name of the account policy .TP .B allow_users_to_change_password (bool) Allows all IAM users in your account to use the AWS Management Console to change their own passwords. .TP .B hard_expiry (bool) Prevents IAM users from setting a new password after their password has expired. .TP .B max_password_age (int) The number of days that an IAM user password is valid. .TP .B minimum_password_length (int) The minimum number of characters allowed in an IAM user password. .TP .B password_reuse_prevention (int) Specifies the number of previous passwords that IAM users are prevented from reusing. .TP .B require_lowercase_characters (bool) Specifies whether IAM user passwords must contain at least one lowercase character from the ISO basic Latin alphabet (a to z). .TP .B require_numbers (bool) Specifies whether IAM user passwords must contain at least one numeric character (0 to 9). .TP .B require_symbols (bool) Specifies whether IAM user passwords must contain at least one of the following non\-alphanumeric characters: ! @ # $ % ^ & * ( ) _ + \- = [ ] { } | \(aq .TP .B require_uppercase_characters (bool) Specifies whether IAM user passwords must contain at least one uppercase character from the ISO basic Latin alphabet (A to Z). .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.group_absent(name, region=None, key=None, keyid=None, profile=None) New in version 2015.8.0. .sp Ensure the IAM group is absent. .INDENT 7.0 .TP .B name (string) The name of the group. .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.group_present(name, policies=None, policies_from_pillars=None, managed_policies=None, users=None, path=\(aq/\(aq, region=None, key=None, keyid=None, profile=None, delete_policies=True) New in version 2015.8.0. .sp Ensure the IAM group is present .INDENT 7.0 .TP .B name (string) The name of the new group. .TP .B path (string) The path for the group, defaults to \(aq/\(aq .TP .B policies (dict) A dict of IAM group policy documents. .TP .B policies_from_pillars (list) A list of pillars that contain role policy dicts. Policies in the pillars will be merged in the order defined in the list and key conflicts will be handled by later defined keys overriding earlier defined keys. The policies defined here will be merged with the policies defined in the policies argument. If keys conflict, the keys in the policies argument will override the keys defined in policies_from_pillars. .TP .B managed_policies (list) A list of policy names or ARNs that should be attached to this group. .TP .B users (list) A list of users to be added to the group. .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B delete_policies (boolean) Delete or detach existing policies that are not in the given list of policies. Default value is \fBTrue\fP\&. If \fBFalse\fP is specified, existing policies will not be deleted or detached allowing manual modifications on the IAM group to be persistent. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.keys_absent(access_keys, user_name, region=None, key=None, keyid=None, profile=None) New in version 2015.8.0. .sp Ensure the IAM user access_key_id is absent. .INDENT 7.0 .TP .B access_key_id (list) A list of access key ids .TP .B user_name (string) The username of the user .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.keys_present(name, number, save_dir, region=None, key=None, keyid=None, profile=None, save_format=\(aq{2}\en{0}\en{3}\en{1}\en\(aq) New in version 2015.8.0. .sp Ensure the IAM access keys are present. .INDENT 7.0 .TP .B name (string) The name of the new user. .TP .B number (int) Number of keys that user should have. .TP .B save_dir (string) The directory that the key/keys will be saved. Keys are saved to a file named according to the username privided. .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B save_format (dict) Save format is repeated for each key. Default format is \(dq{2}n{0}n{3}n{1}n\(dq, where {0} and {1} are placeholders for new key_id and key respectively, whereas {2} and {3} are \(dqkey_id\-{number}\(dq and \(aqkey\-{number}\(aq strings kept for compatibility. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.policy_absent(name, region=None, key=None, keyid=None, profile=None) New in version 2015.8.0. .sp Ensure the IAM managed policy with the specified name is absent .INDENT 7.0 .TP .B name (string) The name of the new policy. .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.policy_present(name, policy_document, path=None, description=None, region=None, key=None, keyid=None, profile=None) New in version 2015.8.0. .sp Ensure the IAM managed policy is present .INDENT 7.0 .TP .B name (string) The name of the new policy. .TP .B policy_document (dict) The document of the new policy .TP .B path (string) The path in which the policy will be created. Default is \(aq/\(aq. .TP .B description (string) Description .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.saml_provider_absent(name, region=None, key=None, keyid=None, profile=None) New in version 2016.11.0. .sp Ensure the SAML provider with the specified name is absent. .INDENT 7.0 .TP .B name (string) The name of the SAML provider. .TP .B saml_metadata_document (string) The xml document of the SAML provider. .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.saml_provider_present(name, saml_metadata_document, region=None, key=None, keyid=None, profile=None) New in version 2016.11.0. .sp Ensure the SAML provider with the specified name is present. .INDENT 7.0 .TP .B name (string) The name of the SAML provider. .TP .B saml_metadata_document (string) The xml document of the SAML provider. .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.server_cert_absent(name, region=None, key=None, keyid=None, profile=None) Deletes a server certificate. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B name (string) The name for the server certificate. Do not include the path in this value. .TP .B region (string) The name of the region to connect to. .TP .B key (string) The key to be used in order to connect .TP .B keyid (string) The keyid to be used in order to connect .TP .B profile (string) The profile that contains a dict of region, key, keyid .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.server_cert_present(name, public_key, private_key, cert_chain=None, path=None, region=None, key=None, keyid=None, profile=None) Crete server certificate. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B name (string) The name for the server certificate. Do not include the path in this value. .TP .B public_key (string) The contents of the public key certificate in PEM\-encoded format. .TP .B private_key (string) The contents of the private key in PEM\-encoded format. .TP .B cert_chain (string) The contents of the certificate chain. This is typically a concatenation of the PEM\-encoded public key certificates of the chain. .TP .B path (string) The path for the server certificate. .TP .B region (string) The name of the region to connect to. .TP .B key (string) The key to be used in order to connect .TP .B keyid (string) The keyid to be used in order to connect .TP .B profile (string) The profile that contains a dict of region, key, keyid .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.user_absent(name, delete_keys=True, delete_mfa_devices=True, delete_profile=True, region=None, key=None, keyid=None, profile=None) New in version 2015.8.0. .sp Ensure the IAM user is absent. User cannot be deleted if it has keys. .INDENT 7.0 .TP .B name (string) The name of the new user. .TP .B delete_keys (bool) Delete all keys from user. .TP .B delete_mfa_devices (bool) Delete all mfa devices from user. .sp New in version 2016.3.0. .TP .B delete_profile (bool) Delete profile from user. .sp New in version 2016.3.0. .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam.user_present(name, policies=None, policies_from_pillars=None, managed_policies=None, password=None, path=None, region=None, key=None, keyid=None, profile=None) New in version 2015.8.0. .sp Ensure the IAM user is present .INDENT 7.0 .TP .B name (string) The name of the new user. .TP .B policies (dict) A dict of IAM group policy documents. .TP .B policies_from_pillars (list) A list of pillars that contain role policy dicts. Policies in the pillars will be merged in the order defined in the list and key conflicts will be handled by later defined keys overriding earlier defined keys. The policies defined here will be merged with the policies defined in the policies argument. If keys conflict, the keys in the policies argument will override the keys defined in policies_from_pillars. .TP .B managed_policies (list) A list of managed policy names or ARNs that should be attached to this user. .TP .B password (string) The password for the new user. Must comply with account policy. .TP .B path (string) The path of the user. Default is \(aq/\(aq. .sp New in version 2015.8.2. .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_iam_role .SS Manage IAM roles .sp New in version 2014.7.0. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit IAM credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C iam.keyid: GKTADJGHEIQSXMKKRBJ08H iam.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp Creating a role will automatically create an instance profile and associate it with the role. This is the default behavior of the AWS console. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myrole: boto_iam_role.present: \- region: us\-east\-1 \- key: GKTADJGHEIQSXMKKRBJ08H \- keyid: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs \- policies_from_pillars: \- shared_iam_bootstrap_policy \- policies: MySQSPolicy: Statement: \- Action: \- sqs:* Effect: Allow Resource: \- arn:aws:sqs:*:*:* Sid: MyPolicySQS1 MyS3Policy: Statement: \- Action: \- s3:GetObject Effect: Allow Resource: \- arn:aws:s3:*:*:mybucket/* # Using a credentials profile from pillars myrole: boto_iam_role.present: \- profile: myiamprofile # Passing in a credentials profile myrole: boto_iam_role.present: \- profile: key: GKTADJGHEIQSXMKKRBJ08H keyid: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp If \fBdelete_policies: False\fP is specified, existing policies that are not in the given list of policies will not be deleted. This allows manual modifications on the IAM role to be persistent. This functionality was added in 2015.8.0. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When using the \fBprofile\fP parameter and \fBregion\fP is set outside of the profile group, region is ignored and a default region will be used. .sp If \fBregion\fP is missing from the \fBprofile\fP data set, \fBus\-east\-1\fP will be used as the default region. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam_role.absent(name, region=None, key=None, keyid=None, profile=None) Ensure the IAM role is deleted. .INDENT 7.0 .TP .B name Name of the IAM role. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iam_role.present(name, policy_document=None, policy_document_from_pillars=None, path=None, policies=None, policies_from_pillars=None, managed_policies=None, create_instance_profile=True, region=None, key=None, keyid=None, profile=None, delete_policies=True) Ensure the IAM role exists. .INDENT 7.0 .TP .B name Name of the IAM role. .TP .B policy_document The policy that grants an entity permission to assume the role. (See \fI\%https://boto.readthedocs.io/en/latest/ref/iam.html#boto.iam.connection.IAMConnection.create_role\fP) .TP .B policy_document_from_pillars A pillar key that contains a role policy document. The statements defined here will be appended with the policy document statements defined in the policy_document argument. .sp New in version 2017.7.0. .TP .B path The path to the role/instance profile. (See \fI\%https://boto.readthedocs.io/en/latest/ref/iam.html#boto.iam.connection.IAMConnection.create_role\fP) .TP .B policies A dict of IAM role policies. .TP .B policies_from_pillars A list of pillars that contain role policy dicts. Policies in the pillars will be merged in the order defined in the list and key conflicts will be handled by later defined keys overriding earlier defined keys. The policies defined here will be merged with the policies defined in the policies argument. If keys conflict, the keys in the policies argument will override the keys defined in policies_from_pillars. .TP .B managed_policies A list of (AWS or Customer) managed policies to be attached to the role. .TP .B create_instance_profile A boolean of whether or not to create an instance profile and associate it with this role. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B delete_policies Deletes existing policies that are not in the given list of policies. Default value is \fBTrue\fP\&. If \fBFalse\fP is specified, existing policies will not be deleted allowing manual modifications on the IAM role to be persistent. .sp New in version 2015.8.0. .UNINDENT .UNINDENT .SS salt.states.boto_iot .SS Manage IoT Objects .sp New in version 2016.3.0. .sp Create and destroy IoT objects. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 boto .IP \(bu 2 boto3 .UNINDENT .UNINDENT .sp The dependencies listed above can be installed via package or pip. .sp This module accepts explicit vpc credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vpc.keyid: GKTADJGHEIQSXMKKRBJ08H vpc.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure policy exists: boto_iot.policy_present: \- policyName: mypolicy \- policyDocument: Version: \(dq2012\-10\-17\(dq Statement: Action: \- iot:Publish Resource: \- \(dq*\(dq Effect: \(dqAllow\(dq \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs Ensure topic rule exists: boto_iot.topic_rule_present: \- ruleName: myrule \- sql: \(dqSELECT * FROM \(aqiot/test\(aq\(dq \- description: \(aqtest rule\(aq \- ruleDisabled: false \- actions: \- lambda: functionArn: \(dqarn:aws:us\-east\-1:1234:function/functionname\(dq \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iot.policy_absent(name, policyName, region=None, key=None, keyid=None, profile=None) Ensure policy with passed properties is absent. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B policyName Name of the policy. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iot.policy_attached(name, policyName, principal, region=None, key=None, keyid=None, profile=None) Ensure policy is attached to the given principal. .INDENT 7.0 .TP .B name The name of the state definition .TP .B policyName Name of the policy. .TP .B principal The principal which can be a certificate ARN or a Cognito ID. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iot.policy_detached(name, policyName, principal, region=None, key=None, keyid=None, profile=None) Ensure policy is attached to the given principal. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B policyName Name of the policy. .TP .B principal The principal which can be a certificate ARN or a Cognito ID. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iot.policy_present(name, policyName, policyDocument, region=None, key=None, keyid=None, profile=None) Ensure policy exists. .INDENT 7.0 .TP .B name The name of the state definition .TP .B policyName Name of the policy. .TP .B policyDocument The JSON document that describes the policy. The length of the policyDocument must be a minimum length of 1, with a maximum length of 2048, excluding whitespace. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iot.thing_type_absent(name, thingTypeName, region=None, key=None, keyid=None, profile=None) Ensure thing type with passed properties is absent. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B thingTypeName Name of the thing type. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iot.thing_type_present(name, thingTypeName, thingTypeDescription, searchableAttributesList, region=None, key=None, keyid=None, profile=None) Ensure thing type exists. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B name The name of the state definition .TP .B thingTypeName Name of the thing type .TP .B thingTypeDescription Description of the thing type .TP .B searchableAttributesList List of string attributes that are searchable for the thing type .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used .TP .B profile A dict with region, key, keyid, or a pillar key (string) that contains a dict with region, key, and keyid .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iot.topic_rule_absent(name, ruleName, region=None, key=None, keyid=None, profile=None) Ensure topic rule with passed properties is absent. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B ruleName Name of the policy. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_iot.topic_rule_present(name, ruleName, sql, actions, description=\(aq\(aq, ruleDisabled=False, region=None, key=None, keyid=None, profile=None) Ensure topic rule exists. .INDENT 7.0 .TP .B name The name of the state definition .TP .B ruleName Name of the rule. .TP .B sql The SQL statement used to query the topic. .TP .B actions The actions associated with the rule. .TP .B description The description of the rule. .TP .B ruleDisable Specifies whether the rule is disabled. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_kinesis .SS Manage Kinesis Streams .sp New in version 2017.7.0. .sp Create and destroy Kinesis streams. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto3\fP, which can be installed via package, or pip. .sp This module accepts explicit Kinesis credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure Kinesis stream does not exist: boto_kinesis.absent: \- name: new_stream \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs \- region: us\-east\-1 Ensure Kinesis stream exists: boto_kinesis.present: \- name: new_stream \- retention_hours: 168 \- enhanced_monitoring: [\(aqALL\(aq] \- num_shards: 2 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs \- region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_kinesis.absent(name, region=None, key=None, keyid=None, profile=None) Delete the kinesis stream, if it exists. .INDENT 7.0 .TP .B name (string) Stream name .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_kinesis.present(name, retention_hours=None, enhanced_monitoring=None, num_shards=None, do_reshard=True, region=None, key=None, keyid=None, profile=None) Ensure the kinesis stream is properly configured and scaled. .INDENT 7.0 .TP .B name (string) Stream name .TP .B retention_hours (int) Retain data for this many hours. AWS allows minimum 24 hours, maximum 168 hours. .TP .B enhanced_monitoring (list of string) Turn on enhanced monitoring for the specified shard\-level metrics. Pass in [\(aqALL\(aq] or True for all metrics, [] or False for no metrics. Turn on individual metrics by passing in a list: [\(aqIncomingBytes\(aq, \(aqOutgoingBytes\(aq] Note that if only some metrics are supplied, the remaining metrics will be turned off. .TP .B num_shards (int) Reshard stream (if necessary) to this number of shards !!!!! Resharding is expensive! Each split or merge can take up to 30 seconds, and the reshard method balances the partition space evenly. Resharding from N to N+1 can require 2N operations. Resharding is much faster with powers of 2 (e.g. 2^N to 2^N+1) !!!!! .TP .B do_reshard (boolean) If set to False, this script will NEVER reshard the stream, regardless of other input. Useful for testing. .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (dict) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_kms .sp Manage KMS keys, key policies and grants. .sp New in version 2015.8.0. .sp Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit kms credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C elb.keyid: GKTADJGHEIQSXMKKRBJ08H elb.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure mykey key exists: boto_kms.key_present: \- name: mykey \- region: us\-east\-1 # Using a profile from pillars Ensure mykey key exists: boto_kms.key_present: \- name: mykey \- region: us\-east\-1 \- profile: myprofile # Passing in a profile Ensure mykey key exists: boto_key.key_present: \- name: mykey \- region: us\-east\-1 \- profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_kms.key_present(name, policy, description=None, key_usage=None, grants=None, manage_grants=False, key_rotation=False, enabled=True, region=None, key=None, keyid=None, profile=None) Ensure the KMS key exists. KMS keys can not be deleted, so this function must be used to ensure the key is enabled or disabled. .INDENT 7.0 .TP .B name Name of the key. .TP .B policy Key usage policy. .TP .B description Description of the key. .TP .B key_usage Specifies the intended use of the key. Can only be set on creation, defaults to ENCRYPT_DECRYPT, which is also the only supported option. .TP .B grants A list of grants to apply to the key. Not currently implemented. .TP .B manage_grants Whether or not to manage grants. False by default, which will not manage any grants. .TP .B key_rotation Whether or not key rotation is enabled for the key. False by default. .TP .B enabled Whether or not the key is enabled. True by default. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_lambda .SS Manage Lambda Functions .sp New in version 2016.3.0. .sp Create and destroy Lambda Functions. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 boto .IP \(bu 2 boto3 .UNINDENT .UNINDENT .sp The dependencies listed above can be installed via package or pip. .sp This module accepts explicit vpc credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vpc.keyid: GKTADJGHEIQSXMKKRBJ08H vpc.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure function exists: boto_lambda.function_present: \- FunctionName: myfunction \- Runtime: python2.7 \- Role: iam_role_name \- Handler: entry_function \- ZipFile: code.zip \- S3Bucket: bucketname \- S3Key: keyname \- S3ObjectVersion: version \- Description: \(dqMy Lambda Function\(dq \- Timeout: 3 \- MemorySize: 128 \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_lambda.alias_absent(name, FunctionName, Name, region=None, key=None, keyid=None, profile=None) Ensure alias with passed properties is absent. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B FunctionName Name of the function. .TP .B Name Name of the alias. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_lambda.alias_present(name, FunctionName, Name, FunctionVersion, Description=\(aq\(aq, region=None, key=None, keyid=None, profile=None) Ensure alias exists. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B FunctionName Name of the function for which you want to create an alias. .TP .B Name The name of the alias to be created. .TP .B FunctionVersion Function version for which you are creating the alias. .TP .B Description A short, user\-defined function description. Lambda does not use this value. Assign a meaningful description as you see fit. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_lambda.event_source_mapping_absent(name, EventSourceArn, FunctionName, region=None, key=None, keyid=None, profile=None) Ensure event source mapping with passed properties is absent. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B EventSourceArn ARN of the event source. .TP .B FunctionName Name of the lambda function. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_lambda.event_source_mapping_present(name, EventSourceArn, FunctionName, StartingPosition, Enabled=True, BatchSize=100, region=None, key=None, keyid=None, profile=None) Ensure event source mapping exists. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B EventSourceArn The Amazon Resource Name (ARN) of the Amazon Kinesis or the Amazon DynamoDB stream that is the event source. .TP .B FunctionName The Lambda function to invoke when AWS Lambda detects an event on the stream. .sp You can specify an unqualified function name (for example, \(dqThumbnail\(dq) or you can specify Amazon Resource Name (ARN) of the function (for example, \(dqarn:aws:lambda:us\-west\-2:account\-id:function:ThumbNail\(dq). AWS Lambda also allows you to specify only the account ID qualifier (for example, \(dqaccount\-id:Thumbnail\(dq). Note that the length constraint applies only to the ARN. If you specify only the function name, it is limited to 64 character in length. .TP .B StartingPosition The position in the stream where AWS Lambda should start reading. (TRIM_HORIZON | LATEST) .TP .B Enabled Indicates whether AWS Lambda should begin polling the event source. By default, Enabled is true. .TP .B BatchSize The largest number of records that AWS Lambda will retrieve from your event source at the time of invoking your function. Your function receives an event with all the retrieved records. The default is 100 records. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_lambda.function_absent(name, FunctionName, region=None, key=None, keyid=None, profile=None) Ensure function with passed properties is absent. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B FunctionName Name of the function. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_lambda.function_present(name, FunctionName, Runtime, Role, Handler, ZipFile=None, S3Bucket=None, S3Key=None, S3ObjectVersion=None, Description=\(aq\(aq, Timeout=3, MemorySize=128, Permissions=None, RoleRetries=5, region=None, key=None, keyid=None, profile=None, VpcConfig=None, Environment=None) Ensure function exists. .INDENT 7.0 .TP .B name The name of the state definition .TP .B FunctionName Name of the Function. .TP .B Runtime The Runtime environment for the function. One of \(aqnodejs\(aq, \(aqjava8\(aq, or \(aqpython2.7\(aq .TP .B Role The name or ARN of the IAM role that the function assumes when it executes your function to access any other AWS resources. .TP .B Handler The function within your code that Lambda calls to begin execution. For Node.js it is the module\-name.*export* value in your function. For Java, it can be package.classname::handler or package.class\-name. .TP .B ZipFile A path to a .zip file containing your deployment package. If this is specified, S3Bucket and S3Key must not be specified. .TP .B S3Bucket Amazon S3 bucket name where the .zip file containing your package is stored. If this is specified, S3Key must be specified and ZipFile must NOT be specified. .TP .B S3Key The Amazon S3 object (the deployment package) key name you want to upload. If this is specified, S3Key must be specified and ZipFile must NOT be specified. .TP .B S3ObjectVersion The version of S3 object to use. Optional, should only be specified if S3Bucket and S3Key are specified. .TP .B Description A short, user\-defined function description. Lambda does not use this value. Assign a meaningful description as you see fit. .TP .B Timeout The function execution time at which Lambda should terminate this function. Because the execution time has cost implications, we recommend you set this value based on your expected execution time. The default is 3 seconds. .TP .B MemorySize The amount of memory, in MB, your function is given. Lambda uses this memory size to infer the amount of CPU and memory allocated to your function. Your function use\-case determines your CPU and memory requirements. For example, a database operation might need less memory compared to an image processing function. The default value is 128 MB. The value must be a multiple of 64 MB. .TP .B VpcConfig If your Lambda function accesses resources in a VPC, you must provide this parameter identifying the list of security group IDs/Names and subnet IDs/Name. These must all belong to the same VPC. This is a dict of the form: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C VpcConfig: SecurityGroupNames: \- mysecgroup1 \- mysecgroup2 SecurityGroupIds: \- sg\-abcdef1234 SubnetNames: \- mysubnet1 SubnetIds: \- subnet\-1234abcd \- subnet\-abcd1234 .ft P .fi .UNINDENT .UNINDENT .sp If VpcConfig is provided at all, you MUST pass at least one security group and one subnet. .TP .B Permissions A list of permission definitions to be added to the function\(aqs policy .TP .B RoleRetries IAM Roles may take some time to propagate to all regions once created. During that time function creation may fail; this state will atuomatically retry this number of times. The default is 5. .TP .B Environment The parent object that contains your environment\(aqs configuration settings. This is a dictionary of the form: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqVariables\(aq: { \(aqVariableName\(aq: \(aqVariableValue\(aq } } .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.0. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_lc .sp Manage Launch Configurations .sp New in version 2014.7.0. .sp Create and destroy Launch Configurations. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp A limitation of this module is that you can not modify launch configurations once they have been created. If a launch configuration with the specified name exists, this module will always report success, even if the specified configuration doesn\(aqt match. This is due to a limitation in Amazon\(aqs launch configuration API, as it only allows launch configurations to be created and deleted. .sp Also note that a launch configuration that\(aqs in use by an autoscale group can not be deleted until the autoscale group is no longer using it. This may affect the way in which you want to order your states. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit autoscale credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C asg.keyid: GKTADJGHEIQSXMKKRBJ08H asg.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .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 Credential information is shared with autoscale groups as launch configurations and autoscale groups are completely dependent on each other. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure mylc exists: boto_lc.present: \- name: mylc \- image_id: ami\-0b9c9f62 \- key_name: mykey \- security_groups: \- mygroup \- instance_type: m1.small \- instance_monitoring: true \- block_device_mappings: \- \(aq/dev/sda1\(aq: size: 20 volume_type: \(aqio1\(aq iops: 220 delete_on_termination: true \- cloud_init: boothooks: \(aqdisable\-master.sh\(aq: | #!/bin/bash echo \(dqmanual\(dq > /etc/init/salt\-master.override scripts: \(aqrun_salt.sh\(aq: | #!/bin/bash add\-apt\-repository \-y ppa:saltstack/salt apt\-get update apt\-get install \-y salt\-minion salt\-call state.highstate \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs # Using a profile from pillars. Ensure mylc exists: boto_lc.present: \- name: mylc \- image_id: ami\-0b9c9f62 \- profile: myprofile # Passing in a profile. Ensure mylc exists: boto_lc.present: \- name: mylc \- image_id: ami\-0b9c9f62 \- profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_lc.absent(name, region=None, key=None, keyid=None, profile=None) Ensure the named launch configuration is deleted. .INDENT 7.0 .TP .B name Name of the launch configuration. .TP .B region The region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_lc.present(name, image_id, key_name=None, vpc_id=None, vpc_name=None, security_groups=None, user_data=None, cloud_init=None, instance_type=\(aqm1.small\(aq, kernel_id=None, ramdisk_id=None, block_device_mappings=None, delete_on_termination=None, instance_monitoring=False, spot_price=None, instance_profile_name=None, ebs_optimized=False, associate_public_ip_address=None, region=None, key=None, keyid=None, profile=None) Ensure the launch configuration exists. .INDENT 7.0 .TP .B name Name of the launch configuration. .TP .B image_id AMI to use for instances. AMI must exist or creation of the launch configuration will fail. .TP .B key_name Name of the EC2 key pair to use for instances. Key must exist or creation of the launch configuration will fail. .TP .B vpc_id The VPC id where the security groups are defined. Only necessary when using named security groups that exist outside of the default VPC. Mutually exclusive with vpc_name. .TP .B vpc_name Name of the VPC where the security groups are defined. Only Necessary when using named security groups that exist outside of the default VPC. Mutually exclusive with vpc_id. .TP .B security_groups List of Names or security group id’s of the security groups with which to associate the EC2 instances or VPC instances, respectively. Security groups must exist, or creation of the launch configuration will fail. .TP .B user_data The user data available to launched EC2 instances. .TP .B cloud_init A dict of cloud_init configuration. Currently supported keys: boothooks, scripts and cloud\-config. Mutually exclusive with user_data. .TP .B instance_type The instance type. ex: m1.small. .TP .B kernel_id The kernel id for the instance. .TP .B ramdisk_id The RAM disk ID for the instance. .TP .B block_device_mappings A dict of block device mappings that contains a dict with volume_type, delete_on_termination, iops, size, encrypted, snapshot_id. .INDENT 7.0 .TP .B volume_type Indicates what volume type to use. Valid values are standard, io1, gp2. Default is standard. .TP .B delete_on_termination Whether the volume should be explicitly marked for deletion when its instance is terminated (True), or left around (False). If not provided, or None is explicitly passed, the default AWS behaviour is used, which is True for ROOT volumes of instances, and False for all others. .TP .B iops For Provisioned IOPS (SSD) volumes only. The number of I/O operations per second (IOPS) to provision for the volume. .TP .B size Desired volume size (in GiB). .TP .B encrypted Indicates whether the volume should be encrypted. Encrypted EBS volumes must be attached to instances that support Amazon EBS encryption. Volumes that are created from encrypted snapshots are automatically encrypted. There is no way to create an encrypted volume from an unencrypted snapshot or an unencrypted volume from an encrypted snapshot. .UNINDENT .TP .B instance_monitoring Whether instances in group are launched with detailed monitoring. .TP .B spot_price The spot price you are bidding. Only applies if you are building an autoscaling group with spot instances. .TP .B instance_profile_name The name or the Amazon Resource Name (ARN) of the instance profile associated with the IAM role for the instance. Instance profile must exist or the creation of the launch configuration will fail. .TP .B ebs_optimized Specifies whether the instance is optimized for EBS I/O (true) or not (false). .TP .B associate_public_ip_address Used for Auto Scaling groups that launch instances into an Amazon Virtual Private Cloud. Specifies whether to assign a public IP address to each instance launched in a Amazon VPC. .TP .B region The region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_rds .SS Manage RDSs .sp New in version 2015.8.0. .sp Create and destroy RDS instances. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit rds credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rds.keyid: GKTADJGHEIQSXMKKRBJ08H rds.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure myrds RDS exists: boto_rds.present: \- name: myrds \- allocated_storage: 5 \- storage_type: standard \- db_instance_class: db.t2.micro \- engine: MySQL \- master_username: myuser \- master_user_password: mypass \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs \- tags: key: value .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure parameter group exists: create\-parameter\-group: boto_rds.parameter_present: \- name: myparametergroup \- db_parameter_group_family: mysql5.6 \- description: \(dqparameter group family\(dq \- parameters: \- binlog_cache_size: 32768 \- binlog_checksum: CRC32 \- region: eu\-west\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_rds.absent(name, skip_final_snapshot=None, final_db_snapshot_identifier=None, tags=None, wait_for_deletion=True, timeout=180, region=None, key=None, keyid=None, profile=None) Ensure RDS instance is absent. .INDENT 7.0 .TP .B name Name of the RDS instance. .TP .B skip_final_snapshot Whether a final db snapshot is created before the instance is deleted. If True, no snapshot is created. If False, a snapshot is created before deleting the instance. .TP .B final_db_snapshot_identifier If a final snapshot is requested, this is the identifier used for that snapshot. .TP .B tags A dict of tags. .TP .B wait_for_deletion (bool) Wait for the RDS instance to be deleted completely before finishing the state. .TP .B timeout (in seconds) The amount of time that can pass before raising an Exception. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_rds.parameter_present(name, db_parameter_group_family, description, parameters=None, apply_method=\(aqpending\-reboot\(aq, tags=None, region=None, key=None, keyid=None, profile=None) Ensure DB parameter group exists and update parameters. .INDENT 7.0 .TP .B name The name for the parameter group. .TP .B db_parameter_group_family The DB parameter group family name. A DB parameter group can be associated with one and only one DB parameter group family, and can be applied only to a DB instance running a database engine and engine version compatible with that DB parameter group family. .TP .B description Parameter group description. .TP .B parameters The DB parameters that need to be changed of type dictionary. .TP .B apply_method The \fIapply\-immediate\fP method can be used only for dynamic parameters; the \fIpending\-reboot\fP method can be used with MySQL and Oracle DB instances for either dynamic or static parameters. For Microsoft SQL Server DB instances, the \fIpending\-reboot\fP method can be used only for static parameters. .TP .B tags A dict of tags. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_rds.present(name, allocated_storage, db_instance_class, engine, master_username, master_user_password, db_name=None, storage_type=None, db_security_groups=None, vpc_security_group_ids=None, vpc_security_groups=None, availability_zone=None, db_subnet_group_name=None, preferred_maintenance_window=None, db_parameter_group_name=None, db_cluster_identifier=None, tde_credential_arn=None, tde_credential_password=None, storage_encrypted=None, kms_keyid=None, backup_retention_period=None, preferred_backup_window=None, port=None, multi_az=None, engine_version=None, auto_minor_version_upgrade=None, license_model=None, iops=None, option_group_name=None, character_set_name=None, publicly_accessible=None, wait_status=None, tags=None, copy_tags_to_snapshot=None, region=None, domain=None, key=None, keyid=None, monitoring_interval=None, monitoring_role_arn=None, domain_iam_role_name=None, promotion_tier=None, profile=None) Ensure RDS instance exists. .INDENT 7.0 .TP .B name Name of the RDS state definition. .TP .B allocated_storage The amount of storage (in gigabytes) to be initially allocated for the database instance. .TP .B db_instance_class The compute and memory capacity of the Amazon RDS DB instance. .TP .B engine The name of the database engine to be used for this instance. Supported engine types are: MySQL, mariadb, oracle\-se1, oracle\-se, oracle\-ee, sqlserver\-ee, sqlserver\-se, sqlserver\-ex, sqlserver\-web, postgres and aurora. For more information, please see the \fBengine\fP argument in the Boto3 RDS \fI\%create_db_instance\fP documentation. .TP .B master_username The name of master user for the client DB instance. .TP .B master_user_password The password for the master database user. Can be any printable ASCII character except \(dq/\(dq, \(aq\(dq\(aq, or \(dq@\(dq. .TP .B db_name The meaning of this parameter differs according to the database engine you use. See the Boto3 RDS documentation to determine the appropriate value for your configuration. \fI\%https://boto3.readthedocs.io/en/latest/reference/services/rds.html#RDS.Client.create_db_instance\fP .TP .B storage_type Specifies the storage type to be associated with the DB instance. Options are standard, gp2 and io1. If you specify io1, you must also include a value for the Iops parameter. .TP .B db_security_groups A list of DB security groups to associate with this DB instance. .TP .B vpc_security_group_ids A list of EC2 VPC security group IDs to associate with this DB instance. .TP .B vpc_security_groups A list of EC2 VPC security groups (IDs or Name tags) to associate with this DB instance. .TP .B availability_zone The EC2 Availability Zone that the database instance will be created in. .TP .B db_subnet_group_name A DB subnet group to associate with this DB instance. .TP .B preferred_maintenance_window The weekly time range (in UTC) during which system maintenance can occur. .TP .B db_parameter_group_name A DB parameter group to associate with this DB instance. .TP .B db_cluster_identifier If the DB instance is a member of a DB cluster, contains the name of the DB cluster that the DB instance is a member of. .TP .B tde_credential_arn The ARN from the Key Store with which the instance is associated for TDE encryption. .TP .B tde_credential_password The password to use for TDE encryption if an encryption key is not used. .TP .B storage_encrypted Specifies whether the DB instance is encrypted. .TP .B kms_keyid If storage_encrypted is true, the KMS key identifier for the encrypted DB instance. .TP .B backup_retention_period The number of days for which automated backups are retained. .TP .B preferred_backup_window The daily time range during which automated backups are created if automated backups are enabled. .TP .B port The port number on which the database accepts connections. .TP .B multi_az Specifies if the DB instance is a Multi\-AZ deployment. You cannot set the AvailabilityZone parameter if the MultiAZ parameter is set to true. .TP .B engine_version The version number of the database engine to use. .TP .B auto_minor_version_upgrade Indicates that minor engine upgrades will be applied automatically to the DB instance during the maintenance window. .TP .B license_model License model information for this DB instance. .TP .B iops The amount of Provisioned IOPS (input/output operations per second) to be initially allocated for the DB instance. .TP .B option_group_name Indicates that the DB instance should be associated with the specified option group. .TP .B character_set_name For supported engines, indicates that the DB instance should be associated with the specified CharacterSet. .TP .B publicly_accessible Specifies the accessibility options for the DB instance. A value of true specifies an Internet\-facing instance with a publicly resolvable DNS name, which resolves to a public IP address. A value of false specifies an internal instance with a DNS name that resolves to a private IP address. .TP .B wait_status Wait for the RDS instance to reach a desired status before finishing the state. Available states: available, modifying, backing\-up .TP .B tags A dict of tags. .TP .B copy_tags_to_snapshot Specifies whether tags are copied from the DB instance to snapshots of the DB instance. .TP .B region Region to connect to. .TP .B domain The identifier of the Active Directory Domain. .TP .B key AWS secret key to be used. .TP .B keyid AWS access key to be used. .TP .B monitoring_interval The interval, in seconds, between points when Enhanced Monitoring metrics are collected for the DB instance. .TP .B monitoring_role_arn The ARN for the IAM role that permits RDS to send Enhanced Monitoring metrics to CloudWatch Logs. .TP .B domain_iam_role_name Specify the name of the IAM role to be used when making API calls to the Directory Service. .TP .B promotion_tier A value that specifies the order in which an Aurora Replica is promoted to the primary instance after a failure of the existing primary instance. For more information, see Fault Tolerance for an Aurora DB Cluster . .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_rds.replica_present(name, source, db_instance_class=None, availability_zone=None, port=None, auto_minor_version_upgrade=None, iops=None, option_group_name=None, publicly_accessible=None, tags=None, region=None, key=None, keyid=None, profile=None, db_parameter_group_name=None) Ensure RDS replica exists. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Ensure myrds replica RDS exists: boto_rds.create_replica: \- name: myreplica \- source: mydb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_rds.subnet_group_absent(name, tags=None, region=None, key=None, keyid=None, profile=None) .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_rds.subnet_group_present(name, description, subnet_ids=None, subnet_names=None, tags=None, region=None, key=None, keyid=None, profile=None) Ensure DB subnet group exists. .INDENT 7.0 .TP .B name The name for the DB subnet group. This value is stored as a lowercase string. .TP .B subnet_ids A list of the EC2 Subnet IDs for the DB subnet group. Either subnet_ids or subnet_names must be provided. .TP .B subnet_names A list of The EC2 Subnet names for the DB subnet group. Either subnet_ids or subnet_names must be provided. .TP .B description Subnet group description. .TP .B tags A dict of tags. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_route53 .sp Manage Route53 records .sp New in version 2014.7.0. .sp Create and delete Route53 records. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit route53 credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C route53.keyid: GKTADJGHEIQSXMKKRBJ08H route53.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mycnamerecord: boto_route53.present: \- name: test.example.com. \- value: my\-elb.us\-east\-1.elb.amazonaws.com. \- zone: example.com. \- ttl: 60 \- record_type: CNAME \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs # Using a profile from pillars myarecord: boto_route53.present: \- name: test.example.com. \- value: 1.1.1.1 \- zone: example.com. \- ttl: 60 \- record_type: A \- region: us\-east\-1 \- profile: myprofile # Passing in a profile myarecord: boto_route53.present: \- name: test.example.com. \- value: 1.1.1.1 \- zone: example.com. \- ttl: 60 \- record_type: A \- region: us\-east\-1 \- profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_route53.absent(name, zone, record_type, identifier=None, region=None, key=None, keyid=None, profile=None, wait_for_sync=True, split_dns=False, private_zone=False) Ensure the Route53 record is deleted. .INDENT 7.0 .TP .B name Name of the record. .TP .B zone The zone to delete the record from. .TP .B record_type The record type (A, NS, MX, TXT, etc.) .TP .B identifier An identifier to match for deletion. .TP .B region The region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B wait_for_sync Wait for an INSYNC change status from Route53. .TP .B split_dns Route53 supports a public and private DNS zone with the same names. .TP .B private_zone If using split_dns, specify if this is the private zone. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_route53.hosted_zone_absent(name, domain_name=None, region=None, key=None, keyid=None, profile=None) Ensure the Route53 Hostes Zone described is absent .INDENT 7.0 .TP .B name The name of the state definition. .TP .B domain_name The FQDN (including final period) of the zone you wish absent. If not provided, the value of name will be used. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_route53.hosted_zone_present(name, domain_name=None, private_zone=False, caller_ref=None, comment=\(aq\(aq, vpc_id=None, vpc_name=None, vpc_region=None, region=None, key=None, keyid=None, profile=None) Ensure a hosted zone exists with the given attributes. Note that most things cannot be modified once a zone is created \- it must be deleted and re\-spun to update these attributes: .INDENT 7.0 .IP \(bu 2 private_zone (AWS API limitation). .IP \(bu 2 comment (the appropriate call exists in the AWS API and in boto3, but has not, as of this writing, been added to boto2). .IP \(bu 2 vpc_id (same story \- we really need to rewrite this module with boto3) .IP \(bu 2 vpc_name (really just a pointer to vpc_id anyway). .IP \(bu 2 vpc_region (again, supported in boto3 but not boto2). .UNINDENT .sp If you need the ability to update these attributes, please use the newer boto3_route53 module instead. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B domain_name The name of the domain. This must be fully\-qualified, terminating with a period. This is the name you have registered with your domain registrar. It is also the name you will delegate from your registrar to the Amazon Route 53 delegation servers returned in response to this request. Defaults to the value of name if not provided. .TP .B private_zone Set True if creating a private hosted zone. .TP .B caller_ref A unique string that identifies the request and that allows create_hosted_zone() calls to be retried without the risk of executing the operation twice. This helps ensure idempotency across state calls, but can cause issues if a zone is deleted and then an attempt is made to recreate it with the same caller_ref. If not provided, a unique UUID will be generated at each state run, which avoids the risk of the above (transient) error. This option is generally not needed. Maximum length of 128. .TP .B comment Any comments you want to include about the hosted zone. .TP .B vpc_id When creating a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with vpe_name. Ignored when creating a non\-private zone. .TP .B vpc_name When creating a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with vpe_id. Ignored when creating a non\-private zone. .TP .B vpc_region When creating a private hosted zone, the region of the associated VPC is required. If not provided, an effort will be made to determine it from vpc_id or vpc_name, where possible. If this fails, you\(aqll need to provide an explicit value for this option. Ignored when creating a non\-private zone. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_route53.present(name, value, zone, record_type, ttl=None, identifier=None, region=None, key=None, keyid=None, profile=None, wait_for_sync=True, split_dns=False, private_zone=False) Ensure the Route53 record is present. .INDENT 7.0 .TP .B name Name of the record. .TP .B value .INDENT 7.0 .TP .B Value of the record. As a special case, you can pass in: \fIprivate:<Name tag>\fP to have the function autodetermine the private IP \fIpublic:<Name tag>\fP to have the function autodetermine the public IP .UNINDENT .TP .B zone The zone to create the record in. .TP .B record_type The record type (A, NS, MX, TXT, etc.) .TP .B ttl The time to live for the record. .TP .B identifier The unique identifier to use for this record. .TP .B region The region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B wait_for_sync Wait for an INSYNC change status from Route53 before returning success. .TP .B split_dns Route53 supports parallel public and private DNS zones with the same name. .TP .B private_zone If using split_dns, specify if this is the private zone. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_route53.rr_absent(*args, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_route53.rr_present(*args, **kwargs) .UNINDENT .SS salt.states.boto_s3 .SS Manage S3 Resources .sp New in version 2018.3.0. .sp Manage S3 resources. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto3\fP, which can be installed via package, or pip. .sp This module accepts explicit AWS credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s3.keyid: GKTADJGHEIQSXMKKRBJ08H s3.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure s3 object exists: boto_s3.object_present: \- name: s3\-bucket/s3\-key \- source: /path/to/local/file \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs \- profile: my\-profile .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends boto3 .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_s3.object_present(name, source=None, hash_type=None, extra_args=None, extra_args_from_pillar=\(aqboto_s3_object_extra_args\(aq, region=None, key=None, keyid=None, profile=None) Ensure object exists in S3. .INDENT 7.0 .TP .B name The name of the state definition. This will be used to determine the location of the object in S3, by splitting on the first slash and using the first part as the bucket name and the remainder as the S3 key. .TP .B source The source file to upload to S3, currently this only supports files hosted on the minion\(aqs local file system (starting with /). .TP .B hash_type Hash algorithm to use to check that the object contents are correct. Defaults to the value of the \fIhash_type\fP config option. .TP .B extra_args A dictionary of extra arguments to use when uploading the file. Note that these are only enforced if new objects are uploaded, and not modified on existing objects. The supported args are those in the ALLOWED_UPLOAD_ARGS list at \fI\%http://boto3.readthedocs.io/en/latest/reference/customizations/s3.html\fP\&. However, Note that the \(aqACL\(aq, \(aqGrantFullControl\(aq, \(aqGrantRead\(aq, \(aqGrantReadACP\(aq, and \(aqGrantWriteACL\(aq keys are currently not supported. .TP .B extra_args_from_pillar Name of pillar dict that contains extra arguments. Extra arguments defined for this specific state will be merged over those from the pillar. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_s3_bucket .SS Manage S3 Buckets .sp New in version 2016.3.0. .sp Create and destroy S3 buckets. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 boto .IP \(bu 2 boto3 .UNINDENT .UNINDENT .sp The dependencies listed above can be installed via package or pip. .sp This module accepts explicit vpc credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vpc.keyid: GKTADJGHEIQSXMKKRBJ08H vpc.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure bucket exists: boto_s3_bucket.present: \- Bucket: mybucket \- LocationConstraint: EU \- ACL: \- GrantRead: \(dquri=http://acs.amazonaws.com/groups/global/AllUsers\(dq \- CORSRules: \- AllowedHeaders: [] AllowedMethods: [\(dqGET\(dq] AllowedOrigins: [\(dq*\(dq] ExposeHeaders: [] MaxAgeSeconds: 123 \- LifecycleConfiguration: \- Expiration: Days: 123 ID: \(dqidstring\(dq Prefix: \(dqprefixstring\(dq Status: \(dqenabled\(dq, ID: \(dqlc1\(dq Transitions: \- Days: 123 StorageClass: \(dqGLACIER\(dq NoncurrentVersionTransitions: \- NoncurrentDays: 123 StorageClass: \(dqGLACIER\(dq NoncurrentVersionExpiration: NoncurrentDays: 123 \- Logging: TargetBucket: log_bucket TargetPrefix: prefix TargetGrants: \- Grantee: DisplayName: \(dqstring\(dq EmailAddress: \(dqstring\(dq ID: \(dqstring\(dq Type: \(dqAmazonCustomerByEmail\(dq URI: \(dqstring\(dq Permission: \(dqREAD\(dq \- NotificationConfiguration: LambdaFunctionConfiguration: \- Id: \(dqstring\(dq LambdaFunctionArn: \(dqstring\(dq Events: \- \(dqs3:ObjectCreated:*\(dq Filter: Key: FilterRules: \- Name: \(dqprefix\(dq Value: \(dqstring\(dq \- Policy: Version: \(dq2012\-10\-17\(dq Statement: \- Sid: \(dqString\(dq Effect: \(dqAllow\(dq Principal: AWS: \(dqarn:aws:iam::133434421342:root\(dq Action: \(dqs3:PutObject\(dq Resource: \(dqarn:aws:s3:::my\-bucket/*\(dq \- Replication: Role: myrole Rules: \- ID: \(dqstring\(dq Prefix: \(dqstring\(dq Status: \(dqEnabled\(dq Destination: Bucket: \(dqarn:aws:s3:::my\-bucket\(dq \- RequestPayment: Payer: Requester \- Tagging: tag_name: tag_value tag_name_2: tag_value \- Versioning: Status: \(dqEnabled\(dq \- Website: ErrorDocument: Key: \(dqerror.html\(dq IndexDocument: Suffix: \(dqindex.html\(dq RedirectAllRequestsTo: Hostname: \(dqstring\(dq Protocol: \(dqhttp\(dq RoutingRules: \- Condition: HttpErrorCodeReturnedEquals: \(dqstring\(dq KeyPrefixEquals: \(dqstring\(dq Redirect: HostName: \(dqstring\(dq HttpRedirectCode: \(dqstring\(dq Protocol: \(dqhttp\(dq ReplaceKeyPrefixWith: \(dqstring\(dq ReplaceKeyWith: \(dqstring\(dq \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_s3_bucket.absent(name, Bucket, Force=False, region=None, key=None, keyid=None, profile=None) Ensure bucket with passed properties is absent. .INDENT 7.0 .TP .B name The name of the state definition. .TP .B Bucket Name of the bucket. .TP .B Force Empty the bucket first if necessary \- Boolean. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_s3_bucket.present(name, Bucket, LocationConstraint=None, ACL=None, CORSRules=None, LifecycleConfiguration=None, Logging=None, NotificationConfiguration=None, Policy=None, Replication=None, RequestPayment=None, Tagging=None, Versioning=None, Website=None, region=None, key=None, keyid=None, profile=None) Ensure bucket exists. .INDENT 7.0 .TP .B name The name of the state definition .TP .B Bucket Name of the bucket. .TP .B LocationConstraint \(aqEU\(aq|\(aqeu\-west\-1\(aq|\(aqus\-west\-1\(aq|\(aqus\-west\-2\(aq|\(aqap\-southeast\-1\(aq|\(aqap\-southeast\-2\(aq|\(aqap\-northeast\-1\(aq|\(aqsa\-east\-1\(aq|\(aqcn\-north\-1\(aq|\(aqeu\-central\-1\(aq .TP .B ACL The permissions on a bucket using access control lists (ACL). .TP .B CORSRules The cors configuration for a bucket. .TP .B LifecycleConfiguration Lifecycle configuration for your bucket .TP .B Logging The logging parameters for a bucket and to specify permissions for who can view and modify the logging parameters. .TP .B NotificationConfiguration notifications of specified events for a bucket .TP .B Policy Policy on the bucket .TP .B Replication Replication rules. You can add as many as 1,000 rules. Total replication configuration size can be up to 2 MB .TP .B RequestPayment The request payment configuration for a bucket. By default, the bucket owner pays for downloads from the bucket. This configuration parameter enables the bucket owner (only) to specify that the person requesting the download will be charged for the download .TP .B Tagging A dictionary of tags that should be set on the bucket .TP .B Versioning The versioning state of the bucket .TP .B Website The website configuration of the bucket .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_secgroup .SS Manage Security Groups .sp New in version 2014.7.0. .sp Create and destroy Security Groups. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit EC2 credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C secgroup.keyid: GKTADJGHEIQSXMKKRBJ08H secgroup.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure mysecgroup exists: boto_secgroup.present: \- name: mysecgroup \- description: My security group \- vpc_name: myvpc \- rules: \- ip_protocol: tcp from_port: 80 to_port: 80 cidr_ip: \- 10.0.0.0/8 \- 192.168.0.0/16 \- ip_protocol: tcp from_port: 8080 to_port: 8090 cidr_ip: \- 10.0.0.0/8 \- 192.168.0.0/16 \- ip_protocol: icmp from_port: \-1 to_port: \-1 source_group_name: mysecgroup \- ip_protocol: tcp from_port: 8080 to_port: 8080 source_group_name: MyOtherSecGroup source_group_name_vpc: MyPeeredVPC \- rules_egress: \- ip_protocol: all from_port: \-1 to_port: \-1 cidr_ip: \- 10.0.0.0/8 \- 192.168.0.0/16 \- tags: SomeTag: \(aqMy Tag Value\(aq SomeOtherTag: \(aqOther Tag Value\(aq \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs # Using a profile from pillars Ensure mysecgroup exists: boto_secgroup.present: \- name: mysecgroup \- description: My security group \- profile: myprofile # Passing in a profile Ensure mysecgroup exists: boto_secgroup.present: \- name: mysecgroup \- description: My security group \- profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When using the \fBprofile\fP parameter and \fBregion\fP is set outside of the profile group, region is ignored and a default region will be used. .sp If \fBregion\fP is missing from the \fBprofile\fP data set, \fBus\-east\-1\fP will be used as the default region. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_secgroup.absent(name, vpc_id=None, vpc_name=None, region=None, key=None, keyid=None, profile=None) Ensure a security group with the specified name does not exist. .INDENT 7.0 .TP .B name Name of the security group. .TP .B vpc_id The ID of the VPC to remove the security group from, if any. Exclusive with vpc_name. .TP .B vpc_name The name of the VPC to remove the security group from, if any. Exclusive with vpc_name. .sp New in version 2016.3.0. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .sp New in version 2016.3.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_secgroup.present(name, description, vpc_id=None, vpc_name=None, rules=None, rules_egress=None, delete_ingress_rules=True, delete_egress_rules=True, region=None, key=None, keyid=None, profile=None, tags=None) Ensure the security group exists with the specified rules. .INDENT 7.0 .TP .B name Name of the security group. .TP .B description A description of this security group. .TP .B vpc_id The ID of the VPC to create the security group in, if any. Exclusive with vpc_name. .TP .B vpc_name The name of the VPC to create the security group in, if any. Exclusive with vpc_id. .sp New in version 2016.3.0. .sp New in version 2015.8.2. .TP .B rules A list of ingress rule dicts. If not specified, \fBrules=None\fP, the ingress rules will be unmanaged. If set to an empty list, \fB[]\fP, then all ingress rules will be removed. .TP .B rules_egress A list of egress rule dicts. If not specified, \fBrules_egress=None\fP, the egress rules will be unmanaged. If set to an empty list, \fB[]\fP, then all egress rules will be removed. .TP .B delete_ingress_rules Some tools (EMR comes to mind) insist on adding rules on\-the\-fly, which salt will happily remove on the next run. Set this param to False to avoid deleting rules which were added outside of salt. .TP .B delete_egress_rules Some tools (EMR comes to mind) insist on adding rules on\-the\-fly, which salt will happily remove on the next run. Set this param to False to avoid deleting rules which were added outside of salt. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key, and keyid. .TP .B tags List of key:value pairs of tags to set on the security group .sp New in version 2016.3.0. .UNINDENT .UNINDENT .SS salt.states.boto_sns .sp Manage SNS Topics .sp Create and destroy SNS topics. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit AWS credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sns.keyid: GKTADJGHEIQSXMKKRBJ08H sns.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mytopic: boto_sns.present: \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs # Using a profile from pillars mytopic: boto_sns.present: \- region: us\-east\-1 \- profile: mysnsprofile # Passing in a profile mytopic: boto_sns.present: \- region: us\-east\-1 \- profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_sns.absent(name, region=None, key=None, keyid=None, profile=None, unsubscribe=False) Ensure the named sns topic is deleted. .INDENT 7.0 .TP .B name Name of the SNS topic. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B unsubscribe If True, unsubscribe all subcriptions to the SNS topic before deleting the SNS topic .sp New in version 2016.11.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_sns.present(name, subscriptions=None, region=None, key=None, keyid=None, profile=None) Ensure the SNS topic exists. .INDENT 7.0 .TP .B name Name of the SNS topic. .TP .B subscriptions List of SNS subscriptions. .sp Each subscription is a dictionary with a protocol and endpoint key: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ {\(aqprotocol\(aq: \(aqhttps\(aq, \(aqendpoint\(aq: \(aqhttps://www.example.com/sns\-endpoint\(aq}, {\(aqprotocol\(aq: \(aqsqs\(aq, \(aqendpoint\(aq: \(aqarn:aws:sqs:us\-west\-2:123456789012:MyQueue\(aq} ] .ft P .fi .UNINDENT .UNINDENT .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_sqs .sp Manage SQS Queues .sp New in version 2014.7.0. .sp Create and destroy SQS queues. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module uses \fBboto\fP, which can be installed via package, or pip. .sp This module accepts explicit SQS credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sqs.keyid: GKTADJGHEIQSXMKKRBJ08H sqs.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myqueue: boto_sqs.present: \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs \- attributes: ReceiveMessageWaitTimeSeconds: 20 # Using a profile from pillars myqueue: boto_sqs.present: \- region: us\-east\-1 \- profile: mysqsprofile # Passing in a profile myqueue: boto_sqs.present: \- region: us\-east\-1 \- profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_sqs.absent(name, region=None, key=None, keyid=None, profile=None) Ensure the named sqs queue is deleted. .INDENT 7.0 .TP .B name Name of the SQS queue. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_sqs.present(name, attributes=None, region=None, key=None, keyid=None, profile=None) Ensure the SQS queue exists. .INDENT 7.0 .TP .B name Name of the SQS queue. .TP .B attributes A dict of key/value SQS attributes. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .SS salt.states.boto_vpc .SS Manage VPCs .sp New in version 2015.8.0. .INDENT 0.0 .TP .B depends .UNINDENT .INDENT 0.0 .IP \(bu 2 boto >= 2.8.0 .IP \(bu 2 boto3 >= 1.2.6 .UNINDENT .sp Create and destroy VPCs. Be aware that this interacts with Amazon\(aqs services, and so may incur charges. .sp This module accepts explicit vpc credentials but 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 \fI\%here\fP\&. .sp If IAM roles are not used you need to specify them either in a pillar file or in the minion\(aqs config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vpc.keyid: GKTADJGHEIQSXMKKRBJ08H vpc.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either passed in as a dict, or as a string to pull from pillars or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C aws: region: us\-east\-1: profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure VPC exists: boto_vpc.present: \- name: myvpc \- cidr_block: 10.10.11.0/24 \- dns_hostnames: True \- region: us\-east\-1 \- keyid: GKTADJGHEIQSXMKKRBJ08H \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs Ensure subnet exists: boto_vpc.subnet_present: \- name: mysubnet \- vpc_id: vpc\-123456 \- cidr_block: 10.0.0.0/16 \- region: us\-east\-1 \- profile: myprofile {% set profile = salt[\(aqpillar.get\(aq](\(aqaws:region:us\-east\-1:profile\(aq ) %} Ensure internet gateway exists: boto_vpc.internet_gateway_present: \- name: myigw \- vpc_name: myvpc \- profile: {{ profile }} Ensure route table exists: boto_vpc.route_table_present: \- name: my_route_table \- vpc_id: vpc\-123456 \- routes: \- destination_cidr_block: 0.0.0.0/0 instance_id: i\-123456 \- subnet_names: \- subnet1 \- subnet2 \- region: us\-east\-1 \- profile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .sp Request, accept and delete VPC peering connections. VPC peering connections can be named allowing the name to be used throughout the state file. Following example shows how to request and accept a VPC peering connection. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C accept the vpc peering connection: boto_vpc.accept_vpc_peering_connection: \- conn_name: salt_vpc_peering \- region: us\-west\-2 \- require: \- boto_vpc: request a vpc peering connection request a vpc peering connection: boto_vpc.request_vpc_peering_connection: \- requester_vpc_id: vpc\-4a3d522e \- peer_vpc_id: vpc\-ae81e9ca \- region: us\-west\-2 \- conn_name: salt_vpc_peering .ft P .fi .UNINDENT .UNINDENT .sp VPC peering connections need not be named. In this case the VPC peering connection ID should be used in the state file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C accept the vpc peering connection: boto_vpc.accept_vpc_peering_connection: \- conn_id: pcx\-1873c371 \- region: us\-west\-2 .ft P .fi .UNINDENT .UNINDENT .sp VPC peering connections can be deleted, as shown below. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C delete a named vpc peering connection: boto_vpc.delete_vpc_peering_connection: \- conn_name: salt_vpc_peering .ft P .fi .UNINDENT .UNINDENT .sp Delete also accepts a VPC peering connection id. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C delete a vpc peering connection by id: boto_vpc.delete_vpc_peering_connection: \- conn_id: pcx\-1873c371 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.absent(name, tags=None, region=None, key=None, keyid=None, profile=None) Ensure VPC with passed properties is absent. .INDENT 7.0 .TP .B name Name of the VPC. .TP .B tags A list of tags. All tags must match. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.accept_vpc_peering_connection(name=None, conn_id=None, conn_name=None, region=None, key=None, keyid=None, profile=None) Accept a VPC pending requested peering connection between two VPCs. .INDENT 7.0 .TP .B name Name of this state .TP .B conn_id The connection ID to accept. Exclusive with conn_name. String type. .TP .B conn_name The name of the VPC peering connection to accept. Exclusive with conn_id. String type. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .sp New in version 2016.11.0. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C boto_vpc.accept_vpc_peering_connection: \- conn_name: salt_peering_connection # usage with vpc peering connection id and region boto_vpc.accept_vpc_peering_connection: \- conn_id: pbx\-1873d472 \- region: us\-west\-2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.delete_vpc_peering_connection(name, conn_id=None, conn_name=None, region=None, key=None, keyid=None, profile=None) .INDENT 7.0 .TP .B name Name of the state .TP .B conn_id ID of the peering connection to delete. Exclusive with conn_name. .TP .B conn_name The name of the peering connection to delete. Exclusive with conn_id. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .sp New in version 2016.11.0. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C delete a vpc peering connection: boto_vpc.delete_vpc_peering_connection: \- region: us\-west\-2 \- conn_id: pcx\-4613b12e .ft P .fi .UNINDENT .UNINDENT .sp Connection name can be specified (instead of ID). Specifying both conn_name and conn_id will result in an error. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C delete a vpc peering connection: boto_vpc.delete_vpc_peering_connection: \- conn_name: salt_vpc_peering .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.dhcp_options_absent(name=None, dhcp_options_id=None, region=None, key=None, keyid=None, profile=None) Ensure a set of DHCP options with the given settings exist. .INDENT 7.0 .TP .B name (string) Name of the DHCP options set. .TP .B dhcp_options_id (string) Id of the DHCP options set. .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (various) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.dhcp_options_present(name, dhcp_options_id=None, vpc_name=None, vpc_id=None, domain_name=None, domain_name_servers=None, ntp_servers=None, netbios_name_servers=None, netbios_node_type=None, tags=None, region=None, key=None, keyid=None, profile=None) Ensure a set of DHCP options with the given settings exist. Note that the current implementation only SETS values during option set creation. It is unable to update option sets in place, and thus merely verifies the set exists via the given name and/or dhcp_options_id param. .INDENT 7.0 .TP .B name (string) Name of the DHCP options. .TP .B vpc_name (string) Name of a VPC to which the options should be associated. Either vpc_name or vpc_id must be provided. .TP .B vpc_id (string) Id of a VPC to which the options should be associated. Either vpc_name or vpc_id must be provided. .TP .B domain_name (string) Domain name to be assiciated with this option set. .TP .B domain_name_servers (list of strings) The IP address(es) of up to four domain name servers. .TP .B ntp_servers (list of strings) The IP address(es) of up to four desired NTP servers. .TP .B netbios_name_servers (list of strings) The IP address(es) of up to four NetBIOS name servers. .TP .B netbios_node_type (string) The NetBIOS node type (1, 2, 4, or 8). For more information about the allowed values, see RFC 2132. The recommended is 2 at this time (broadcast and multicast are currently not supported). .TP .B tags (dict of key:value pairs) A set of tags to be added. .TP .B region (string) Region to connect to. .TP .B key (string) Secret key to be used. .TP .B keyid (string) Access key to be used. .TP .B profile (various) A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.internet_gateway_absent(name, detach=False, region=None, key=None, keyid=None, profile=None) Ensure the named internet gateway is absent. .INDENT 7.0 .TP .B name Name of the internet gateway. .TP .B detach First detach the internet gateway from a VPC, if attached. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.internet_gateway_present(name, vpc_name=None, vpc_id=None, tags=None, region=None, key=None, keyid=None, profile=None) Ensure an internet gateway exists. .INDENT 7.0 .TP .B name Name of the internet gateway. .TP .B vpc_name Name of the VPC to which the internet gateway should be attached. .TP .B vpc_id Id of the VPC to which the internet_gateway should be attached. Only one of vpc_name or vpc_id may be provided. .TP .B tags A list of tags. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.nat_gateway_absent(name=None, subnet_name=None, subnet_id=None, region=None, key=None, keyid=None, profile=None, wait_for_delete_retries=0) Ensure the nat gateway in the named subnet is absent. .sp This function requires boto3. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B name Name of the state. .TP .B subnet_name Name of the subnet within which the nat gateway should exist .TP .B subnet_id Id of the subnet within which the nat gateway should exist. Either subnet_name or subnet_id must be provided. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .TP .B wait_for_delete_retries NAT gateway may take some time to be go into deleted or failed state. During the deletion process, subsequent release of elastic IPs may fail; this state will automatically retry this number of times to ensure the NAT gateway is in deleted or failed state before proceeding. Default is set to 0 for backward compatibility. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.nat_gateway_present(name, subnet_name=None, subnet_id=None, region=None, key=None, keyid=None, profile=None, allocation_id=None) Ensure a nat gateway exists within the specified subnet .sp This function requires boto3. .sp New in version 2016.11.0. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C boto_vpc.nat_gateway_present: \- subnet_name: my\-subnet .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the state .TP .B subnet_name Name of the subnet within which the nat gateway should exist .TP .B subnet_id Id of the subnet within which the nat gateway should exist. Either subnet_name or subnet_id must be provided. .TP .B allocation_id If specified, the elastic IP address referenced by the ID is associated with the gateway. Otherwise, a new allocation_id is created and used. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.present(name, cidr_block, instance_tenancy=None, dns_support=None, dns_hostnames=None, tags=None, region=None, key=None, keyid=None, profile=None) Ensure VPC exists. .INDENT 7.0 .TP .B name Name of the VPC. .TP .B cidr_block The range of IPs in CIDR format, for example: 10.0.0.0/24. Block size must be between /16 and /28 netmask. .TP .B instance_tenancy Instances launched in this VPC will be ingle\-tenant or dedicated hardware. .TP .B dns_support Indicates whether the DNS resolution is supported for the VPC. .TP .B dns_hostnames Indicates whether the instances launched in the VPC get DNS hostnames. .TP .B tags A list of tags. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.request_vpc_peering_connection(name, requester_vpc_id=None, requester_vpc_name=None, peer_vpc_id=None, peer_vpc_name=None, conn_name=None, peer_owner_id=None, peer_region=None, region=None, key=None, keyid=None, profile=None) .INDENT 7.0 .TP .B name Name of the state .TP .B requester_vpc_id ID of the requesting VPC. Exclusive with requester_vpc_name. String type. .TP .B requester_vpc_name Name tag of the requesting VPC. Exclusive with requester_vpc_id. String type. .TP .B peer_vpc_id ID of the VPC tp crete VPC peering connection with. This can be a VPC in another account. Exclusive with peer_vpc_name. String type. .TP .B peer_vpc_name Name tag of the VPC tp crete VPC peering connection with. This can only be a VPC the same account and region. Exclusive with peer_vpc_id. String type. .TP .B conn_name The (optional) name to use for this VPC peering connection. String type. .TP .B peer_owner_id ID of the owner of the peer VPC. String type. If this isn\(aqt supplied AWS uses your account ID. Required if peering to a different account. .TP .B peer_region Region of peer VPC. For inter\-region vpc peering connections. Not required for intra\-region peering connections. .sp New in version 3005. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .sp New in version 2016.11.0. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C request a vpc peering connection: boto_vpc.request_vpc_peering_connection: \- requester_vpc_id: vpc\-4b3522e \- peer_vpc_id: vpc\-ae83f9ca \- conn_name: salt_peering_connection .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.route_table_absent(name, region=None, key=None, keyid=None, profile=None) Ensure the named route table is absent. .INDENT 7.0 .TP .B name Name of the route table. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.route_table_present(name, vpc_name=None, vpc_id=None, routes=None, subnet_ids=None, subnet_names=None, tags=None, region=None, key=None, keyid=None, profile=None) Ensure route table with routes exists and is associated to a VPC. .sp This function requires boto3 to be installed if nat gatewyas are specified. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C boto_vpc.route_table_present: \- name: my_route_table \- vpc_id: vpc\-123456 \- routes: \- destination_cidr_block: 0.0.0.0/0 internet_gateway_name: InternetGateway \- destination_cidr_block: 10.10.11.0/24 instance_id: i\-123456 \- destination_cidr_block: 10.10.12.0/24 interface_id: eni\-123456 \- destination_cidr_block: 10.10.13.0/24 instance_name: mygatewayserver \- subnet_names: \- subnet1 \- subnet2 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Name of the route table. .TP .B vpc_name Name of the VPC with which the route table should be associated. .TP .B vpc_id Id of the VPC with which the route table should be associated. Either vpc_name or vpc_id must be provided. .TP .B routes A list of routes. Each route has a cidr and a target. .TP .B subnet_ids A list of subnet ids to associate .TP .B subnet_names A list of subnet names to associate .TP .B tags A list of tags. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.subnet_absent(name=None, subnet_id=None, region=None, key=None, keyid=None, profile=None) Ensure subnet with passed properties is absent. .INDENT 7.0 .TP .B name Name of the subnet. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.subnet_present(name, cidr_block, vpc_name=None, vpc_id=None, availability_zone=None, tags=None, region=None, key=None, keyid=None, profile=None, route_table_id=None, route_table_name=None, auto_assign_public_ipv4=False) Ensure a subnet exists. .INDENT 7.0 .TP .B name Name of the subnet. .TP .B cidr_block The range if IPs for the subnet, in CIDR format. For example: 10.0.0.0/24. Block size must be between /16 and /28 netmask. .TP .B vpc_name Name of the VPC in which the subnet should be placed. Either vpc_name or vpc_id must be provided. .TP .B vpc_id Id of the VPC in which the subnet should be placed. Either vpc_name or vpc_id must be provided. .TP .B availability_zone AZ in which the subnet should be placed. .TP .B tags A list of tags. .TP .B route_table_id A route table ID to explicitly associate the subnet with. If both route_table_id and route_table_name are specified, route_table_id will take precedence. .sp New in version 2016.11.0. .TP .B route_table_name A route table name to explicitly associate the subnet with. If both route_table_id and route_table_name are specified, route_table_id will take precedence. .sp New in version 2016.11.0. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.vpc_peering_connection_absent(name, conn_id=None, conn_name=None, region=None, key=None, keyid=None, profile=None) .UNINDENT .INDENT 0.0 .TP .B salt.states.boto_vpc.vpc_peering_connection_present(name, requester_vpc_id=None, requester_vpc_name=None, peer_vpc_id=None, peer_vpc_name=None, conn_name=None, peer_owner_id=None, peer_region=None, region=None, key=None, keyid=None, profile=None) .INDENT 7.0 .TP .B name Name of the state .TP .B requester_vpc_id ID of the requesting VPC. Exclusive with requester_vpc_name. .TP .B requester_vpc_name Name tag of the requesting VPC. Exclusive with requester_vpc_id. .TP .B peer_vpc_id ID of the VPC tp crete VPC peering connection with. This can be a VPC in another account. Exclusive with peer_vpc_name. .TP .B peer_vpc_name Name tag of the VPC tp crete VPC peering connection with. This can only be a VPC in the same account, else resolving it into a vpc ID will fail. Exclusive with peer_vpc_id. .TP .B conn_name The name to use for this VPC peering connection. .TP .B peer_owner_id ID of the owner of the peer VPC. Defaults to your account ID, so a value is required if peering with a VPC in a different account. .TP .B peer_region Region of peer VPC. For inter\-region vpc peering connections. Not required for intra\-region peering connections. .sp New in version 3005. .TP .B region Region to connect to. .TP .B key Secret key to be used. .TP .B keyid Access key to be used. .TP .B profile A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid. .UNINDENT .sp New in version 2016.11.0. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ensure peering twixt local vpc and the other guys: boto_vpc.vpc_peering_connection_present: \- requester_vpc_name: my_local_vpc \- peer_vpc_name: some_other_guys_vpc \- conn_name: peering_from_here_to_there \- peer_owner_id: 012345654321 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.bower .SS Installation of Bower Packages .sp These states manage the installed packages using Bower. Note that npm, git and bower must be installed for these states to be available, so bower states should include requisites to pkg.installed states for the packages which provide npm and git (simply \fBnpm\fP and \fBgit\fP in most cases), and npm.installed state for the package which provides bower. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C npm: pkg.installed git: pkg.installed bower: npm.installed require: \- pkg: npm \- pkg: git underscore: bower.installed: \- dir: /path/to/project \- require: \- npm: bower .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bower.bootstrap(name, user=None) Bootstraps a frontend distribution. .sp Will execute \(aqbower install\(aq on the specified directory. .INDENT 7.0 .TP .B user The user to run Bower with .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bower.installed(name, dir, pkgs=None, user=None, env=None) Verify that the given package is installed and is at the correct version (if specified). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C underscore: bower.installed: \- dir: /path/to/project \- user: someuser jquery#2.0: bower.installed: \- dir: /path/to/project .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The package to install .TP .B dir The target directory in which to install the package .TP .B pkgs A list of packages to install with a single Bower invocation; specifying this argument will ignore the \fBname\fP argument .TP .B user The user to run Bower with .TP .B env A list of environment variables to be set prior to execution. The format is the same as the \fI\%cmd.run\fP\&. state function. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bower.pruned(name, user=None, env=None) New in version 2017.7.0. .sp Cleans up local bower_components directory. .sp Will execute \(aqbower prune\(aq on the specified directory (param: name) .INDENT 7.0 .TP .B user The user to run Bower with .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.bower.removed(name, dir, user=None) Verify that the given package is not installed. .INDENT 7.0 .TP .B dir The target directory in which to install the package .TP .B user The user to run Bower with .UNINDENT .UNINDENT .SS salt.states.btrfs .sp Manage BTRFS file systems. .INDENT 0.0 .TP .B maintainer Alberto Planas <\fI\%aplanas@suse.com\fP> .TP .B maturity new .TP .B depends None .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.states.btrfs.properties(name, device, use_default=False, __dest=None, **properties) Makes sure that a list of properties are set in a subvolume, file or device. .INDENT 7.0 .TP .B name Name of the object to change .TP .B device Device where the object lives, if None, the device will be in name .TP .B use_default If True, this subvolume will be resolved to the default subvolume assigned during the create operation .TP .B properties Dictionary of properties .UNINDENT .sp Valid properties are \(aqro\(aq, \(aqlabel\(aq or \(aqcompression\(aq. Check the documentation to see where those properties are valid for each object. .UNINDENT .INDENT 0.0 .TP .B salt.states.btrfs.subvolume_created(name, device, qgroupids=None, set_default=False, copy_on_write=True, force_set_default=True, __dest=None) Makes sure that a btrfs subvolume is present. .INDENT 7.0 .TP .B name Name of the subvolume to add .TP .B device Device where to create the subvolume .TP .B qgroupids Add the newly created subcolume to a qgroup. This parameter is a list .TP .B set_default If True, this new subvolume will be set as default when mounted, unless subvol option in mount is used .TP .B copy_on_write If false, set the subvolume with chattr +C .TP .B force_set_default If false and the subvolume is already present, it will not force it as default if \fBset_default\fP is True .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.btrfs.subvolume_deleted(name, device, commit=False, __dest=None) Makes sure that a btrfs subvolume is removed. .INDENT 7.0 .TP .B name Name of the subvolume to remove .TP .B device Device where to remove the subvolume .TP .B commit Wait until the transaction is over .UNINDENT .UNINDENT .SS salt.states.cabal .SS Installation of Cabal Packages .sp New in version 2015.8.0. .sp These states manage the installed packages for Haskell using cabal. Note that cabal\-install must be installed for these states to be available, so cabal states should include a requisite to a pkg.installed state for the package which provides cabal (\fBcabal\-install\fP in case of Debian based distributions). Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&.. code\-block:: yaml .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B cabal\-install: pkg.installed .TP .B ShellCheck: .INDENT 7.0 .TP .B cabal.installed: .INDENT 7.0 .IP \(bu 2 require: \- pkg: cabal\-install .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cabal.installed(name, pkgs=None, user=None, install_global=False, env=None) Verify that the given package is installed and is at the correct version (if specified). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ShellCheck\-0.3.5: cabal: \- installed: .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The package to install .TP .B user The user to run cabal install with .TP .B install_global Install package globally instead of locally .TP .B env A list of environment variables to be set prior to execution. The format is the same as the \fI\%cmd.run\fP\&. state function. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cabal.removed(name, user=None, env=None) Verify that given package is not installed. .UNINDENT .SS salt.states.ceph .sp Manage ceph with salt. .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.states.ceph.quorum(name, **kwargs) Quorum state .sp This state checks the mon daemons are in quorum. It does not alter the cluster but can be used in formula as a dependency for many cluster operations. .sp Example usage in sls file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C quorum: sesceph.quorum: \- require: \- sesceph: mon_running .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.chef .SS Execute Chef client runs .sp Run chef\-client or chef\-solo .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-chef\-run: chef.client: \- override\-runlist: \(aqdemo1,demo2\(aq \- server: \(aqhttps://chef.domain.com\(aq default\-chef\-run: chef.client: [] my\-solo\-run: chef.solo: \- environment: dev .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.chef.client(name, **kwargs) .INDENT 7.0 .TP .B name Unique identifier for the state. Does not affect the Chef run. .TP .B server The chef server URL .TP .B client_key Set the client key file location .TP .B config The configuration file to use .TP .B config\-file\-jail Directory under which config files are allowed to be loaded (no client.rb or knife.rb outside this path will be loaded). .TP .B environment Set the Chef Environment on the node .TP .B group Group to set privilege to .TP .B json\-attributes Load attributes from a JSON file or URL .TP .B localmode Point chef\-client at local repository if True .TP .B log_level Set the log level (debug, info, warn, error, fatal) .TP .B logfile Set the log file location .TP .B node\-name The node name for this client .TP .B override\-runlist Replace current run list with specified items for a single run .TP .B pid Set the PID file location, defaults to /tmp/chef\-client.pid .TP .B run\-lock\-timeout Set maximum duration to wait for another client run to finish, default is indefinitely. .TP .B runlist Permanently replace current run list with specified items .TP .B user User to set privilege to .TP .B validation_key Set the validation key file location, used for registering new clients .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.chef.solo(name, **kwargs) .INDENT 7.0 .TP .B name Unique identifier for the state. Does not affect the Chef run. .TP .B config The configuration file to use .TP .B environment Set the Chef Environment on the node .TP .B group Group to set privilege to .TP .B json\-attributes Load attributes from a JSON file or URL .TP .B log_level Set the log level (debug, info, warn, error, fatal) .TP .B logfile Set the log file location .TP .B node\-name The node name for this client .TP .B override\-runlist Replace current run list with specified items for a single run .TP .B recipe\-url Pull down a remote gzipped tarball of recipes and untar it to the cookbook cache .TP .B run\-lock\-timeout Set maximum duration to wait for another client run to finish, default is indefinitely. .TP .B user User to set privilege to .UNINDENT .UNINDENT .SS salt.states.chocolatey .sp Manage Windows Packages using Chocolatey \&.. versionadded:: 2016.3.0 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Chocolatey pulls data from the Chocolatey internet database to determine current versions, find available versions, etc. This is normally a slow operation and may be optimized by specifying a local, smaller chocolatey repo. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.chocolatey.bootstrapped(name, force=False, source=None, version=None) New in version 3007.1. .sp Ensure chocolatey is installed on the system. .sp You can\(aqt upgrade an existing installation with this state. You must use chocolatey to upgrade chocolatey. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C choco upgrade chocolatey \-\-version 2.2.0 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the state that installs chocolatey. Required for all states. This is ignored. .IP \(bu 2 \fBforce\fP (\fI\%bool\fP) \-\- .sp Run the bootstrap process even if Chocolatey is found in the path. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 If chocolatey is already installed this will just re\-run the install script over the existing version. The \fBversion\fP parameter is ignored. .UNINDENT .UNINDENT .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- .sp The location of the \fB\&.nupkg\fP file or \fB\&.ps1\fP file to run from an alternate location. This can be one of the following types of URLs: .INDENT 2.0 .IP \(bu 2 salt:// .IP \(bu 2 http(s):// .IP \(bu 2 \fI\%ftp://\fP .IP \(bu 2 \fI\%file://\fP \- A local file on the system .UNINDENT .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- The version of chocolatey to install. The latest version is installed if this value is \fBNone\fP\&. Default is \fBNone\fP .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Bootstrap the latest version of chocolatey bootstrap_chocolatey: chocolatey.bootstrapped # Bootstrap the latest version of chocolatey # If chocolatey is already present, re\-run the install script bootstrap_chocolatey: chocolatey.bootstrapped: \- force: True # Bootstrap Chocolatey version 1.4.0 bootstrap_chocolatey: chocolatey.bootstrapped: \- version: 1.4.0 # Bootstrap Chocolatey from a local file bootstrap_chocolatey: chocolatey.bootstrapped: \- source: C:\eTemp\echocolatey.nupkg # Bootstrap Chocolatey from a file on the salt master bootstrap_chocolatey: chocolatey.bootstrapped: \- source: salt://Temp/chocolatey.nupkg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.chocolatey.installed(name, version=None, source=None, force=False, pre_versions=False, install_args=None, override_args=False, force_x86=False, package_args=None, allow_multiple=False, execution_timeout=None) Installs a package if not already installed .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be installed. Required. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- Install a specific version of the package. Defaults to the latest version. If the version is different to the one installed, then the specified version will be installed. Default is \fBNone\fP\&. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- Chocolatey repository (directory, share or remote URL, feed). \fBNone\fP defaults to the official Chocolatey feed. Default is \fBNone\fP\&. .IP \(bu 2 \fBforce\fP (\fI\%bool\fP) \-\- Reinstall the current version of an existing package. Do not use with \fBallow_multiple\fP\&. Default is \fBFalse\fP\&. .IP \(bu 2 \fBpre_versions\fP (\fI\%bool\fP) \-\- Include pre\-release packages. Default is \fBFalse\fP\&. .IP \(bu 2 \fBinstall_args\fP (\fI\%str\fP) \-\- Install arguments you want to pass to the installation process, i.e. product key or feature list. Default is \fBNone\fP\&. .IP \(bu 2 \fBoverride_args\fP (\fI\%bool\fP) \-\- Set to \fBTrue\fP to override the original install arguments (for the native installer) in the package and use your own. When this is set to \fBFalse\fP, install_args will be appended to the end of the default arguments. Default is \fBFalse\fP\&. .IP \(bu 2 \fBforce_x86\fP (\fI\%bool\fP) \-\- Force x86 (32bit) installation on 64bit systems. Default is \fBFalse\fP\&. .IP \(bu 2 \fBpackage_args\fP (\fI\%str\fP) \-\- Arguments you want to pass to the package. Default is \fBNone\fP\&. .IP \(bu 2 \fBallow_multiple\fP (\fI\%bool\fP) \-\- .sp Allow multiple versions of the package to be installed. Do not use with \fBforce\fP\&. Does not work with all packages. Default is \fBFalse\fP\&. .sp New in version 2017.7.0. .IP \(bu 2 \fBexecution_timeout\fP (\fI\%str\fP) \-\- Chocolatey execution timeout value you want to pass to the installation process. Default is \fBNone\fP\&. .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C install_some_package: chocolatey.installed: \- name: packagename \- version: \(aq12.04\(aq \- source: \(aqmychocolatey/source\(aq \- force: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.chocolatey.source_present(name, source_location, username=None, password=None, force=False, priority=None) Adds a Chocolatey source if not already present. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the source to be added as a chocolatey repository. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- Location of the source you want to work with. .IP \(bu 2 \fBusername\fP (\fI\%str\fP) \-\- The username for a chocolatey source that needs authentication credentials. .IP \(bu 2 \fBpassword\fP (\fI\%str\fP) \-\- The password for a chocolatey source that needx authentication credentials. .IP \(bu 2 \fBforce\fP (\fI\%bool\fP) \-\- Salt will not modify an existing repository with the same name. Set this option to \fBTrue\fP to update an existing repository. .IP \(bu 2 \fBpriority\fP (\fI\%int\fP) \-\- The priority order of this source as compared to other sources. Lower is better. Defaults to 0 (no priority). All priorities above 0 will be evaluated first, then zero\-based values will be evaluated in config file order. .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C add_some_source: chocolatey.source_present: \- name: reponame \- source: https://repo.exemple.com \- username: myuser \- password: mypassword \- priority: 100 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.chocolatey.unbootstrapped(name) New in version 3007.1. .sp Ensure chocolatey is removed from the system. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the state that uninstalls chocolatey. Required for all states. This is ignored. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Uninstall chocolatey uninstall_chocolatey: chocolatey.unbootstrapped .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.chocolatey.uninstalled(name, version=None, uninstall_args=None, override_args=False) Uninstalls a chocolatey package .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be uninstalled. Required. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- Uninstalls a specific version of the package. Defaults to the latest version installed. .IP \(bu 2 \fBuninstall_args\fP (\fI\%str\fP) \-\- A list of uninstall arguments you want to pass to the uninstallation process, i.e. product key or feature list .IP \(bu 2 \fBoverride_args\fP (\fI\%str\fP) \-\- Set to \fBTrue\fP if you want to override the original uninstall arguments (for the native uninstaller) in the package and use your own. When this is set to \fBFalse\fP, uninstall_args will be appended to the end of the default arguments .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C remove_my_package: chocolatey.uninstalled: \- name: mypackage \- version: \(aq21.5\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.chocolatey.upgraded(name, version=None, source=None, force=False, pre_versions=False, install_args=None, override_args=False, force_x86=False, package_args=None) Upgrades a chocolatey package. Will install the package if not installed. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be installed. Required. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- Install a specific version of the package. Defaults to latest version. If the version is greater than the one installed then the specified version will be installed. Default is \fBNone\fP\&. .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- Chocolatey repository (directory, share or remote URL, feed). Defaults to the official Chocolatey feed. Default is \fBNone\fP\&. .IP \(bu 2 \fBforce\fP (\fI\%bool\fP) \-\- \fBTrue\fP will reinstall an existing package with the same version. Default is \fBFalse\fP\&. .IP \(bu 2 \fBpre_versions\fP (\fI\%bool\fP) \-\- \fBTrue\fP will include pre\-release packages. Default is \fBFalse\fP\&. .IP \(bu 2 \fBinstall_args\fP (\fI\%str\fP) \-\- Install arguments you want to pass to the installation process, i.e product key or feature list. Default is \fBNone\fP\&. .IP \(bu 2 \fBoverride_args\fP (\fI\%bool\fP) \-\- \fBTrue\fP will override the original install arguments (for the native installer) in the package and use those specified in \fBinstall_args\fP\&. \fBFalse\fP will append install_args to the end of the default arguments. Default is \fBFalse\fP\&. .IP \(bu 2 \fBforce_x86\fP (\fI\%bool\fP) \-\- \fBTrue\fP forces 32bit installation on 64bit systems. Default is \fBFalse\fP\&. .IP \(bu 2 \fBpackage_args\fP (\fI\%str\fP) \-\- Arguments you want to pass to the package. Default is \fBNone\fP\&. .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C upgrade_some_package: chocolatey.upgraded: \- name: packagename \- version: \(aq12.04\(aq \- source: \(aqmychocolatey/source\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.chronos_job .sp Configure Chronos jobs via a salt proxy. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_job: chronos_job.config: \- config: schedule: \(dqR//PT2S\(dq command: \(dqecho \(aqhi\(aq\(dq owner: \(dqme@example.com\(dq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.2. .INDENT 0.0 .TP .B salt.states.chronos_job.absent(name) Ensure that the chronos job with the given name is not present. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The app name .TP .B Returns A standard Salt changes dictionary .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.chronos_job.config(name, config) Ensure that the chronos job with the given name is present and is configured to match the given config values. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The job name .IP \(bu 2 \fBconfig\fP \-\- The configuration to apply (dict) .UNINDENT .TP .B Returns A standard Salt changes dictionary .UNINDENT .UNINDENT .SS salt.states.cimc .sp A state module to manage Cisco UCS chassis devices. .INDENT 0.0 .TP .B codeauthor \fBSpencer Ervin <spencer_ervin@hotmail.com>\fP .TP .B maturity new .TP .B depends none .TP .B platform unix .UNINDENT .SS About .sp This state module was designed to handle connections to a Cisco Unified Computing System (UCS) chassis. This module relies on the CIMC proxy module to interface with the device. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%CIMC Proxy Module\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cimc.hostname(name, hostname=None) Ensures that the hostname is set to the specified value. .sp New in version 2019.2.0. .sp name: The name of the module function to execute. .sp hostname(str): The hostname of the server. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C set_name: cimc.hostname: \- hostname: foobar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cimc.logging_levels(name, remote=None, local=None) Ensures that the logging levels are set on the device. The logging levels must match the following options: emergency, alert, critical, error, warning, notice, informational, debug. .sp New in version 2019.2.0. .sp name: The name of the module function to execute. .sp remote(str): The logging level for SYSLOG logs. .sp local(str): The logging level for the local device. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C logging_levels: cimc.logging_levels: \- remote: informational \- local: notice .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cimc.ntp(name, servers) Ensures that the NTP servers are configured. Servers are provided as an individual string or list format. Only four NTP servers will be reviewed. Any entries past four will be ignored. .sp name: The name of the module function to execute. .sp servers(str, list): The IP address or FQDN of the NTP servers. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ntp_configuration_list: cimc.ntp: \- servers: \- foo.bar.com \- 10.10.10.10 ntp_configuration_str: cimc.ntp: \- servers: foo.bar.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cimc.power_configuration(name, policy=None, delayType=None, delayValue=None) Ensures that the power configuration is configured on the system. This is only available on some C\-Series servers. .sp New in version 2019.2.0. .sp name: The name of the module function to execute. .sp policy(str): The action to be taken when chassis power is restored after an unexpected power loss. This can be one of the following: .INDENT 7.0 .INDENT 3.5 reset: The server is allowed to boot up normally when power is restored. The server can restart immediately or, optionally, after a fixed or random delay. .sp stay\-off: The server remains off until it is manually restarted. .sp last\-state: The server restarts and the system attempts to restore any processes that were running before power was lost. .UNINDENT .UNINDENT .sp delayType(str): If the selected policy is reset, the restart can be delayed with this option. This can be one of the following: .INDENT 7.0 .INDENT 3.5 fixed: The server restarts after a fixed delay. .sp random: The server restarts after a random delay. .UNINDENT .UNINDENT .sp delayValue(int): If a fixed delay is selected, once chassis power is restored and the Cisco IMC has finished rebooting, the system waits for the specified number of seconds before restarting the server. Enter an integer between 0 and 240. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C reset_power: cimc.power_configuration: \- policy: reset \- delayType: fixed \- delayValue: 0 power_off: cimc.power_configuration: \- policy: stay\-off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cimc.syslog(name, primary=None, secondary=None) Ensures that the syslog servers are set to the specified values. A value of None will be ignored. .sp name: The name of the module function to execute. .sp primary(str): The IP address or FQDN of the primary syslog server. .sp secondary(str): The IP address or FQDN of the secondary syslog server. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C syslog_configuration: cimc.syslog: \- primary: 10.10.10.10 \- secondary: foo.bar.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cimc.user(name, id=\(aq\(aq, user=\(aq\(aq, priv=\(aq\(aq, password=\(aq\(aq, status=\(aqactive\(aq) Ensures that a user is configured on the device. Due to being unable to verify the user password. This is a forced operation. .sp New in version 2019.2.0. .sp name: The name of the module function to execute. .sp id(int): The user ID slot on the device. .sp user(str): The username of the user. .sp priv(str): The privilege level of the user. .sp password(str): The password of the user. .sp status(str): The status of the user. Can be either active or inactive. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C user_configuration: cimc.user: \- id: 11 \- user: foo \- priv: admin \- password: mypassword \- status: active .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.cisconso .sp State module for Cisco NSO Proxy minions .sp New in version 2016.11.0. .sp For documentation on setting up the cisconso proxy minion look in the documentation for \fI\%salt.proxy.cisconso\fP\&. .INDENT 0.0 .TP .B salt.states.cisconso.value_present(name, datastore, path, config) Ensure a specific value exists at a given path .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- The name for this rule .IP \(bu 2 \fBdatastore\fP (\fBDatastoreType\fP (\fBstr\fP enum).) \-\- The datastore, e.g. running, operational. One of the NETCONF store IETF types .IP \(bu 2 \fBpath\fP (\fBlist\fP, \fBstr\fP OR \fBtuple\fP) \-\- The device path to set the value at, a list of element names in order, / separated .IP \(bu 2 \fBconfig\fP (\fBdict\fP) \-\- The new value at the given path .UNINDENT .UNINDENT .sp Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C enable pap auth: cisconso.config_present: \- name: enable_pap_auth \- datastore: running \- path: devices/device/ex0/config/sys/interfaces/serial/ppp0/authentication \- config: authentication: method: pap \(dqlist\-name\(dq: foobar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.cloud .SS Using states instead of maps to deploy clouds .sp New in version 2014.1.0. .sp Use this minion to spin up a cloud instance: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-instance: cloud.profile: my\-ec2\-config .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cloud.absent(name, onlyif=None, unless=None) Ensure that no instances with the specified names exist. .sp CAUTION: This is a destructive state, which will search all configured cloud providers for the named instance, and destroy it. .INDENT 7.0 .TP .B name The name of the instance to destroy .TP .B onlyif Do run the state only if is unless succeed .TP .B unless Do not run the state at least unless succeed .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cloud.present(name, cloud_provider, onlyif=None, unless=None, opts=None, **kwargs) Spin up a single instance on a cloud provider, using salt\-cloud. This state does not take a profile argument; rather, it takes the arguments that would normally be configured as part of the state. .sp Note that while this function does take any configuration argument that would normally be used to create an instance, it will not verify the state of any of those arguments on an existing instance. Stateful properties of an instance should be configured using their own individual state (i.e., cloud.tagged, cloud.untagged, etc). .INDENT 7.0 .TP .B name The name of the instance to create .TP .B cloud_provider The name of the cloud provider to use .TP .B onlyif Do run the state only if is unless succeed .TP .B unless Do not run the state at least unless succeed .TP .B opts Any extra opts that need to be used .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cloud.profile(name, profile, onlyif=None, unless=None, opts=None, **kwargs) Create a single instance on a cloud provider, using a salt\-cloud profile. .sp Note that while profiles used this function do take any configuration argument that would normally be used to create an instance using a profile, this state will not verify the state of any of those arguments on an existing instance. Stateful properties of an instance should be configured using their own individual state (i.e., cloud.tagged, cloud.untagged, etc). .INDENT 7.0 .TP .B name The name of the instance to create .TP .B profile The name of the cloud profile to use .TP .B onlyif Do run the state only if is unless succeed .TP .B unless Do not run the state at least unless succeed .TP .B kwargs Any profile override or addition .TP .B opts Any extra opts that need to be used .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cloud.volume_absent(name, provider=None, **kwargs) Check that a block volume exists. .UNINDENT .INDENT 0.0 .TP .B salt.states.cloud.volume_attached(name, server_name, provider=None, **kwargs) Check if a block volume is attached. .UNINDENT .INDENT 0.0 .TP .B salt.states.cloud.volume_detached(name, server_name=None, provider=None, **kwargs) Check if a block volume is attached. .sp Returns True if server or Volume do not exist. .UNINDENT .INDENT 0.0 .TP .B salt.states.cloud.volume_present(name, provider=None, **kwargs) Check that a block volume exists. .UNINDENT .SS salt.states.cmd .SS Execution of arbitrary commands .sp The cmd state module manages the enforcement of executed commands, this state can tell a command to run under certain circumstances. .sp A simple example to execute a command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Store the current date in a file \(aqdate > /tmp/salt\-run\(aq: cmd.run .ft P .fi .UNINDENT .UNINDENT .sp Only run if another execution failed, in this case truncate syslog if there is no disk space: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aq> /var/log/messages/\(aq: cmd.run: \- unless: echo \(aqfoo\(aq > /tmp/.test && rm \-f /tmp/.test .ft P .fi .UNINDENT .UNINDENT .sp Only run if the file specified by \fBcreates\fP does not exist, in this case touch /tmp/foo if it does not exist: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C touch /tmp/foo: cmd.run: \- creates: /tmp/foo .ft P .fi .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 .sp .nf .ft C \(dqecho \(aqfoo\(aq | tee /tmp/bar > /tmp/baz\(dq: cmd.run: \- creates: \- /tmp/bar \- /tmp/baz .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBcreates\fP option was added to the cmd state in version 2014.7.0, and made a global requisite in 3001. .UNINDENT .UNINDENT .sp Sometimes when running a command that starts up a daemon, the init script doesn\(aqt return properly which causes Salt to wait indefinitely for a response. In situations like this try the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C run_installer: cmd.run: \- name: /tmp/installer.bin > /dev/null 2>&1 .ft P .fi .UNINDENT .UNINDENT .sp Salt determines whether the \fBcmd\fP state is successfully enforced based on the exit code returned by the command. If the command returns a zero exit code, then salt determines that the state was successfully enforced. If the script returns a non\-zero exit code, then salt determines that it failed to successfully enforce the state. If a command returns a non\-zero exit code but you wish to treat this as a success, then you must place the command in a script and explicitly set the exit code of the script to zero. .sp Please note that the success or failure of the state is not affected by whether a state change occurred nor the stateful argument. .sp When executing a command or script, the state (i.e., changed or not) of the command is unknown to Salt\(aqs state system. Therefore, by default, the \fBcmd\fP state assumes that any command execution results in a changed state. .sp This means that if a \fBcmd\fP state is watched by another state then the state that\(aqs watching will always be executed due to the \fIchanged\fP state in the \fBcmd\fP state. .SS Using the \(dqStateful\(dq Argument .sp Many state functions in this module now also accept a \fBstateful\fP argument. If \fBstateful\fP is specified to be true then it is assumed that the command or script will determine its own state and communicate it back by following a simple protocol described below: .INDENT 0.0 .IP 1. 3 \fBIf there\(aqs nothing in the stdout of the command, then assume no changes.\fP Otherwise, the stdout must be either in JSON or its \fIlast\fP non\-empty line must be a string of key=value pairs delimited by spaces (no spaces on either side of \fB=\fP). .IP 2. 3 \fBIf it\(aqs JSON then it must be a JSON object (e.g., {}).\fP If it\(aqs key=value pairs then quoting may be used to include spaces. (Python\(aqs shlex module is used to parse the key=value string) .sp Two special keys or attributes are recognized in the output: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C changed: bool (i.e., \(aqyes\(aq, \(aqno\(aq, \(aqtrue\(aq, \(aqfalse\(aq, case\-insensitive) comment: str (i.e., any string) .ft P .fi .UNINDENT .UNINDENT .sp So, only if \fBchanged\fP is \fBTrue\fP then assume the command execution has changed the state, and any other key values or attributes in the output will be set as part of the changes. .IP 3. 3 \fBIf there\(aqs a comment then it will be used as the comment of the state.\fP .sp Here\(aqs an example of how one might write a shell script for use with a stateful command: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C #!/bin/bash # echo \(dqWorking hard...\(dq # writing the state line echo # an empty line here so the next line will be the last. echo \(dqchanged=yes comment=\(aqsomething has changed\(aq whatever=123\(dq .ft P .fi .UNINDENT .UNINDENT .sp And an example SLS file using this module: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C Run myscript: cmd.run: \- name: /path/to/myscript \- cwd: / \- stateful: True Run only if myscript changed something: cmd.run: \- name: echo hello \- cwd: / \- onchanges: \- cmd: Run myscript .ft P .fi .UNINDENT .UNINDENT .sp Note that if the second \fBcmd.run\fP state also specifies \fBstateful: True\fP it can then be watched by some other states as well. .IP 4. 3 \fBThe stateful argument can optionally include a test_name parameter.\fP .sp This is used to specify a command to run in test mode. This command should return stateful data for changes that would be made by the command in the name parameter. .sp New in version 2015.2.0. .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C Run myscript: cmd.run: \- name: /path/to/myscript \- cwd: / \- stateful: \- test_name: /path/to/myscript test Run masterscript: cmd.script: \- name: masterscript \- source: salt://path/to/masterscript \- cwd: / \- stateful: \- test_name: masterscript test .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS Should I use \fI\%cmd.run\fP or \fI\%cmd.wait\fP? .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Use \fI\%cmd.run\fP together with \fI\%onchanges\fP instead of \fI\%cmd.wait\fP\&. .UNINDENT .UNINDENT .sp These two states are often confused. The important thing to remember about them is that \fI\%cmd.run\fP states are run each time the SLS file that contains them is applied. If it is more desirable to have a command that only runs after some other state changes, then \fI\%cmd.wait\fP does just that. \fI\%cmd.wait\fP is designed to \fI\%watch\fP other states, and is executed when the state it is watching changes. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /usr/local/bin/postinstall.sh: cmd.wait: \- watch: \- pkg: mycustompkg file.managed: \- source: salt://utils/scripts/postinstall.sh mycustompkg: pkg.installed: \- require: \- file: /usr/local/bin/postinstall.sh .ft P .fi .UNINDENT .UNINDENT .sp \fBcmd.wait\fP itself do not do anything; all functionality is inside its \fBmod_watch\fP function, which is called by \fBwatch\fP on changes. .sp The preferred format is using the \fI\%onchanges Requisite\fP, which works on \fBcmd.run\fP as well as on any other state. The example would then look as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /usr/local/bin/postinstall.sh: cmd.run: \- onchanges: \- pkg: mycustompkg file.managed: \- source: salt://utils/scripts/postinstall.sh mycustompkg: pkg.installed: \- require: \- file: /usr/local/bin/postinstall.sh .ft P .fi .UNINDENT .UNINDENT .SS How do I create an environment from a pillar map? .sp The map that comes from a pillar can be directly consumed by the env option! To use it, one may pass it like this. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C printenv: cmd.run: \- env: {{ salt[\(aqpillar.get\(aq](\(aqexample:key\(aq, {}) }} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cmd.call(name, func, args=(), kws=None, output_loglevel=\(aqdebug\(aq, hide_output=False, use_vt=False, **kwargs) Invoke a pre\-defined Python function with arguments specified in the state declaration. This function is mainly used by the \fI\%salt.renderers.pydsl\fP renderer. .sp In addition, the \fBstateful\fP argument has no effects here. .sp The return value of the invoked function will be interpreted as follows. .sp If it\(aqs a dictionary then it will be passed through to the state system, which expects it to have the usual structure returned by any salt state function. .sp Otherwise, the return value (denoted as \fBresult\fP in the code below) is expected to be a JSON serializable object, and this dictionary is returned: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqname\(aq: name \(aqchanges\(aq: {\(aqretval\(aq: result}, \(aqresult\(aq: True if result is None else bool(result), \(aqcomment\(aq: result if isinstance(result, str) else \(aq\(aq } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cmd.mod_watch(name, **kwargs) Execute a cmd function based on a watch call .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBwatch\fP \fI\%requisite\fP\&. It should not be called directly. .sp Parameters for this function should be set by the state being triggered. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cmd.run(name, cwd=None, root=None, runas=None, shell=None, env=None, prepend_path=None, stateful=False, output_loglevel=\(aqdebug\(aq, hide_output=False, timeout=None, ignore_timeout=False, use_vt=False, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Run a command if certain circumstances are met. Use \fBcmd.wait\fP if you want to use the \fBwatch\fP requisite. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fB**kwargs\fP of \fBcmd.run\fP are passed down to one of the following exec modules: .INDENT 0.0 .IP \(bu 2 \fBcmdmod.run_all\fP: If used with default \fBrunas\fP .IP \(bu 2 \fBcmdmod.run_chroot\fP: If used with non\-\fBroot\fP value for \fBrunas\fP .UNINDENT .sp For more information on what args are available for either of these, refer to the \fI\%cmdmod documentation\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The command to execute, remember that the command will execute with the path and permissions of the salt\-minion. .TP .B cwd The current working directory to execute the command in, defaults to /root .TP .B root Path to the root of the jail to use. If this parameter is set, the command will run inside a chroot .TP .B runas The user name (or uid) to run the command as .TP .B shell The shell to use for execution, defaults to the shell grain .TP .B env A list of environment variables to be set prior to execution. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C script\-foo: cmd.run: \- env: \- BATCH: \(aqyes\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The above illustrates a common PyYAML pitfall, that \fByes\fP, \fBno\fP, \fBon\fP, \fBoff\fP, \fBtrue\fP, and \fBfalse\fP are all loaded as boolean \fBTrue\fP and \fBFalse\fP values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found \fI\%here\fP\&. .UNINDENT .UNINDENT .sp Variables as values are not evaluated. So $PATH in the following example is a literal \(aq$PATH\(aq: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C script\-bar: cmd.run: \- env: \(dqPATH=/some/path:$PATH\(dq .ft P .fi .UNINDENT .UNINDENT .sp One can still use the existing $PATH by using a bit of Jinja: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set current_path = salt[\(aqenviron.get\(aq](\(aqPATH\(aq, \(aq/bin:/usr/bin\(aq) %} mycommand: cmd.run: \- name: ls \-l / \- env: \- PATH: {{ [current_path, \(aq/my/special/bin\(aq]|join(\(aq:\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When using environment variables on Windows, case\-sensitivity matters, i.e. Windows uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .TP .B prepend_path $PATH segment to prepend (trailing \(aq:\(aq not necessary) to $PATH. This is an easier alternative to the Jinja workaround. .sp New in version 2018.3.0. .TP .B stateful The command being executed is expected to return data about executing a state. For more information, see the \fI\%Using the \(dqStateful\(dq Argument\fP section. .TP .B output_loglevel debug Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .TP .B hide_output False Suppress stdout and stderr in the state\(aqs results. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .TP .B timeout If the command has not terminated after timeout seconds, send the subprocess sigterm, and if sigterm is ignored, follow up with sigkill .TP .B ignore_timeout Ignore the timeout of commands, which is useful for running nohup processes. .sp New in version 2015.8.0. .TP .B creates Only run if the file specified by \fBcreates\fP do not exist. If you specify a list of files then this state will only run if \fBany\fP of the files do not exist. .sp New in version 2014.7.0. .TP .B use_vt False Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .TP .B bg False If \fBTrue\fP, run command in background and do not await or deliver its results. .sp New in version 2016.3.6. .TP .B success_retcodes .INDENT 7.0 .INDENT 3.5 This parameter allows you to specify a list of non\-zero return codes that should be considered as successful. If the return code from the command matches any in the list, the state will have a \fBTrue\fP result instead of \fBFalse\fP\&. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B success_stdout: This parameter will allow a list of .INDENT 7.0 .INDENT 3.5 strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .UNINDENT .sp New in version 3004. .TP .B success_stderr: This parameter will allow a list of .INDENT 7.0 .INDENT 3.5 strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .UNINDENT .sp New in version 3004. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 cmd.run supports the usage of \fBreload_modules\fP\&. This functionality allows you to force Salt to reload all modules. You should only use \fBreload_modules\fP if your cmd.run does some sort of installation (such as \fBpip\fP), if you do not reload the modules future items in your state which rely on the software being installed will fail. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C getpip: cmd.run: \- name: /usr/bin/python /usr/local/sbin/get\-pip.py \- unless: which pip \- require: \- pkg: python \- file: /usr/local/sbin/get\-pip.py \- reload_modules: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cmd.script(name, source=None, template=None, cwd=None, runas=None, password=None, shell=None, env=None, stateful=False, timeout=None, use_vt=False, output_loglevel=\(aqdebug\(aq, hide_output=False, defaults=None, context=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Download a script and execute it with specified arguments. .INDENT 7.0 .TP .B source The location of the script to download. If the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs .TP .B template If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported .TP .B name Either \(dqcmd arg1 arg2 arg3...\(dq (cmd is not used) or a source \(dqsalt://...\(dq. .TP .B cwd The current working directory to execute the command in, defaults to /root .TP .B runas Specify an alternate user to run the command. The default behavior is to run as the user under which Salt is running. If running on a Windows minion you must also use the \fBpassword\fP argument, and the target user account must be in the Administrators group. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For Windows users, specifically Server users, it may be necessary to specify your runas user using the User Logon Name instead of the legacy logon name. Traditionally, logons would be in the following format. .INDENT 0.0 .INDENT 3.5 \fBDomain/user\fP .UNINDENT .UNINDENT .sp In the event this causes issues when executing scripts, use the UPN format which looks like the following. .INDENT 0.0 .INDENT 3.5 \fBuser@domain.local\fP .UNINDENT .UNINDENT .sp More information <\fI\%https://github.com/saltstack/salt/issues/55080\fP> .UNINDENT .UNINDENT .UNINDENT .sp password .sp New in version 3000: Windows only. Required when specifying \fBrunas\fP\&. This parameter will be ignored on non\-Windows platforms. .INDENT 7.0 .TP .B shell The shell to use for execution. The default is set in grains[\(aqshell\(aq] .TP .B env A list of environment variables to be set prior to execution. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt://scripts/foo.sh: cmd.script: \- env: \- BATCH: \(aqyes\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The above illustrates a common PyYAML pitfall, that \fByes\fP, \fBno\fP, \fBon\fP, \fBoff\fP, \fBtrue\fP, and \fBfalse\fP are all loaded as boolean \fBTrue\fP and \fBFalse\fP values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found \fI\%here\fP\&. .UNINDENT .UNINDENT .sp Variables as values are not evaluated. So $PATH in the following example is a literal \(aq$PATH\(aq: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt://scripts/bar.sh: cmd.script: \- env: \(dqPATH=/some/path:$PATH\(dq .ft P .fi .UNINDENT .UNINDENT .sp One can still use the existing $PATH by using a bit of Jinja: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set current_path = salt[\(aqenviron.get\(aq](\(aqPATH\(aq, \(aq/bin:/usr/bin\(aq) %} mycommand: cmd.run: \- name: ls \-l / \- env: \- PATH: {{ [current_path, \(aq/my/special/bin\(aq]|join(\(aq:\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When using environment variables on Windows, case\-sensitivity matters, i.e. Windows uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .TP .B saltenv \fBbase\fP The Salt environment to use .TP .B stateful The command being executed is expected to return data about executing a state. For more information, see the \fI\%Using the \(dqStateful\(dq Argument\fP section. .TP .B timeout If the command has not terminated after timeout seconds, send the subprocess sigterm, and if sigterm is ignored, follow up with sigkill .TP .B args String of command line args to pass to the script. Only used if no args are specified as part of the \fIname\fP argument. To pass a string containing spaces in YAML, you will need to doubly\-quote it: \(dqarg1 \(aqarg two\(aq arg3\(dq .TP .B creates Only run if the file specified by \fBcreates\fP do not exist. If you specify a list of files then this state will only run if \fBany\fP of the files do not exist. .sp New in version 2014.7.0. .TP .B use_vt Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .TP .B context New in version 2016.3.0. .sp Overrides default context variables passed to the template. .TP .B defaults New in version 2016.3.0. .sp Default context passed to the template. .TP .B output_loglevel debug Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .TP .B hide_output False Suppress stdout and stderr in the state\(aqs results. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .TP .B success_retcodes .INDENT 7.0 .INDENT 3.5 This parameter allows you to specify a list of non\-zero return codes that should be considered as successful. If the return code from the command matches any in the list, the state will have a \fBTrue\fP result instead of \fBFalse\fP\&. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B success_stdout: This parameter will allow a list of .INDENT 7.0 .INDENT 3.5 strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .UNINDENT .sp New in version 3004. .TP .B success_stderr: This parameter will allow a list of .INDENT 7.0 .INDENT 3.5 strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .UNINDENT .sp New in version 3004. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cmd.wait(name, cwd=None, root=None, runas=None, shell=None, env=(), stateful=False, output_loglevel=\(aqdebug\(aq, hide_output=False, use_vt=False, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Run the given command only if the watch statement calls it. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Use \fI\%cmd.run\fP together with \fBonchanges\fP instead of \fI\%cmd.wait\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The command to execute, remember that the command will execute with the path and permissions of the salt\-minion. .TP .B cwd The current working directory to execute the command in, defaults to /root .TP .B root Path to the root of the jail to use. If this parameter is set, the command will run inside a chroot .TP .B runas The user name to run the command as .TP .B shell The shell to use for execution, defaults to /bin/sh .TP .B env A list of environment variables to be set prior to execution. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C script\-foo: cmd.wait: \- env: \- BATCH: \(aqyes\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The above illustrates a common PyYAML pitfall, that \fByes\fP, \fBno\fP, \fBon\fP, \fBoff\fP, \fBtrue\fP, and \fBfalse\fP are all loaded as boolean \fBTrue\fP and \fBFalse\fP values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found \fI\%here\fP\&. .UNINDENT .UNINDENT .sp Variables as values are not evaluated. So $PATH in the following example is a literal \(aq$PATH\(aq: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C script\-bar: cmd.wait: \- env: \(dqPATH=/some/path:$PATH\(dq .ft P .fi .UNINDENT .UNINDENT .sp One can still use the existing $PATH by using a bit of Jinja: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set current_path = salt[\(aqenviron.get\(aq](\(aqPATH\(aq, \(aq/bin:/usr/bin\(aq) %} mycommand: cmd.run: \- name: ls \-l / \- env: \- PATH: {{ [current_path, \(aq/my/special/bin\(aq]|join(\(aq:\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When using environment variables on Windows, case\-sensitivity matters, i.e. Windows uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .TP .B stateful The command being executed is expected to return data about executing a state. For more information, see the \fI\%Using the \(dqStateful\(dq Argument\fP section. .TP .B creates Only run if the file specified by \fBcreates\fP do not exist. If you specify a list of files then this state will only run if \fBany\fP of the files do not exist. .sp New in version 2014.7.0. .TP .B output_loglevel debug Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .TP .B hide_output False Suppress stdout and stderr in the state\(aqs results. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .TP .B use_vt Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .TP .B success_retcodes .INDENT 7.0 .INDENT 3.5 This parameter allows you to specify a list of non\-zero return codes that should be considered as successful. If the return code from the command matches any in the list, the state will have a \fBTrue\fP result instead of \fBFalse\fP\&. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B success_stdout: This parameter will allow a list of .INDENT 7.0 .INDENT 3.5 strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .UNINDENT .sp New in version 3004. .TP .B success_stderr: This parameter will allow a list of .INDENT 7.0 .INDENT 3.5 strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .UNINDENT .sp New in version 3004. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cmd.wait_call(name, func, args=(), kws=None, stateful=False, use_vt=False, output_loglevel=\(aqdebug\(aq, hide_output=False, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.states.cmd.wait_script(name, source=None, template=None, cwd=None, runas=None, shell=None, env=None, stateful=False, use_vt=False, output_loglevel=\(aqdebug\(aq, hide_output=False, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) Download a script from a remote source and execute it only if a watch statement calls it. .INDENT 7.0 .TP .B source The source script being downloaded to the minion, this source script is hosted on the salt master server. If the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs .TP .B template If this setting is applied then the named templating engine will be used to render the downloaded file, currently jinja, mako, and wempy are supported .TP .B name The command to execute, remember that the command will execute with the path and permissions of the salt\-minion. .TP .B cwd The current working directory to execute the command in, defaults to /root .TP .B runas The user name to run the command as .TP .B shell The shell to use for execution, defaults to the shell grain .TP .B env A list of environment variables to be set prior to execution. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt://scripts/foo.sh: cmd.wait_script: \- env: \- BATCH: \(aqyes\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The above illustrates a common PyYAML pitfall, that \fByes\fP, \fBno\fP, \fBon\fP, \fBoff\fP, \fBtrue\fP, and \fBfalse\fP are all loaded as boolean \fBTrue\fP and \fBFalse\fP values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found \fI\%here\fP\&. .UNINDENT .UNINDENT .sp Variables as values are not evaluated. So $PATH in the following example is a literal \(aq$PATH\(aq: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt://scripts/bar.sh: cmd.wait_script: \- env: \(dqPATH=/some/path:$PATH\(dq .ft P .fi .UNINDENT .UNINDENT .sp One can still use the existing $PATH by using a bit of Jinja: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set current_path = salt[\(aqenviron.get\(aq](\(aqPATH\(aq, \(aq/bin:/usr/bin\(aq) %} mycommand: cmd.run: \- name: ls \-l / \- env: \- PATH: {{ [current_path, \(aq/my/special/bin\(aq]|join(\(aq:\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When using environment variables on Windows, case\-sensitivity matters, i.e. Windows uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .TP .B stateful The command being executed is expected to return data about executing a state. For more information, see the \fI\%Using the \(dqStateful\(dq Argument\fP section. .TP .B use_vt Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .TP .B output_loglevel debug Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .TP .B hide_output False Suppress stdout and stderr in the state\(aqs results. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .TP .B success_retcodes .INDENT 7.0 .INDENT 3.5 This parameter allows you to specify a list of non\-zero return codes that should be considered as successful. If the return code from the command matches any in the list, the state will have a \fBTrue\fP result instead of \fBFalse\fP\&. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B success_stdout: This parameter will allow a list of .INDENT 7.0 .INDENT 3.5 strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .UNINDENT .sp New in version 3004. .TP .B success_stderr: This parameter will allow a list of .INDENT 7.0 .INDENT 3.5 strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .UNINDENT .sp New in version 3004. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cmd.watch(name, cwd=None, root=None, runas=None, shell=None, env=(), stateful=False, output_loglevel=\(aqdebug\(aq, hide_output=False, use_vt=False, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs) This function is an alias of \fBwait\fP\&. .INDENT 7.0 .INDENT 3.5 Run the given command only if the watch statement calls it. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Use \fI\%cmd.run\fP together with \fBonchanges\fP instead of \fI\%cmd.wait\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B name The command to execute, remember that the command will execute with the path and permissions of the salt\-minion. .TP .B cwd The current working directory to execute the command in, defaults to /root .TP .B root Path to the root of the jail to use. If this parameter is set, the command will run inside a chroot .TP .B runas The user name to run the command as .TP .B shell The shell to use for execution, defaults to /bin/sh .TP .B env A list of environment variables to be set prior to execution. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C script\-foo: cmd.wait: \- env: \- BATCH: \(aqyes\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The above illustrates a common PyYAML pitfall, that \fByes\fP, \fBno\fP, \fBon\fP, \fBoff\fP, \fBtrue\fP, and \fBfalse\fP are all loaded as boolean \fBTrue\fP and \fBFalse\fP values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found \fI\%here\fP\&. .UNINDENT .UNINDENT .sp Variables as values are not evaluated. So $PATH in the following example is a literal \(aq$PATH\(aq: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C script\-bar: cmd.wait: \- env: \(dqPATH=/some/path:$PATH\(dq .ft P .fi .UNINDENT .UNINDENT .sp One can still use the existing $PATH by using a bit of Jinja: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set current_path = salt[\(aqenviron.get\(aq](\(aqPATH\(aq, \(aq/bin:/usr/bin\(aq) %} mycommand: cmd.run: \- name: ls \-l / \- env: \- PATH: {{ [current_path, \(aq/my/special/bin\(aq]|join(\(aq:\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When using environment variables on Windows, case\-sensitivity matters, i.e. Windows uses \fIPath\fP as opposed to \fIPATH\fP for other systems. .UNINDENT .UNINDENT .TP .B stateful The command being executed is expected to return data about executing a state. For more information, see the \fI\%Using the \(dqStateful\(dq Argument\fP section. .TP .B creates Only run if the file specified by \fBcreates\fP do not exist. If you specify a list of files then this state will only run if \fBany\fP of the files do not exist. .sp New in version 2014.7.0. .TP .B output_loglevel debug Control the loglevel at which the output from the command is logged to the minion log. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The command being run will still be logged at the \fBdebug\fP loglevel regardless, unless \fBquiet\fP is used for this value. .UNINDENT .UNINDENT .TP .B hide_output False Suppress stdout and stderr in the state\(aqs results. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is separate from \fBoutput_loglevel\fP, which only handles how Salt logs to the minion log. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .TP .B use_vt Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental. .TP .B success_retcodes .INDENT 7.0 .INDENT 3.5 This parameter allows you to specify a list of non\-zero return codes that should be considered as successful. If the return code from the command matches any in the list, the state will have a \fBTrue\fP result instead of \fBFalse\fP\&. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B success_stdout: This parameter will allow a list of .INDENT 7.0 .INDENT 3.5 strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .UNINDENT .sp New in version 3004. .TP .B success_stderr: This parameter will allow a list of .INDENT 7.0 .INDENT 3.5 strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero. .UNINDENT .UNINDENT .sp New in version 3004. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.states.composer .SS Installation of Composer Packages .sp These states manage the installed packages for composer for PHP. Note that either composer is installed and accessible via a bin directory or you can pass the location of composer in the state. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C get\-composer: cmd.run: \- name: \(aqCURL=\(gawhich curl\(ga; $CURL \-sS https://getcomposer.org/installer | php\(aq \- unless: test \-f /usr/local/bin/composer \- cwd: /root/ install\-composer: cmd.wait: \- name: mv /root/composer.phar /usr/local/bin/composer \- cwd: /root/ \- watch: \- cmd: get\-composer /path/to/project: composer.installed: \- no_dev: true \- require: \- cmd: install\-composer # Without composer installed in your PATH # Note: composer.phar must be executable for state to work properly /path/to/project: composer.installed: \- composer: /path/to/composer.phar \- php: /usr/local/bin/php \- no_dev: true .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.composer.installed(name, composer=None, php=None, user=None, prefer_source=None, prefer_dist=None, no_scripts=None, no_plugins=None, optimize=None, no_dev=None, quiet=False, composer_home=\(aq/root\(aq, always_check=True, env=None) Verify that the correct versions of composer dependencies are present. .INDENT 7.0 .TP .B name Directory location of the \fBcomposer.json\fP file. .TP .B composer Location of the \fBcomposer.phar\fP file. If not set composer will just execute \fBcomposer\fP as if it is installed globally. (i.e. \fB/path/to/composer.phar\fP) .TP .B php Location of the php executable to use with composer. (i.e. \fB/usr/bin/php\fP) .TP .B user Which system user to run composer as. .sp New in version 2014.1.4. .TP .B prefer_source \fB\-\-prefer\-source\fP option of composer. .TP .B prefer_dist \fB\-\-prefer\-dist\fP option of composer. .TP .B no_scripts \fB\-\-no\-scripts\fP option of composer. .TP .B no_plugins \fB\-\-no\-plugins\fP option of composer. .TP .B optimize \fB\-\-optimize\-autoloader\fP option of composer. Recommended for production. .TP .B no_dev \fB\-\-no\-dev\fP option for composer. Recommended for production. .TP .B quiet \fB\-\-quiet\fP option for composer. Whether or not to return output from composer. .TP .B composer_home \fB$COMPOSER_HOME\fP environment variable .TP .B always_check If \fBTrue\fP, \fIalways\fP run \fBcomposer install\fP in the directory. This is the default behavior. If \fBFalse\fP, only run \fBcomposer install\fP if there is no vendor directory present. .TP .B env A list of environment variables to be set prior to execution. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.composer.update(name, composer=None, php=None, user=None, prefer_source=None, prefer_dist=None, no_scripts=None, no_plugins=None, optimize=None, no_dev=None, quiet=False, composer_home=\(aq/root\(aq, env=None) Composer update the directory to ensure we have the latest versions of all project dependencies. .INDENT 7.0 .TP .B name Directory location of the \fBcomposer.json\fP file. .TP .B composer Location of the \fBcomposer.phar\fP file. If not set composer will just execute \fBcomposer\fP as if it is installed globally. (i.e. /path/to/composer.phar) .TP .B php Location of the php executable to use with composer. (i.e. \fB/usr/bin/php\fP) .TP .B user Which system user to run composer as. .sp New in version 2014.1.4. .TP .B prefer_source \fB\-\-prefer\-source\fP option of composer. .TP .B prefer_dist \fB\-\-prefer\-dist\fP option of composer. .TP .B no_scripts \fB\-\-no\-scripts\fP option of composer. .TP .B no_plugins \fB\-\-no\-plugins\fP option of composer. .TP .B optimize \fB\-\-optimize\-autoloader\fP option of composer. Recommended for production. .TP .B no_dev \fB\-\-no\-dev\fP option for composer. Recommended for production. .TP .B quiet \fB\-\-quiet\fP option for composer. Whether or not to return output from composer. .TP .B composer_home \fB$COMPOSER_HOME\fP environment variable .TP .B env A list of environment variables to be set prior to execution. .UNINDENT .UNINDENT .SS salt.states.consul .SS Consul Management .sp New in version 3005. .sp The consul module is used to create and manage Consul ACLs .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C acl_present: consul.acl_present: \- id: 38AC8470\-4A83\-4140\-8DFD\-F924CD32917F \- name: acl_name \- rules: node \(dq\(dq {policy = \(dqwrite\(dq} service \(dq\(dq {policy = \(dqread\(dq} key \(dq_rexec\(dq {policy = \(dqwrite\(dq} \- type: client \- consul_url: http://localhost:8500 acl_delete: consul.acl_absent: \- id: 38AC8470\-4A83\-4140\-8DFD\-F924CD32917F .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.consul.acl_absent(name, id=None, token=None, consul_url=\(aqhttp://localhost:8500\(aq) Ensure the ACL is absent .INDENT 7.0 .TP .B name Specifies a human\-friendly name for the ACL token. .TP .B id Specifies the ID of the ACL. .TP .B token token to authenticate you Consul query .TP .B consul_url \fI\%http://locahost:8500\fP consul URL to query .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For more information \fI\%https://www.consul.io/api/acl.html#delete\-acl\-token\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.consul.acl_present(name, id=None, token=None, type=\(aqclient\(aq, rules=\(aq\(aq, consul_url=\(aqhttp://localhost:8500\(aq) Ensure the ACL is present .INDENT 7.0 .TP .B name Specifies a human\-friendly name for the ACL token. .TP .B id Specifies the ID of the ACL. .TP .B type: client Specifies the type of ACL token. Valid values are: client and management. .TP .B rules Specifies rules for this ACL token. .TP .B consul_url \fI\%http://locahost:8500\fP consul URL to query .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For more information \fI\%https://www.consul.io/api/acl.html#create\-acl\-token\fP, \fI\%https://www.consul.io/api/acl.html#update\-acl\-token\fP .UNINDENT .UNINDENT .UNINDENT .SS salt.states.cron .SS Management of cron, the Unix command scheduler .sp Cron declarations require a number of parameters. The following are the parameters used by Salt to define the various timing values for a cron job: .INDENT 0.0 .IP \(bu 2 \fBminute\fP .IP \(bu 2 \fBhour\fP .IP \(bu 2 \fBdaymonth\fP .IP \(bu 2 \fBmonth\fP .IP \(bu 2 \fBdayweek\fP (0 to 6 are Sunday through Saturday, 7 can also be used for Sunday) .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Any timing arguments not specified take a value of \fB*\fP\&. This means that setting \fBhour\fP to \fB5\fP, while not defining the \fBminute\fP param, will result in Salt adding a job that will execute every minute between 5 and 6 A.M.! .sp Additionally, the default user for these states is \fBroot\fP\&. Therefore, if the cron job is for another user, it is necessary to specify that user with the \fBuser\fP parameter. .UNINDENT .UNINDENT .sp A long time ago (before 2014.2), when making changes to an existing cron job, the name declaration is the parameter used to uniquely identify the job, so if an existing cron that looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C date > /tmp/crontest: cron.present: \- user: root \- minute: 5 .ft P .fi .UNINDENT .UNINDENT .sp Is changed to this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C date > /tmp/crontest: cron.present: \- user: root \- minute: 7 \- hour: 2 .ft P .fi .UNINDENT .UNINDENT .sp Then the existing cron will be updated, but if the cron command is changed, then a new cron job will be added to the user\(aqs crontab. .sp The current behavior is still relying on that mechanism, but you can also specify an identifier to identify your crontabs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C date > /tmp/crontest: cron.present: \- identifier: SUPERCRON \- user: root \- minute: 7 \- hour: 2 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2014.1.2. .sp And, some months later, you modify it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C superscript > /tmp/crontest: cron.present: \- identifier: SUPERCRON \- user: root \- minute: 3 \- hour: 4 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2014.1.2. .sp The old \fBdate > /tmp/crontest\fP will be replaced by \fBsuperscript > /tmp/crontest\fP\&. .sp Additionally, Salt also supports running a cron every \fBx minutes\fP very similarly to the Unix convention of using \fB*/5\fP to have a job run every five minutes. In Salt, this looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C date > /tmp/crontest: cron.present: \- user: root \- minute: \(aq*/5\(aq .ft P .fi .UNINDENT .UNINDENT .sp The job will now run every 5 minutes. .sp Additionally, the temporal parameters (minute, hour, etc.) can be randomized by using \fBrandom\fP instead of using a specific value. For example, by using the \fBrandom\fP keyword in the \fBminute\fP parameter of a cron state, the same cron job can be pushed to hundreds or thousands of hosts, and they would each use a randomly\-generated minute. This can be helpful when the cron job accesses a network resource, and it is not desirable for all hosts to run the job concurrently. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /path/to/cron/script: cron.present: \- user: root \- minute: random \- hour: 2 .ft P .fi .UNINDENT .UNINDENT .sp New in version 0.16.0. .sp Since Salt assumes a value of \fB*\fP for unspecified temporal parameters, adding a parameter to the state and setting it to \fBrandom\fP will change that value from \fB*\fP to a randomized numeric value. However, if that field in the cron entry on the minion already contains a numeric value, then using the \fBrandom\fP keyword will not modify it. .sp Added the opportunity to set a job with a special keyword like \fI\%\(aq@reboot\fP\(aq or \fI\%\(aq@hourly\fP\(aq. Quotes must be used, otherwise PyYAML will strip the \(aq@\(aq sign. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /path/to/cron/script: cron.present: \- user: root \- special: \(aq@hourly\(aq .ft P .fi .UNINDENT .UNINDENT .sp The script will be executed every reboot if cron daemon support this option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /path/to/cron/otherscript: cron.absent: \- user: root \- special: \(aq@daily\(aq .ft P .fi .UNINDENT .UNINDENT .sp This counter part definition will ensure than a job with a special keyword is not set. .INDENT 0.0 .TP .B salt.states.cron.absent(name, user=\(aqroot\(aq, identifier=False, special=None, **kwargs) Verifies that the specified cron job is absent for the specified user. .sp If an \fBidentifier\fP is not passed then the \fBname\fP is used to identify the cron job for removal. .INDENT 7.0 .TP .B name The command that should be absent in the user crontab. .TP .B user The name of the user whose crontab needs to be modified, defaults to the root user .TP .B identifier Custom\-defined identifier for tracking the cron line for future crontab edits. This defaults to the state name .TP .B special The special keyword used in the job (eg. @reboot, @hourly...). Quotes must be used, otherwise PyYAML will strip the \(aq@\(aq sign. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cron.env_absent(name, user=\(aqroot\(aq) Verifies that the specified environment variable is absent from the crontab for the specified user .INDENT 7.0 .TP .B name The name of the environment variable to remove from the user crontab .TP .B user The name of the user whose crontab needs to be modified, defaults to the root user .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cron.env_present(name, value=None, user=\(aqroot\(aq) Verifies that the specified environment variable is present in the crontab for the specified user. .INDENT 7.0 .TP .B name The name of the environment variable to set in the user crontab .TP .B user The name of the user whose crontab needs to be modified, defaults to the root user .TP .B value The value to set for the given environment variable .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cron.file(name, source_hash=\(aq\(aq, source_hash_name=None, user=\(aqroot\(aq, template=None, context=None, replace=True, defaults=None, backup=\(aq\(aq, **kwargs) Provides file.managed\-like functionality (templating, etc.) for a pre\-made crontab file, to be assigned to a given user. .INDENT 7.0 .TP .B name The source file to be used as the crontab. This source file can be hosted on either the salt master server, or on an HTTP or FTP server. For files hosted on the salt file server, if the file is located on the master in the directory named spam, and is called eggs, the source string is \fBsalt://spam/eggs\fP .sp If the file is hosted on a HTTP or FTP server then the source_hash argument is also required .TP .B source_hash This can be either a file which contains a source hash string for the source, or a source hash string. The source hash string is the hash algorithm followed by the hash of the file: \fBmd5=e138491e9d5b97023cea823fe17bac22\fP .TP .B source_hash_name When \fBsource_hash\fP refers to a hash file, Salt will try to find the correct hash by matching the filename/URI associated with that hash. By default, Salt will look for the filename being managed. When managing a file at path \fB/tmp/foo.txt\fP, then the following line in a hash file would match: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C acbd18db4cc2f85cedef654fccc4a4d8 foo.txt .ft P .fi .UNINDENT .UNINDENT .sp However, sometimes a hash file will include multiple similar paths: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C 37b51d194a7513e45b56f6524f2d51f2 ./dir1/foo.txt acbd18db4cc2f85cedef654fccc4a4d8 ./dir2/foo.txt 73feffa4b7f6bb68e44cf984c85f6e88 ./dir3/foo.txt .ft P .fi .UNINDENT .UNINDENT .sp In cases like this, Salt may match the incorrect hash. This argument can be used to tell Salt which filename to match, to ensure that the correct hash is identified. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo_crontab: cron.file: \- name: https://mydomain.tld/dir2/foo.txt \- source_hash: https://mydomain.tld/hashes \- source_hash_name: ./dir2/foo.txt .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument must contain the full filename entry from the checksum file, as this argument is meant to disambiguate matches for multiple files that have the same basename. So, in the example above, simply using \fBfoo.txt\fP would not match. .UNINDENT .UNINDENT .sp New in version 2016.3.5. .TP .B user The user to whom the crontab should be assigned. This defaults to root. .TP .B template If this setting is applied then the named templating engine will be used to render the downloaded file. Currently, jinja and mako are supported. .TP .B context Overrides default context variables passed to the template. .TP .B replace If the crontab should be replaced, if False then this command will be ignored if a crontab exists for the specified user. Default is True. .TP .B defaults Default context passed to the template. .TP .B backup Overrides the default backup mode for the user\(aqs crontab. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cron.present(name, user=\(aqroot\(aq, minute=\(aq*\(aq, hour=\(aq*\(aq, daymonth=\(aq*\(aq, month=\(aq*\(aq, dayweek=\(aq*\(aq, comment=None, commented=False, identifier=False, special=None) Verifies that the specified cron job is present for the specified user. It is recommended to use \fIidentifier\fP\&. Otherwise the cron job is installed twice if you change the name. For more advanced information about what exactly can be set in the cron timing parameters, check your cron system\(aqs documentation. Most Unix\-like systems\(aq cron documentation can be found via the crontab man page: \fBman 5 crontab\fP\&. .INDENT 7.0 .TP .B name The command that should be executed by the cron job. .TP .B user The name of the user whose crontab needs to be modified, defaults to the root user .TP .B minute The information to be set into the minute section, this can be any string supported by your cron system\(aqs the minute field. Default is \fB*\fP .TP .B hour The information to be set in the hour section. Default is \fB*\fP .TP .B daymonth The information to be set in the day of month section. Default is \fB*\fP .TP .B month The information to be set in the month section. Default is \fB*\fP .TP .B dayweek The information to be set in the day of week section. Default is \fB*\fP .TP .B comment User comment to be added on line previous the cron job .TP .B commented The cron job is set commented (prefixed with \fB#DISABLED#\fP). Defaults to False. .sp New in version 2016.3.0. .TP .B identifier Custom\-defined identifier for tracking the cron line for future crontab edits. This defaults to the state name .TP .B special A special keyword to specify periodicity (eg. @reboot, @hourly...). Quotes must be used, otherwise PyYAML will strip the \(aq@\(aq sign. .sp New in version 2016.3.0. .UNINDENT .UNINDENT .SS salt.states.cryptdev .SS Opening of Encrypted Devices .sp Ensure that an encrypted device is mapped with the \fImapped\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mappedname: cryptdev.mapped: \- device: /dev/sdb1 \- keyfile: /etc/keyfile.key \- opts: \- size=256 swap: cryptdev.mapped: \- device: /dev/sdx4 \- keyfile: /dev/urandom \- opts: swap,cipher=aes\-cbc\-essiv:sha256,size=256 mappedbyuuid: cryptdev.mapped: \- device: UUID=066e0200\-2867\-4ebe\-b9e6\-f30026ca2314 \- keyfile: /etc/keyfile.key \- config: /etc/alternate\-crypttab .ft P .fi .UNINDENT .UNINDENT .sp New in version 2018.3.0. .INDENT 0.0 .TP .B salt.states.cryptdev.mapped(name, device, keyfile=None, opts=None, config=\(aq/etc/crypttab\(aq, persist=True, immediate=False, match_on=\(aqname\(aq) Verify that a device is mapped .INDENT 7.0 .TP .B name The name under which the device is to be mapped .TP .B device The device name, typically the device node, such as \fB/dev/sdb1\fP or \fBUUID=066e0200\-2867\-4ebe\-b9e6\-f30026ca2314\fP\&. .TP .B keyfile Either \fBNone\fP if the password is to be entered manually on boot, or an absolute path to a keyfile. If the password is to be asked interactively, the mapping cannot be performed with \fBimmediate=True\fP\&. .TP .B opts A list object of options or a comma delimited list .TP .B config Set an alternative location for the crypttab, if the map is persistent, Default is \fB/etc/crypttab\fP .TP .B persist Set if the map should be saved in the crypttab, Default is \fBTrue\fP .TP .B immediate Set if the device mapping should be executed immediately. Requires that the keyfile not be \fBNone\fP, because the password cannot be asked interactively. Note that options are not passed through on the initial mapping. Default is \fBFalse\fP\&. .TP .B match_on A name or list of crypttab properties on which this state should be applied. Default is \fBname\fP, meaning that the line is matched only by the name parameter. If the desired configuration requires two devices mapped to the same name, supply a list of parameters to match on. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cryptdev.unmapped(name, config=\(aq/etc/crypttab\(aq, persist=True, immediate=False) Ensure that a device is unmapped .INDENT 7.0 .TP .B name The name to ensure is not mapped .TP .B config Set an alternative location for the crypttab, if the map is persistent, Default is \fB/etc/crypttab\fP .TP .B persist Set if the map should be removed from the crypttab. Default is \fBTrue\fP .TP .B immediate Set if the device should be unmapped immediately. Default is \fBFalse\fP\&. .UNINDENT .UNINDENT .SS salt.states.csf .SS CSF Ip tables management .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 csf utility .UNINDENT .TP .B configuration See \fI\%http://download.configserver.com/csf/install.txt\fP for setup instructions. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Simply allow/deny rules: csf.rule_present: ip: 1.2.3.4 method: allow .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.csf.nics_skip(name, nics, ipv6) Alias for \fI\%csf.nics_skipped\fP .UNINDENT .INDENT 0.0 .TP .B salt.states.csf.nics_skipped(name, nics, ipv6=False) .INDENT 7.0 .TP .B name Meaningless arg, but required for state. .TP .B nics A list of nics to skip. .TP .B ipv6 Boolean. Set to true if you want to skip the ipv6 interface. Default false (ipv4). .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.csf.option_present(name, value, reload=False) Ensure the state of a particular option/setting in csf. .INDENT 7.0 .TP .B name The option name in csf.conf .TP .B value The value it should be set to. .TP .B reload Boolean. If set to true, csf will be reloaded after. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.csf.ports_open(name, ports, proto=\(aqtcp\(aq, direction=\(aqin\(aq) Ensure ports are open for a protocol, in a direction. e.g. \- proto=\(aqtcp\(aq, direction=\(aqin\(aq would set the values for TCP_IN in the csf.conf file. .INDENT 7.0 .TP .B ports A list of ports that should be open. .TP .B proto The protocol. May be one of \(aqtcp\(aq, \(aqudp\(aq, \(aqtcp6\(aq, or \(aqudp6\(aq. .TP .B direction Choose \(aqin\(aq, \(aqout\(aq, or both to indicate the port should be opened for inbound traffic, outbound traffic, or both. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.csf.rule_absent(name, method, port=None, proto=\(aqtcp\(aq, direction=\(aqin\(aq, port_origin=\(aqd\(aq, ip_origin=\(aqs\(aq, ttl=None, reload=False) Ensure iptable is not present. .INDENT 7.0 .TP .B name The ip address or CIDR for the rule. .TP .B method The type of rule. Either \(aqallow\(aq or \(aqdeny\(aq. .TP .B port Optional port to be open or closed for the iptables rule. .TP .B proto The protocol. Either \(aqtcp\(aq, \(aqudp\(aq. Only applicable if port is specified. .TP .B direction The diretion of traffic to apply the rule to. Either \(aqin\(aq, or \(aqout\(aq. Only applicable if port is specified. .TP .B port_origin Specifies either the source or destination port is relevant for this rule. Only applicable if port is specified. Either \(aqs\(aq, or \(aqd\(aq. .TP .B ip_origin Specifies whether the ip in this rule refers to the source or destination ip. Either \(aqs\(aq, or \(aqd\(aq. Only applicable if port is specified. .TP .B ttl How long the rule should exist. If supplied, \fIcsf.tempallow()\fP or csf.tempdeny()\(ga are used. .TP .B reload Reload the csf service after applying this rule. Default false. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.csf.rule_present(name, method, port=None, proto=\(aqtcp\(aq, direction=\(aqin\(aq, port_origin=\(aqd\(aq, ip_origin=\(aqs\(aq, ttl=None, comment=\(aq\(aq, reload=False) Ensure iptable rule exists. .INDENT 7.0 .TP .B name The ip address or CIDR for the rule. .TP .B method The type of rule. Either \(aqallow\(aq or \(aqdeny\(aq. .TP .B port Optional port to be open or closed for the iptables rule. .TP .B proto The protocol. Either \(aqtcp\(aq, or \(aqudp\(aq. Only applicable if port is specified. .TP .B direction The diretion of traffic to apply the rule to. Either \(aqin\(aq, or \(aqout\(aq. Only applicable if port is specified. .TP .B port_origin Specifies either the source or destination port is relevant for this rule. Only applicable if port is specified. Either \(aqs\(aq, or \(aqd\(aq. .TP .B ip_origin Specifies whether the ip in this rule refers to the source or destination ip. Either \(aqs\(aq, or \(aqd\(aq. Only applicable if port is specified. .TP .B ttl How long the rule should exist. If supplied, \fIcsf.tempallow()\fP or csf.tempdeny()\(ga are used. .TP .B comment An optional comment to appear after the rule as a #comment . .TP .B reload Reload the csf service after applying this rule. Default false. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.csf.testing_off(name, reload=False) Ensure testing mode is enabled in csf. .INDENT 7.0 .TP .B reload Reload CSF after changing the testing status. Default false. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.csf.testing_on(name, reload=False) Ensure testing mode is enabled in csf. .INDENT 7.0 .TP .B reload Reload CSF after changing the testing status. Default false. .UNINDENT .UNINDENT .SS salt.states.cyg .sp Installation of Cygwin packages. .sp A state module to manage cygwin packages. Packages can be installed or removed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C dos2unix: cyg.installed .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.states.cyg.DictDiffer(current_dict, past_dict) Calculate the difference between two dictionaries. .INDENT 7.0 .IP 1. 3 items added .IP 2. 3 items removed .IP 3. 3 keys same in both but changed values .IP 4. 3 keys same in both and unchanged values .UNINDENT .INDENT 7.0 .TP .B added() Return a set of additions to past_dict. .UNINDENT .INDENT 7.0 .TP .B changed() Return a set of the keys with changed values. .UNINDENT .INDENT 7.0 .TP .B removed() Return a set of things removed from past_dict. .UNINDENT .INDENT 7.0 .TP .B same() True if the two dicts are the same. .UNINDENT .INDENT 7.0 .TP .B unchanged() Return a set of the keys with unchanged values. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cyg.installed(name, cyg_arch=\(aqx86_64\(aq, mirrors=None) Make sure that a package is installed. .INDENT 7.0 .TP .B name The name of the package to install .TP .B cyg_arch x86_64 The cygwin architecture to install the package into. Current options are x86 and x86_64 .TP .B mirrors None List of mirrors to check. None will use a default mirror (kernel.org) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C rsync: cyg.installed: \- mirrors: \- http://mirror/without/public/key: \(dq\(dq \- http://mirror/with/public/key: http://url/of/public/key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cyg.removed(name, cyg_arch=\(aqx86_64\(aq, mirrors=None) Make sure that a package is not installed. .INDENT 7.0 .TP .B name The name of the package to uninstall .TP .B cyg_arch x86_64 The cygwin architecture to remove the package from. Current options are x86 and x86_64 .TP .B mirrors None List of mirrors to check. None will use a default mirror (kernel.org) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C rsync: cyg.removed: \- mirrors: \- http://mirror/without/public/key: \(dq\(dq \- http://mirror/with/public/key: http://url/of/public/key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cyg.updated(name=None, cyg_arch=\(aqx86_64\(aq, mirrors=None) Make sure all packages are up to date. .INDENT 7.0 .TP .B name None No affect, salt fails poorly without the arg available .TP .B cyg_arch x86_64 The cygwin architecture to update. Current options are x86 and x86_64 .TP .B mirrors None List of mirrors to check. None will use a default mirror (kernel.org) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C rsync: cyg.updated: \- mirrors: \- http://mirror/without/public/key: \(dq\(dq \- http://mirror/with/public/key: http://url/of/public/key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.ddns .SS Dynamic DNS updates .sp Ensure a DNS record is present or absent utilizing RFC 2136 type dynamic updates. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 \fI\%dnspython\fP .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBdnspython\fP module is required when managing DDNS using a TSIG key. If you are not using a TSIG key, DDNS is allowed by ACLs based on IP address and the \fBdnspython\fP module is not required. .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C webserver: ddns.present: \- zone: example.com \- ttl: 60 \- data: 111.222.333.444 \- nameserver: 123.234.345.456 \- keyfile: /srv/salt/dnspy_tsig_key.txt .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ddns.absent(name, zone, data=None, rdtype=None, **kwargs) Ensures that the named DNS record is absent. .INDENT 7.0 .TP .B name The host portion of the DNS record, e.g., \(aqwebserver\(aq. Name and zone are concatenated when the entry is created unless name includes a trailing dot, so make sure that information is not duplicated in these two arguments. .TP .B zone The zone to check .TP .B data Data for the DNS record. E.g., the IP address for an A record. If omitted, all records matching name (and rdtype, if provided) will be purged. .TP .B rdtype DNS resource type. If omitted, all types will be purged. .TP .B \fB**kwargs\fP Additional arguments the ddns.update function may need (e.g. nameserver, keyfile, keyname). Note that the nsupdate key file can’t be reused by this function, the keyfile and other arguments must follow the \fI\%dnspython\fP spec. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ddns.present(name, zone, ttl, data, rdtype=\(aqA\(aq, **kwargs) Ensures that the named DNS record is present with the given ttl. .INDENT 7.0 .TP .B name The host portion of the DNS record, e.g., \(aqwebserver\(aq. Name and zone are concatenated when the entry is created unless name includes a trailing dot, so make sure that information is not duplicated in these two arguments. .TP .B zone The zone to check/update .TP .B ttl TTL for the record .TP .B data Data for the DNS record. E.g., the IP address for an A record. .TP .B rdtype DNS resource type. Default \(aqA\(aq. .TP .B \fB**kwargs\fP Additional arguments the ddns.update function may need (e.g. nameserver, keyfile, keyname). Note that the nsupdate key file can’t be reused by this function, the keyfile and other arguments must follow the \fI\%dnspython\fP spec. .UNINDENT .UNINDENT .SS salt.states.debconfmod .SS Management of debconf selections .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 debconf\-utils package .UNINDENT .UNINDENT .sp The debconfmod state module manages the enforcement of debconf selections, this state can set those selections prior to package installation. .SS Available Functions .sp The debconfmod state has two functions, the \fBset\fP and \fBset_file\fP functions .INDENT 0.0 .TP .B set Set debconf selections from the state itself .TP .B set_file Set debconf selections from a file .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nullmailer\-debconf: debconf.set: \- name: nullmailer \- data: \(aqshared/mailname\(aq: {\(aqtype\(aq: \(aqstring\(aq, \(aqvalue\(aq: \(aqserver.domain.tld\(aq} \(aqnullmailer/relayhost\(aq: {\(aqtype\(aq: \(aqstring\(aq, \(aqvalue\(aq: \(aqmail.domain.tld\(aq} ferm\-debconf: debconf.set: \- name: ferm \- data: \(aqferm/enable\(aq: {\(aqtype\(aq: \(aqboolean\(aq, \(aqvalue\(aq: True} .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Due to how PyYAML imports nested dicts (see \fI\%here\fP), the values in the \fBdata\fP dict must be indented four spaces instead of two. .UNINDENT .UNINDENT .sp If you\(aqre setting debconf values that requires \fIdpkg\-reconfigure\fP, you can use the \fBonchanges\fP requisite to reconfigure your package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C set\-default\-shell: debconf.set: \- name: dash \- data: \(aqdash/sh\(aq: {\(aqtype\(aq: \(aqboolean\(aq, \(aqvalue\(aq: false} reconfigure\-dash: cmd.run: \- name: dpkg\-reconfigure \-f noninteractive dash \- onchanges: \- debconf: set\-default\-shell .ft P .fi .UNINDENT .UNINDENT .sp Every time the \fBset\-default\-shell\fP state changes, the \fBreconfigure\-dash\fP state will also run. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For boolean types, the value should be \fBtrue\fP or \fBfalse\fP, not \fB\(aqtrue\(aq\fP or \fB\(aqfalse\(aq\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.debconfmod.set(name, data, **kwargs) Set debconf selections .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C <state_id>: debconf.set: \- name: <name> \- data: <question>: {\(aqtype\(aq: <type>, \(aqvalue\(aq: <value>} <question>: {\(aqtype\(aq: <type>, \(aqvalue\(aq: <value>} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name: The package name to set answers for. .TP .B data: A set of questions/answers for debconf. Note that everything under this must be indented twice. .TP .B question: The question the is being pre\-answered .TP .B type: The type of question that is being asked (string, boolean, select, etc.) .TP .B value: The answer to the question .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.debconfmod.set_file(name, source, template=None, context=None, defaults=None, **kwargs) Set debconf selections from a file or a template .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C <state_id>: debconf.set_file: \- source: salt://pathto/pkg.selections <state_id>: debconf.set_file: \- source: salt://pathto/pkg.selections?saltenv=myenvironment <state_id>: debconf.set_file: \- source: salt://pathto/pkg.selections.jinja2 \- template: jinja \- context: some_value: \(dqfalse\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B source: The location of the file containing the package selections .TP .B template If this setting is applied then the named templating engine will be used to render the package selections file, currently jinja, mako, and wempy are supported .TP .B context Overrides default context variables passed to the template. .TP .B defaults Default context passed to the template. .UNINDENT .UNINDENT .SS salt.states.dellchassis .sp Manage chassis via Salt Proxies. .sp New in version 2015.8.2. .sp Below is an example state that sets basic parameters: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-dell\-chassis: dellchassis.chassis: \- chassis_name: my\-dell\-chassis \- datacenter: dc\-1\-us \- location: my\-location \- mode: 2 \- idrac_launch: 1 \- slot_names: \- server\-1: my\-slot\-name \- server\-2: my\-other\-slot\-name \- blade_power_states: \- server\-1: on \- server\-2: off \- server\-3: powercycle .ft P .fi .UNINDENT .UNINDENT .sp However, it is possible to place the entire set of chassis configuration data in pillar. Here\(aqs an example pillar structure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: host: 10.27.20.18 admin_username: root fallback_admin_username: root passwords: \- super\-secret \- old\-secret proxytype: fx2 chassis: name: fx2\-1 username: root password: saltstack1 datacenter: london location: rack\-1\-shelf\-3 management_mode: 2 idrac_launch: 0 slot_names: \- \(aqserver\-1\(aq: blade1 \- \(aqserver\-2\(aq: blade2 servers: server\-1: idrac_password: saltstack1 ipmi_over_lan: True ip: 172.17.17.132 netmask: 255.255.0.0 gateway: 172.17.17.1 server\-2: idrac_password: saltstack1 ipmi_over_lan: True ip: 172.17.17.2 netmask: 255.255.0.0 gateway: 172.17.17.1 server\-3: idrac_password: saltstack1 ipmi_over_lan: True ip: 172.17.17.20 netmask: 255.255.0.0 gateway: 172.17.17.1 server\-4: idrac_password: saltstack1 ipmi_over_lan: True ip: 172.17.17.2 netmask: 255.255.0.0 gateway: 172.17.17.1 switches: switch\-1: ip: 192.168.1.2 netmask: 255.255.255.0 gateway: 192.168.1.1 snmp: nonpublic password: saltstack1 switch\-2: ip: 192.168.1.3 netmask: 255.255.255.0 gateway: 192.168.1.1 snmp: nonpublic password: saltstack1 .ft P .fi .UNINDENT .UNINDENT .sp And to go with it, here\(aqs an example state that pulls the data from the pillar stated above: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set details = pillar.get(\(aqproxy:chassis\(aq, {}) %} standup\-step1: dellchassis.chassis: \- name: {{ details[\(aqname\(aq] }} \- location: {{ details[\(aqlocation\(aq] }} \- mode: {{ details[\(aqmanagement_mode\(aq] }} \- idrac_launch: {{ details[\(aqidrac_launch\(aq] }} \- slot_names: {% for entry details[\(aqslot_names\(aq] %} \- {{ next(iter(entry)) }}: {{ entry[next(iter(entry))] }} {% endfor %} blade_powercycle: dellchassis.chassis: \- blade_power_states: \- server\-1: powercycle \- server\-2: powercycle \- server\-3: powercycle \- server\-4: powercycle # Set idrac_passwords for blades. racadm needs them to be called \(aqserver\-x\(aq {% for k, v in details[\(aqservers\(aq].iteritems() %} {{ k }}: dellchassis.blade_idrac: \- idrac_password: {{ v[\(aqidrac_password\(aq] }} {% endfor %} # Set management ip addresses, passwords, and snmp strings for switches {% for k, v in details[\(aqswitches\(aq].iteritems() %} {{ k }}\-switch\-setup: dellchassis.switch: \- name: {{ k }} \- ip: {{ v[\(aqip\(aq] }} \- netmask: {{ v[\(aqnetmask\(aq] }} \- gateway: {{ v[\(aqgateway\(aq] }} \- password: {{ v[\(aqpassword\(aq] }} \- snmp: {{ v[\(aqsnmp\(aq] }} {% endfor %} .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This state module relies on the dracr.py execution module, which runs racadm commands on the chassis, blades, etc. The racadm command runs very slowly and, depending on your state, the proxy minion return might timeout before the racadm commands have completed. If you are repeatedly seeing minions timeout after state calls, please use the \fB\-t\fP CLI argument to increase the timeout variable. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.sls my\-dell\-chasis\-state\-name \-t 60 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The Dell CMC units perform adequately but many iDRACs are \fBexcruciatingly\fP slow. Some functions can take minutes to execute. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.dellchassis.blade_idrac(name, idrac_password=None, idrac_ipmi=None, idrac_ip=None, idrac_netmask=None, idrac_gateway=None, idrac_dnsname=None, idrac_dhcp=None) Set parameters for iDRAC in a blade. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBidrac_password\fP \-\- Password to use to connect to the iDRACs directly (idrac_ipmi and idrac_dnsname must be set directly on the iDRAC. They can\(aqt be set through the CMC. If this password is present, use it instead of the CMC password) .IP \(bu 2 \fBidrac_ipmi\fP \-\- Enable/Disable IPMI over LAN .IP \(bu 2 \fBidrac_ip\fP \-\- Set IP address for iDRAC .IP \(bu 2 \fBidrac_netmask\fP \-\- Set netmask for iDRAC .IP \(bu 2 \fBidrac_gateway\fP \-\- Set gateway for iDRAC .IP \(bu 2 \fBidrac_dhcp\fP \-\- Turn on DHCP for iDRAC (True turns on, False does nothing becaause setting a static IP will disable DHCP). .UNINDENT .TP .B Returns A standard Salt changes dictionary .UNINDENT .sp NOTE: If any of the IP address settings is configured, all of ip, netmask, and gateway must be present .UNINDENT .INDENT 0.0 .TP .B salt.states.dellchassis.chassis(name, chassis_name=None, password=None, datacenter=None, location=None, mode=None, idrac_launch=None, slot_names=None, blade_power_states=None) Manage a Dell Chassis. .INDENT 7.0 .TP .B chassis_name The name of the chassis. .TP .B datacenter The datacenter in which the chassis is located .TP .B location The location of the chassis. .TP .B password Password for the chassis. Note: If this password is set for the chassis, the current implementation of this state will set this password both on the chassis and the iDrac passwords on any configured blades. If the password for the blades should be distinct, they should be set separately with the blade_idrac function. .TP .B mode The management mode of the chassis. Viable options are: .INDENT 7.0 .IP \(bu 2 0: None .IP \(bu 2 1: Monitor .IP \(bu 2 2: Manage and Monitor .UNINDENT .TP .B idrac_launch The iDRAC launch method of the chassis. Viable options are: .INDENT 7.0 .IP \(bu 2 0: Disabled (launch iDRAC using IP address) .IP \(bu 2 1: Enabled (launch iDRAC using DNS name) .UNINDENT .TP .B slot_names The names of the slots, provided as a list identified by their slot numbers. .TP .B blade_power_states The power states of a blade server, provided as a list and identified by their server numbers. Viable options are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 on: Ensure the blade server is powered on. .IP \(bu 2 off: Ensure the blade server is powered off. .IP \(bu 2 powercycle: Power cycle the blade server. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my\-dell\-chassis: dellchassis.chassis: \- chassis_name: my\-dell\-chassis \- location: my\-location \- datacenter: london \- mode: 2 \- idrac_launch: 1 \- slot_names: \- 1: my\-slot\-name \- 2: my\-other\-slot\-name \- blade_power_states: \- server\-1: on \- server\-2: off \- server\-3: powercycle .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.dellchassis.firmware_update(hosts=None, directory=\(aq\(aq) .INDENT 7.0 .INDENT 3.5 State to update the firmware on host using the \fBracadm\fP command .INDENT 0.0 .TP .B firmwarefile filename (string) starting with \fBsalt://\fP .TP .B host string representing the hostname supplied to the \fBracadm\fP command .TP .B directory Directory name where firmwarefile will be downloaded .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C dell\-chassis\-firmware\-update: dellchassis.firmware_update: hosts: cmc: salt://firmware_cmc.exe server\-1: salt://firmware.exe directory: /opt/firmwares .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.dellchassis.switch(name, ip=None, netmask=None, gateway=None, dhcp=None, password=None, snmp=None) Manage switches in a Dell Chassis. .INDENT 7.0 .TP .B name The switch designation (e.g. switch\-1, switch\-2) .TP .B ip The Static IP Address of the switch .TP .B netmask The netmask for the static IP .TP .B gateway The gateway for the static IP .TP .B dhcp True: Enable DHCP False: Do not change DHCP setup (disabling DHCP is automatic when a static IP is set) .TP .B password The access (root) password for the switch .TP .B snmp The SNMP community string for the switch .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my\-dell\-chassis: dellchassis.switch: \- switch: switch\-1 \- ip: 192.168.1.1 \- netmask: 255.255.255.0 \- gateway: 192.168.1.254 \- dhcp: True \- password: secret \- snmp: public .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.disk .sp Disk monitoring state .sp Monitor the state of disk resources. .sp The \fBdisk.status\fP function can be used to report that the used space of a filesystem is within the specified limits. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C used_space: disk.status: \- name: /dev/xda1 \- maximum: 79% \- minimum: 11% .ft P .fi .UNINDENT .UNINDENT .sp It can be used with an \fBonfail\fP requisite, for example, to take additional action in response to or in preparation for other states. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C storage_threshold: disk.status: \- name: /dev/xda1 \- maximum: 97% clear_cache: cmd.run: \- name: rm \-r /var/cache/app \- onfail: \- disk: storage_threshold .ft P .fi .UNINDENT .UNINDENT .sp To use kilobytes (KB) for \fBminimum\fP and \fBmaximum\fP rather than percents, specify the \fBabsolute\fP flag: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C used_space: disk.status: \- name: /dev/xda1 \- minimum: 1024 KB \- maximum: 1048576 KB \- absolute: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.disk.status(name, maximum=None, minimum=None, absolute=False, free=False) Return the current disk usage stats for the named mount point .INDENT 7.0 .TP .B name Disk mount or directory for which to check used space .TP .B maximum The maximum disk utilization .TP .B minimum The minimum disk utilization .TP .B absolute By default, the utilization is measured in percentage. Set the \fIabsolute\fP flag to use kilobytes. .sp New in version 2016.11.0. .TP .B free By default, \fIminimum\fP & \fImaximum\fP refer to the amount of used space. Set to \fITrue\fP to evaluate the free space instead. .UNINDENT .UNINDENT .SS salt.states.docker_container .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%docker Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Management of Docker containers .sp New in version 2017.7.0. .INDENT 0.0 .TP .B depends \fI\%docker\fP Python module .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Older releases of the Python bindings for Docker were called \fI\%docker\-py\fP in PyPI. All releases of \fI\%docker\fP, and releases of \fI\%docker\-py\fP >= 1.6.0 are supported. These python bindings can easily be installed using \fI\%pip.install\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pip.install docker .ft P .fi .UNINDENT .UNINDENT .sp To upgrade from \fI\%docker\-py\fP to \fI\%docker\fP, you must first uninstall \fI\%docker\-py\fP, and then install \fI\%docker\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pip.uninstall docker\-py salt myminion pip.install docker .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp These states were moved from the \fBdocker\fP state module (formerly called \fBdockerng\fP) in the 2017.7.0 release. When running the \fI\%docker_container.running\fP state for the first time after upgrading to 2017.7.0, your container(s) may be replaced. The changes may show diffs for certain parameters which say that the old value was an empty string, and the new value is \fBNone\fP\&. This is due to the fact that in prior releases Salt was passing empty strings for these values when creating the container if they were undefined in the SLS file, where now Salt simply does not pass any arguments not explicitly defined in the SLS file. Subsequent runs of the state should not replace the container if the configuration remains unchanged. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To pull from a Docker registry, authentication must be configured. See \fI\%here\fP for more information on how to configure access to docker registries in \fI\%Pillar\fP data. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.docker_container.absent(name, force=False) Ensure that a container is absent .INDENT 7.0 .TP .B name Name of the container .TP .B force False Set to \fBTrue\fP to remove the container even if it is running .UNINDENT .sp Usage Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mycontainer: docker_container.absent multiple_containers: docker_container.absent: \- names: \- foo \- bar \- baz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.docker_container.mod_watch(name, sfun=None, **kwargs) The docker_container watcher, called to invoke the watch command. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBwatch\fP \fI\%requisite\fP\&. It should not be called directly. .sp Parameters for this function should be set by the state being triggered. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.docker_container.run(name, image=None, bg=False, failhard=True, replace=False, force=False, skip_translate=None, ignore_collisions=False, validate_ip_addrs=True, client_timeout=60, **kwargs) New in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If no tag is specified in the image name, and nothing matching the specified image is pulled on the minion, the \fBdocker pull\fP that retrieves the image will pull \fIall tags\fP for the image. A tag of \fBlatest\fP is not implicit for the pull. For this reason, it is recommended to specify the image in \fBrepo:tag\fP notation. .UNINDENT .UNINDENT .sp Like the \fI\%cmd.run\fP state, only for Docker. Does the equivalent of a \fBdocker run\fP and returns information about the container that was created, as well as its output. .sp This state accepts the same arguments as \fI\%docker_container.running\fP, with the exception of \fBwatch_action\fP, \fBstart\fP, and \fBshutdown_timeout\fP (though the \fBforce\fP argument has a different meaning in this state). .sp In addition, this state accepts the arguments from \fI\%docker.logs\fP, with the exception of \fBfollow\fP, to control how logs are returned. .sp Additionally, the following arguments are supported: .INDENT 7.0 .TP .B creates A path or list of paths. Only run if one or more of the specified paths do not exist on the minion. .TP .B bg False If \fBTrue\fP, run container in background and do not await or deliver its results. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This may not be useful in cases where other states depend on the results of this state. Also, the logs will be inaccessible once the container exits if \fBauto_remove\fP is set to \fBTrue\fP, so keep this in mind. .UNINDENT .UNINDENT .TP .B failhard True If \fBTrue\fP, the state will return a \fBFalse\fP result if the exit code of the container is non\-zero. When this argument is set to \fBFalse\fP, the state will return a \fBTrue\fP result regardless of the container\(aqs exit code. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This has no effect if \fBbg\fP is set to \fBTrue\fP\&. .UNINDENT .UNINDENT .TP .B replace False If \fBTrue\fP, and if the named container already exists, this will remove the existing container. The default behavior is to return a \fBFalse\fP result when the container already exists. .TP .B force False If \fBTrue\fP, and the named container already exists, \fIand\fP \fBreplace\fP is also set to \fBTrue\fP, then the container will be forcibly removed. Otherwise, the state will not proceed and will return a \fBFalse\fP result. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion docker.run_container myuser/myimage command=/usr/local/bin/myscript.sh .ft P .fi .UNINDENT .UNINDENT .sp \fBUSAGE EXAMPLE\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set pkg_version = salt.pillar.get(\(aqpkg_version\(aq, \(aq1.0\-1\(aq) %} build_package: docker_container.run: \- image: myuser/builder:latest \- binds: /home/myuser/builds:/build_dir \- command: /scripts/build.sh {{ pkg_version }} \- creates: /home/myuser/builds/myapp\-{{ pkg_version }}.noarch.rpm \- replace: True \- networks: \- mynet \- require: \- docker_network: mynet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.docker_container.running(name, image=None, skip_translate=None, ignore_collisions=False, validate_ip_addrs=True, force=False, watch_action=\(aqforce\(aq, start=True, shutdown_timeout=None, client_timeout=60, networks=None, **kwargs) Ensure that a container with a specific configuration is present and running .INDENT 7.0 .TP .B name Name of the container .TP .B image Image to use for the container .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state will pull the image if it is not present. However, if the image needs to be built from a Dockerfile or loaded from a saved image, or if you would like to use requisites to trigger a replacement of the container when the image is updated, then the \fBdocker_image.present\fP state should be used to manage the image. .UNINDENT .UNINDENT .sp Changed in version 2018.3.0: If no tag is specified in the image name, and nothing matching the specified image is pulled on the minion, the \fBdocker pull\fP that retrieves the image will pull \fIall tags\fP for the image. A tag of \fBlatest\fP is no longer implicit for the pull. For this reason, it is recommended to specify the image in \fBrepo:tag\fP notation. .UNINDENT .INDENT 7.0 .TP .B skip_translate This function translates Salt CLI or SLS input into the format which \fI\%docker\-py\fP expects. However, in the event that Salt\(aqs translation logic fails (due to potential changes in the Docker Remote API, or to bugs in the translation code), this argument can be used to exert granular control over which arguments are translated and which are not. .sp Pass this argument as a comma\-separated list (or Python list) of arguments, and translation for each passed argument name will be skipped. Alternatively, pass \fBTrue\fP and \fIall\fP translation will be skipped. .sp Skipping tranlsation allows for arguments to be formatted directly in the format which \fI\%docker\-py\fP expects. This allows for API changes and other issues to be more easily worked around. An example of using this option to skip translation would be: .sp For example, imagine that there is an issue with processing the \fBport_bindings\fP argument, and the following configuration no longer works as expected: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mycontainer: docker_container.running: \- image: 7.3.1611 \- port_bindings: \- 10.2.9.10:8080:80 .ft P .fi .UNINDENT .UNINDENT .sp By using \fBskip_translate\fP, you can forego the input translation and configure the port binding in the format \fI\%docker\-py\fP needs: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mycontainer: docker_container.running: \- image: 7.3.1611 \- skip_translate: port_bindings \- port_bindings: {8080: [(\(aq10.2.9.10\(aq, 80)], \(aq4193/udp\(aq: 9314} .ft P .fi .UNINDENT .UNINDENT .sp See the following links for more information: .INDENT 7.0 .IP \(bu 2 \fI\%docker\-py Low\-level API\fP .IP \(bu 2 \fI\%Docker Engine API\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B ignore_collisions False Since many of \fI\%docker\-py\fP\(aqs arguments differ in name from their CLI counterparts (with which most Docker users are more familiar), Salt detects usage of these and aliases them to the \fI\%docker\-py\fP version of that argument so that both CLI and API versions of a given argument are supported. However, if both the alias and the \fI\%docker\-py\fP version of the same argument (e.g. \fBenv\fP and \fBenvironment\fP) are used, an error will be raised. Set this argument to \fBTrue\fP to suppress these errors and keep the \fI\%docker\-py\fP version of the argument. .TP .B validate_ip_addrs True For parameters which accept IP addresses as input, IP address validation will be performed. To disable, set this to \fBFalse\fP .TP .B force False Set this parameter to \fBTrue\fP to force Salt to re\-create the container irrespective of whether or not it is configured as desired. .TP .B watch_action force Control what type of action is taken when this state \fI\%watches\fP another state that has changes. The default action is \fBforce\fP, which runs the state with \fBforce\fP set to \fBTrue\fP, triggering a rebuild of the container. .sp If any other value is passed, it will be assumed to be a kill signal. If the container matches the specified configuration, and is running, then the action will be to send that signal to the container. Kill signals can be either strings or numbers, and are defined in the \fBStandard Signals\fP section of the \fBsignal(7)\fP manpage. Run \fBman 7 signal\fP on a Linux host to browse this manpage. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mycontainer: docker_container.running: \- image: busybox \- watch_action: SIGHUP \- watch: \- file: some_file .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the container differs from the specified configuration, or is not running, then instead of sending a signal to the container, the container will be re\-created/started and no signal will be sent. .UNINDENT .UNINDENT .TP .B start True Set to \fBFalse\fP to suppress starting of the container if it exists, matches the desired configuration, but is not running. This is useful for data\-only containers, or for non\-daemonized container processes, such as the Django \fBmigrate\fP and \fBcollectstatic\fP commands. In instances such as this, the container only needs to be started the first time. .TP .B shutdown_timeout If the container needs to be replaced, the container will be stopped using \fI\%docker.stop\fP\&. If a \fBshutdown_timout\fP is not set, and the container was created using \fBstop_timeout\fP, that timeout will be used. If neither of these values were set, then a timeout of 10 seconds will be used. .sp Changed in version 2017.7.0: This option was renamed from \fBstop_timeout\fP to \fBshutdown_timeout\fP to accommodate the \fBstop_timeout\fP container configuration setting. .TP .B client_timeout 60 Timeout in seconds for the Docker client. This is not a timeout for this function, but for receiving a response from the API. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is only used if Salt needs to pull the requested image. .UNINDENT .UNINDENT .UNINDENT .sp \fBNETWORK MANAGEMENT\fP .sp New in version 2018.3.0. .sp Changed in version 2019.2.0: If the \fBnetworks\fP option is used, any networks (including the default \fBbridge\fP network) which are not specified will be disconnected. .sp The \fBnetworks\fP argument can be used to ensure that a container is attached to one or more networks. Optionally, arguments can be passed to the networks. In the example below, \fBnet1\fP is being configured with arguments, while \fBnet2\fP and \fBbridge\fP are being configured \fIwithout\fP arguments: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: myuser/myimage:foo \- networks: \- net1: \- aliases: \- bar \- baz \- ipv4_address: 10.0.20.50 \- net2 \- bridge \- require: \- docker_network: net1 \- docker_network: net2 .ft P .fi .UNINDENT .UNINDENT .sp The supported arguments are the ones from the docker\-py\(aqs \fI\%connect_container_to_network\fP function (other than \fBcontainer\fP and \fBnet_id\fP). .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 Unlike with the arguments described in the \fBCONTAINER CONFIGURATION PARAMETERS\fP section below, these network configuration parameters are not translated at all. Consult the \fI\%connect_container_to_network\fP documentation for the correct type/format of data to pass. .UNINDENT .UNINDENT .sp To start a container with no network connectivity (only possible in 2019.2.0 and later) pass this option as an empty list. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: myuser/myimage:foo \- networks: [] .ft P .fi .UNINDENT .UNINDENT .sp \fBCONTAINER CONFIGURATION PARAMETERS\fP .INDENT 7.0 .TP .B auto_remove (or \fIrm\fP) False Enable auto\-removal of the container on daemon side when the container’s process exits (analogous to running a docker container with \fB\-\-rm\fP on the CLI). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- auto_remove: True .ft P .fi .UNINDENT .UNINDENT .TP .B binds Files/directories to bind mount. Each bind mount should be passed in one of the following formats: .INDENT 7.0 .IP \(bu 2 \fB<host_path>:<container_path>\fP \- \fBhost_path\fP is mounted within the container as \fBcontainer_path\fP with read\-write access. .IP \(bu 2 \fB<host_path>:<container_path>:<selinux_context>\fP \- \fBhost_path\fP is mounted within the container as \fBcontainer_path\fP with read\-write access. Additionally, the specified selinux context will be set within the container. .IP \(bu 2 \fB<host_path>:<container_path>:<read_only>\fP \- \fBhost_path\fP is mounted within the container as \fBcontainer_path\fP, with the read\-only or read\-write setting explicitly defined. .IP \(bu 2 \fB<host_path>:<container_path>:<read_only>,<selinux_context>\fP \- \fBhost_path\fP is mounted within the container as \fBcontainer_path\fP, with the read\-only or read\-write setting explicitly defined. Additionally, the specified selinux context will be set within the container. .UNINDENT .sp \fB<read_only>\fP can be either \fBrw\fP for read\-write access, or \fBro\fP for read\-only access. When omitted, it is assumed to be read\-write. .sp \fB<selinux_context>\fP can be \fBz\fP if the volume is shared between multiple containers, or \fBZ\fP if the volume should be private. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When both \fB<read_only>\fP and \fB<selinux_context>\fP are specified, there must be a comma before \fB<selinux_context>\fP\&. .UNINDENT .UNINDENT .sp Binds can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- binds: /srv/www:/var/www:ro,/etc/foo.conf:/usr/local/etc/foo.conf:rw .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- binds: \- /srv/www:/var/www:ro \- /home/myuser/conf/foo.conf:/etc/foo.conf:rw .ft P .fi .UNINDENT .UNINDENT .sp However, in cases where both ro/rw and an selinux context are combined, the only option is to use a YAML list, like so: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- binds: \- /srv/www:/var/www:ro,Z \- /home/myuser/conf/foo.conf:/etc/foo.conf:rw,Z .ft P .fi .UNINDENT .UNINDENT .sp Since the second bind in the previous example is mounted read\-write, the \fBrw\fP and comma can be dropped. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- binds: \- /srv/www:/var/www:ro,Z \- /home/myuser/conf/foo.conf:/etc/foo.conf:Z .ft P .fi .UNINDENT .UNINDENT .TP .B blkio_weight Block IO weight (relative weight), accepts a weight value between 10 and 1000. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- blkio_weight: 100 .ft P .fi .UNINDENT .UNINDENT .TP .B blkio_weight_device Block IO weight (relative device weight), specified as a list of expressions in the format \fBPATH:RATE\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- blkio_weight_device: /dev/sda:100 .ft P .fi .UNINDENT .UNINDENT .TP .B cap_add List of capabilities to add within the container. Can be expressed as a comma\-separated list or a Python list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- cap_add: SYS_ADMIN,MKNOD .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- cap_add: \- SYS_ADMIN \- MKNOD .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option requires Docker 1.2.0 or newer. .UNINDENT .UNINDENT .TP .B cap_drop List of capabilities to drop within the container. Can be expressed as a comma\-separated list or a Python list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- cap_drop: SYS_ADMIN,MKNOD .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- cap_drop: \- SYS_ADMIN \- MKNOD .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option requires Docker 1.2.0 or newer. .UNINDENT .UNINDENT .TP .B command (or \fIcmd\fP) Command to run in the container .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- command: bash .ft P .fi .UNINDENT .UNINDENT .TP .B cpuset_cpus (or \fIcpuset\fP) CPUs on which which to allow execution, specified as a string containing a range (e.g. \fB0\-3\fP) or a comma\-separated list of CPUs (e.g. \fB0,1\fP). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- cpuset_cpus: \(dq0,1\(dq .ft P .fi .UNINDENT .UNINDENT .TP .B cpuset_mems Memory nodes on which which to allow execution, specified as a string containing a range (e.g. \fB0\-3\fP) or a comma\-separated list of MEMs (e.g. \fB0,1\fP). Only effective on NUMA systems. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- cpuset_mems: \(dq0,1\(dq .ft P .fi .UNINDENT .UNINDENT .TP .B cpu_group The length of a CPU period in microseconds .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- cpu_group: 100000 .ft P .fi .UNINDENT .UNINDENT .TP .B cpu_period Microseconds of CPU time that the container can get in a CPU period .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- cpu_period: 50000 .ft P .fi .UNINDENT .UNINDENT .TP .B cpu_shares CPU shares (relative weight), specified as an integer between 2 and 1024. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- cpu_shares: 512 .ft P .fi .UNINDENT .UNINDENT .TP .B detach False If \fBTrue\fP, run the container\(aqs command in the background (daemon mode) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- detach: True .ft P .fi .UNINDENT .UNINDENT .TP .B devices List of host devices to expose within the container. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- devices: /dev/net/tun,/dev/xvda1:/dev/xvda1,/dev/xvdb1:/dev/xvdb1:r .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- devices: \- /dev/net/tun \- /dev/xvda1:/dev/xvda1 \- /dev/xvdb1:/dev/xvdb1:r .ft P .fi .UNINDENT .UNINDENT .TP .B device_read_bps Limit read rate (bytes per second) from a device, specified as a list of expressions in the format \fBPATH:RATE\fP, where \fBRATE\fP is either an integer number of bytes, or a string ending in \fBkb\fP, \fBmb\fP, or \fBgb\fP\&. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- devices_read_bps: /dev/sda:1mb,/dev/sdb:5mb .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- devices_read_bps: \- /dev/sda:1mb \- /dev/sdb:5mb .ft P .fi .UNINDENT .UNINDENT .TP .B device_read_iops Limit read rate (I/O per second) from a device, specified as a list of expressions in the format \fBPATH:RATE\fP, where \fBRATE\fP is a number of I/O operations. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- devices_read_iops: /dev/sda:1000,/dev/sdb:500 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- devices_read_iops: \- /dev/sda:1000 \- /dev/sdb:500 .ft P .fi .UNINDENT .UNINDENT .TP .B device_write_bps Limit write rate (bytes per second) from a device, specified as a list of expressions in the format \fBPATH:RATE\fP, where \fBRATE\fP is either an integer number of bytes, or a string ending in \fBkb\fP, \fBmb\fP, or \fBgb\fP\&. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- devices_write_bps: /dev/sda:1mb,/dev/sdb:5mb .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- devices_write_bps: \- /dev/sda:1mb \- /dev/sdb:5mb .ft P .fi .UNINDENT .UNINDENT .TP .B device_write_iops Limit write rate (I/O per second) from a device, specified as a list of expressions in the format \fBPATH:RATE\fP, where \fBRATE\fP is a number of I/O operations. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- devices_write_iops: /dev/sda:1000,/dev/sdb:500 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- devices_write_iops: \- /dev/sda:1000 \- /dev/sdb:500 .ft P .fi .UNINDENT .UNINDENT .TP .B dns List of DNS nameservers. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- dns: 8.8.8.8,8.8.4.4 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- dns: \- 8.8.8.8 \- 8.8.4.4 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To skip IP address validation, use \fBvalidate_ip_addrs=False\fP .UNINDENT .UNINDENT .TP .B dns_opt Additional options to be added to the container’s \fBresolv.conf\fP file. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- dns_opt: ndots:9 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- dns_opt: \- ndots:9 .ft P .fi .UNINDENT .UNINDENT .TP .B dns_search List of DNS search domains. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- dns_search: foo1.domain.tld,foo2.domain.tld .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- dns_search: \- foo1.domain.tld \- foo2.domain.tld .ft P .fi .UNINDENT .UNINDENT .TP .B domainname The domain name to use for the container .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- dommainname: domain.tld .ft P .fi .UNINDENT .UNINDENT .TP .B entrypoint Entrypoint for the container .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- entrypoint: \(dqmycmd \-\-arg1 \-\-arg2\(dq .ft P .fi .UNINDENT .UNINDENT .sp This argument can also be specified as a list: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- entrypoint: \- mycmd \- \-\-arg1 \- \-\-arg2 .ft P .fi .UNINDENT .UNINDENT .TP .B environment Either a list of variable/value mappings, or a list of strings in the format \fBVARNAME=value\fP\&. The below three examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- environment: \- VAR1: value \- VAR2: value .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- environment: \(aqVAR1=value,VAR2=value\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- environment: \- VAR1=value \- VAR2=value .ft P .fi .UNINDENT .UNINDENT .TP .B extra_hosts Additional hosts to add to the container\(aqs /etc/hosts file. Can be expressed as a comma\-separated list or a Python list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- extra_hosts: web1:10.9.8.7,web2:10.9.8.8 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- extra_hosts: \- web1:10.9.8.7 \- web2:10.9.8.8 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To skip IP address validation, use \fBvalidate_ip_addrs=False\fP .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option requires Docker 1.3.0 or newer. .UNINDENT .UNINDENT .TP .B group_add List of additional group names and/or IDs that the container process will run as. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- group_add: web,network .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- group_add: \- web \- network .ft P .fi .UNINDENT .UNINDENT .TP .B hostname Hostname of the container. If not provided, the value passed as the container\(aqs\(ga\(ganame\(ga\(ga will be used for the hostname. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- hostname: web1 .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 \fBhostname\fP cannot be set if \fBnetwork_mode\fP is set to \fBhost\fP\&. The below example will result in an error: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- hostname: web1 \- network_mode: host .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B interactive (or \fIstdin_open\fP) False Leave stdin open, even if not attached .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- interactive: True .ft P .fi .UNINDENT .UNINDENT .TP .B ipc_mode (or \fIipc\fP) Set the IPC mode for the container. The default behavior is to create a private IPC namespace for the container, but this option can be used to change that behavior: .INDENT 7.0 .IP \(bu 2 \fBcontainer:<container_name_or_id>\fP reuses another container shared memory, semaphores and message queues .IP \(bu 2 \fBhost\fP: use the host\(aqs shared memory, semaphores and message queues .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- ipc_mode: container:foo .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- ipc_mode: host .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Using \fBhost\fP gives the container full access to local shared memory and is therefore considered insecure. .UNINDENT .UNINDENT .TP .B isolation Specifies the type of isolation technology used by containers .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- isolation: hyperv .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The default value on Windows server is \fBprocess\fP, while the default value on Windows client is \fBhyperv\fP\&. On Linux, only \fBdefault\fP is supported. .UNINDENT .UNINDENT .TP .B labels Add metadata to the container. Labels can be set both with and without values, and labels with values can be passed either as \fBkey=value\fP or \fBkey: value\fP pairs. For example, while the below would be very confusing to read, it is technically valid, and demonstrates the different ways in which labels can be passed: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- labels: \- foo \- bar=baz \- hello: world .ft P .fi .UNINDENT .UNINDENT .sp The labels can also simply be passed as a YAML dictionary, though this can be error\-prone due to some \fI\%idiosyncrasies\fP with how PyYAML loads nested data structures: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_network.present: \- labels: foo: \(aq\(aq bar: baz hello: world .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2018.3.0: Methods for specifying labels can now be mixed. Earlier releases required either labels with or without values. .TP .B links Link this container to another. Links can be specified as a list of mappings or a comma\-separated or Python list of expressions in the format \fB<container_name_or_id>:<link_alias>\fP\&. The below three examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- links: \- web1: link1 \- web2: link2 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- links: web1:link1,web2:link2 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- links: \- web1:link1 \- web2:link2 .ft P .fi .UNINDENT .UNINDENT .TP .B log_driver and log_opt Set container\(aqs logging driver and options to configure that driver. Requires Docker 1.6 or newer. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- log_driver: syslog \- log_opt: \- syslog\-address: tcp://192.168.0.42 \- syslog\-facility: daemon .ft P .fi .UNINDENT .UNINDENT .sp The \fBlog_opt\fP can also be expressed as a comma\-separated or YAML list of \fBkey=value\fP pairs. The below two examples are equivalent to the above one: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- log_driver: syslog \- log_opt: \(dqsyslog\-address=tcp://192.168.0.42,syslog\-facility=daemon\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- log_driver: syslog \- log_opt: \- syslog\-address=tcp://192.168.0.42 \- syslog\-facility=daemon .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The logging driver feature was improved in Docker 1.13 introducing option name changes. Please see Docker\(aqs \fI\%Configure logging drivers\fP documentation for more information. .UNINDENT .UNINDENT .TP .B lxc_conf Additional LXC configuration parameters to set before starting the container. Either a list of variable/value mappings, or a list of strings in the format \fBVARNAME=value\fP\&. The below three examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- lxc_conf: \- lxc.utsname: docker \- lxc.arch: x86_64 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- lxc_conf: lxc.utsname=docker,lxc.arch=x86_64 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- lxc_conf: \- lxc.utsname=docker \- lxc.arch=x86_64 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 These LXC configuration parameters will only have the desired effect if the container is using the LXC execution driver, which has been deprecated for some time. .UNINDENT .UNINDENT .TP .B mac_address MAC address to use for the container. If not specified, a random MAC address will be used. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- mac_address: 01:23:45:67:89:0a .ft P .fi .UNINDENT .UNINDENT .TP .B mem_limit (or \fImemory\fP) 0 Memory limit. Can be specified in bytes or using single\-letter units (i.e. \fB512M\fP, \fB2G\fP, etc.). A value of \fB0\fP (the default) means no memory limit. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- mem_limit: 512M .ft P .fi .UNINDENT .UNINDENT .TP .B mem_swappiness Tune a container\(aqs memory swappiness behavior. Accepts an integer between 0 and 100. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- mem_swappiness: 60 .ft P .fi .UNINDENT .UNINDENT .TP .B memswap_limit (or \fImemory_swap\fP) \-1 Total memory limit (memory plus swap). Set to \fB\-1\fP to disable swap. A value of \fB0\fP means no swap limit. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- memswap_limit: 1G .ft P .fi .UNINDENT .UNINDENT .TP .B network_disabled False If \fBTrue\fP, networking will be disabled within the container .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- network_disabled: True .ft P .fi .UNINDENT .UNINDENT .TP .B network_mode bridge One of the following: .INDENT 7.0 .IP \(bu 2 \fBbridge\fP \- Creates a new network stack for the container on the docker bridge .IP \(bu 2 \fBnone\fP \- No networking (equivalent of the Docker CLI argument \fB\-\-net=none\fP). Not to be confused with Python\(aqs \fBNone\fP\&. .IP \(bu 2 \fBcontainer:<name_or_id>\fP \- Reuses another container\(aqs network stack .IP \(bu 2 \fBhost\fP \- Use the host\(aqs network stack inside the container .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 Using \fBhost\fP mode gives the container full access to the hosts system\(aqs services (such as D\-bus), and is therefore considered insecure. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- network_mode: \(dqnone\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- network_mode: container:web1 .ft P .fi .UNINDENT .UNINDENT .TP .B oom_kill_disable Whether to disable OOM killer .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- oom_kill_disable: False .ft P .fi .UNINDENT .UNINDENT .TP .B oom_score_adj An integer value containing the score given to the container in order to tune OOM killer preferences .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- oom_score_adj: 500 .ft P .fi .UNINDENT .UNINDENT .TP .B pid_mode Set to \fBhost\fP to use the host container\(aqs PID namespace within the container. Requires Docker 1.5.0 or newer. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- pid_mode: host .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option requires Docker 1.5.0 or newer. .UNINDENT .UNINDENT .TP .B pids_limit Set the container\(aqs PID limit. Set to \fB\-1\fP for unlimited. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- pids_limit: 2000 .ft P .fi .UNINDENT .UNINDENT .TP .B port_bindings (or \fIpublish\fP) Bind exposed ports. Port bindings should be passed in the same way as the \fB\-\-publish\fP argument to the \fBdocker run\fP CLI command: .INDENT 7.0 .IP \(bu 2 \fBip:hostPort:containerPort\fP \- Bind a specific IP and port on the host to a specific port within the container. .IP \(bu 2 \fBip::containerPort\fP \- Bind a specific IP and an ephemeral port to a specific port within the container. .IP \(bu 2 \fBhostPort:containerPort\fP \- Bind a specific port on all of the host\(aqs interfaces to a specific port within the container. .IP \(bu 2 \fBcontainerPort\fP \- Bind an ephemeral port on all of the host\(aqs interfaces to a specific port within the container. .UNINDENT .sp Multiple bindings can be separated by commas, or expressed as a YAML list, and port ranges can be defined using dashes. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- port_bindings: \(dq4505\-4506:14505\-14506,2123:2123/udp,8080\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- port_bindings: \- 4505\-4506:14505\-14506 \- 2123:2123/udp \- 8080 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When specifying a protocol, it must be passed in the \fBcontainerPort\fP value, as seen in the examples above. .UNINDENT .UNINDENT .TP .B ports A list of ports to expose on the container. Can either be a comma\-separated list or a YAML list. If the protocol is omitted, the port will be assumed to be a TCP port. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- ports: 1111,2222/udp .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- ports: \- 1111 \- 2222/udp .ft P .fi .UNINDENT .UNINDENT .TP .B privileged False If \fBTrue\fP, runs the exec process with extended privileges .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- privileged: True .ft P .fi .UNINDENT .UNINDENT .TP .B publish_all_ports (or \fIpublish_all\fP) False Publish all ports to the host .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- ports: 8080 \- publish_all_ports: True .ft P .fi .UNINDENT .UNINDENT .TP .B read_only False If \fBTrue\fP, mount the container’s root filesystem as read only .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- read_only: True .ft P .fi .UNINDENT .UNINDENT .TP .B restart_policy (or \fIrestart\fP) Set a restart policy for the container. Must be passed as a string in the format \fBpolicy[:retry_count]\fP where \fBpolicy\fP is one of \fBalways\fP, \fBunless\-stopped\fP, or \fBon\-failure\fP, and \fBretry_count\fP is an optional limit to the number of retries. The retry count is ignored when using the \fBalways\fP or \fBunless\-stopped\fP restart policy. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- restart_policy: on\-failure:5 bar: docker_container.running: \- image: bar/baz:latest \- restart_policy: always .ft P .fi .UNINDENT .UNINDENT .TP .B security_opt (or \fIsecurity_opts\fP): Security configuration for MLS systems such as SELinux and AppArmor. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- security_opt: apparmor:unconfined .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- security_opt: \- apparmor:unconfined .ft P .fi .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 Some security options can contain commas. In these cases, this argument \fImust\fP be passed as a Python list, as splitting by comma will result in an invalid configuration. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 See the documentation for security_opt at \fI\%https://docs.docker.com/engine/reference/run/#security\-configuration\fP .UNINDENT .UNINDENT .TP .B shm_size Size of /dev/shm .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- shm_size: 128M .ft P .fi .UNINDENT .UNINDENT .TP .B stop_signal Specify the signal docker will send to the container when stopping. Useful when running systemd as PID 1 inside the container. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- stop_signal: SIGRTMIN+3 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option requires Docker 1.9.0 or newer and docker\-py 1.7.0 or newer. .UNINDENT .UNINDENT .sp New in version 2016.11.0. .TP .B stop_timeout Timeout to stop the container, in seconds .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- stop_timeout: 5 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 In releases prior to 2017.7.0, this option was not set in the container configuration, but rather this timeout was enforced only when shutting down an existing container to replace it. To remove the ambiguity, and to allow for the container to have a stop timeout set for it, the old \fBstop_timeout\fP argument has been renamed to \fBshutdown_timeout\fP, while \fBstop_timeout\fP now refer\(aqs to the container\(aqs configured stop timeout. .UNINDENT .UNINDENT .TP .B storage_opt Storage driver options for the container. Can be either a list of strings in the format \fBoption=value\fP, or a list of mappings between option and value. The below three examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- storage_opt: \- dm.basesize: 40G .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- storage_opt: dm.basesize=40G .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- storage_opt: \- dm.basesize=40G .ft P .fi .UNINDENT .UNINDENT .TP .B sysctls (or \fIsysctl\fP) Set sysctl options for the container. Can be either a list of strings in the format \fBoption=value\fP, or a list of mappings between option and value. The below three examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- sysctls: \- fs.nr_open: 1048576 \- kernel.pid_max: 32768 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- sysctls: fs.nr_open=1048576,kernel.pid_max=32768 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- sysctls: \- fs.nr_open=1048576 \- kernel.pid_max=32768 .ft P .fi .UNINDENT .UNINDENT .TP .B tmpfs A map of container directories which should be replaced by tmpfs mounts and their corresponding mount options. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- tmpfs: \- /run: rw,noexec,nosuid,size=65536k .ft P .fi .UNINDENT .UNINDENT .TP .B tty False Attach TTYs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- tty: True .ft P .fi .UNINDENT .UNINDENT .TP .B ulimits List of ulimits. These limits should be passed in the format \fB<ulimit_name>:<soft_limit>:<hard_limit>\fP, with the hard limit being optional. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- ulimits: nofile=1024:1024,nproc=60 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- ulimits: \- nofile=1024:1024 \- nproc=60 .ft P .fi .UNINDENT .UNINDENT .TP .B user User under which to run exec process .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- user: foo .ft P .fi .UNINDENT .UNINDENT .TP .B userns_mode (or \fIuser_ns_mode\fP) Sets the user namsepace mode, when the user namespace remapping option is enabled .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- userns_mode: host .ft P .fi .UNINDENT .UNINDENT .TP .B volumes (or \fIvolume\fP) List of directories to expose as volumes. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- volumes: /mnt/vol1,/mnt/vol2 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- volumes: \- /mnt/vol1 \- /mnt/vol2 .ft P .fi .UNINDENT .UNINDENT .TP .B volumes_from Container names or IDs from which the container will get volumes. Can be expressed as a comma\-separated list or a YAML list. The below two examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- volumes_from: foo .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- volumes_from: \- foo .ft P .fi .UNINDENT .UNINDENT .TP .B volume_driver sets the container\(aqs volume driver .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- volume_driver: foobar .ft P .fi .UNINDENT .UNINDENT .TP .B working_dir (or \fIworkdir\fP) Working directory inside the container .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_container.running: \- image: bar/baz:latest \- working_dir: /var/log/nginx .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.docker_container.stopped(name=None, containers=None, shutdown_timeout=None, unpause=False, error_on_absent=True, **kwargs) Ensure that a container (or containers) is stopped .INDENT 7.0 .TP .B name Name or ID of the container .TP .B containers Run this state on more than one container at a time. The following two examples accomplish the same thing: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C stopped_containers: docker_container.stopped: \- names: \- foo \- bar \- baz .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C stopped_containers: docker_container.stopped: \- containers: \- foo \- bar \- baz .ft P .fi .UNINDENT .UNINDENT .sp However, the second example will be a bit quicker since Salt will stop all specified containers in a single run, rather than executing the state separately on each image (as it would in the first example). .TP .B shutdown_timeout Timeout for graceful shutdown of the container. If this timeout is exceeded, the container will be killed. If this value is not passed, then the container\(aqs configured \fBstop_timeout\fP will be observed. If \fBstop_timeout\fP was also unset on the container, then a timeout of 10 seconds will be used. .TP .B unpause False Set to \fBTrue\fP to unpause any paused containers before stopping. If unset, then an error will be raised for any container that was paused. .TP .B error_on_absent True By default, this state will return an error if any of the specified containers are absent. Set this to \fBFalse\fP to suppress that error. .UNINDENT .UNINDENT .SS salt.states.docker_image .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%docker Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Management of Docker images .sp New in version 2017.7.0. .INDENT 0.0 .TP .B depends \fI\%docker\fP Python module .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Older releases of the Python bindings for Docker were called \fI\%docker\-py\fP in PyPI. All releases of \fI\%docker\fP, and releases of \fI\%docker\-py\fP >= 1.6.0 are supported. These python bindings can easily be installed using \fI\%pip.install\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pip.install docker .ft P .fi .UNINDENT .UNINDENT .sp To upgrade from \fI\%docker\-py\fP to \fI\%docker\fP, you must first uninstall \fI\%docker\-py\fP, and then install \fI\%docker\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pip.uninstall docker\-py salt myminion pip.install docker .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp These states were moved from the \fBdocker\fP state module (formerly called \fBdockerng\fP) in the 2017.7.0 release. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To pull from a Docker registry, authentication must be configured. See \fI\%here\fP for more information on how to configure access to docker registries in \fI\%Pillar\fP data. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.docker_image.absent(name=None, images=None, force=False) Ensure that an image is absent from the Minion. Image names can be specified either using \fBrepo:tag\fP notation, or just the repo name (in which case a tag of \fBlatest\fP is assumed). .INDENT 7.0 .TP .B name The name of the docker image. .TP .B images Run this state on more than one image at a time. The following two examples accomplish the same thing: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C remove_images: docker_image.absent: \- names: \- busybox \- centos:6 \- nginx .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C remove_images: docker_image.absent: \- images: \- busybox \- centos:6 \- nginx .ft P .fi .UNINDENT .UNINDENT .sp However, the second example will be a bit quicker since Salt will do all the deletions in a single run, rather than executing the state separately on each image (as it would in the first example). .TP .B force Salt will fail to remove any images currently in use by a container. Set this option to true to remove the image even if it is already present. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option can also be overridden by Pillar data. If the Minion has a pillar variable named \fBdocker.running.force\fP which is set to \fBTrue\fP, it will turn on this option. This pillar variable can even be set at runtime. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion state.sls docker_stuff pillar=\(dq{docker.force: True}\(dq .ft P .fi .UNINDENT .UNINDENT .sp If this pillar variable is present and set to \fBFalse\fP, then it will turn off this option. .sp For more granular control, setting a pillar variable named \fBdocker.force.image_name\fP will affect only the named image. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.docker_image.mod_watch(name, sfun=None, **kwargs) The docker_image watcher, called to invoke the watch command. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBwatch\fP \fI\%requisite\fP\&. It should not be called directly. .sp Parameters for this function should be set by the state being triggered. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.docker_image.present(name, tag=None, build=None, load=None, force=False, insecure_registry=False, client_timeout=60, dockerfile=None, sls=None, base=\(aqopensuse/python\(aq, saltenv=\(aqbase\(aq, pillarenv=None, pillar=None, **kwargs) Changed in version 2018.3.0: The \fBtag\fP argument has been added. It is now required unless pulling from a registry. .sp Ensure that an image is present. The image can either be pulled from a Docker registry, built from a Dockerfile, loaded from a saved image, or built by running SLS files against a base image. .sp If none of the \fBbuild\fP, \fBload\fP, or \fBsls\fP arguments are used, then Salt will pull from the \fI\%configured registries\fP\&. If the specified image already exists, it will not be pulled unless \fBforce\fP is set to \fBTrue\fP\&. Here is an example of a state that will pull an image from the Docker Hub: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myuser/myimage: docker_image.present: \- tag: mytag .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the docker image. .TP .B tag Tag name for the image. Required when using \fBbuild\fP, \fBload\fP, or \fBsls\fP to create the image, but optional if pulling from a repository. .sp New in version 2018.3.0. .TP .B build Path to directory on the Minion containing a Dockerfile .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myuser/myimage: docker_image.present: \- build: /home/myuser/docker/myimage \- tag: mytag myuser/myimage: docker_image.present: \- build: /home/myuser/docker/myimage \- tag: mytag \- dockerfile: Dockerfile.alternative .ft P .fi .UNINDENT .UNINDENT .sp The image will be built using \fI\%docker.build\fP and the specified image name and tag will be applied to it. .sp New in version 2016.11.0. .sp Changed in version 2018.3.0: The \fBtag\fP must be manually specified using the \fBtag\fP argument. .TP .B load Loads a tar archive created with \fI\%docker.save\fP (or the \fBdocker save\fP Docker CLI command), and assigns it the specified repo and tag. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myuser/myimage: docker_image.present: \- load: salt://path/to/image.tar \- tag: mytag .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2018.3.0: The \fBtag\fP must be manually specified using the \fBtag\fP argument. .TP .B force Set this parameter to \fBTrue\fP to force Salt to pull/build/load the image even if it is already present. .TP .B insecure_registry If \fBTrue\fP, the Docker client will permit the use of insecure (non\-HTTPS) registries. .TP .B client_timeout Timeout in seconds for the Docker client. This is not a timeout for the state, but for receiving a response from the API. .TP .B dockerfile Allows for an alternative Dockerfile to be specified. Path to alternative Dockefile is relative to the build path for the Docker container. .sp New in version 2016.11.0. .TP .B sls Allow for building of image with \fI\%docker.sls_build\fP by specifying the SLS files with which to build. This can be a list or comma\-separated string. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myuser/myimage: docker_image.present: \- tag: latest \- sls: \- webapp1 \- webapp2 \- base: centos \- saltenv: base .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.0. .sp Changed in version 2018.3.0: The \fBtag\fP must be manually specified using the \fBtag\fP argument. .TP .B base Base image with which to start \fI\%docker.sls_build\fP .sp New in version 2017.7.0. .TP .B saltenv Specify the environment from which to retrieve the SLS indicated by the \fImods\fP parameter. .sp New in version 2017.7.0. .sp Changed in version 2018.3.0: Now uses the effective saltenv if not explicitly passed. In earlier versions, \fBbase\fP was assumed as a default. .TP .B pillarenv Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the \fI\%pillarenv\fP option. When neither the \fI\%pillarenv\fP minion config option nor this CLI argument is used, all Pillar environments will be merged together. .sp New in version 2018.3.0. .TP .B pillar Custom Pillar values, passed as a dictionary of key\-value pairs .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Values passed this way will override Pillar values set via \fBpillar_roots\fP or an external Pillar source. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .TP .B kwargs Additional keyword arguments to pass to \fI\%docker.build\fP .UNINDENT .UNINDENT .SS salt.states.docker_network .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%docker Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Management of Docker networks .sp New in version 2017.7.0. .INDENT 0.0 .TP .B depends \fI\%docker\fP Python module .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Older releases of the Python bindings for Docker were called \fI\%docker\-py\fP in PyPI. All releases of \fI\%docker\fP, and releases of \fI\%docker\-py\fP >= 1.6.0 are supported. These python bindings can easily be installed using \fI\%pip.install\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pip.install docker .ft P .fi .UNINDENT .UNINDENT .sp To upgrade from \fI\%docker\-py\fP to \fI\%docker\fP, you must first uninstall \fI\%docker\-py\fP, and then install \fI\%docker\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pip.uninstall docker\-py salt myminion pip.install docker .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp These states were moved from the \fBdocker\fP state module (formerly called \fBdockerng\fP) in the 2017.7.0 release. .INDENT 0.0 .TP .B salt.states.docker_network.absent(name) Ensure that a network is absent. .INDENT 7.0 .TP .B name Name of the network .UNINDENT .sp Usage Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C network_foo: docker_network.absent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.docker_network.present(name, skip_translate=None, ignore_collisions=False, validate_ip_addrs=True, containers=None, reconnect=True, **kwargs) Changed in version 2018.3.0: Support added for network configuration options other than \fBdriver\fP and \fBdriver_opts\fP, as well as IPAM configuration. .sp Ensure that a network is present .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state supports all arguments for network and IPAM pool configuration which are available for the release of docker\-py installed on the minion. For that reason, the arguments described below in the \fI\%NETWORK CONFIGURATION\fP and \fI\%IP ADDRESS MANAGEMENT (IPAM)\fP sections may not accurately reflect what is available on the minion. The \fI\%docker.get_client_args\fP function can be used to check the available arguments for the installed version of docker\-py (they are found in the \fBnetwork_config\fP and \fBipam_config\fP sections of the return data), but Salt will not prevent a user from attempting to use an argument which is unsupported in the release of Docker which is installed. In those cases, network creation be attempted but will fail. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Network name .TP .B skip_translate This function translates Salt SLS input into the format which docker\-py expects. However, in the event that Salt\(aqs translation logic fails (due to potential changes in the Docker Remote API, or to bugs in the translation code), this argument can be used to exert granular control over which arguments are translated and which are not. .sp Pass this argument as a comma\-separated list (or Python list) of arguments, and translation for each passed argument name will be skipped. Alternatively, pass \fBTrue\fP and \fIall\fP translation will be skipped. .sp Skipping tranlsation allows for arguments to be formatted directly in the format which docker\-py expects. This allows for API changes and other issues to be more easily worked around. See the following links for more information: .INDENT 7.0 .IP \(bu 2 \fI\%docker\-py Low\-level API\fP .IP \(bu 2 \fI\%Docker Engine API\fP .UNINDENT .sp New in version 2018.3.0. .UNINDENT .INDENT 7.0 .TP .B ignore_collisions False Since many of docker\-py\(aqs arguments differ in name from their CLI counterparts (with which most Docker users are more familiar), Salt detects usage of these and aliases them to the docker\-py version of that argument. However, if both the alias and the docker\-py version of the same argument (e.g. \fBoptions\fP and \fBdriver_opts\fP) are used, an error will be raised. Set this argument to \fBTrue\fP to suppress these errors and keep the docker\-py version of the argument. .sp New in version 2018.3.0. .TP .B validate_ip_addrs True For parameters which accept IP addresses/subnets as input, validation will be performed. To disable, set this to \fBFalse\fP\&. .sp New in version 2018.3.0. .TP .B containers A list of containers which should be connected to this network. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 As of the 2018.3.0 release, this is not the recommended way of managing a container\(aqs membership in a network, for a couple reasons: .INDENT 0.0 .IP 1. 3 It does not support setting static IPs, aliases, or links in the container\(aqs IP configuration. .IP 2. 3 If a \fI\%docker_container.running\fP state replaces a container, it will not be reconnected to the network until the \fBdocker_network.present\fP state is run again. Since containers often have \fBrequire\fP requisites to ensure that the network is present, this means that the \fBdocker_network.present\fP state ends up being run \fIbefore\fP the \fI\%docker_container.running\fP, leaving the container unattached at the end of the Salt run. .UNINDENT .sp For these reasons, it is recommended to use \fI\%docker_container.running\(aqs network management support\fP\&. .UNINDENT .UNINDENT .TP .B reconnect True If \fBcontainers\fP is not used, and the network is replaced, then Salt will keep track of the containers which were connected to the network and reconnect them to the network after it is replaced. Salt will first attempt to reconnect using the same IP the container had before the network was replaced. If that fails (for instance, if the network was replaced because the subnet was modified), then the container will be reconnected without an explicit IP address, and its IP will be assigned by Docker. .sp Set this option to \fBFalse\fP to keep Salt from trying to reconnect containers. This can be useful in some cases when \fI\%managing static IPs in docker_container.running\fP\&. For instance, if a network\(aqs subnet is modified, it is likely that the static IP will need to be updated in the \fBdocker_container.running\fP state as well. When the network is replaced, the initial reconnect attempt would fail, and the container would be reconnected with an automatically\-assigned IP address. Then, when the \fBdocker_container.running\fP state executes, it would disconnect the network \fIagain\fP and reconnect using the new static IP. Disabling the reconnect behavior in these cases would prevent the unnecessary extra reconnection. .sp New in version 2018.3.0. .UNINDENT .sp \fBNETWORK CONFIGURATION ARGUMENTS\fP .INDENT 7.0 .TP .B driver Network driver .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- driver: macvlan .ft P .fi .UNINDENT .UNINDENT .TP .B driver_opts (or \fIdriver_opt\fP, or \fIoptions\fP) Options for the network driver. Either a dictionary of option names and values or a Python list of strings in the format \fBvarname=value\fP\&. The below three examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- driver: macvlan \- driver_opts: macvlan_mode=bridge,parent=eth0 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- driver: macvlan \- driver_opts: \- macvlan_mode=bridge \- parent=eth0 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- driver: macvlan \- driver_opts: \- macvlan_mode: bridge \- parent: eth0 .ft P .fi .UNINDENT .UNINDENT .sp The options can also simply be passed as a dictionary, though this can be error\-prone due to some \fI\%idiosyncrasies\fP with how PyYAML loads nested data structures: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- driver: macvlan \- driver_opts: macvlan_mode: bridge parent: eth0 .ft P .fi .UNINDENT .UNINDENT .TP .B check_duplicate True If \fBTrue\fP, checks for networks with duplicate names. Since networks are primarily keyed based on a random ID and not on the name, and network name is strictly a user\-friendly alias to the network which is uniquely identified using ID, there is no guaranteed way to check for duplicates. This option providess a best effort, checking for any networks which have the same name, but it is not guaranteed to catch all name collisions. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- check_duplicate: False .ft P .fi .UNINDENT .UNINDENT .TP .B internal False If \fBTrue\fP, restricts external access to the network .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- internal: True .ft P .fi .UNINDENT .UNINDENT .TP .B labels Add metadata to the network. Labels can be set both with and without values, and labels with values can be passed either as \fBkey=value\fP or \fBkey: value\fP pairs. For example, while the below would be very confusing to read, it is technically valid, and demonstrates the different ways in which labels can be passed: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- labels: \- foo \- bar=baz \- hello: world .ft P .fi .UNINDENT .UNINDENT .sp The labels can also simply be passed as a YAML dictionary, though this can be error\-prone due to some \fI\%idiosyncrasies\fP with how PyYAML loads nested data structures: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: docker_network.present: \- labels: foo: \(aq\(aq bar: baz hello: world .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2018.3.0: Methods for specifying labels can now be mixed. Earlier releases required either labels with or without values. .TP .B enable_ipv6 (or \fIipv6\fP) False Enable IPv6 on the network .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- enable_ipv6: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 While it should go without saying, this argument must be set to \fBTrue\fP to \fI\%configure an IPv6 subnet\fP\&. Also, if this option is turned on without an IPv6 subnet explicitly configured, you will get an error unless you have set up a fixed IPv6 subnet. Consult the \fI\%Docker IPv6 docs\fP for information on how to do this. .UNINDENT .UNINDENT .TP .B attachable False If \fBTrue\fP, and the network is in the global scope, non\-service containers on worker nodes will be able to connect to the network. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- attachable: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option cannot be reliably managed on CentOS 7. This is because while support for this option was added in API version 1.24, its value was not added to the inpsect results until API version 1.26. The version of Docker which is available for CentOS 7 runs API version 1.24, meaning that while Salt can pass this argument to the API, it has no way of knowing the value of this config option in an existing Docker network. .UNINDENT .UNINDENT .TP .B scope Specify the network\(aqs scope (\fBlocal\fP, \fBglobal\fP or \fBswarm\fP) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- scope: local .ft P .fi .UNINDENT .UNINDENT .TP .B ingress False If \fBTrue\fP, create an ingress network which provides the routing\-mesh in swarm mode .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- ingress: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp \fBIP ADDRESS MANAGEMENT (IPAM)\fP .sp This state supports networks with either IPv4, or both IPv4 and IPv6. If configuring IPv4, then you can pass the \fI\%IPAM pool arguments\fP below as individual arguments. However, if configuring IPv4 and IPv6, the arguments must be passed as a list of dictionaries, in the \fBipam_pools\fP argument (click \fI\%here\fP for some examples). \fI\%These docs\fP also have more information on these arguments. .sp \fIIPAM ARGUMENTS\fP .INDENT 7.0 .TP .B ipam_driver IPAM driver to use, if different from the default one .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- ipam_driver: foo .ft P .fi .UNINDENT .UNINDENT .TP .B ipam_opts Options for the IPAM driver. Either a dictionary of option names and values or a Python list of strings in the format \fBvarname=value\fP\&. The below three examples are equivalent: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- ipam_driver: foo \- ipam_opts: foo=bar,baz=qux .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- ipam_driver: foo \- ipam_opts: \- foo=bar \- baz=qux .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- ipam_driver: foo \- ipam_opts: \- foo: bar \- baz: qux .ft P .fi .UNINDENT .UNINDENT .sp The options can also simply be passed as a dictionary, though this can be error\-prone due to some \fI\%idiosyncrasies\fP with how PyYAML loads nested data structures: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- ipam_driver: macvlan \- ipam_opts: foo: bar baz: qux .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp \fIIPAM POOL ARGUMENTS\fP .INDENT 7.0 .TP .B subnet Subnet in CIDR format that represents a network segment .TP .B iprange (or \fIip_range\fP) Allocate container IP from a sub\-range within the subnet .sp Subnet in CIDR format that represents a network segment .TP .B gateway IPv4 or IPv6 gateway for the master subnet .TP .B aux_addresses (or \fIaux_address\fP) A dictionary of mapping container names to IP addresses which should be allocated for them should they connect to the network. Either a dictionary of option names and values or a Python list of strings in the format \fBhost=ipaddr\fP\&. .UNINDENT .sp \fIIPAM CONFIGURATION EXAMPLES\fP .sp Below is an example of an IPv4\-only network (keep in mind that \fBsubnet\fP is the only required argument). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- subnet: 10.0.20.0/24 \- iprange: 10.0.20.128/25 \- gateway: 10.0.20.254 \- aux_addresses: \- foo.bar.tld: 10.0.20.50 \- hello.world.tld: 10.0.20.51 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fBaux_addresses\fP can be passed differently, in the same way that \fBdriver_opts\fP and \fBipam_opts\fP can. .UNINDENT .UNINDENT .sp This same network could also be configured this way: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- ipam_pools: \- subnet: 10.0.20.0/24 iprange: 10.0.20.128/25 gateway: 10.0.20.254 aux_addresses: foo.bar.tld: 10.0.20.50 hello.world.tld: 10.0.20.51 .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of a mixed IPv4/IPv6 subnet. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mynet: docker_network.present: \- ipam_pools: \- subnet: 10.0.20.0/24 gateway: 10.0.20.1 \- subnet: fe3f:2180:26:1::/123 gateway: fe3f:2180:26:1::1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.docker_volume .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%docker Salt Extension\fP\&. .UNINDENT .UNINDENT .sp Management of Docker volumes .sp New in version 2017.7.0. .INDENT 0.0 .TP .B depends \fI\%docker\fP Python module .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Older releases of the Python bindings for Docker were called \fI\%docker\-py\fP in PyPI. All releases of \fI\%docker\fP, and releases of \fI\%docker\-py\fP >= 1.6.0 are supported. These python bindings can easily be installed using \fI\%pip.install\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pip.install docker .ft P .fi .UNINDENT .UNINDENT .sp To upgrade from \fI\%docker\-py\fP to \fI\%docker\fP, you must first uninstall \fI\%docker\-py\fP, and then install \fI\%docker\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion pip.uninstall docker\-py salt myminion pip.install docker .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp These states were moved from the \fBdocker\fP state module (formerly called \fBdockerng\fP) in the 2017.7.0 release. .INDENT 0.0 .TP .B salt.states.docker_volume.absent(name, driver=None) Ensure that a volume is absent. .sp New in version 2015.8.4. .sp Changed in version 2017.7.0: This state was renamed from \fBdocker.volume_absent\fP to \fBdocker_volume.absent\fP .INDENT 7.0 .TP .B name Name of the volume .UNINDENT .sp Usage Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C volume_foo: docker_volume.absent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.docker_volume.present(name, driver=None, driver_opts=None, force=False) Ensure that a volume is present. .sp New in version 2015.8.4. .sp Changed in version 2015.8.6: This state no longer deletes and re\-creates a volume if the existing volume\(aqs driver does not match the \fBdriver\fP parameter (unless the \fBforce\fP parameter is set to \fBTrue\fP). .sp Changed in version 2017.7.0: This state was renamed from \fBdocker.volume_present\fP to \fBdocker_volume.present\fP .INDENT 7.0 .TP .B name Name of the volume .TP .B driver Type of driver for that volume. If \fBNone\fP and the volume does not yet exist, the volume will be created using Docker\(aqs default driver. If \fBNone\fP and the volume does exist, this function does nothing, even if the existing volume\(aqs driver is not the Docker default driver. (To ensure that an existing volume\(aqs driver matches the Docker default, you must explicitly name Docker\(aqs default driver here.) .TP .B driver_opts Options for the volume driver .TP .B force False If the volume already exists but the existing volume\(aqs driver does not match the driver specified by the \fBdriver\fP parameter, this parameter controls whether the function errors out (if \fBFalse\fP) or deletes and re\-creates the volume (if \fBTrue\fP). .sp New in version 2015.8.6. .UNINDENT .sp Usage Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C volume_foo: docker_volume.present .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C volume_bar: docker_volume.present \- name: bar \- driver: local \- driver_opts: foo: bar .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C volume_bar: docker_volume.present \- name: bar \- driver: local \- driver_opts: \- foo: bar \- option: value .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.drac .sp Management of Dell DRAC .sp The DRAC module is used to create and manage DRAC cards on Dell servers .sp Ensure the user damian is present .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C damian: drac.present: \- name: damian \- password: secret \- permission: login,test_alerts,clear_logs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Ensure the user damian does not exist .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C damian: drac.absent: \- name: damian .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Ensure DRAC network is in a consistent state .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_network: drac.network: \- ip: 10.225.108.29 \- netmask: 255.255.255.224 \- gateway: 10.225.108.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.drac.absent(name) Ensure a user does not exist on the Dell DRAC .INDENT 7.0 .TP .B name: The users username .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.drac.network(ip, netmask, gateway) Ensure the DRAC network settings are consistent .UNINDENT .INDENT 0.0 .TP .B salt.states.drac.present(name, password, permission) Ensure the user exists on the Dell DRAC .INDENT 7.0 .TP .B name: The users username .TP .B password The password used to authenticate .TP .B permission The permissions that should be assigned to a user .UNINDENT .UNINDENT .SS salt.states.dvs .sp Manage VMware distributed virtual switches (DVSs) and their distributed virtual portgroups (DVportgroups). .INDENT 0.0 .TP .B codeauthor \fIAlexandru Bleotu <alexandru.bleotu@morganstaley.com>\fP .UNINDENT .sp Examples .sp Several settings can be changed for DVSs and DVporgroups. Here are two examples covering all of the settings. Fewer settings can be used .SS DVS .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aqname\(aq: \(aqdvs1\(aq, \(aqmax_mtu\(aq: 1000, \(aquplink_names\(aq: [ \(aqdvUplink1\(aq, \(aqdvUplink2\(aq, \(aqdvUplink3\(aq ], \(aqcapability\(aq: { \(aqportgroup_operation_supported\(aq: false, \(aqoperation_supported\(aq: true, \(aqport_operation_supported\(aq: false }, \(aqlacp_api_version\(aq: \(aqmultipleLag\(aq, \(aqcontact_email\(aq: \(aqfoo@email.com\(aq, \(aqproduct_info\(aq: { \(aqversion\(aq: \(aq6.0.0\(aq, \(aqvendor\(aq: \(aqVMware, Inc.\(aq, \(aqname\(aq: \(aqDVS\(aq }, \(aqnetwork_resource_management_enabled\(aq: true, \(aqcontact_name\(aq: \(aqme@email.com\(aq, \(aqinfrastructure_traffic_resource_pools\(aq: [ { \(aqreservation\(aq: 0, \(aqlimit\(aq: 1000, \(aqshare_level\(aq: \(aqhigh\(aq, \(aqkey\(aq: \(aqmanagement\(aq, \(aqnum_shares\(aq: 100 }, { \(aqreservation\(aq: 0, \(aqlimit\(aq: \-1, \(aqshare_level\(aq: \(aqnormal\(aq, \(aqkey\(aq: \(aqfaultTolerance\(aq, \(aqnum_shares\(aq: 50 }, { \(aqreservation\(aq: 0, \(aqlimit\(aq: 32000, \(aqshare_level\(aq: \(aqnormal\(aq, \(aqkey\(aq: \(aqvmotion\(aq, \(aqnum_shares\(aq: 50 }, { \(aqreservation\(aq: 10000, \(aqlimit\(aq: \-1, \(aqshare_level\(aq: \(aqnormal\(aq, \(aqkey\(aq: \(aqvirtualMachine\(aq, \(aqnum_shares\(aq: 50 }, { \(aqreservation\(aq: 0, \(aqlimit\(aq: \-1, \(aqshare_level\(aq: \(aqcustom\(aq, \(aqkey\(aq: \(aqiSCSI\(aq, \(aqnum_shares\(aq: 75 }, { \(aqreservation\(aq: 0, \(aqlimit\(aq: \-1, \(aqshare_level\(aq: \(aqnormal\(aq, \(aqkey\(aq: \(aqnfs\(aq, \(aqnum_shares\(aq: 50 }, { \(aqreservation\(aq: 0, \(aqlimit\(aq: \-1, \(aqshare_level\(aq: \(aqnormal\(aq, \(aqkey\(aq: \(aqhbr\(aq, \(aqnum_shares\(aq: 50 }, { \(aqreservation\(aq: 8750, \(aqlimit\(aq: 15000, \(aqshare_level\(aq: \(aqhigh\(aq, \(aqkey\(aq: \(aqvsan\(aq, \(aqnum_shares\(aq: 100 }, { \(aqreservation\(aq: 0, \(aqlimit\(aq: \-1, \(aqshare_level\(aq: \(aqnormal\(aq, \(aqkey\(aq: \(aqvdp\(aq, \(aqnum_shares\(aq: 50 } ], \(aqlink_discovery_protocol\(aq: { \(aqoperation\(aq: \(aqlisten\(aq, \(aqprotocol\(aq: \(aqcdp\(aq }, \(aqnetwork_resource_control_version\(aq: \(aqversion3\(aq, \(aqdescription\(aq: \(aqManaged by Salt. Random settings.\(aq .ft P .fi .UNINDENT .UNINDENT .sp Note: The mandatory attribute is: \fBname\fP\&. .SS Portgroup .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aqsecurity_policy\(aq: { \(aqallow_promiscuous\(aq: true, \(aqmac_changes\(aq: false, \(aqforged_transmits\(aq: true }, \(aqname\(aq: \(aqvmotion\-v702\(aq, \(aqout_shaping\(aq: { \(aqenabled\(aq: true, \(aqaverage_bandwidth\(aq: 1500, \(aqburst_size\(aq: 4096, \(aqpeak_bandwidth\(aq: 1500 }, \(aqnum_ports\(aq: 128, \(aqteaming\(aq: { \(aqport_order\(aq: { \(aqactive\(aq: [ \(aqdvUplink2\(aq ], \(aqstandby\(aq: [ \(aqdvUplink1\(aq ] }, \(aqnotify_switches\(aq: false, \(aqreverse_policy\(aq: true, \(aqrolling_order\(aq: false, \(aqpolicy\(aq: \(aqfailover_explicit\(aq, \(aqfailure_criteria\(aq: { \(aqcheck_error_percent\(aq: true, \(aqfull_duplex\(aq: false, \(aqcheck_duplex\(aq: false, \(aqpercentage\(aq: 50, \(aqcheck_speed\(aq: \(aqminimum\(aq, \(aqspeed\(aq: 20, \(aqcheck_beacon\(aq: true } }, \(aqtype\(aq: \(aqearlyBinding\(aq, \(aqvlan_id\(aq: 100, \(aqdescription\(aq: \(aqManaged by Salt. Random settings.\(aq .ft P .fi .UNINDENT .UNINDENT .sp Note: The mandatory attributes are: \fBname\fP, \fBtype\fP\&. .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.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 ESXi State Module was developed against. .INDENT 0.0 .TP .B salt.states.dvs.dvs_configured(name, dvs) Configures a DVS. .sp Creates a new DVS, if it doesn\(aqt exist in the provided datacenter or reconfigures it if configured differently. .INDENT 7.0 .TP .B dvs DVS dict representations (see module sysdocs) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.dvs.portgroups_configured(name, dvs, portgroups) Configures portgroups on a DVS. .sp Creates/updates/removes portgroups in a provided DVS .INDENT 7.0 .TP .B dvs Name of the DVS .TP .B portgroups Portgroup dict representations (see module sysdocs) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.dvs.uplink_portgroup_configured(name, dvs, uplink_portgroup) Configures the uplink portgroup on a DVS. The state assumes there is only one uplink portgroup. .INDENT 7.0 .TP .B dvs Name of the DVS .TP .B upling_portgroup Uplink portgroup dict representations (see module sysdocs) .UNINDENT .UNINDENT .SS salt.states.elasticsearch .sp State module to manage Elasticsearch. .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.states.elasticsearch.alias_absent(name, index) Ensure that the index alias is absent. .INDENT 7.0 .TP .B name Name of the index alias to remove .TP .B index Name of the index for the alias .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.elasticsearch.alias_present(name, index, definition=None) Ensure that the named index alias is present. .INDENT 7.0 .TP .B name Name of the alias .TP .B index Name of the index .TP .B definition Optional dict for filters as per \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/indices\-aliases.html\fP .UNINDENT .sp \fBExample:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mytestalias: elasticsearch.alias_present: \- index: testindex \- definition: filter: term: user: kimchy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.elasticsearch.index_absent(name) Ensure that the named index is absent. .INDENT 7.0 .TP .B name Name of the index to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.elasticsearch.index_present(name, definition=None) Ensure that the named index is present. .INDENT 7.0 .TP .B name Name of the index to add .TP .B definition Optional dict for creation parameters as per \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/indices\-create\-index.html\fP .UNINDENT .sp \fBExample:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Default settings mytestindex: elasticsearch_index.present # Extra settings mytestindex2: elasticsearch_index.present: \- definition: settings: index: number_of_shards: 10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.elasticsearch.index_template_absent(name) Ensure that the named index template is absent. .INDENT 7.0 .TP .B name Name of the index to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.elasticsearch.index_template_present(name, definition, check_definition=False) Ensure that the named index template is present. .INDENT 7.0 .TP .B name Name of the index to add .TP .B definition Required dict for creation parameters as per \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/indices\-templates.html\fP .TP .B check_definition If the template already exists and the definition is up to date .UNINDENT .sp \fBExample:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mytestindex2_template: elasticsearch.index_template_present: \- definition: template: logstash\-* order: 1 settings: number_of_shards: 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.elasticsearch.pipeline_absent(name) Ensure that the named pipeline is absent .INDENT 7.0 .TP .B name Name of the pipeline to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.elasticsearch.pipeline_present(name, definition) Ensure that the named pipeline is present. .INDENT 7.0 .TP .B name Name of the index to add .TP .B definition Required dict for creation parameters as per \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/master/pipeline.html\fP .UNINDENT .sp \fBExample:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C test_pipeline: elasticsearch.pipeline_present: \- definition: description: example pipeline processors: \- set: field: collector_timestamp_millis value: \(aq{{ \(aq{{\(aq }}_ingest.timestamp{{ \(aq}}\(aq }}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.elasticsearch.search_template_absent(name) Ensure that the search template is absent .INDENT 7.0 .TP .B name Name of the search template to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.elasticsearch.search_template_present(name, definition) Ensure that the named search template is present. .INDENT 7.0 .TP .B name Name of the search template to add .TP .B definition Required dict for creation parameters as per \fI\%http://www.elastic.co/guide/en/elasticsearch/reference/current/search\-template.html\fP .UNINDENT .sp \fBExample:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C test_pipeline: elasticsearch.search_template_present: \- definition: inline: size: 10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.elasticsearch_index .sp State module to manage Elasticsearch indices .sp New in version 2015.8.0. .sp Deprecated since version 2017.7.0: Use elasticsearch state instead .INDENT 0.0 .TP .B salt.states.elasticsearch_index.absent(name) Ensure that the named index is absent. .INDENT 7.0 .TP .B name Name of the index to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.elasticsearch_index.present(name, definition=None) New in version 2015.8.0. .sp Changed in version 2017.3.0: Marked \fBdefinition\fP as optional. .sp Ensure that the named index is present. .INDENT 7.0 .TP .B name Name of the index to add .TP .B definition Optional dict for creation parameters as per \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/indices\-create\-index.html\fP .UNINDENT .sp \fBExample:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Default settings mytestindex: elasticsearch_index.present # Extra settings mytestindex2: elasticsearch_index.present: \- definition: settings: index: number_of_shards: 10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.elasticsearch_index_template .sp State module to manage Elasticsearch index templates .sp New in version 2015.8.0. .sp Deprecated since version 2017.7.0: Use elasticsearch state instead .INDENT 0.0 .TP .B salt.states.elasticsearch_index_template.absent(name) Ensure that the named index template is absent. .INDENT 7.0 .TP .B name Name of the index to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.elasticsearch_index_template.present(name, definition) New in version 2015.8.0. .sp Changed in version 2017.3.0: Marked \fBdefinition\fP as required. .sp Ensure that the named index templat eis present. .INDENT 7.0 .TP .B name Name of the index to add .TP .B definition Required dict for creation parameters as per \fI\%https://www.elastic.co/guide/en/elasticsearch/reference/current/indices\-templates.html\fP .UNINDENT .sp \fBExample:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mytestindex2_template: elasticsearch_index_template.present: \- definition: template: logstash\-* order: 1 settings: number_of_shards: 1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.environ .sp Support for getting and setting the environment variables of the current salt process. .INDENT 0.0 .TP .B salt.states.environ.setenv(name, value, false_unsets=False, clear_all=False, update_minion=False, permanent=False) Set the salt process environment variables. .INDENT 7.0 .TP .B name The environment key to set. Must be a string. .TP .B value Either a string or dict. When string, it will be the value set for the environment key of \(aqname\(aq above. When a dict, each key/value pair represents an environment variable to set. .TP .B false_unsets If a key\(aqs value is False and false_unsets is True, then the key will be removed from the salt processes environment dict entirely. If a key\(aqs value is False and false_unsets is not True, then the key\(aqs value will be set to an empty string. Default: False .TP .B clear_all USE WITH CAUTION! This option can unset environment variables needed for salt to function properly. If clear_all is True, then any environment variables not defined in the environ dict will be deleted. Default: False .TP .B update_minion If True, apply these environ changes to the main salt\-minion process. If False, the environ changes will only affect the current salt subprocess. Default: False .TP .B permanent On Windows minions this will set the environment variable in the registry so that it is always added as a environment variable when applications open. If you want to set the variable to HKLM instead of HKCU just pass in \(dqHKLM\(dq for this parameter. On all other minion types this will be ignored. Note: This will only take affect on applications opened after this has been set. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C a_string_env: environ.setenv: \- name: foo \- value: bar \- update_minion: True a_dict_env: environ.setenv: \- name: does_not_matter \- value: foo: bar baz: quux .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.eselect .SS Management of Gentoo configuration using eselect .sp A state module to manage Gentoo configuration via eselect .INDENT 0.0 .TP .B salt.states.eselect.set_(name, target, module_parameter=None, action_parameter=None) Verify that the given module is set to the given target .INDENT 7.0 .TP .B name The name of the module .TP .B target The target to be set for this module .TP .B module_parameter additional params passed to the defined module .TP .B action_parameter additional params passed to the defined action .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C profile: eselect.set: \- target: hardened/linux/amd64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.esxcluster .sp Manage VMware ESXi Clusters. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be deprecated in a future release of Salt. VMware strongly recommends using the \fI\%VMware Salt extensions\fP instead of the ESX cluster module. Because the Salt extensions are newer and actively supported by VMware, they are more compatible with current versions of ESXi and they work well with the latest features in the VMware product line. .UNINDENT .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.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 ESXi State Module was developed against. .INDENT 0.0 .TP .B salt.states.esxcluster.cluster_configured(name, cluster_config) Configures a cluster. Creates a new cluster, if it doesn\(aqt exist on the vCenter or reconfigures it if configured differently .sp Supported proxies: esxdatacenter, esxcluster .INDENT 7.0 .TP .B name Name of the state. If the state is run in by an \fBesxdatacenter\fP proxy, it will be the name of the cluster. .TP .B cluster_config Configuration applied to the cluster. Complex datastructure following the ESXClusterConfigSchema. Valid example is: .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C drs: default_vm_behavior: fullyAutomated enabled: true vmotion_rate: 3 ha: admission_control _enabled: false default_vm_settings: isolation_response: powerOff restart_priority: medium enabled: true hb_ds_candidate_policy: userSelectedDs host_monitoring: enabled options: \- key: das.ignoreinsufficienthbdatastore value: \(aqtrue\(aq vm_monitoring: vmMonitoringDisabled vm_swap_placement: vmDirectory vsan: auto_claim_storage: false compression_enabled: true dedup_enabled: true enabled: true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.esxcluster.licenses_configured(name, licenses=None) Configures licenses on the cluster entity .INDENT 7.0 .TP .B Checks if each license exists on the server: .INDENT 7.0 .IP \(bu 2 if it doesn\(aqt, it creates it .UNINDENT .TP .B Check if license is assigned to the cluster: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B if it\(aqs not assigned to the cluster: .INDENT 7.0 .IP \(bu 2 assign it to the cluster if there is space .IP \(bu 2 error if there\(aqs no space .UNINDENT .UNINDENT .IP \(bu 2 if it\(aqs assigned to the cluster nothing needs to be done .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.esxcluster.vsan_datastore_configured(name, datastore_name) Configures the cluster\(aqs VSAN datastore .sp WARNING: The VSAN datastore is created automatically after the first ESXi host is added to the cluster; the state assumes that the datastore exists and errors if it doesn\(aqt. .UNINDENT .SS salt.states.esxdatacenter .sp Salt states to create and manage VMware vSphere datacenters (datacenters). .INDENT 0.0 .TP .B codeauthor \fIAlexandru Bleotu <alexandru.bleotu@morganstaley.com>\fP .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be deprecated in a future release of Salt. VMware strongly recommends using the \fI\%VMware Salt extensions\fP instead of the ESX data center module. Because the Salt extensions are newer and actively supported by VMware, they are more compatible with current versions of ESXi and they work well with the latest features in the VMware product line. .UNINDENT .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 pyVmomi Python Module .UNINDENT .SS States .SS datacenter_configured .sp Makes sure a datacenter exists and is correctly configured. .sp If the state is run by an \fBesxdatacenter\fP minion, the name of the datacenter is retrieved from the proxy details, otherwise the datacenter has the same name as the state. .sp Supported proxies: esxdatacenter .sp Example: .sp 1. Make sure that a datacenter named \fBtarget_dc\fP exists on the vCenter, using a \fBesxdatacenter\fP proxy: .sp Proxy minion configuration (connects passthrough to the vCenter): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: esxdatacenter datacenter: target_dc vcenter: vcenter.fake.com mechanism: sspi domain: fake.com principal: host .ft P .fi .UNINDENT .UNINDENT .sp State configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C datacenter_state: esxdatacenter.datacenter_configured .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.esxdatacenter.datacenter_configured(name) Makes sure a datacenter exists. .sp If the state is run by an \fBesxdatacenter\fP minion, the name of the datacenter is retrieved from the proxy details, otherwise the datacenter has the same name as the state. .sp Supported proxies: esxdatacenter .INDENT 7.0 .TP .B name: Datacenter name. Ignored if the proxytype is \fBesxdatacenter\fP\&. .UNINDENT .UNINDENT .SS salt.states.esxi .sp Manage VMware ESXi Hosts. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be deprecated in a future release of Salt. VMware strongly recommends using the \fI\%VMware Salt extensions\fP instead of the ESXi module. Because the Salt extensions are newer and actively supported by VMware, they are more compatible with current versions of ESXi and they work well with the latest features in the VMware product line. .UNINDENT .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 pyVmomi Python Module .IP \(bu 2 ESXCLI .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 ESXi State Module was developed against. .SS ESXCLI .sp Currently, about a third of the functions used in the vSphere Execution Module 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 or vCenter server by running the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C esxcli \-s <host\-location> \-u <username> \-p <password> 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Be aware that some functionality in this state module may depend on the type of license attached to the ESXi host. .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 About .sp This state module was written to be used in conjunction with Salt\(aqs \fI\%ESXi Proxy Minion\fP\&. For a tutorial on how to use Salt\(aqs ESXi Proxy Minion, please refer to the \fI\%ESXi Proxy Minion Tutorial\fP for configuration examples, dependency installation instructions, how to run remote execution functions against ESXi hosts via a Salt Proxy Minion, and a larger state example. .INDENT 0.0 .TP .B salt.states.esxi.coredump_configured(name, enabled, dump_ip, host_vnic=\(aqvmk0\(aq, dump_port=6500) Ensures a host\(aqs core dump configuration. .INDENT 7.0 .TP .B name Name of the state. .TP .B enabled Sets whether or not ESXi core dump collection should be enabled. This is a boolean value set to \fBTrue\fP or \fBFalse\fP to enable or disable core dumps. .sp Note that ESXi requires that the core dump must be enabled before any other parameters may be set. This also affects the \fBchanges\fP results in the state return dictionary. If \fBenabled\fP is \fBFalse\fP, we can\(aqt obtain any previous settings to compare other state variables, resulting in many \fBold\fP references returning \fBNone\fP\&. .sp Once \fBenabled\fP is \fBTrue\fP the \fBchanges\fP dictionary comparisons will be more accurate. This is due to the way the system coredemp network configuration command returns data. .TP .B dump_ip The IP address of host that will accept the dump. .TP .B host_vnic Host VNic port through which to communicate. Defaults to \fBvmk0\fP\&. .TP .B dump_port TCP port to use for the dump. Defaults to \fB6500\fP\&. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C configure\-host\-coredump: esxi.coredump_configured: \- enabled: True \- dump_ip: \(aqmy\-coredump\-ip.example.com\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.esxi.diskgroups_configured(name, diskgroups, erase_disks=False) Configures the disk groups to use for vsan. .sp This function will do the following: .INDENT 7.0 .IP 1. 3 Check whether or not all disks in the diskgroup spec exist, and raises and errors if they do not. .IP 2. 3 Create diskgroups with the correct disk configurations if diskgroup (identified by the cache disk canonical name) doesn\(aqt exist .IP 3. 3 Adds extra capacity disks to the existing diskgroup .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqcache_scsi_addr\(aq: \(aqvmhba1:C0:T0:L0\(aq, \(aqcapacity_scsi_addrs\(aq: [ \(aqvmhba2:C0:T0:L0\(aq, \(aqvmhba3:C0:T0:L0\(aq, \(aqvmhba4:C0:T0:L0\(aq, ] } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Mandatory state name .TP .B diskgroups Disk group representation containing scsi disk addresses. Scsi addresses are expected for disks in the diskgroup: .TP .B erase_disks Specifies whether to erase all partitions on all disks member of the disk group before the disk group is created. Default value is False. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.esxi.host_cache_configured(name, enabled, datastore, swap_size=\(aq100%\(aq, dedicated_backing_disk=False, erase_backing_disk=False) Configures the host cache used for swapping. .sp It will do the following: .INDENT 7.0 .IP 1. 3 Checks if backing disk exists .IP 2. 3 Creates the VMFS datastore if doesn\(aqt exist (datastore partition will be created and use the entire disk) .IP 3. 3 Raises an error if \fBdedicated_backing_disk\fP is \fBTrue\fP and partitions already exist on the backing disk .IP 4. 3 Configures host_cache to use a portion of the datastore for caching (either a specific size or a percentage of the datastore) .UNINDENT .sp Examples .sp Percentage swap size (can\(aqt be 100%) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqenabled\(aq: true, \(aqdatastore\(aq: { \(aqbacking_disk_scsi_addr\(aq: \(aqvmhba0:C0:T0:L0\(aq, \(aqvmfs_version\(aq: 5, \(aqname\(aq: \(aqhostcache\(aq } \(aqdedicated_backing_disk\(aq: false \(aqswap_size\(aq: \(aq98%\(aq, } .ft P .fi .UNINDENT .UNINDENT .sp Fixed sized swap size .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqenabled\(aq: true, \(aqdatastore\(aq: { \(aqbacking_disk_scsi_addr\(aq: \(aqvmhba0:C0:T0:L0\(aq, \(aqvmfs_version\(aq: 5, \(aqname\(aq: \(aqhostcache\(aq } \(aqdedicated_backing_disk\(aq: true \(aqswap_size\(aq: \(aq10GiB\(aq, } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Mandatory state name. .TP .B enabled Specifies whether the host cache is enabled. .TP .B datastore Specifies the host cache datastore. .TP .B swap_size Specifies the size of the host cache swap. Can be a percentage or a value in GiB. Default value is \fB100%\fP\&. .TP .B dedicated_backing_disk Specifies whether the backing disk is dedicated to the host cache which means it must have no other partitions. Default is False .TP .B erase_backing_disk Specifies whether to erase all partitions on the backing disk before the datastore is created. Default value is False. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.esxi.ntp_configured(name, service_running, ntp_servers=None, service_policy=None, service_restart=False, update_datetime=False) Ensures a host\(aqs NTP server configuration such as setting NTP servers, ensuring the NTP daemon is running or stopped, or restarting the NTP daemon for the ESXi host. .INDENT 7.0 .TP .B name Name of the state. .TP .B service_running Ensures the running state of the ntp daemon for the host. Boolean value where \fBTrue\fP indicates that ntpd should be running and \fBFalse\fP indicates that it should be stopped. .TP .B ntp_servers A list of servers that should be added to the ESXi host\(aqs NTP configuration. .TP .B service_policy The policy to set for the NTP service. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When setting the service policy to \fBoff\fP or \fBon\fP, you \fImust\fP quote the setting. If you don\(aqt, the yaml parser will set the string to a boolean, which will cause trouble checking for stateful changes and will error when trying to set the policy on the ESXi host. .UNINDENT .UNINDENT .TP .B service_restart If set to \fBTrue\fP, the ntp daemon will be restarted, regardless of its previous running state. Default is \fBFalse\fP\&. .TP .B update_datetime If set to \fBTrue\fP, the date/time on the given host will be updated to UTC. Default setting is \fBFalse\fP\&. This option should be used with caution since network delays and execution delays can result in time skews. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C configure\-host\-ntp: esxi.ntp_configured: \- service_running: True \- ntp_servers: \- 192.174.1.100 \- 192.174.1.200 \- service_policy: \(aqon\(aq \- service_restart: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.esxi.password_present(name, password) Ensures the given password is set on the ESXi host. Passwords cannot be obtained from host, so if a password is set in this state, the \fBvsphere.update_host_password\fP function will always run (except when using test=True functionality) and the state\(aqs changes dictionary will always be populated. .sp The username for which the password will change is the same username that is used to authenticate against the ESXi host via the Proxy Minion. For example, if the pillar definition for the proxy username is defined as \fBroot\fP, then the username that the password will be updated for via this state is \fBroot\fP\&. .INDENT 7.0 .TP .B name Name of the state. .TP .B password The new password to change on the host. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C configure\-host\-password: esxi.password_present: \- password: \(aqnew\-bad\-password\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.esxi.ssh_configured(name, service_running, ssh_key=None, ssh_key_file=None, service_policy=None, service_restart=False, certificate_verify=None) Manage the SSH configuration for a host including whether or not SSH is running or the presence of a given SSH key. Note: Only one ssh key can be uploaded for root. Uploading a second key will replace any existing key. .INDENT 7.0 .TP .B name Name of the state. .TP .B service_running Ensures whether or not the SSH service should be running on a host. Represented as a boolean value where \fBTrue\fP indicates that SSH should be running and \fBFalse\fP indicates that SSH should stopped. .sp In order to update SSH keys, the SSH service must be running. .TP .B ssh_key Public SSH key to added to the authorized_keys file on the ESXi host. You can use \fBssh_key\fP or \fBssh_key_file\fP, but not both. .TP .B ssh_key_file File containing the public SSH key to be added to the authorized_keys file on the ESXi host. You can use \fBssh_key_file\fP or \fBssh_key\fP, but not both. .TP .B service_policy The policy to set for the NTP service. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When setting the service policy to \fBoff\fP or \fBon\fP, you \fImust\fP quote the setting. If you don\(aqt, the yaml parser will set the string to a boolean, which will cause trouble checking for stateful changes and will error when trying to set the policy on the ESXi host. .UNINDENT .UNINDENT .TP .B service_restart If set to \fBTrue\fP, the SSH service will be restarted, regardless of its previous running state. Default is \fBFalse\fP\&. .TP .B certificate_verify If set to \fBTrue\fP, the SSL connection must present a valid certificate. Default is \fBTrue\fP\&. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C configure\-host\-ssh: esxi.ssh_configured: \- service_running: True \- ssh_key_file: /etc/salt/ssh_keys/my_key.pub \- service_policy: \(aqon\(aq \- service_restart: True \- certificate_verify: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.esxi.syslog_configured(name, syslog_configs, firewall=True, reset_service=True, reset_syslog_config=False, reset_configs=None) Ensures the specified syslog configuration parameters. By default, this state will reset the syslog service after any new or changed parameters are set successfully. .INDENT 7.0 .TP .B name Name of the state. .TP .B syslog_configs Name of parameter to set (corresponds to the command line switch for esxcli without the double dashes (\-\-)) .sp Valid syslog_config values are \fBlogdir\fP, \fBloghost\fP, \fBlogdir\-unique\fP, \fBdefault\-rotate\fP, \fBdefault\-size\fP, and \fBdefault\-timeout\fP\&. .sp Each syslog_config option also needs a configuration value to set. For example, \fBloghost\fP requires URLs or IP addresses to use for logging. Multiple log servers can be specified by listing them, comma\-separated, but without spaces before or after commas .sp (reference: \fI\%https://blogs.vmware.com/vsphere/2012/04/configuring\-multiple\-syslog\-servers\-for\-esxi\-5.html\fP) .TP .B firewall Enable the firewall rule set for syslog. Defaults to \fBTrue\fP\&. .TP .B reset_service After a successful parameter set, reset the service. Defaults to \fBTrue\fP\&. .TP .B reset_syslog_config Resets the syslog service to its default settings. Defaults to \fBFalse\fP\&. If set to \fBTrue\fP, default settings defined by the list of syslog configs in \fBreset_configs\fP will be reset before running any other syslog settings. .TP .B reset_configs A comma\-delimited list of parameters to reset. Only runs if \fBreset_syslog_config\fP is set to \fBTrue\fP\&. If \fBreset_syslog_config\fP is set to \fBTrue\fP, but no syslog configs are listed in \fBreset_configs\fP, then \fBreset_configs\fP will be set to \fBall\fP by default. .sp See \fBsyslog_configs\fP parameter above for a list of valid options. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C 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 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.esxi.vmotion_configured(name, enabled, device=\(aqvmk0\(aq) Configures a host\(aqs VMotion properties such as enabling VMotion and setting the device VirtualNic that VMotion will use. .INDENT 7.0 .TP .B name Name of the state. .TP .B enabled Ensures whether or not VMotion should be enabled on a host as a boolean value where \fBTrue\fP indicates that VMotion should be enabled and \fBFalse\fP indicates that VMotion should be disabled. .TP .B device The device that uniquely identifies the VirtualNic that will be used for VMotion for the host. Defaults to \fBvmk0\fP\&. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C configure\-vmotion: esxi.vmotion_configured: \- enabled: True \- device: sample\-device .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.esxi.vsan_configured(name, enabled, add_disks_to_vsan=False) Configures a host\(aqs VSAN properties such as enabling or disabling VSAN, or adding VSAN\-eligible disks to the VSAN system for the host. .INDENT 7.0 .TP .B name Name of the state. .TP .B enabled Ensures whether or not VSAN should be enabled on a host as a boolean value where \fBTrue\fP indicates that VSAN should be enabled and \fBFalse\fP indicates that VSAN should be disabled. .TP .B add_disks_to_vsan If set to \fBTrue\fP, any VSAN\-eligible disks for the given host will be added to the host\(aqs VSAN system. Default is \fBFalse\fP\&. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C configure\-host\-vsan: esxi.vsan_configured: \- enabled: True \- add_disks_to_vsan: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.esxvm .sp Salt state to create, update VMware ESXi Virtual Machines. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be deprecated in a future release of Salt. VMware strongly recommends using the \fI\%VMware Salt extensions\fP instead of the ESX VSM module. Because the Salt extensions are newer and actively supported by VMware, they are more compatible with current versions of ESXi and they work well with the latest features in the VMware product line. .UNINDENT .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 pyVmomi .IP \(bu 2 jsonschema .UNINDENT .SS States .SS vm_configured .sp Enforces correct virtual machine configuration. Creates, updates and registers a virtual machine. .sp This state identifies the action which should be taken for the virtual machine and applies that action via the create, update, register state functions. .sp Supported proxies: esxvm .sp Example: .INDENT 0.0 .IP 1. 3 Get the virtual machine \fBmy_vm\fP status with an \fBesxvm\fP proxy: .UNINDENT .sp Proxy minion configuration for \fBesxvm\fP proxy: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: esxvm datacenter: my_dc vcenter: vcenter.fake.com mechanism: sspi domain: fake.com principal: host .ft P .fi .UNINDENT .UNINDENT .sp State configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myvm_state: esxvm.vm_configured: \- vm_name: my_vm \- cpu: {{ {\(aqcount\(aq: 4, \(aqcores_per_socket\(aq: 2} }} \- memory: {{ {\(aqsize\(aq: 16384, \(aqunit\(aq: \(aqMB\(aq} }} \- image: rhel7_64Guest \- version: vmx\-12 \- interfaces: {{ [{ \(aqadapter\(aq: \(aqNetwork adapter 1\(aq, \(aqname\(aq: \(aqmy_pg1\(aq, \(aqswitch_type\(aq: \(aqdistributed\(aq, \(aqadapter_type\(aq: \(aqvmxnet3\(aq, \(aqmac\(aq: \(aq00:50:56:00:01:02, \(aqconnectable\(aq: { \(aqstart_connected\(aq: true, \(aqallow_guest_control\(aq: true, \(aqconnected\(aq: true}}, { \(aqadapter\(aq: \(aqNetwork adapter 2\(aq, \(aqname\(aq: \(aqmy_pg2\(aq, \(aqswitch_type\(aq: \(aqdistributed\(aq, \(aqadapter_type\(aq: \(aqvmxnet3\(aq, \(aqmac\(aq: \(aq00:50:56:00:01:03\(aq, \(aqconnectable\(aq: { \(aqstart_connected\(aq: true, \(aqallow_guest_control\(aq: true, \(aqconnected\(aq: true}} ] }} \- disks: {{ [{ \(aqadapter\(aq: \(aqHard disk 1\(aq, \(aqunit\(aq: \(aqMB\(aq, \(aqsize\(aq: 51200, \(aqfilename\(aq: \(aqmy_vm/sda.vmdk\(aq, \(aqdatastore\(aq: \(aqmy_datastore\(aq, \(aqaddress\(aq: \(aq0:0\(aq, \(aqthin_provision\(aq: true, \(aqeagerly_scrub\(aq: false, \(aqcontroller\(aq: \(aqSCSI controller 0\(aq}, { \(aqadapter\(aq: \(aqHard disk 2\(aq, \(aqunit\(aq: \(aqMB\(aq, \(aqsize\(aq: 10240, \(aqfilename\(aq: \(aqmy_vm/sdb.vmdk\(aq, \(aqdatastore\(aq: \(aqmy_datastore\(aq, \(aqaddress\(aq: \(aq0:1\(aq, \(aqthin_provision\(aq: true, \(aqeagerly_scrub\(aq: false, \(aqcontroller\(aq: \(aqSCSI controller 0\(aq} ] }} \- scsi_devices: {{ [{ \(aqadapter\(aq: \(aqSCSI controller 0\(aq, \(aqtype\(aq: \(aqparavirtual\(aq, \(aqbus_sharing\(aq: \(aqno_sharing\(aq, \(aqbus_number\(aq: 0} ] }} \- serial_ports: {{ [{ \(aqadapter\(aq: \(aqSerial port 1\(aq, \(aqtype\(aq: \(aqnetwork\(aq, \(aqyield\(aq: false, \(aqbacking\(aq: { \(aquri\(aq: \(aqmy_uri\(aq, \(aqdirection\(aq: \(aqserver\(aq, \(aqfilename\(aq: \(aqmy_file\(aq}, \(aqconnectable\(aq: { \(aqstart_connected\(aq: true, \(aqallow_guest_control\(aq: true, \(aqconnected\(aq: true}} ] }} \- datacenter: {{ \(aqmy_dc\(aq }} \- datastore: \(aqmy_datastore\(aq \- placement: {{ {\(aqcluster\(aq: \(aqmy_cluster\(aq} }} \- cd_dvd_drives: {{ [] }} \- advanced_configs: {{ {\(aqmy_param\(aq: \(aq1\(aq} }} \- template: false \- tools: false \- power_on: false \- deploy: false .ft P .fi .UNINDENT .UNINDENT .SS vm_updated .sp Updates a virtual machine to a given configuration. .SS vm_created .sp Creates a virtual machine with a given configuration. .SS vm_registered .sp Registers a virtual machine with its configuration file path. .SS Dependencies .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==6.0.0.2016.4 .ft P .fi .UNINDENT .UNINDENT .sp The 5.5.0.2014.1.1 is a known stable version that this original ESXi State Module was developed against. To be able to connect through SSPI you must use pyvmomi 6.0.0.2016.4 or above. The ESXVM State Module was tested with this version. .SS About .sp This state module was written to be used in conjunction with Salt\(aqs \fI\%ESXi Proxy Minion\fP For a tutorial on how to use Salt\(aqs ESXi Proxy Minion, please refer to the \fI\%ESXi Proxy Minion Tutorial\fP for configuration examples, dependency installation instructions, how to run remote execution functions against ESXi hosts via a Salt Proxy Minion, and a larger state example. .INDENT 0.0 .TP .B salt.states.esxvm.vm_cloned(name) Clones a virtual machine from a template virtual machine if it doesn\(aqt exist and a template is defined. .UNINDENT .INDENT 0.0 .TP .B salt.states.esxvm.vm_configured(name, vm_name, cpu, memory, image, version, interfaces, disks, scsi_devices, serial_ports, datacenter, datastore, placement, cd_dvd_drives=None, sata_controllers=None, advanced_configs=None, template=None, tools=True, power_on=False, deploy=False) Selects the correct operation to be executed on a virtual machine, non existing machines will be created, existing ones will be updated if the config differs. .UNINDENT .INDENT 0.0 .TP .B salt.states.esxvm.vm_created(name, vm_name, cpu, memory, image, version, interfaces, disks, scsi_devices, serial_ports, datacenter, datastore, placement, ide_controllers=None, sata_controllers=None, cd_dvd_drives=None, advanced_configs=None, power_on=False) Creates a virtual machine with the given properties if it doesn\(aqt exist. .UNINDENT .INDENT 0.0 .TP .B salt.states.esxvm.vm_registered(vm_name, datacenter, placement, vm_file, power_on=False) Registers a virtual machine if the machine files are available on the main datastore. .UNINDENT .INDENT 0.0 .TP .B salt.states.esxvm.vm_updated(name, vm_name, cpu, memory, image, version, interfaces, disks, scsi_devices, serial_ports, datacenter, datastore, cd_dvd_drives=None, sata_controllers=None, advanced_configs=None, power_on=False) Updates a virtual machine configuration if there is a difference between the given and deployed configuration. .UNINDENT .SS salt.states.etcd_mod .SS Manage etcd Keys .sp New in version 2015.8.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 python\-etcd or etcd3\-py .UNINDENT .UNINDENT .sp This state module supports setting and removing keys from etcd. .SS Configuration .sp To work with an etcd server you must configure an etcd profile. The etcd config can be set in either the Salt Minion configuration file or in pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_etd_config: etcd.host: 127.0.0.1 etcd.port: 4001 .ft P .fi .UNINDENT .UNINDENT .sp It is technically possible to configure etcd without using a profile, but this is not considered to be a best practice, especially when multiple etcd servers or clusters are available. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.host: 127.0.0.1 etcd.port: 4001 .ft P .fi .UNINDENT .UNINDENT .sp In order to choose whether to use etcd API v2 or v3, you can put the following configuration option in the same place as your etcd configuration. This option defaults to true, meaning you will use v2 unless you specify otherwise. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.require_v2: True .ft P .fi .UNINDENT .UNINDENT .sp When using API v3, there are some specific options available to be configured within your etcd profile. They are defaulted to the following... .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.encode_keys: False etcd.encode_values: True etcd.raw_keys: False etcd.raw_values: False etcd.unicode_errors: \(dqsurrogateescape\(dq .ft P .fi .UNINDENT .UNINDENT .sp \fBetcd.encode_keys\fP indicates whether you want to pre\-encode keys using msgpack before adding them to etcd. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you set \fBetcd.encode_keys\fP to \fBTrue\fP, all recursive functionality will no longer work. This includes \fBtree\fP and \fBls\fP and all other methods if you set \fBrecurse\fP/\fBrecursive\fP to \fBTrue\fP\&. This is due to the fact that when encoding with msgpack, keys like \fB/salt\fP and \fB/salt/stack\fP will have differing byte prefixes, and etcd v3 searches recursively using prefixes. .UNINDENT .UNINDENT .sp \fBetcd.encode_values\fP indicates whether you want to pre\-encode values using msgpack before adding them to etcd. This defaults to \fBTrue\fP to avoid data loss on non\-string values wherever possible. .sp \fBetcd.raw_keys\fP determines whether you want the raw key or a string returned. .sp \fBetcd.raw_values\fP determines whether you want the raw value or a string returned. .sp \fBetcd.unicode_errors\fP determines what you policy to follow when there are encoding/decoding errors. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The etcd configuration can also be set in the Salt Master config file, but in order to use any etcd configurations defined in the Salt Master config, the \fI\%pillar_opts\fP must be set to \fBTrue\fP\&. .sp Be aware that setting \fBpillar_opts\fP to \fBTrue\fP has security implications as this makes all master configuration settings available in all minion\(aqs pillars. .UNINDENT .UNINDENT .sp Etcd profile configuration can be overridden using following arguments: \fBhost\fP, \fBport\fP, \fBusername\fP, \fBpassword\fP, \fBca\fP, \fBclient_key\fP and \fBclient_cert\fP\&. The v3 specific arguments can also be used for overriding if you are using v3. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-value: etcd.set: \- name: /path/to/key \- value: value \- host: 127.0.0.1 \- port: 2379 \- username: user \- password: pass .ft P .fi .UNINDENT .UNINDENT .SS Available Functions .INDENT 0.0 .IP \(bu 2 \fBset\fP .sp This will set a value to a key in etcd. Changes will be returned if the key has been created or the value of the key has been updated. This means you can watch these states for changes. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C /foo/bar/baz: etcd.set: \- value: foo \- profile: my_etcd_config .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBwait_set\fP .sp Performs the same functionality as \fBset\fP but only if a watch requisite is \fBTrue\fP\&. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C /some/file.txt: file.managed: \- source: salt://file.txt /foo/bar/baz: etcd.wait_set: \- value: foo \- profile: my_etcd_config \- watch: \- file: /some/file.txt .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBrm\fP .sp This will delete a key from etcd. If the key exists then changes will be returned and thus you can watch for changes on the state, if the key does not exist then no changes will occur. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C /foo/bar/baz: etcd.rm: \- profile: my_etcd_config .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBwait_rm\fP .sp Performs the same functionality as \fBrm\fP but only if a watch requisite is \fBTrue\fP\&. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C /some/file.txt: file.managed: \- source: salt://file.txt /foo/bar/baz: etcd.wait_rm: \- profile: my_etcd_config \- watch: \- file: /some/file.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.etcd_mod.directory(name, profile=None, **kwargs) Create a directory in etcd. .INDENT 7.0 .TP .B name The etcd directory name, for example: \fB/foo/bar/baz\fP\&. .TP .B profile Optional, defaults to \fBNone\fP\&. Sets the etcd profile to use which has been defined in the Salt Master config. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my_etd_config: etcd.host: 127.0.0.1 etcd.port: 4001 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.etcd_mod.mod_watch(name, **kwargs) The etcd watcher, called to invoke the watch command. When called, execute a etcd function based on a watch call requisite. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBwatch\fP \fI\%requisite\fP\&. It should not be called directly. .sp Parameters for this function should be set by the state being triggered. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.etcd_mod.rm(name, recurse=False, profile=None, **kwargs) Deletes a key from etcd .INDENT 7.0 .TP .B name The etcd key name to remove, for example \fB/foo/bar/baz\fP\&. .TP .B recurse Optional, defaults to \fBFalse\fP\&. If \fBTrue\fP performs a recursive delete. .TP .B profile Optional, defaults to \fBNone\fP\&. Sets the etcd profile to use which has been defined in the Salt Master config. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my_etd_config: etcd.host: 127.0.0.1 etcd.port: 4001 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.etcd_mod.set_(name, value, profile=None, **kwargs) Set a key in etcd .INDENT 7.0 .TP .B name The etcd key name, for example: \fB/foo/bar/baz\fP\&. .TP .B value The value the key should contain. .TP .B profile Optional, defaults to \fBNone\fP\&. Sets the etcd profile to use which has been defined in the Salt Master config. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my_etd_config: etcd.host: 127.0.0.1 etcd.port: 4001 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.etcd_mod.wait_rm(name, recurse=False, profile=None, **kwargs) Deletes a key from etcd only if the watch statement calls it. This function is also aliased as \fBwait_rm\fP\&. .INDENT 7.0 .TP .B name The etcd key name to remove, for example \fB/foo/bar/baz\fP\&. .TP .B recurse Optional, defaults to \fBFalse\fP\&. If \fBTrue\fP performs a recursive delete, see: \fI\%https://python\-etcd.readthedocs.io/en/latest/#delete\-a\-key\fP\&. .TP .B profile Optional, defaults to \fBNone\fP\&. Sets the etcd profile to use which has been defined in the Salt Master config. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my_etd_config: etcd.host: 127.0.0.1 etcd.port: 4001 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.etcd_mod.wait_set(name, value, profile=None, **kwargs) Set a key in etcd only if the watch statement calls it. This function is also aliased as \fBwait_set\fP\&. .INDENT 7.0 .TP .B name The etcd key name, for example: \fB/foo/bar/baz\fP\&. .TP .B value The value the key should contain. .TP .B profile The etcd profile to use that has been configured on the Salt Master, this is optional and defaults to \fBNone\fP\&. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my_etd_config: etcd.host: 127.0.0.1 etcd.port: 4001 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.states.ethtool .sp Configuration of network device .sp New in version 2016.11.0. .INDENT 0.0 .TP .B codeauthor Krzysztof Pawlowski <\fI\%msciciel@msciciel.eu\fP> .TP .B maturity new .TP .B depends python\-ethtool .TP .B platform linux .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C eth0: ethtool.coalesce: \- name: eth0 \- rx_usecs: 24 \- tx_usecs: 48 eth0: ethtool.ring: \- name: eth0 \- rx: 1024 \- tx: 1024 eth0: ethtool.offload: \- name: eth0 \- tcp_segmentation_offload: on .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ethtool.coalesce(name, **kwargs) Manage coalescing settings of network device .INDENT 7.0 .TP .B name Interface name to apply coalescing settings .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C eth0: ethtool.coalesce: \- name: eth0 \- adaptive_rx: on \- adaptive_tx: on \- rx_usecs: 24 \- rx_frame: 0 \- rx_usecs_irq: 0 \- rx_frames_irq: 0 \- tx_usecs: 48 \- tx_frames: 0 \- tx_usecs_irq: 0 \- tx_frames_irq: 0 \- stats_block_usecs: 0 \- pkt_rate_low: 0 \- rx_usecs_low: 0 \- rx_frames_low: 0 \- tx_usecs_low: 0 \- tx_frames_low: 0 \- pkt_rate_high: 0 \- rx_usecs_high: 0 \- rx_frames_high: 0 \- tx_usecs_high: 0 \- tx_frames_high: 0 \- sample_interval: 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ethtool.offload(name, **kwargs) Manage protocol offload and other features of network device .INDENT 7.0 .TP .B name Interface name to apply coalescing settings .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C eth0: ethtool.offload: \- name: eth0 \- tcp_segmentation_offload: on .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ethtool.pause(name, **kwargs) New in version 3006.0. .sp Manage pause parameters of network device .INDENT 7.0 .TP .B name Interface name to apply pause parameters .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C eth0: ethtool.pause: \- name: eth0 \- autoneg: off \- rx: off \- tx: off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ethtool.ring(name, **kwargs) Manage rx/tx ring parameters of network device .sp Use \(aqmax\(aq word to set with factory maximum .INDENT 7.0 .TP .B name Interface name to apply ring parameters .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C eth0: ethtool.ring: \- name: eth0 \- rx: 1024 \- rx_mini: 0 \- rx_jumbo: 0 \- tx: max .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.event .sp Send events through Salt\(aqs event system during state runs .INDENT 0.0 .TP .B salt.states.event.fire_master(name, data=None, preload=None, with_env=False, with_grains=False, with_pillar=False, show_changed=True, **kwargs) This function is an alias of \fBsend\fP\&. .INDENT 7.0 .INDENT 3.5 Send an event to the Salt Master .sp New in version 2014.7.0. .sp Accepts the same arguments as the \fI\%event.send\fP execution module of the same name, with the additional argument: .INDENT 0.0 .TP .B param show_changed If \fBTrue\fP, state will show as changed with the data argument as the change value. If \fBFalse\fP, shows as unchanged. .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # ...snip bunch of states above mycompany/mystaterun/status/update: event.send: \- data: status: \(dqHalf\-way through the state run!\(dq # ...snip bunch of states below .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.event.mod_watch(name, data=None, preload=None, with_env=False, with_grains=False, with_pillar=False, show_changed=True, **kwargs) This function is an alias of \fBsend\fP\&. .INDENT 7.0 .INDENT 3.5 Send an event to the Salt Master .sp New in version 2014.7.0. .sp Accepts the same arguments as the \fI\%event.send\fP execution module of the same name, with the additional argument: .INDENT 0.0 .TP .B param show_changed If \fBTrue\fP, state will show as changed with the data argument as the change value. If \fBFalse\fP, shows as unchanged. .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # ...snip bunch of states above mycompany/mystaterun/status/update: event.send: \- data: status: \(dqHalf\-way through the state run!\(dq # ...snip bunch of states below .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.event.send(name, data=None, preload=None, with_env=False, with_grains=False, with_pillar=False, show_changed=True, **kwargs) Send an event to the Salt Master .sp New in version 2014.7.0. .sp Accepts the same arguments as the \fI\%event.send\fP execution module of the same name, with the additional argument: .INDENT 7.0 .TP .B Parameters \fBshow_changed\fP \-\- If \fBTrue\fP, state will show as changed with the data argument as the change value. If \fBFalse\fP, shows as unchanged. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # ...snip bunch of states above mycompany/mystaterun/status/update: event.send: \- data: status: \(dqHalf\-way through the state run!\(dq # ...snip bunch of states below .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.event.wait(name, sfun=None, data=None) Fire an event on the Salt master event bus if called from a watch statement .sp New in version 2014.7.0. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Stand up a new web server. apache: pkg: \- installed \- name: httpd service: \- running \- enable: True \- name: httpd # Notify the load balancer to update the pool once Apache is running. refresh_pool: event: \- wait \- name: mycompany/loadbalancer/pool/update \- data: new_web_server_ip: {{ grains[\(aqipv4\(aq] | first() }} \- watch: \- pkg: apache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.file .SS Operations on regular files, special files, directories, and symlinks .sp Salt States can aggressively manipulate files on a system. There are a number of ways in which files can be managed. .sp Regular files can be enforced with the \fI\%file.managed\fP state. This state downloads files from the salt master and places them on the target system. Managed files can be rendered as a jinja, mako, or wempy template, adding a dynamic component to file management. An example of \fI\%file.managed\fP which makes use of the jinja templating system would look like this: .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 \- attrs: ai \- template: jinja \- defaults: custom_var: \(dqdefault value\(dq other_var: 123 {% if grains[\(aqos\(aq] == \(aqUbuntu\(aq %} \- context: custom_var: \(dqoverride\(dq {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp It is also possible to use the \fI\%py renderer\fP as a templating option. The template would be a Python script which would need to contain a function called \fBrun()\fP, which returns a string. All arguments to the state will be made available to the Python script as globals. The returned string will be the contents of the managed file. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def run(): lines = [\(aqfoo\(aq, \(aqbar\(aq, \(aqbaz\(aq] lines.extend([source, name, user, context]) # Arguments as globals return \(aq\en\en\(aq.join(lines) .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBdefaults\fP and \fBcontext\fP arguments require extra indentation (four spaces instead of the normal two) in order to create a nested dictionary. \fI\%More information\fP\&. .UNINDENT .UNINDENT .sp If using a template, any user\-defined template variables in the file defined in \fBsource\fP must be passed in using the \fBdefaults\fP and/or \fBcontext\fP arguments. The general best practice is to place default values in \fBdefaults\fP, with conditional overrides going into \fBcontext\fP, as seen above. .sp The template will receive a variable \fBcustom_var\fP, which would be accessed in the template using \fB{{ custom_var }}\fP\&. If the operating system is Ubuntu, the value of the variable \fBcustom_var\fP would be \fIoverride\fP, otherwise it is the default \fIdefault value\fP .sp The \fBsource\fP parameter can be specified as a list. If this is done, then the first file to be matched will be the one that is used. This allows you to have a default file on which to fall back if the desired file does not exist on the salt fileserver. Here\(aqs an example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/foo.conf: file.managed: \- source: \- salt://foo.conf.{{ grains[\(aqfqdn\(aq] }} \- salt://foo.conf.fallback \- user: foo \- group: users \- mode: 644 \- attrs: i \- backup: minion .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt supports backing up managed files via the backup option. For more details on this functionality please review the \fI\%backup_mode documentation\fP\&. .UNINDENT .UNINDENT .sp The \fBsource\fP parameter can also specify a file in another Salt environment. In this example \fBfoo.conf\fP in the \fBdev\fP environment will be used instead. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/foo.conf: file.managed: \- source: \- \(aqsalt://foo.conf?saltenv=dev\(aq \- user: foo \- group: users \- mode: \(aq0644\(aq \- attrs: i .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 When using a mode that includes a leading zero you must wrap the value in single quotes. If the value is not wrapped in quotes it will be read by YAML as an integer and evaluated as an octal. .UNINDENT .UNINDENT .sp The \fBnames\fP parameter, which is part of the state compiler, can be used to expand the contents of a single state declaration into multiple, single state declarations. Each item in the \fBnames\fP list receives its own individual state \fBname\fP and is converted into its own low\-data structure. This is a convenient way to manage several files with similar attributes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt_master_conf: file.managed: \- user: root \- group: root \- mode: \(aq0644\(aq \- names: \- /etc/salt/master.d/master.conf: \- source: salt://saltmaster/master.conf \- /etc/salt/minion.d/minion\-99.conf: \- source: salt://saltmaster/minion.conf .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There is more documentation about this feature in the \fI\%Names declaration\fP section of the \fI\%Highstate docs\fP\&. .UNINDENT .UNINDENT .sp Special files can be managed via the \fBmknod\fP function. This function will create and enforce the permissions on a special file. The function supports the creation of character devices, block devices, and FIFO pipes. The function will create the directory structure up to the special file if it is needed on the minion. The function will not overwrite or operate on (change major/minor numbers) existing special files with the exception of user, group, and permissions. In most cases the creation of some special files require root permissions on the minion. This would require that the minion to be run as the root user. Here is an example of a character device: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /var/named/chroot/dev/random: file.mknod: \- ntype: c \- major: 1 \- minor: 8 \- user: named \- group: named \- mode: 660 .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of a block device: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /var/named/chroot/dev/loop0: file.mknod: \- ntype: b \- major: 7 \- minor: 0 \- user: named \- group: named \- mode: 660 .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of a fifo pipe: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /var/named/chroot/var/log/logfifo: file.mknod: \- ntype: p \- user: named \- group: named \- mode: 660 .ft P .fi .UNINDENT .UNINDENT .sp Directories can be managed via the \fBdirectory\fP function. This function can create and enforce the permissions on a directory. A directory statement will look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /srv/stuff/substuf: file.directory: \- user: fred \- group: users \- mode: 755 \- makedirs: True .ft P .fi .UNINDENT .UNINDENT .sp If you need to enforce user and/or group ownership or permissions recursively on the directory\(aqs contents, you can do so by adding a \fBrecurse\fP directive: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /srv/stuff/substuf: file.directory: \- user: fred \- group: users \- mode: 755 \- makedirs: True \- recurse: \- user \- group \- mode .ft P .fi .UNINDENT .UNINDENT .sp As a default, \fBmode\fP will resolve to \fBdir_mode\fP and \fBfile_mode\fP, to specify both directory and file permissions, use this form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /srv/stuff/substuf: file.directory: \- user: fred \- group: users \- file_mode: 744 \- dir_mode: 755 \- makedirs: True \- recurse: \- user \- group \- mode .ft P .fi .UNINDENT .UNINDENT .sp Symlinks can be easily created; the symlink function is very simple and only takes a few arguments: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/grub.conf: file.symlink: \- target: /boot/grub/grub.conf .ft P .fi .UNINDENT .UNINDENT .sp Recursive directory management can also be set via the \fBrecurse\fP function. Recursive directory management allows for a directory on the salt master to be recursively copied down to the minion. This is a great tool for deploying large code and configuration systems. A state using \fBrecurse\fP would look something like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /opt/code/flask: file.recurse: \- source: salt://code/flask \- include_empty: True .ft P .fi .UNINDENT .UNINDENT .sp A more complex \fBrecurse\fP example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set site_user = \(aqtestuser\(aq %} {% set site_name = \(aqtest_site\(aq %} {% set project_name = \(aqtest_proj\(aq %} {% set sites_dir = \(aqtest_dir\(aq %} django\-project: file.recurse: \- name: {{ sites_dir }}/{{ site_name }}/{{ project_name }} \- user: {{ site_user }} \- dir_mode: 2775 \- file_mode: \(aq0644\(aq \- template: jinja \- source: salt://project/templates_dir \- include_empty: True .ft P .fi .UNINDENT .UNINDENT .sp Retention scheduling can be applied to manage contents of backup directories. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /var/backups/example_directory: file.retention_schedule: \- strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2 \- retain: most_recent: 5 first_of_hour: 4 first_of_day: 14 first_of_week: 6 first_of_month: 6 first_of_year: all .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.absent(name, **kwargs) Make sure that the named file or directory is absent. If it exists, it will be deleted. This will work to reverse any of the functions in the file state module. If a directory is supplied, it will be recursively deleted. .sp If only the contents of the directory need to be deleted but not the directory itself, use \fI\%file.directory\fP with \fBclean=True\fP .INDENT 7.0 .TP .B name The path which should be deleted .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.accumulated(name, filename, text, **kwargs) Prepare accumulator which can be used in template in file.managed state. Accumulator dictionary becomes available in template. It can also be used in file.blockreplace. .INDENT 7.0 .TP .B name Accumulator name .TP .B filename Filename which would receive this accumulator (see file.managed state documentation about \fBname\fP) .TP .B text String or list for adding in accumulator .TP .B require_in / watch_in One of them required for sure we fill up accumulator before we manage the file. Probably the same as filename .UNINDENT .sp Example: .sp Given the following: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C animals_doing_things: file.accumulated: \- filename: /tmp/animal_file.txt \- text: \(aq jumps over the lazy dog.\(aq \- require_in: \- file: animal_file animal_file: file.managed: \- name: /tmp/animal_file.txt \- source: salt://animal_file.txt \- template: jinja .ft P .fi .UNINDENT .UNINDENT .sp One might write a template for \fBanimal_file.txt\fP like the following: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C The quick brown fox{% for animal in accumulator[\(aqanimals_doing_things\(aq] %}{{ animal }}{% endfor %} .ft P .fi .UNINDENT .UNINDENT .sp Collectively, the above states and template file will produce: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C The quick brown fox jumps over the lazy dog. .ft P .fi .UNINDENT .UNINDENT .sp Multiple accumulators can be \(dqchained\(dq together. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \(aqaccumulator\(aq data structure is a Python dictionary. Do not expect any loop over the keys in a deterministic order! .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.append(name, text=None, makedirs=False, source=None, source_hash=None, template=\(aqjinja\(aq, sources=None, source_hashes=None, defaults=None, context=None, ignore_whitespace=True) Ensure that some text appears at the end of a file. .sp The text will not be appended if it already exists in the file. A single string of text or a list of strings may be appended. .INDENT 7.0 .TP .B name The location of the file to append to. .TP .B text The text to be appended, which can be a single string or a list of strings. .TP .B makedirs If the file is located in a path without a parent directory, then the state will fail. If makedirs is set to True, then the parent directories will be created to facilitate the creation of the named file. Defaults to False. .TP .B source A single source file to append. This source file can be hosted on either the salt master server, or on an HTTP or FTP server. Both HTTPS and HTTP are supported as well as downloading directly from Amazon S3 compatible URLs with both pre\-configured and automatic IAM credentials (see s3.get state documentation). File retrieval from Openstack Swift object storage is supported via swift://container/object_path URLs (see swift.get documentation). .sp For files hosted on the salt file server, if the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs. .sp If the file is hosted on an HTTP or FTP server, the source_hash argument is also required. .TP .B source_hash .INDENT 7.0 .TP .B This can be one of the following: .INDENT 7.0 .IP 1. 3 a source hash string .IP 2. 3 the URI of a file that contains source hash strings .UNINDENT .UNINDENT .sp The function accepts the first encountered long unbroken alphanumeric string of correct length as a valid hash, in order from most secure to least secure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Type Length ====== ====== sha512 128 sha384 96 sha256 64 sha224 56 sha1 40 md5 32 .ft P .fi .UNINDENT .UNINDENT .sp See the \fBsource_hash\fP parameter description for \fI\%file.managed\fP function for more details and examples. .TP .B template The named templating engine will be used to render the appended\-to file. Defaults to \fBjinja\fP\&. The following templates are supported: .INDENT 7.0 .IP \(bu 2 \fI\%cheetah\fP .IP \(bu 2 \fI\%genshi\fP .IP \(bu 2 \fI\%jinja\fP .IP \(bu 2 \fI\%mako\fP .IP \(bu 2 \fI\%py\fP .IP \(bu 2 \fI\%wempy\fP .UNINDENT .TP .B sources A list of source files to append. If the files are hosted on an HTTP or FTP server, the source_hashes argument is also required. .TP .B source_hashes A list of source_hashes corresponding to the sources list specified in the sources argument. .TP .B defaults Default context passed to the template. .TP .B context Overrides default context variables passed to the template. .TP .B ignore_whitespace New in version 2015.8.4. .sp Spaces and Tabs in text are ignored by default, when searching for the appending content, one space or multiple tabs are the same for salt. Set this option to \fBFalse\fP if you want to change this behavior. .UNINDENT .sp Multi\-line example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/motd: file.append: \- text: | Thou hadst better eat salt with the Philosophers of Greece, than sugar with the Courtiers of Italy. \- Benjamin Franklin .ft P .fi .UNINDENT .UNINDENT .sp Multiple lines of text: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/motd: file.append: \- text: \- Trust no one unless you have eaten much salt with him. \- \(dqSalt is born of the purest of parents: the sun and the sea.\(dq .ft P .fi .UNINDENT .UNINDENT .sp Gather text from multiple template files: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/motd: file: \- append \- template: jinja \- sources: \- salt://motd/devops\-messages.tmpl \- salt://motd/hr\-messages.tmpl \- salt://motd/general\-messages.tmpl .ft P .fi .UNINDENT .UNINDENT .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.states.file.blockreplace(name, marker_start=\(aq#\-\- start managed zone \-\-\(aq, marker_end=\(aq#\-\- end managed zone \-\-\(aq, source=None, source_hash=None, template=\(aqjinja\(aq, sources=None, source_hashes=None, defaults=None, context=None, content=\(aq\(aq, append_if_not_found=False, prepend_if_not_found=False, backup=\(aq.bak\(aq, show_changes=True, append_newline=None, insert_before_match=None, insert_after_match=None) Maintain an edit in a file in a zone delimited by two line markers .sp New in version 2014.1.0. .sp Changed in version 2017.7.5,2018.3.1: \fBappend_newline\fP argument added. Additionally, to improve idempotence, if the string represented by \fBmarker_end\fP is found in the middle of the line, the content preceding the marker will be removed when the block is replaced. This allows one to remove \fBappend_newline: False\fP from the SLS and have the block properly replaced if the end of the content block is immediately followed by the \fBmarker_end\fP (i.e. no newline before the marker). .sp A block of content delimited by comments can help you manage several lines entries without worrying about old entries removal. This can help you maintaining an un\-managed file containing manual edits. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function will store two copies of the file in\-memory (the original version and the edited version) in order to detect changes and only edit the targeted file if necessary. .sp Additionally, you can use \fI\%file.accumulated\fP and target this state. All accumulated data dictionaries\(aq content will be added in the content block. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Filesystem path to the file to be edited .TP .B marker_start The line content identifying a line as the start of the content block. Note that the whole line containing this marker will be considered, so whitespace or extra content before or after the marker is included in final output .TP .B marker_end The line content identifying the end of the content block. As of versions 2017.7.5 and 2018.3.1, everything up to the text matching the marker will be replaced, so it\(aqs important to ensure that your marker includes the beginning of the text you wish to replace. .TP .B content The content to be used between the two lines identified by \fBmarker_start\fP and \fBmarker_end\fP .TP .B source The source file to download to the minion, this source file can be hosted on either the salt master server, or on an HTTP or FTP server. Both HTTPS and HTTP are supported as well as downloading directly from Amazon S3 compatible URLs with both pre\-configured and automatic IAM credentials. (see s3.get state documentation) File retrieval from Openstack Swift object storage is supported via swift://container/object_path URLs, see swift.get documentation. For files hosted on the salt file server, if the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs. If source is left blank or None (use ~ in YAML), the file will be created as an empty file and the content will not be managed. This is also the case when a file already exists and the source is undefined; the contents of the file will not be changed or managed. .sp If the file is hosted on a HTTP or FTP server then the source_hash argument is also required. .sp A list of sources can also be passed in to provide a default source and a set of fallbacks. The first source in the list that is found to exist will be used and subsequent entries in the list will be ignored. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C file_override_example: file.blockreplace: \- name: /etc/example.conf \- source: \- salt://file_that_does_not_exist \- salt://file_that_exists .ft P .fi .UNINDENT .UNINDENT .TP .B source_hash .INDENT 7.0 .TP .B This can be one of the following: .INDENT 7.0 .IP 1. 3 a source hash string .IP 2. 3 the URI of a file that contains source hash strings .UNINDENT .UNINDENT .sp The function accepts the first encountered long unbroken alphanumeric string of correct length as a valid hash, in order from most secure to least secure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Type Length ====== ====== sha512 128 sha384 96 sha256 64 sha224 56 sha1 40 md5 32 .ft P .fi .UNINDENT .UNINDENT .sp See the \fBsource_hash\fP parameter description for \fI\%file.managed\fP function for more details and examples. .TP .B template Templating engine to be used to render the downloaded file. The following engines are supported: .INDENT 7.0 .IP \(bu 2 \fI\%cheetah\fP .IP \(bu 2 \fI\%genshi\fP .IP \(bu 2 \fI\%jinja\fP .IP \(bu 2 \fI\%mako\fP .IP \(bu 2 \fI\%py\fP .IP \(bu 2 \fI\%wempy\fP .UNINDENT .TP .B context Overrides default context variables passed to the template .TP .B defaults Default context passed to the template .TP .B append_if_not_found If markers are not found and this option is set to \fBTrue\fP, the content block will be appended to the file. .TP .B prepend_if_not_found If markers are not found and this option is set to \fBTrue\fP, the content block will be prepended to the file. .TP .B insert_before_match If markers are not found, this parameter can be set to a regex which will insert the block before the first found occurrence in the file. .sp New in version 3001. .TP .B insert_after_match If markers are not found, this parameter can be set to a regex which will insert the block after the first found occurrence in the file. .sp New in version 3001. .TP .B backup The file extension to use for a backup of the file if any edit is made. Set this to \fBFalse\fP to skip making a backup. .TP .B show_changes Controls how changes are presented. If \fBTrue\fP, the \fBChanges\fP section of the state return will contain a unified diff of the changes made. If False, then it will contain a boolean (\fBTrue\fP if any changes were made, otherwise \fBFalse\fP). .TP .B append_newline Controls whether or not a newline is appended to the content block. If the value of this argument is \fBTrue\fP then a newline will be added to the content block. If it is \fBFalse\fP, then a newline will \fInot\fP be added to the content block. If it is unspecified, then a newline will only be added to the content block if it does not already end in a newline. .sp New in version 2017.7.5,2018.3.1. .UNINDENT .sp Example of usage with an accumulator and with a variable: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set myvar = 42 %} hosts\-config\-block\-{{ myvar }}: file.blockreplace: \- name: /etc/hosts \- marker_start: \(dq# START managed zone {{ myvar }} \-DO\-NOT\-EDIT\-\(dq \- marker_end: \(dq# END managed zone {{ myvar }} \-\-\(dq \- content: \(aqFirst line of content\(aq \- append_if_not_found: True \- backup: \(aq.bak\(aq \- show_changes: True hosts\-config\-block\-{{ myvar }}\-accumulated1: file.accumulated: \- filename: /etc/hosts \- name: my\-accumulator\-{{ myvar }} \- text: \(dqtext 2\(dq \- require_in: \- file: hosts\-config\-block\-{{ myvar }} hosts\-config\-block\-{{ myvar }}\-accumulated2: file.accumulated: \- filename: /etc/hosts \- name: my\-accumulator\-{{ myvar }} \- text: | text 3 text 4 \- require_in: \- file: hosts\-config\-block\-{{ myvar }} .ft P .fi .UNINDENT .UNINDENT .sp will generate and maintain a block of content in \fB/etc/hosts\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # START managed zone 42 \-DO\-NOT\-EDIT\- First line of content text 2 text 3 text 4 # END managed zone 42 \-\- .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.cached(name, source_hash=\(aq\(aq, source_hash_name=None, skip_verify=False, saltenv=\(aqbase\(aq, use_etag=False, source_hash_sig=None, signed_by_any=None, signed_by_all=None, keyring=None, gnupghome=None) New in version 2017.7.3. .sp Changed in version 3005. .sp Ensures that a file is saved to the minion\(aqs cache. This state is primarily invoked by other states to ensure that we do not re\-download a source file if we do not need to. .INDENT 7.0 .TP .B name The URL of the file to be cached. To cache a file from an environment other than \fBbase\fP, either use the \fBsaltenv\fP argument or include the saltenv in the URL (e.g. \fBsalt://path/to/file.conf?saltenv=dev\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A list of URLs is not supported, this must be a single URL. If a local file is passed here, then the state will obviously not try to download anything, but it will compare a hash if one is specified. .UNINDENT .UNINDENT .TP .B source_hash See the documentation for this same argument in the \fI\%file.managed\fP state. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For remote files not originating from the \fBsalt://\fP fileserver, such as http(s) or ftp servers, this state will not re\-download the file if the locally\-cached copy matches this hash. This is done to prevent unnecessary downloading on repeated runs of this state. To update the cached copy of a file, it is necessary to update this hash. .UNINDENT .UNINDENT .TP .B source_hash_name See the documentation for this same argument in the \fI\%file.managed\fP state. .TP .B skip_verify See the documentation for this same argument in the \fI\%file.managed\fP state. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Setting this to \fBTrue\fP will result in a copy of the file being downloaded from a remote (http(s), ftp, etc.) source each time the state is run. .UNINDENT .UNINDENT .TP .B saltenv Used to specify the environment from which to download a file from the Salt fileserver (i.e. those with \fBsalt://\fP URL). .TP .B use_etag If \fBTrue\fP, remote http/https file sources will attempt to use the ETag header to determine if the remote file needs to be downloaded. This provides a lightweight mechanism for promptly refreshing files changed on a web server without requiring a full hash comparison via the \fBsource_hash\fP parameter. .sp New in version 3005. .TP .B source_hash_sig When \fBname\fP is a remote file source, \fBsource_hash\fP is a file, \fBskip_verify\fP is not true and \fBuse_etag\fP is not true, ensure a valid GPG signature exists on the source hash file. Set this to \fBtrue\fP for an inline (clearsigned) signature, or to a file URI retrievable by \fI:py:func:\(gacp.cache_file <salt.modules.cp.cache_file>\fP for a detached one. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A signature on the \fBsource_hash\fP file is enforced regardless of changes since its contents are used to check if an existing file is in the correct state \- but only for remote sources! .UNINDENT .UNINDENT .sp New in version 3007.0. .TP .B signed_by_any When verifying \fBsource_hash_sig\fP, require at least one valid signature from one of a list of key fingerprints. This is passed to \fI\%gpg.verify\fP\&. .sp New in version 3007.0. .TP .B signed_by_all When verifying \fBsource_hash_sig\fP, require a valid signature from each of the key fingerprints in this list. This is passed to \fI\%gpg.verify\fP\&. .sp New in version 3007.0. .TP .B keyring When verifying signatures, use this keyring. .sp New in version 3007.0. .TP .B gnupghome When verifying signatures, use this GnuPG home. .sp New in version 3007.0. .UNINDENT .sp This state will in most cases not be useful in SLS files, but it is useful when writing a state or remote\-execution module that needs to make sure that a file at a given URL has been downloaded to the cachedir. One example of this is in the \fBarchive.extracted\fP state: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C result = __states__[\(aqfile.cached\(aq](source_match, source_hash=source_hash, source_hash_name=source_hash_name, skip_verify=skip_verify, saltenv=__env__) .ft P .fi .UNINDENT .UNINDENT .sp This will return a dictionary containing the state\(aqs return data, including a \fBresult\fP key which will state whether or not the state was successful. Note that this will not catch exceptions, so it is best used within a try/except. .sp Once this state has been run from within another state or remote\-execution module, the actual location of the cached file can be obtained using \fI\%cp.is_cached\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cached = __salt__[\(aqcp.is_cached\(aq](source_match, saltenv=__env__) .ft P .fi .UNINDENT .UNINDENT .sp This function will return the cached path of the file, or an empty string if the file is not present in the minion cache. .UNINDENT .INDENT 0.0 .TP .B salt.states.file.comment(name, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq, ignore_missing=False) New in version 0.9.5. .sp Changed in version 3005. .sp Comment out specified lines in a file. .INDENT 7.0 .TP .B name The full path to the file to be edited .TP .B regex A regular expression used to find the lines that are to be commented; this pattern will be wrapped in parenthesis and will move any preceding/trailing \fB^\fP or \fB$\fP characters outside the parenthesis (e.g., the pattern \fB^foo$\fP will be rewritten as \fB^(foo)$\fP) Note that you _need_ the leading ^, otherwise each time you run highstate, another comment char will be inserted. .TP .B char The character to be inserted at the beginning of a line in order to comment it out .TP .B backup The file will be backed up before edit with this file extension .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This backup will be overwritten each time \fBsed\fP / \fBcomment\fP / \fBuncomment\fP is called. Meaning the backup will only be useful after the first invocation. .UNINDENT .UNINDENT .sp Set to False/None to not keep a backup. .TP .B ignore_missing Ignore a failure to find the regex in the file. This is useful for scenarios where a line must only be commented if it is found in the file. .sp New in version 3005. .UNINDENT .sp Usage: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/fstab: file.comment: \- regex: ^bind 127.0.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.copy_(name, source, force=False, makedirs=False, preserve=False, user=None, group=None, mode=None, dir_mode=None, subdir=False, **kwargs) If the file defined by the \fBsource\fP option exists on the minion, copy it to the named path. The file will not be overwritten if it already exists, unless the \fBforce\fP option is set to \fBTrue\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state only copies files from one location on a minion to another location on the same minion. For copying files from the master, use a \fI\%file.managed\fP state. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The location of the file to copy to .TP .B source The location of the file to copy to the location specified with name .TP .B force If the target location is present then the file will not be moved, specify \(dqforce: True\(dq to overwrite the target file .TP .B makedirs If the target subdirectories don\(aqt exist create them .TP .B preserve New in version 2015.5.0. .sp Set \fBpreserve: True\fP to preserve user/group ownership and mode after copying. Default is \fBFalse\fP\&. If \fBpreserve\fP is set to \fBTrue\fP, then user/group/mode attributes will be ignored. .TP .B user New in version 2015.5.0. .sp The user to own the copied file, this defaults to the user salt is running as on the minion. If \fBpreserve\fP is set to \fBTrue\fP, then this will be ignored .TP .B group New in version 2015.5.0. .sp The group to own the copied file, this defaults to the group salt is running as on the minion. If \fBpreserve\fP is set to \fBTrue\fP or on Windows this will be ignored .TP .B mode New in version 2015.5.0. .sp The permissions to set on the copied file, aka 644, \(aq0775\(aq, \(aq4664\(aq. If \fBpreserve\fP is set to \fBTrue\fP, then this will be ignored. Not supported on Windows. .sp The default mode for new files and directories corresponds umask of salt process. For existing files and directories it\(aqs not enforced. .TP .B dir_mode New in version 3006.0. .sp If directories are to be created, passing this option specifies the permissions for those directories. If this is not set, directories will be assigned permissions by adding the execute bit to the mode of the files. .sp The default mode for new files and directories corresponds to the umask of the salt process. Not enforced for existing files and directories. .TP .B subdir New in version 2015.5.0. .sp If the name is a directory then place the file inside the named directory .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The copy function accepts paths that are local to the Salt minion. This function does not support salt://, http://, or the other additional file paths that are supported by \fI\%states.file.managed\fP and \fI\%states.file.recurse\fP\&. .UNINDENT .UNINDENT .sp Usage: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Use \(aqcopy\(aq, not \(aqcopy_\(aq /etc/example.conf: file.copy: \- source: /tmp/example.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.decode(name, encoded_data=None, contents_pillar=None, encoding_type=\(aqbase64\(aq, checksum=\(aqmd5\(aq) Decode an encoded file and write it to disk .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name Path of the file to be written. .TP .B encoded_data The encoded file. Either this option or \fBcontents_pillar\fP must be specified. .TP .B contents_pillar A Pillar path to the encoded file. Uses the same path syntax as \fI\%pillar.get\fP\&. The \fI\%hashutil.base64_encodefile\fP function can load encoded content into Pillar. Either this option or \fBencoded_data\fP must be specified. .TP .B encoding_type The type of encoding. .TP .B checksum The hashing algorithm to use to generate checksums. Wraps the \fI\%hashutil.digest\fP execution function. .UNINDENT .sp Usage: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C write_base64_encoded_string_to_a_file: file.decode: \- name: /tmp/new_file \- encoding_type: base64 \- contents_pillar: mypillar:thefile # or write_base64_encoded_string_to_a_file: file.decode: \- name: /tmp/new_file \- encoding_type: base64 \- encoded_data: | Z2V0IHNhbHRlZAo= .ft P .fi .UNINDENT .UNINDENT .sp Be careful with multi\-line strings that the YAML indentation is correct. E.g., .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C write_base64_encoded_string_to_a_file: file.decode: \- name: /tmp/new_file \- encoding_type: base64 \- encoded_data: | {{ salt.pillar.get(\(aqpath:to:data\(aq) | indent(8) }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.directory(name, user=None, group=None, recurse=None, max_depth=None, dir_mode=None, file_mode=None, makedirs=False, clean=False, require=None, exclude_pat=None, follow_symlinks=False, force=False, backupname=None, allow_symlink=True, children_only=False, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=True, win_perms_reset=False, **kwargs) Ensure that a named directory is present and has the right perms .INDENT 7.0 .TP .B name The location to create or manage a directory, as an absolute path .TP .B user The user to own the directory; this defaults to the user salt is running as on the minion .TP .B group The group ownership set for the directory; this defaults to the group salt is running as on the minion. On Windows, this is ignored .TP .B recurse Enforce user/group ownership and mode of directory recursively. Accepts a list of strings representing what you would like to recurse. If \fBmode\fP is defined, will recurse on both \fBfile_mode\fP and \fBdir_mode\fP if they are defined. If \fBignore_files\fP or \fBignore_dirs\fP is included, files or directories will be left unchanged respectively. directories will be left unchanged respectively. If \fBsilent\fP is defined, individual file/directory change notifications will be suppressed. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /var/log/httpd: file.directory: \- user: root \- group: root \- dir_mode: 755 \- file_mode: 644 \- recurse: \- user \- group \- mode .ft P .fi .UNINDENT .UNINDENT .sp Leave files or directories unchanged: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /var/log/httpd: file.directory: \- user: root \- group: root \- dir_mode: 755 \- file_mode: 644 \- recurse: \- user \- group \- mode \- ignore_dirs .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.5.0. .TP .B max_depth Limit the recursion depth. The default is no limit=None. \(aqmax_depth\(aq and \(aqclean\(aq are mutually exclusive. .sp New in version 2016.11.0. .TP .B dir_mode / mode The permissions mode to set any directories created. Not supported on Windows. .sp The default mode for new files and directories corresponds umask of salt process. For existing files and directories it\(aqs not enforced. .TP .B file_mode The permissions mode to set any files created if \(aqmode\(aq is run in \(aqrecurse\(aq. This defaults to dir_mode. Not supported on Windows. .sp The default mode for new files and directories corresponds umask of salt process. For existing files and directories it\(aqs not enforced. .TP .B makedirs If the directory is located in a path without a parent directory, then the state will fail. If makedirs is set to True, then the parent directories will be created to facilitate the creation of the named file. .TP .B clean Remove any files that are not referenced by a required \fBfile\fP state. See examples below for more info. If this option is set then everything in this directory will be deleted unless it is required. \(aqclean\(aq and \(aqmax_depth\(aq are mutually exclusive. .TP .B require Require other resources such as packages or files. .TP .B exclude_pat When \(aqclean\(aq is set to True, exclude this pattern from removal list and preserve in the destination. .TP .B follow_symlinks If the desired path is a symlink (or \fBrecurse\fP is defined and a symlink is encountered while recursing), follow it and check the permissions of the directory/file to which the symlink points. .sp New in version 2014.1.4. .sp Changed in version 3001.1: If set to False symlinks permissions are ignored on Linux systems because it does not support permissions modification. Symlinks permissions are always 0o777 on Linux. .TP .B force If the name of the directory exists and is not a directory and force is set to False, the state will fail. If force is set to True, the file in the way of the directory will be deleted to make room for the directory, unless backupname is set, then it will be renamed. .sp New in version 2014.7.0. .TP .B backupname If the name of the directory exists and is not a directory, it will be renamed to the backupname. If the backupname already exists and force is False, the state will fail. Otherwise, the backupname will be removed first. .sp New in version 2014.7.0. .TP .B allow_symlink If allow_symlink is True and the specified path is a symlink, it will be allowed to remain if it points to a directory. If allow_symlink is False then the state will fail, unless force is also set to True, in which case it will be removed or renamed, depending on the value of the backupname argument. .sp New in version 2014.7.0. .TP .B children_only If children_only is True the base of a path is excluded when performing a recursive operation. In case of /path/to/base, base will be ignored while all of /path/to/base/* are still operated on. .TP .B win_owner The owner of the directory. If this is not passed, user will be used. If user is not passed, the account under which Salt is running will be used. .sp New in version 2017.7.0. .TP .B win_perms A dictionary containing permissions to grant and their propagation. For example: \fB{\(aqAdministrators\(aq: {\(aqperms\(aq: \(aqfull_control\(aq, \(aqapplies_to\(aq: \(aqthis_folder_only\(aq}}\fP Can be a single basic perm or a list of advanced perms. \fBperms\fP must be specified. \fBapplies_to\fP is optional and defaults to \fBthis_folder_subfolder_files\fP\&. .sp New in version 2017.7.0. .TP .B win_deny_perms A dictionary containing permissions to deny and their propagation. For example: \fB{\(aqAdministrators\(aq: {\(aqperms\(aq: \(aqfull_control\(aq, \(aqapplies_to\(aq: \(aqthis_folder_only\(aq}}\fP Can be a single basic perm or a list of advanced perms. .sp New in version 2017.7.0. .TP .B win_inheritance True to inherit permissions from the parent directory, False not to inherit permission. .sp New in version 2017.7.0. .TP .B win_perms_reset If \fBTrue\fP the existing DACL will be cleared and replaced with the settings defined in this function. If \fBFalse\fP, new entries will be appended to the existing DACL. Default is \fBFalse\fP\&. .sp New in version 2018.3.0. .UNINDENT .sp Here\(aqs an example using the above \fBwin_*\fP parameters: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C create_config_dir: file.directory: \- name: \(aqC:\econfig\e\(aq \- win_owner: Administrators \- win_perms: # Basic Permissions dev_ops: perms: full_control # List of advanced permissions appuser: perms: \- read_attributes \- read_ea \- create_folders \- read_permissions applies_to: this_folder_only joe_snuffy: perms: read applies_to: this_folder_files \- win_deny_perms: fred_snuffy: perms: full_control \- win_inheritance: False .ft P .fi .UNINDENT .UNINDENT .sp For \fBclean: True\fP there is no mechanism that allows all states and modules to enumerate the files that they manage, so for file.directory to know what files are managed by Salt, a \fBfile\fP state targeting managed files is required. To use a contrived example, the following states will always have changes, despite the file named \fBokay\fP being created by a Salt state: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C silly_way_of_creating_a_file: cmd.run: \- name: mkdir \-p /tmp/dont/do/this && echo \(dqseriously\(dq > /tmp/dont/do/this/okay \- unless: grep seriously /tmp/dont/do/this/okay will_always_clean: file.directory: \- name: /tmp/dont/do/this \- clean: True .ft P .fi .UNINDENT .UNINDENT .sp Because \fBcmd.run\fP has no way of communicating that it\(aqs creating a file, \fBwill_always_clean\fP will remove the newly created file. Of course, every time the states run the same thing will happen \- the \fBsilly_way_of_creating_a_file\fP will crete the file and \fBwill_always_clean\fP will always remove it. Over and over again, no matter how many times you run it. .sp To make this example work correctly, we need to add a \fBfile\fP state that targets the file, and a \fBrequire\fP between the file states. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C silly_way_of_creating_a_file: cmd.run: \- name: mkdir \-p /tmp/dont/do/this && echo \(dqseriously\(dq > /tmp/dont/do/this/okay \- unless: grep seriously /tmp/dont/do/this/okay file.managed: \- name: /tmp/dont/do/this/okay \- create: False \- replace: False \- require_in: \- file: will_always_clean .ft P .fi .UNINDENT .UNINDENT .sp Now there is a \fBfile\fP state that \fBclean\fP can check, so running those states will work as expected. The file will be created with the specific contents, and \fBclean\fP will ignore the file because it is being managed by a salt \fBfile\fP state. Note that if \fBrequire_in\fP was placed under \fBcmd.run\fP, it would \fBnot\fP work, because the requisite is for the cmd, not the file. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C silly_way_of_creating_a_file: cmd.run: \- name: mkdir \-p /tmp/dont/do/this && echo \(dqseriously\(dq > /tmp/dont/do/this/okay \- unless: grep seriously /tmp/dont/do/this/okay # This part should be under file.managed \- require_in: \- file: will_always_clean file.managed: \- name: /tmp/dont/do/this/okay \- create: False \- replace: False .ft P .fi .UNINDENT .UNINDENT .sp Any other state that creates a file as a result, for example \fBpkgrepo\fP, must have the resulting files referenced in a file state in order for \fBclean: True\fP to ignore them. Also note that the requisite (\fBrequire_in\fP vs \fBrequire\fP) works in both directions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C clean_dir: file.directory: \- name: /tmp/a/better/way \- require: \- file: a_better_way a_better_way: file.managed: \- name: /tmp/a/better/way/truely \- makedirs: True \- contents: a much better way .ft P .fi .UNINDENT .UNINDENT .sp Works the same as this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C clean_dir: file.directory: \- name: /tmp/a/better/way \- clean: True a_better_way: file.managed: \- name: /tmp/a/better/way/truely \- makedirs: True \- contents: a much better way \- require_in: \- file: clean_dir .ft P .fi .UNINDENT .UNINDENT .sp A common mistake here is to forget the state name and id are both required for requisites: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Correct: /path/to/some/file: file.managed: \- contents: Cool \- require_in: \- file: clean_dir # Incorrect /path/to/some/file: file.managed: \- contents: Cool \- require_in: # should be \(ga\- file: clean_dir\(ga \- clean_dir # Also incorrect /path/to/some/file: file.managed: \- contents: Cool \- require_in: # should be \(ga\- file: clean_dir\(ga \- file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.exists(name, **kwargs) Verify that the named file or directory is present or exists. Ensures pre\-requisites outside of Salt\(aqs purview (e.g., keytabs, private keys, etc.) have been previously satisfied before deployment. .sp This function does not create the file if it doesn\(aqt exist, it will return an error. .INDENT 7.0 .TP .B name Absolute path which must exist .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.hardlink(name, target, force=False, makedirs=False, user=None, group=None, dir_mode=None, **kwargs) Create a hard link If the file already exists and is a hard link pointing to any location other than the specified target, the hard link will be replaced. If the hard link is a regular file or directory then the state will return False. If the regular file is desired to be replaced with a hard link pass force: True .INDENT 7.0 .TP .B name The location of the hard link to create .TP .B target The location that the hard link points to .TP .B force If the name of the hard link exists and force is set to False, the state will fail. If force is set to True, the file or directory in the way of the hard link file will be deleted to make room for the hard link, unless backupname is set, when it will be renamed .TP .B makedirs If the location of the hard link does not already have a parent directory then the state will fail, setting makedirs to True will allow Salt to create the parent directory .TP .B user The user to own any directories made if makedirs is set to true. This defaults to the user salt is running as on the minion .TP .B group The group ownership set on any directories made if makedirs is set to true. This defaults to the group salt is running as on the minion. On Windows, this is ignored .TP .B dir_mode If directories are to be created, passing this option specifies the permissions for those directories. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.keyvalue(name, key=None, value=None, key_values=None, separator=\(aq=\(aq, append_if_not_found=False, prepend_if_not_found=False, search_only=False, show_changes=True, ignore_if_missing=False, count=1, uncomment=None, key_ignore_case=False, value_ignore_case=False, create_if_missing=False) Key/Value based editing of a file. .sp New in version 3001. .sp This function differs from \fBfile.replace\fP in that it is able to search for keys, followed by a customizable separator, and replace the value with the given value. Should the value be the same as the one already in the file, no changes will be made. .sp Either supply both \fBkey\fP and \fBvalue\fP parameters, or supply a dictionary with key / value pairs. It is an error to supply both. .INDENT 7.0 .TP .B name Name of the file to search/replace in. .TP .B key Key to search for when ensuring a value. Use in combination with a \fBvalue\fP parameter. .TP .B value Value to set for a given key. Use in combination with a \fBkey\fP parameter. .TP .B key_values Dictionary of key / value pairs to search for and ensure values for. Used to specify multiple key / values at once. .TP .B separator Separator which separates key from value. .TP .B append_if_not_found Append the key/value to the end of the file if not found. Note that this takes precedence over \fBprepend_if_not_found\fP\&. .TP .B prepend_if_not_found Prepend the key/value to the beginning of the file if not found. Note that \fBappend_if_not_found\fP takes precedence. .TP .B show_changes Show a diff of the resulting removals and inserts. .TP .B ignore_if_missing Return with success even if the file is not found (or not readable). .TP .B count Number of occurrences to allow (and correct), default is 1. Set to \-1 to replace all, or set to 0 to remove all lines with this key regardsless of its value. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Any additional occurrences after \fBcount\fP are removed. A count of \-1 will only replace all occurrences that are currently uncommented already. Lines commented out will be left alone. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B uncomment Disregard and remove supplied leading characters when finding keys. When set to None, lines that are commented out are left for what they are. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The argument to \fBuncomment\fP is not a prefix string. Rather; it is a set of characters, each of which are stripped. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B key_ignore_case Keys are matched case insensitively. When a value is changed the matched key is kept as\-is. .TP .B value_ignore_case Values are checked case insensitively, trying to set e.g. \(aqYes\(aq while the current value is \(aqyes\(aq, will not result in changes when \fBvalue_ignore_case\fP is set to True. .TP .B create_if_missing Create the file if the destination file is not found. .sp New in version 3007.0. .UNINDENT .sp An example of using \fBfile.keyvalue\fP to ensure sshd does not allow for root to login with a password and at the same time setting the login\-gracetime to 1 minute and disabling all forwarding: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sshd_config_harden: file.keyvalue: \- name: /etc/ssh/sshd_config \- key_values: permitrootlogin: \(aqwithout\-password\(aq LoginGraceTime: \(aq1m\(aq DisableForwarding: \(aqyes\(aq \- separator: \(aq \(aq \- uncomment: \(aq# \(aq \- key_ignore_case: True \- append_if_not_found: True .ft P .fi .UNINDENT .UNINDENT .sp The same example, except for only ensuring PermitRootLogin is set correctly. Thus being able to use the shorthand \fBkey\fP and \fBvalue\fP parameters instead of \fBkey_values\fP\&. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sshd_config_harden: file.keyvalue: \- name: /etc/ssh/sshd_config \- key: PermitRootLogin \- value: without\-password \- separator: \(aq \(aq \- uncomment: \(aq# \(aq \- key_ignore_case: True \- append_if_not_found: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Notice how the key is not matched case\-sensitively, this way it will correctly identify both \(aqPermitRootLogin\(aq as well as \(aqpermitrootlogin\(aq. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.line(name, content=None, match=None, mode=None, location=None, before=None, after=None, show_changes=True, backup=False, quiet=False, indent=True, create=False, user=None, group=None, file_mode=None) Line\-focused editing of a file. .sp New in version 2015.8.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBfile.line\fP exists for historic reasons, and is not generally recommended. It has a lot of quirks. You may find \fBfile.replace\fP to be more suitable. .UNINDENT .UNINDENT .sp \fBfile.line\fP is most useful if you have single lines in a file, potentially a config file, that you would like to manage. It can remove, add, and replace lines. .INDENT 7.0 .TP .B name Filesystem path to the file to be edited. .TP .B content Content of the line. Allowed to be empty if mode=delete. .TP .B match Match the target line for an action by a fragment of a string or regular expression. .sp If neither \fBbefore\fP nor \fBafter\fP are provided, and \fBmatch\fP is also \fBNone\fP, match falls back to the \fBcontent\fP value. .TP .B mode Defines how to edit a line. One of the following options is required: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B ensure If line does not exist, it will be added. If \fBbefore\fP and \fBafter\fP are specified either zero lines, or lines that contain the \fBcontent\fP line are allowed to be in between \fBbefore\fP and \fBafter\fP\&. If there are lines, and none of them match then it will produce an error. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B replace If line already exists, it will be replaced. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B delete Delete the line, if found. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B insert Nearly identical to \fBensure\fP\&. If a line does not exist, it will be added. .sp The differences are that multiple (and non\-matching) lines are alloweed between \fBbefore\fP and \fBafter\fP, if they are specified. The line will always be inserted right before \fBbefore\fP\&. \fBinsert\fP also allows the use of \fBlocation\fP to specify that the line should be added at the beginning or end of the file. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If \fBmode=insert\fP is used, at least one of the following options must also be defined: \fBlocation\fP, \fBbefore\fP, or \fBafter\fP\&. If \fBlocation\fP is used, it takes precedence over the other two options. .UNINDENT .UNINDENT .TP .B location In \fBmode=insert\fP only, whether to place the \fBcontent\fP at the beginning or end of a the file. If \fBlocation\fP is provided, \fBbefore\fP and \fBafter\fP are ignored. Valid locations: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B start Place the content at the beginning of the file. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B end Place the content at the end of the file. .UNINDENT .UNINDENT .TP .B before Regular expression or an exact case\-sensitive fragment of the string. Will be tried as \fBboth\fP a regex \fBand\fP a part of the line. Must match \fBexactly\fP one line in the file. This value is only used in \fBensure\fP and \fBinsert\fP modes. The \fBcontent\fP will be inserted just before this line, matching its \fBindent\fP unless \fBindent=False\fP\&. .TP .B after Regular expression or an exact case\-sensitive fragment of the string. Will be tried as \fBboth\fP a regex \fBand\fP a part of the line. Must match \fBexactly\fP one line in the file. This value is only used in \fBensure\fP and \fBinsert\fP modes. The \fBcontent\fP will be inserted directly after this line, unless \fBbefore\fP is also provided. If \fBbefore\fP is not matched, indentation will match this line, unless \fBindent=False\fP\&. .TP .B show_changes Output a unified diff of the old file and the new file. If \fBFalse\fP return a boolean if any changes were made. Default is \fBTrue\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Using this option will store two copies of the file in\-memory (the original version and the edited version) in order to generate the diff. .UNINDENT .UNINDENT .TP .B backup Create a backup of the original file with the extension: \(dqYear\-Month\-Day\-Hour\-Minutes\-Seconds\(dq. .TP .B quiet Do not raise any exceptions. E.g. ignore the fact that the file that is tried to be edited does not exist and nothing really happened. .TP .B indent Keep indentation with the previous line. This option is not considered when the \fBdelete\fP mode is specified. Default is \fBTrue\fP\&. .TP .B create Create an empty file if doesn\(aqt exist. .sp New in version 2016.11.0. .TP .B user The user to own the file, this defaults to the user salt is running as on the minion. .sp New in version 2016.11.0. .TP .B group The group ownership set for the file, this defaults to the group salt is running as on the minion On Windows, this is ignored. .sp New in version 2016.11.0. .TP .B file_mode The permissions to set on this file, aka 644, 0775, 4664. Not supported on Windows. .sp New in version 2016.11.0. .UNINDENT .sp If an equal sign (\fB=\fP) appears in an argument to a Salt command, it is interpreted as a keyword argument in the format of \fBkey=val\fP\&. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C update_config: file.line: \- name: /etc/myconfig.conf \- mode: ensure \- content: my key = my value \- before: somekey.*? .ft P .fi .UNINDENT .UNINDENT .sp \fBExamples:\fP .sp Here\(aqs a simple config file. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [some_config] # Some config file # this line will go away here=False away=True goodybe=away .ft P .fi .UNINDENT .UNINDENT .sp And an sls file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C remove_lines: file.line: \- name: /some/file.conf \- mode: delete \- match: away .ft P .fi .UNINDENT .UNINDENT .sp This will produce: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [some_config] # Some config file here=False away=True goodbye=away .ft P .fi .UNINDENT .UNINDENT .sp If that state is executed 2 more times, this will be the result: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [some_config] # Some config file here=False .ft P .fi .UNINDENT .UNINDENT .sp Given that original file with this state: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C replace_things: file.line: \- name: /some/file.conf \- mode: replace \- match: away \- content: here .ft P .fi .UNINDENT .UNINDENT .sp Three passes will this state will result in this file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [some_config] # Some config file here here=False here here .ft P .fi .UNINDENT .UNINDENT .sp Each pass replacing the first line found. .sp Given this file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C insert after me something insert before me .ft P .fi .UNINDENT .UNINDENT .sp The following state: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C insert_a_line: file.line: \- name: /some/file.txt \- mode: insert \- after: insert after me \- before: insert before me \- content: thrice .ft P .fi .UNINDENT .UNINDENT .sp If this state is executed 3 times, the result will be: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C insert after me something thrice thrice thrice insert before me .ft P .fi .UNINDENT .UNINDENT .sp If the mode is ensure instead, it will fail each time. To succeed, we need to remove the incorrect line between before and after: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C insert after me insert before me .ft P .fi .UNINDENT .UNINDENT .sp With an ensure mode, this will insert \fBthrice\fP the first time and make no changes for subsequent calls. For something simple this is fine, but if you have instead blocks like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Begin SomeBlock foo = bar End Begin AnotherBlock another = value End .ft P .fi .UNINDENT .UNINDENT .sp And given this state: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ensure_someblock: file.line: \- name: /some/file.conf \- mode: ensure \- after: Begin SomeBlock \- content: this = should be my content \- before: End .ft P .fi .UNINDENT .UNINDENT .sp This will fail because there are multiple \fBEnd\fP lines. Without that problem, it still would fail because there is a non\-matching line, \fBfoo = bar\fP\&. Ensure \fBonly\fP allows either zero, or the matching line present to be present in between \fBbefore\fP and \fBafter\fP\&. .UNINDENT .INDENT 0.0 .TP .B salt.states.file.managed(name, source=None, source_hash=\(aq\(aq, source_hash_name=None, keep_source=True, user=None, group=None, mode=None, attrs=None, template=None, makedirs=False, dir_mode=None, context=None, replace=True, defaults=None, backup=\(aq\(aq, show_changes=True, create=True, contents=None, tmp_dir=\(aq\(aq, tmp_ext=\(aq\(aq, contents_pillar=None, contents_grains=None, contents_newline=True, contents_delimiter=\(aq:\(aq, encoding=None, encoding_errors=\(aqstrict\(aq, allow_empty=True, follow_symlinks=True, check_cmd=None, skip_verify=False, selinux=None, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=True, win_perms_reset=False, verify_ssl=True, use_etag=False, signature=None, source_hash_sig=None, signed_by_any=None, signed_by_all=None, keyring=None, gnupghome=None, **kwargs) Manage a given file, this function allows for a file to be downloaded from the salt master and potentially run through a templating system. .INDENT 7.0 .TP .B name The location of the file to manage, as an absolute path. .TP .B source The source file to download to the minion, this source file can be hosted on either the salt master server (\fBsalt://\fP), the salt minion local file system (\fB/\fP), or on an HTTP or FTP server (\fBhttp(s)://\fP, \fBftp://\fP). .sp Both HTTPS and HTTP are supported as well as downloading directly from Amazon S3 compatible URLs with both pre\-configured and automatic IAM credentials. (see s3.get state documentation) File retrieval from Openstack Swift object storage is supported via swift://container/object_path URLs, see swift.get documentation. For files hosted on the salt file server, if the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs. If source is left blank or None (use ~ in YAML), the file will be created as an empty file and the content will not be managed. This is also the case when a file already exists and the source is undefined; the contents of the file will not be changed or managed. If source is left blank or None, please also set replaced to False to make your intention explicit. .sp If the file is hosted on a HTTP or FTP server then the source_hash argument is also required. .sp A list of sources can also be passed in to provide a default source and a set of fallbacks. The first source in the list that is found to exist will be used and subsequent entries in the list will be ignored. Source list functionality only supports local files and remote files hosted on the salt master server or retrievable via HTTP, HTTPS, or FTP. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C file_override_example: file.managed: \- source: \- salt://file_that_does_not_exist \- salt://file_that_exists .ft P .fi .UNINDENT .UNINDENT .TP .B source_hash .INDENT 7.0 .TP .B This can be one of the following: .INDENT 7.0 .IP 1. 3 a source hash string .IP 2. 3 the URI of a file that contains source hash strings .UNINDENT .UNINDENT .sp The function accepts the first encountered long unbroken alphanumeric string of correct length as a valid hash, in order from most secure to least secure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Type Length ====== ====== sha512 128 sha384 96 sha256 64 sha224 56 sha1 40 md5 32 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP \fBUsing a Source Hash File\fP The file can contain several checksums for several files. Each line must contain both the file name and the hash. If no file name is matched, the first hash encountered will be used, otherwise the most secure hash with the correct source file name will be used. .sp When using a source hash file the source_hash argument needs to be a url, the standard download urls are supported, ftp, http, salt etc: .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C tomdroid\-src\-0.7.3.tar.gz: file.managed: \- name: /tmp/tomdroid\-src\-0.7.3.tar.gz \- source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid\-src\-0.7.3.tar.gz \- source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid\-src\-0.7.3.hash .ft P .fi .UNINDENT .UNINDENT .sp The following lines are all supported formats: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27 sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a /etc/resolv.conf ead48423703509d37c4a90e6a0d53e143b6fc268 .ft P .fi .UNINDENT .UNINDENT .sp Debian file type \fB*.dsc\fP files are also supported. .UNINDENT .sp \fBInserting the Source Hash in the SLS Data\fP .sp The source_hash can be specified as a simple checksum, like so: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C tomdroid\-src\-0.7.3.tar.gz: file.managed: \- name: /tmp/tomdroid\-src\-0.7.3.tar.gz \- source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid\-src\-0.7.3.tar.gz \- source_hash: 79eef25f9b0b2c642c62b7f737d4f53f .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Releases prior to 2016.11.0 must also include the hash type, like in the below example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tomdroid\-src\-0.7.3.tar.gz: file.managed: \- name: /tmp/tomdroid\-src\-0.7.3.tar.gz \- source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid\-src\-0.7.3.tar.gz \- source_hash: md5=79eef25f9b0b2c642c62b7f737d4f53f .ft P .fi .UNINDENT .UNINDENT .sp source_hash is ignored if the file hosted is not on a HTTP, HTTPS or FTP server. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Known issues: If the remote server URL has the hash file as an apparent sub\-directory of the source file, the module will discover that it has already cached a directory where a file should be cached. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C tomdroid\-src\-0.7.3.tar.gz: file.managed: \- name: /tmp/tomdroid\-src\-0.7.3.tar.gz \- source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid\-src\-0.7.3.tar.gz \- source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid\-src\-0.7.3.tar.gz/+md5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .TP .B source_hash_name When \fBsource_hash\fP refers to a hash file, Salt will try to find the correct hash by matching the filename/URI associated with that hash. By default, Salt will look for the filename being managed. When managing a file at path \fB/tmp/foo.txt\fP, then the following line in a hash file would match: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C acbd18db4cc2f85cedef654fccc4a4d8 foo.txt .ft P .fi .UNINDENT .UNINDENT .sp However, sometimes a hash file will include multiple similar paths: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C 37b51d194a7513e45b56f6524f2d51f2 ./dir1/foo.txt acbd18db4cc2f85cedef654fccc4a4d8 ./dir2/foo.txt 73feffa4b7f6bb68e44cf984c85f6e88 ./dir3/foo.txt .ft P .fi .UNINDENT .UNINDENT .sp In cases like this, Salt may match the incorrect hash. This argument can be used to tell Salt which filename to match, to ensure that the correct hash is identified. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /tmp/foo.txt: file.managed: \- source: https://mydomain.tld/dir2/foo.txt \- source_hash: https://mydomain.tld/hashes \- source_hash_name: ./dir2/foo.txt .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument must contain the full filename entry from the checksum file, as this argument is meant to disambiguate matches for multiple files that have the same basename. So, in the example above, simply using \fBfoo.txt\fP would not match. .UNINDENT .UNINDENT .sp New in version 2016.3.5. .TP .B keep_source Set to \fBFalse\fP to discard the cached copy of the source file once the state completes. This can be useful for larger files to keep them from taking up space in minion cache. However, keep in mind that discarding the source file might result in the state needing to re\-download the source file if the state is run again. If the source is not a local or \fBsalt://\fP one, the source hash is known, \fBskip_verify\fP is not true and the managed file exists with the correct hash and is not templated, this is not the case (i.e. remote downloads are avoided if the local hash matches the expected one). .sp New in version 2017.7.3. .TP .B user The user to own the file, this defaults to the user salt is running as on the minion .TP .B group The group ownership set for the file, this defaults to the group salt is running as on the minion. On Windows, this is ignored .TP .B mode The permissions to set on this file, e.g. \fB644\fP, \fB0775\fP, or \fB4664\fP\&. .sp The default mode for new files and directories corresponds to the umask of the salt process. The mode of existing files and directories will only be changed if \fBmode\fP is specified. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is \fBnot\fP supported on Windows. .UNINDENT .UNINDENT .sp Changed in version 2016.11.0: This option can be set to \fBkeep\fP, and Salt will keep the mode from the Salt fileserver. This is only supported when the \fBsource\fP URL begins with \fBsalt://\fP, or for files local to the minion. Because the \fBsource\fP option cannot be used with any of the \fBcontents\fP options, setting the \fBmode\fP to \fBkeep\fP is also incompatible with the \fBcontents\fP options. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 keep does not work with salt\-ssh. .sp As a consequence of how the files are transferred to the minion, and the inability to connect back to the master with salt\-ssh, salt is unable to stat the file as it exists on the fileserver and thus cannot mirror the mode on the salt\-ssh minion .UNINDENT .UNINDENT .TP .B attrs The attributes to have on this file, e.g. \fBa\fP, \fBi\fP\&. The attributes can be any or a combination of the following characters: \fBaAcCdDeijPsStTu\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is \fBnot\fP supported on Windows. .UNINDENT .UNINDENT .sp New in version 2018.3.0. .TP .B template If this setting is applied, the named templating engine will be used to render the downloaded file. The following templates are supported: .INDENT 7.0 .IP \(bu 2 \fI\%cheetah\fP .IP \(bu 2 \fI\%genshi\fP .IP \(bu 2 \fI\%jinja\fP .IP \(bu 2 \fI\%mako\fP .IP \(bu 2 \fI\%py\fP .IP \(bu 2 \fI\%wempy\fP .UNINDENT .TP .B makedirs If set to \fBTrue\fP, then the parent directories will be created to facilitate the creation of the named file. If \fBFalse\fP, and the parent directory of the destination file doesn\(aqt exist, the state will fail. .TP .B dir_mode If directories are to be created, passing this option specifies the permissions for those directories. If this is not set, directories will be assigned permissions by adding the execute bit to the mode of the files. .sp The default mode for new files and directories corresponds umask of salt process. For existing files and directories it\(aqs not enforced. .TP .B replace If set to \fBFalse\fP and the file already exists, the file will not be modified even if changes would otherwise be made. Permissions and ownership will still be enforced, however. .TP .B context Overrides default context variables passed to the template. .TP .B defaults Default context passed to the template. .TP .B backup Overrides the default backup mode for this specific file. See \fI\%backup_mode documentation\fP for more details. .TP .B show_changes Output a unified diff of the old file and the new file. If \fBFalse\fP return a boolean if any changes were made. .TP .B create If set to \fBFalse\fP, then the file will only be managed if the file already exists on the system. .TP .B contents Specify the contents of the file. Cannot be used in combination with \fBsource\fP\&. Ignores hashes and does not use a templating engine. .sp This value can be either a single string, a multiline YAML string or a list of strings. If a list of strings, then the strings will be joined together with newlines in the resulting file. For example, the below two example states would result in identical file contents: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /path/to/file1: file.managed: \- contents: \- This is line 1 \- This is line 2 /path/to/file2: file.managed: \- contents: | This is line 1 This is line 2 .ft P .fi .UNINDENT .UNINDENT .TP .B contents_pillar New in version 0.17.0. .sp Changed in version 2016.11.0: contents_pillar can also be a list, and the pillars will be concatenated together to form one file. .sp Operates like \fBcontents\fP, but draws from a value stored in pillar, using the pillar path syntax used in \fI\%pillar.get\fP\&. This is useful when the pillar value contains newlines, as referencing a pillar variable using a jinja/mako template can result in YAML formatting issues due to the newlines causing indentation mismatches. .sp For example, the following could be used to deploy an SSH private key: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /home/deployer/.ssh/id_rsa: file.managed: \- user: deployer \- group: deployer \- mode: 600 \- attrs: a \- contents_pillar: userdata:deployer:id_rsa .ft P .fi .UNINDENT .UNINDENT .sp This would populate \fB/home/deployer/.ssh/id_rsa\fP with the contents of \fBpillar[\(aquserdata\(aq][\(aqdeployer\(aq][\(aqid_rsa\(aq]\fP\&. An example of this pillar setup would be like so: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C userdata: deployer: id_rsa: | \-\-\-\-\-BEGIN RSA PRIVATE KEY\-\-\-\-\- MIIEowIBAAKCAQEAoQiwO3JhBquPAalQF9qP1lLZNXVjYMIswrMe2HcWUVBgh+vY U7sCwx/dH6+VvNwmCoqmNnP+8gTPKGl1vgAObJAnMT623dMXjVKwnEagZPRJIxDy B/HaAre9euNiY3LvIzBTWRSeMfT+rWvIKVBpvwlgGrfgz70m0pqxu+UyFbAGLin+ GpxzZAMaFpZw4sSbIlRuissXZj/sHpQb8p9M5IeO4Z3rjkCP1cxI \-\-\-\-\-END RSA PRIVATE KEY\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The private key above is shortened to keep the example brief, but shows how to do multiline string in YAML. The key is followed by a pipe character, and the multiline string is indented two more spaces. .sp To avoid the hassle of creating an indented multiline YAML string, the \fI\%file_tree external pillar\fP can be used instead. However, this will not work for binary files in Salt releases before 2015.8.4. .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For information on using Salt Slots and how to incorporate execution module returns into file content or data, refer to the \fI\%Salt Slots documentation\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B contents_grains New in version 2014.7.0. .sp Operates like \fBcontents\fP, but draws from a value stored in grains, using the grains path syntax used in \fI\%grains.get\fP\&. This functionality works similarly to \fBcontents_pillar\fP, but with grains. .sp For example, the following could be used to deploy a \(dqmessage of the day\(dq file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C write_motd: file.managed: \- name: /etc/motd \- contents_grains: motd .ft P .fi .UNINDENT .UNINDENT .sp This would populate \fB/etc/motd\fP file with the contents of the \fBmotd\fP grain. The \fBmotd\fP grain is not a default grain, and would need to be set prior to running the state: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.set motd \(aqWelcome! This system is managed by Salt.\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B contents_newline New in version 2014.7.0. .sp Changed in version 2015.8.4: This option is now ignored if the contents being deployed contain binary data. .sp If \fBTrue\fP, files managed using \fBcontents\fP, \fBcontents_pillar\fP, or \fBcontents_grains\fP will have a newline added to the end of the file if one is not present. Setting this option to \fBFalse\fP will ensure the final line, or entry, does not contain a new line. If the last line, or entry in the file does contain a new line already, this option will not remove it. .TP .B contents_delimiter New in version 2015.8.4. .sp Can be used to specify an alternate delimiter for \fBcontents_pillar\fP or \fBcontents_grains\fP\&. This delimiter will be passed through to \fI\%pillar.get\fP or \fI\%grains.get\fP when retrieving the contents. .TP .B encoding If specified, then the specified encoding will be used. Otherwise, the file will be encoded using the system locale (usually UTF\-8). See \fI\%https://docs.python.org/3/library/codecs.html#standard\-encodings\fP for the list of available encodings. .sp New in version 2017.7.0. .TP .B encoding_errors Error encoding scheme. Default is \fB\(ga\(aqstrict\(aq\(ga\fP\&. See \fI\%https://docs.python.org/2/library/codecs.html#codec\-base\-classes\fP for the list of available schemes. .sp New in version 2017.7.0. .TP .B allow_empty New in version 2015.8.4. .sp If set to \fBFalse\fP, then the state will fail if the contents specified by \fBcontents_pillar\fP or \fBcontents_grains\fP are empty. .TP .B follow_symlinks New in version 2014.7.0. .sp If the desired path is a symlink follow it and make changes to the file to which the symlink points. .TP .B check_cmd New in version 2014.7.0. .sp The specified command will be run with an appended argument of a \fItemporary\fP file containing the new managed contents. If the command exits with a zero status the new managed contents will be written to the managed destination. If the command exits with a nonzero exit code, the state will fail and no changes will be made to the file. .sp For example, the following could be used to verify sudoers before making changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/sudoers: file.managed: \- user: root \- group: root \- mode: 0440 \- attrs: i \- source: salt://sudoers/files/sudoers.jinja \- template: jinja \- check_cmd: /usr/sbin/visudo \-c \-f .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE\fP: This \fBcheck_cmd\fP functions differently than the requisite \fBcheck_cmd\fP\&. .TP .B tmp_dir Directory for temp file created by \fBcheck_cmd\fP\&. Useful for checkers dependent on config file location (e.g. daemons restricted to their own config directories by an apparmor profile). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/dhcp/dhcpd.conf: file.managed: \- user: root \- group: root \- mode: 0755 \- tmp_dir: \(aq/etc/dhcp\(aq \- contents: \(dq# Managed by Salt\(dq \- check_cmd: dhcpd \-t \-cf .ft P .fi .UNINDENT .UNINDENT .TP .B tmp_ext Suffix for temp file created by \fBcheck_cmd\fP\&. Useful for checkers dependent on config file extension (e.g. the init\-checkconf upstart config checker). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/init/test.conf: file.managed: \- user: root \- group: root \- mode: 0440 \- tmp_ext: \(aq.conf\(aq \- contents: \- \(aqdescription \(dqSalt Minion\(dq\(aq \- \(aqstart on started mountall\(aq \- \(aqstop on shutdown\(aq \- \(aqrespawn\(aq \- \(aqexec salt\-minion\(aq \- check_cmd: init\-checkconf \-f .ft P .fi .UNINDENT .UNINDENT .TP .B skip_verify If \fBTrue\fP, hash verification of remote file sources (\fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP) will be skipped, and the \fBsource_hash\fP argument will be ignored. .sp New in version 2016.3.0. .TP .B selinux Allows setting the selinux user, role, type, and range of a managed file .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /tmp/selinux.test file.managed: \- user: root \- selinux: seuser: system_u serole: object_r setype: system_conf_t serange: s0 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3000. .TP .B win_owner The owner of the directory. If this is not passed, user will be used. If user is not passed, the account under which Salt is running will be used. .sp New in version 2017.7.0. .TP .B win_perms A dictionary containing permissions to grant and their propagation. For example: \fB{\(aqAdministrators\(aq: {\(aqperms\(aq: \(aqfull_control\(aq}}\fP Can be a single basic perm or a list of advanced perms. \fBperms\fP must be specified. \fBapplies_to\fP does not apply to file objects. .sp New in version 2017.7.0. .TP .B win_deny_perms A dictionary containing permissions to deny and their propagation. For example: \fB{\(aqAdministrators\(aq: {\(aqperms\(aq: \(aqfull_control\(aq}}\fP Can be a single basic perm or a list of advanced perms. \fBperms\fP must be specified. \fBapplies_to\fP does not apply to file objects. .sp New in version 2017.7.0. .TP .B win_inheritance True to inherit permissions from the parent directory, False not to inherit permission. .sp New in version 2017.7.0. .TP .B win_perms_reset If \fBTrue\fP the existing DACL will be cleared and replaced with the settings defined in this function. If \fBFalse\fP, new entries will be appended to the existing DACL. Default is \fBFalse\fP\&. .sp New in version 2018.3.0. .UNINDENT .sp Here\(aqs an example using the above \fBwin_*\fP parameters: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C create_config_file: file.managed: \- name: C:\econfig\esettings.cfg \- source: salt://settings.cfg \- win_owner: Administrators \- win_perms: # Basic Permissions dev_ops: perms: full_control # List of advanced permissions appuser: perms: \- read_attributes \- read_ea \- create_folders \- read_permissions joe_snuffy: perms: read \- win_deny_perms: fred_snuffy: perms: full_control \- win_inheritance: False .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B verify_ssl If \fBFalse\fP, remote https file sources (\fBhttps://\fP) and source_hash will not attempt to validate the servers certificate. Default is True. .sp New in version 3002. .TP .B use_etag If \fBTrue\fP, remote http/https file sources will attempt to use the ETag header to determine if the remote file needs to be downloaded. This provides a lightweight mechanism for promptly refreshing files changed on a web server without requiring a full hash comparison via the \fBsource_hash\fP parameter. .sp New in version 3005. .TP .B signature Ensure a valid GPG signature exists on the selected \fBsource\fP file. Set this to true for inline signatures, or to a file URI retrievable by \fI:py:func:\(gacp.cache_file <salt.modules.cp.cache_file>\fP for a detached one. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A signature is only enforced directly after caching the file, before it is moved to its final destination. Existing target files (with the correct checksum) will neither be checked nor deleted. .sp It will be enforced regardless of source type and will be required on the final output, therefore this does not lend itself well when templates are rendered. The file will not be modified, meaning inline signatures are not removed. .UNINDENT .UNINDENT .sp New in version 3007.0. .TP .B source_hash_sig When \fBsource\fP is a remote file source, \fBsource_hash\fP is a file, \fBskip_verify\fP is not true and \fBuse_etag\fP is not true, ensure a valid GPG signature exists on the source hash file. Set this to \fBtrue\fP for an inline (clearsigned) signature, or to a file URI retrievable by \fI:py:func:\(gacp.cache_file <salt.modules.cp.cache_file>\fP for a detached one. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A signature on the \fBsource_hash\fP file is enforced regardless of changes since its contents are used to check if an existing file is in the correct state \- but only for remote sources! As for \fBsignature\fP, existing target files will not be modified, only the cached source_hash and source_hash_sig files will be removed. .UNINDENT .UNINDENT .sp New in version 3007.0. .TP .B signed_by_any When verifying signatures either on the managed file or its source hash file, require at least one valid signature from one of a list of key fingerprints. This is passed to \fI\%gpg.verify\fP\&. .sp New in version 3007.0. .TP .B signed_by_all When verifying signatures either on the managed file or its source hash file, require a valid signature from each of the key fingerprints in this list. This is passed to \fI\%gpg.verify\fP\&. .sp New in version 3007.0. .TP .B keyring When verifying signatures, use this keyring. .sp New in version 3007.0. .TP .B gnupghome When verifying signatures, use this GnuPG home. .sp New in version 3007.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.missing(name, **kwargs) Verify that the named file or directory is missing, this returns True only if the named file is missing but does not remove the file if it is present. .INDENT 7.0 .TP .B name Absolute path which must NOT exist .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.mknod(name, ntype, major=0, minor=0, user=None, group=None, mode=\(aq0600\(aq) Create a special file similar to the \(aqnix mknod command. The supported device types are \fBp\fP (fifo pipe), \fBc\fP (character device), and \fBb\fP (block device). Provide the major and minor numbers when specifying a character device or block device. A fifo pipe does not require this information. The command will create the necessary dirs if needed. If a file of the same name not of the same type/major/minor exists, it will not be overwritten or unlinked (deleted). This is logically in place as a safety measure because you can really shoot yourself in the foot here and it is the behavior of \(aqnix \fBmknod\fP\&. It is also important to note that not just anyone can create special devices. Usually this is only done as root. If the state is executed as none other than root on a minion, you may receive a permission error. .INDENT 7.0 .TP .B name name of the file .TP .B ntype node type \(aqp\(aq (fifo pipe), \(aqc\(aq (character device), or \(aqb\(aq (block device) .TP .B major major number of the device does not apply to a fifo pipe .TP .B minor minor number of the device does not apply to a fifo pipe .TP .B user owning user of the device/pipe .TP .B group owning group of the device/pipe .TP .B mode permissions on the device/pipe .UNINDENT .sp Usage: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /dev/chr: file.mknod: \- ntype: c \- major: 180 \- minor: 31 \- user: root \- group: root \- mode: 660 /dev/blk: file.mknod: \- ntype: b \- major: 8 \- minor: 999 \- user: root \- group: root \- mode: 660 /dev/fifo: file.mknod: \- ntype: p \- user: root \- group: root \- mode: 660 .ft P .fi .UNINDENT .UNINDENT .sp New in version 0.17.0. .UNINDENT .INDENT 0.0 .TP .B salt.states.file.mod_beacon(name, **kwargs) Create a beacon to monitor a file based on a beacon state argument. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBbeacon\fP state argument for supported state functions. It should not be called directly. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.mod_run_check_cmd(cmd, filename, **check_cmd_opts) Execute the check_cmd logic. .sp Return True if \fBcheck_cmd\fP succeeds (check_cmd == 0) otherwise return a result dict .UNINDENT .INDENT 0.0 .TP .B salt.states.file.not_cached(name, saltenv=\(aqbase\(aq) New in version 2017.7.3. .sp Ensures that a file is not present in the minion\(aqs cache, deleting it if found. This state is primarily invoked by other states to ensure that a fresh copy is fetched. .INDENT 7.0 .TP .B name The URL of the file to be removed from cache. To remove a file from cache in an environment other than \fBbase\fP, either use the \fBsaltenv\fP argument or include the saltenv in the URL (e.g. \fBsalt://path/to/file.conf?saltenv=dev\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A list of URLs is not supported, this must be a single URL. If a local file is passed here, the state will take no action. .UNINDENT .UNINDENT .TP .B saltenv Used to specify the environment from which to download a file from the Salt fileserver (i.e. those with \fBsalt://\fP URL). .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.patch(name, source=None, source_hash=None, source_hash_name=None, skip_verify=False, template=None, context=None, defaults=None, options=\(aq\(aq, reject_file=None, strip=None, saltenv=None, **kwargs) Ensure that a patch has been applied to the specified file or directory .sp Changed in version 2019.2.0: The \fBhash\fP and \fBdry_run_first\fP options are now ignored, as the logic which determines whether or not the patch has already been applied no longer requires them. Additionally, this state now supports patch files that modify more than one file. To use these sort of patches, specify a directory (and, if necessary, the \fBstrip\fP option) instead of a file. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A suitable \fBpatch\fP executable must be available on the minion. Also, keep in mind that the pre\-check this state does to determine whether or not changes need to be made will create a temp file and send all patch output to that file. This means that, in the event that the patch would not have applied cleanly, the comment included in the state results will reference a temp file that will no longer exist once the state finishes running. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The file or directory to which the patch should be applied .TP .B source The patch file to apply .sp Changed in version 2019.2.0: The source can now be from any file source supported by Salt (\fBsalt://\fP, \fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP, etc.). Templating is also now supported. .TP .B source_hash Works the same way as in \fI\%file.managed\fP\&. .sp New in version 2019.2.0. .TP .B source_hash_name Works the same way as in \fI\%file.managed\fP .sp New in version 2019.2.0. .TP .B skip_verify Works the same way as in \fI\%file.managed\fP .sp New in version 2019.2.0. .TP .B template Works the same way as in \fI\%file.managed\fP .sp New in version 2019.2.0. .TP .B context Works the same way as in \fI\%file.managed\fP .sp New in version 2019.2.0. .TP .B defaults Works the same way as in \fI\%file.managed\fP .sp New in version 2019.2.0. .TP .B options Extra options to pass to patch. This should not be necessary in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For best results, short opts should be separate from one another. The \fB\-N\fP and \fB\-r\fP, and \fB\-o\fP options are used internally by this state and cannot be used here. Additionally, instead of using \fB\-pN\fP or \fB\-\-strip=N\fP, use the \fBstrip\fP option documented below. .UNINDENT .UNINDENT .TP .B reject_file If specified, any rejected hunks will be written to this file. If not specified, then they will be written to a temp file which will be deleted when the state finishes running. .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 The parent directory must exist. Also, this will overwrite the file if it is already present. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B strip Number of directories to strip from paths in the patch file. For example, using the below SLS would instruct Salt to use \fB\-p1\fP when applying the patch: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/myfile.conf: file.patch: \- source: salt://myfile.patch \- strip: 1 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2019.2.0: In previous versions, \fB\-p1\fP would need to be passed as part of the \fBoptions\fP value. .TP .B saltenv Specify the environment from which to retrieve the patch file indicated by the \fBsource\fP parameter. If not provided, this defaults to the environment from which the state is being executed. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Ignored when the patch file is from a non\-\fBsalt://\fP source. .UNINDENT .UNINDENT .UNINDENT .sp \fBUsage:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Equivalent to \(ga\(gapatch \-\-forward /opt/myfile.txt myfile.patch\(ga\(ga /opt/myfile.txt: file.patch: \- source: salt://myfile.patch .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.prepend(name, text=None, makedirs=False, source=None, source_hash=None, template=\(aqjinja\(aq, sources=None, source_hashes=None, defaults=None, context=None, header=None) Ensure that some text appears at the beginning of a file .sp The text will not be prepended again if it already exists in the file. You may specify a single line of text or a list of lines to append. .INDENT 7.0 .TP .B name The location of the file to prepend to. .TP .B text The text to be prepended, which can be a single string or a list of strings. .TP .B makedirs If the file is located in a path without a parent directory, then the state will fail. If makedirs is set to True, then the parent directories will be created to facilitate the creation of the named file. Defaults to False. .TP .B source A single source file to prepend. This source file can be hosted on either the salt master server, or on an HTTP or FTP server. Both HTTPS and HTTP are supported as well as downloading directly from Amazon S3 compatible URLs with both pre\-configured and automatic IAM credentials (see s3.get state documentation). File retrieval from Openstack Swift object storage is supported via swift://container/object_path URLs (see swift.get documentation). .sp For files hosted on the salt file server, if the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs. .sp If the file is hosted on an HTTP or FTP server, the source_hash argument is also required. .TP .B source_hash .INDENT 7.0 .TP .B This can be one of the following: .INDENT 7.0 .IP 1. 3 a source hash string .IP 2. 3 the URI of a file that contains source hash strings .UNINDENT .UNINDENT .sp The function accepts the first encountered long unbroken alphanumeric string of correct length as a valid hash, in order from most secure to least secure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Type Length ====== ====== sha512 128 sha384 96 sha256 64 sha224 56 sha1 40 md5 32 .ft P .fi .UNINDENT .UNINDENT .sp See the \fBsource_hash\fP parameter description for \fI\%file.managed\fP function for more details and examples. .TP .B template The named templating engine will be used to render the source file(s). Defaults to \fBjinja\fP\&. The following templates are supported: .INDENT 7.0 .IP \(bu 2 \fI\%cheetah\fP .IP \(bu 2 \fI\%genshi\fP .IP \(bu 2 \fI\%jinja\fP .IP \(bu 2 \fI\%mako\fP .IP \(bu 2 \fI\%py\fP .IP \(bu 2 \fI\%wempy\fP .UNINDENT .TP .B sources A list of source files to prepend. If the files are hosted on an HTTP or FTP server, the source_hashes argument is also required. .TP .B source_hashes A list of source_hashes corresponding to the sources list specified in the sources argument. .TP .B defaults Default context passed to the template. .TP .B context Overrides default context variables passed to the template. .TP .B ignore_whitespace New in version 2015.8.4. .sp Spaces and Tabs in text are ignored by default, when searching for the appending content, one space or multiple tabs are the same for salt. Set this option to \fBFalse\fP if you want to change this behavior. .TP .B header Forces the text to be prepended. If it exists in the file but not at the beginning, then it prepends a duplicate. .UNINDENT .sp Multi\-line example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/motd: file.prepend: \- text: | Thou hadst better eat salt with the Philosophers of Greece, than sugar with the Courtiers of Italy. \- Benjamin Franklin .ft P .fi .UNINDENT .UNINDENT .sp Multiple lines of text: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/motd: file.prepend: \- text: \- Trust no one unless you have eaten much salt with him. \- \(dqSalt is born of the purest of parents: the sun and the sea.\(dq .ft P .fi .UNINDENT .UNINDENT .sp Optionally, require the text to appear exactly as specified (order and position). Combine with multi\-line or multiple lines of input. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/motd: file.prepend: \- header: True \- text: \- This will be the very first line in the file. \- The 2nd line, regardless of duplicates elsewhere in the file. \- These will be written anew if they do not appear verbatim. .ft P .fi .UNINDENT .UNINDENT .sp Gather text from multiple template files: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/motd: file: \- prepend \- template: jinja \- sources: \- salt://motd/devops\-messages.tmpl \- salt://motd/hr\-messages.tmpl \- salt://motd/general\-messages.tmpl .ft P .fi .UNINDENT .UNINDENT .sp New in version 2014.7.0. .UNINDENT .INDENT 0.0 .TP .B salt.states.file.pruned(name, recurse=False, ignore_errors=False, older_than=None) New in version 3006.0. .sp Ensure that the named directory is absent. If it exists and is empty, it will be deleted. An entire directory tree can be pruned of empty directories as well, by using the \fBrecurse\fP option. .INDENT 7.0 .TP .B name The directory which should be deleted if empty. .TP .B recurse If set to \fBTrue\fP, this option will recursive deletion of empty directories. This is useful if nested paths are all empty, and would be the only items preventing removal of the named root directory. .TP .B ignore_errors If set to \fBTrue\fP, any errors encountered while attempting to delete a directory are ignored. This \fBAUTOMATICALLY ENABLES\fP the \fBrecurse\fP option since it\(aqs not terribly useful to ignore errors on the removal of a single directory. Useful for pruning only the empty directories in a tree which contains non\-empty directories as well. .TP .B older_than When \fBolder_than\fP is set to a number, it is used to determine the \fBnumber of days\fP which must have passed since the last modification timestamp before a directory will be allowed to be removed. Setting the value to 0 is equivalent to leaving it at the default of \fBNone\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.recurse(name, source, keep_source=True, clean=False, require=None, user=None, group=None, dir_mode=None, file_mode=None, sym_mode=None, template=None, context=None, replace=True, defaults=None, include_empty=False, backup=\(aq\(aq, include_pat=None, exclude_pat=None, maxdepth=None, keep_symlinks=False, force_symlinks=False, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=True, **kwargs) Recurse through a subdirectory on the master and copy said subdirectory over to the specified path. .INDENT 7.0 .TP .B name The directory to set the recursion in .TP .B source The source directory, this directory is located on the salt master file server and is specified with the salt:// protocol. If the directory is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs .TP .B keep_source Set to \fBFalse\fP to discard the cached copy of the source file once the state completes. This can be useful for larger files to keep them from taking up space in minion cache. However, keep in mind that discarding the source file will result in the state needing to re\-download the source file if the state is run again. .sp New in version 2017.7.3. .TP .B clean Make sure that only files that are set up by salt and required by this function are kept. If this option is set then everything in this directory will be deleted unless it is required. .TP .B require Require other resources such as packages or files .TP .B user The user to own the directory. This defaults to the user salt is running as on the minion .TP .B group The group ownership set for the directory. This defaults to the group salt is running as on the minion. On Windows, this is ignored .TP .B dir_mode The permissions mode to set on any directories created. .sp The default mode for new files and directories corresponds umask of salt process. For existing files and directories it\(aqs not enforced. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is \fBnot\fP supported on Windows. .UNINDENT .UNINDENT .TP .B file_mode The permissions mode to set on any files created. .sp The default mode for new files and directories corresponds umask of salt process. For existing files and directories it\(aqs not enforced. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is \fBnot\fP supported on Windows. .UNINDENT .UNINDENT .sp Changed in version 2016.11.0: This option can be set to \fBkeep\fP, and Salt will keep the mode from the Salt fileserver. This is only supported when the \fBsource\fP URL begins with \fBsalt://\fP, or for files local to the minion. Because the \fBsource\fP option cannot be used with any of the \fBcontents\fP options, setting the \fBmode\fP to \fBkeep\fP is also incompatible with the \fBcontents\fP options. .TP .B sym_mode The permissions mode to set on any symlink created. .sp The default mode for new files and directories corresponds umask of salt process. For existing files and directories it\(aqs not enforced. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is \fBnot\fP supported on Windows. .UNINDENT .UNINDENT .TP .B template If this setting is applied, the named templating engine will be used to render the downloaded file. The following templates are supported: .INDENT 7.0 .IP \(bu 2 \fI\%cheetah\fP .IP \(bu 2 \fI\%genshi\fP .IP \(bu 2 \fI\%jinja\fP .IP \(bu 2 \fI\%mako\fP .IP \(bu 2 \fI\%py\fP .IP \(bu 2 \fI\%wempy\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The template option is required when recursively applying templates. .UNINDENT .UNINDENT .TP .B replace If set to \fBFalse\fP and the file already exists, the file will not be modified even if changes would otherwise be made. Permissions and ownership will still be enforced, however. .TP .B context Overrides default context variables passed to the template. .TP .B defaults Default context passed to the template. .TP .B include_empty Set this to True if empty directories should also be created (default is False) .TP .B backup Overrides the default backup mode for all replaced files. See \fI\%backup_mode documentation\fP for more details. .TP .B include_pat When copying, include only this pattern, or list of patterns, from the source. Default is glob match; if prefixed with \(aqE@\(aq, then regexp match. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- include_pat: hello* :: glob matches \(aqhello01\(aq, \(aqhello02\(aq ... but not \(aqotherhello\(aq \- include_pat: E@hello :: regexp matches \(aqotherhello\(aq, \(aqhello01\(aq ... .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3001: List patterns are now supported .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- include_pat: \- hello01 \- hello02 .ft P .fi .UNINDENT .UNINDENT .TP .B exclude_pat Exclude this pattern, or list of patterns, from the source when copying. If both \fIinclude_pat\fP and \fIexclude_pat\fP are supplied, then it will apply conditions cumulatively. i.e. first select based on include_pat, and then within that result apply exclude_pat. .sp Also, when \(aqclean=True\(aq, exclude this pattern from the removal list and preserve in the destination. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- exclude_pat: APPDATA* :: glob matches APPDATA.01, APPDATA.02,.. for exclusion \- exclude_pat: E@(APPDATA)|(TEMPDATA) :: regexp matches APPDATA or TEMPDATA for exclusion .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3001: List patterns are now supported .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- exclude_pat: \- APPDATA.01 \- APPDATA.02 .ft P .fi .UNINDENT .UNINDENT .TP .B maxdepth When copying, only copy paths which are of depth \fImaxdepth\fP from the source path. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- maxdepth: 0 :: Only include files located in the source directory \- maxdepth: 1 :: Only include files located in the source or immediate subdirectories .ft P .fi .UNINDENT .UNINDENT .TP .B keep_symlinks Keep symlinks when copying from the source. This option will cause the copy operation to terminate at the symlink. If desire behavior similar to rsync, then set this to True. This option is not taken in account if \fBfileserver_followsymlinks\fP is set to False. .TP .B force_symlinks Force symlink creation. This option will force the symlink creation. If a file or directory is obstructing symlink creation it will be recursively removed so that symlink creation can proceed. This option is usually not needed except in special circumstances. This option is not taken in account if \fBfileserver_followsymlinks\fP is set to False. .TP .B win_owner The owner of the symlink and directories if \fBmakedirs\fP is True. If this is not passed, \fBuser\fP will be used. If \fBuser\fP is not passed, the account under which Salt is running will be used. .sp New in version 2017.7.7. .TP .B win_perms A dictionary containing permissions to grant .sp New in version 2017.7.7. .TP .B win_deny_perms A dictionary containing permissions to deny .sp New in version 2017.7.7. .TP .B win_inheritance True to inherit permissions from parent, otherwise False .sp New in version 2017.7.7. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.rename(name, source, force=False, makedirs=False, **kwargs) If the source file exists on the system, rename it to the named file. The named file will not be overwritten if it already exists unless the force option is set to True. .INDENT 7.0 .TP .B name The location of the file to rename to .TP .B source The location of the file to move to the location specified with name .TP .B force If the target location is present then the file will not be moved, specify \(dqforce: True\(dq to overwrite the target file .TP .B makedirs If the target subdirectories don\(aqt exist create them .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.replace(name, pattern, repl, count=0, flags=8, bufsize=1, append_if_not_found=False, prepend_if_not_found=False, not_found_content=None, backup=\(aq.bak\(aq, show_changes=True, ignore_if_missing=False, backslash_literal=False) Maintain an edit in a file. .sp New in version 0.17.0. .INDENT 7.0 .TP .B name Filesystem path to the file to be edited. If a symlink is specified, it will be resolved to its target. .TP .B pattern A regular expression, to be matched using Python\(aqs \fI\%re.search()\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you need to match a literal string that contains regex special characters, you may want to use salt\(aqs custom Jinja filter, \fBregex_escape\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqhttp://example.com?foo=bar%20baz\(aq | regex_escape }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B repl The replacement text .TP .B count Maximum number of pattern occurrences to be replaced. Defaults to 0. If count is a positive integer n, no more than n occurrences will be replaced, otherwise all occurrences will be replaced. .TP .B flags A list of flags defined in the \fBre\fP module documentation from the Python standard library. Each list item should be a string that will correlate to the human\-friendly flag name. E.g., \fB[\(aqIGNORECASE\(aq, \(aqMULTILINE\(aq]\fP\&. Optionally, \fBflags\fP may be an int, with a value corresponding to the XOR (\fB|\fP) of all the desired flags. Defaults to \fB8\fP (which equates to \fB[\(aqMULTILINE\(aq]\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBfile.replace\fP reads the entire file as a string to support multiline regex patterns. Therefore, when using anchors such as \fB^\fP or \fB$\fP in the pattern, those anchors may be relative to the line OR relative to the file. The default for \fBfile.replace\fP is to treat anchors as relative to the line, which is implemented by setting the default value of \fBflags\fP to \fB[\(aqMULTILINE\(aq]\fP\&. When overriding the default value for \fBflags\fP, if \fB\(aqMULTILINE\(aq\fP is not present then anchors will be relative to the file. If the desired behavior is for anchors to be relative to the line, then simply add \fB\(aqMULTILINE\(aq\fP to the list of flags. .UNINDENT .UNINDENT .TP .B bufsize How much of the file to buffer into memory at once. The default value \fB1\fP processes one line at a time. The special value \fBfile\fP may be specified which will read the entire file into memory before processing. .TP .B append_if_not_found If set to \fBTrue\fP, and pattern is not found, then the content will be appended to the file. .sp New in version 2014.7.0. .TP .B prepend_if_not_found If set to \fBTrue\fP and pattern is not found, then the content will be prepended to the file. .sp New in version 2014.7.0. .TP .B not_found_content Content to use for append/prepend if not found. If \fBNone\fP (default), uses \fBrepl\fP\&. Useful when \fBrepl\fP uses references to group in pattern. .sp New in version 2014.7.0. .TP .B backup The file extension to use for a backup of the file before editing. Set to \fBFalse\fP to skip making a backup. .TP .B show_changes Output a unified diff of the old file and the new file. If \fBFalse\fP return a boolean if any changes were made. Returns a boolean or a string. .TP .B ignore_if_missing New in version 2016.3.4. .sp Controls what to do if the file is missing. If set to \fBFalse\fP, the state will display an error raised by the execution module. If set to \fBTrue\fP, the state will simply report no changes. .TP .B backslash_literal New in version 2016.11.7. .sp Interpret backslashes as literal backslashes for the repl and not escape characters. This will help when using append/prepend so that the backslashes are not interpreted for the repl on the second run of the state. .UNINDENT .sp For complex regex patterns, it can be useful to avoid the need for complex quoting and escape sequences by making use of YAML\(aqs multiline string syntax. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C complex_search_and_replace: file.replace: # <...snip...> \- pattern: | CentOS \e(2.6.32[^\e\en]+\e\en\es+root[^\e\en]+\e\en\e)+ .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When using YAML multiline string syntax in \fBpattern:\fP, make sure to also use that syntax in the \fBrepl:\fP part, or you might loose line feeds. .UNINDENT .UNINDENT .sp When regex capture groups are used in \fBpattern:\fP, their captured value is available for reuse in the \fBrepl:\fP part as a backreference (ex. \fB\e1\fP). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C add_login_group_to_winbind_ssh_access_list: file.replace: \- name: \(aq/etc/security/pam_winbind.conf\(aq \- pattern: \(aq^(require_membership_of = )(.*)$\(aq \- repl: \(aq\e1\e2,append\-new\-group\-to\-line\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fBfile.replace\fP state uses Python\(aqs \fBre\fP module. For more advanced options, see \fI\%https://docs.python.org/2/library/re.html\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.retention_schedule(name, retain, strptime_format=None, timezone=None) Apply retention scheduling to backup storage directory. .sp New in version 2016.11.0. .sp Changed in version 3006.0. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The filesystem path to the directory containing backups to be managed. .IP \(bu 2 \fBretain\fP \-\- .sp Delete the backups, except for the ones we want to keep. The N below should be an integer but may also be the special value of \fBall\fP, which keeps all files matching the criteria. All of the retain options default to None, which means to not keep files based on this criteria. .INDENT 2.0 .TP .B most_recent N Keep the most recent N files. .TP .B first_of_hour N For the last N hours from now, keep the first file after the hour. .TP .B first_of_day N For the last N days from now, keep the first file after midnight. See also \fBtimezone\fP\&. .TP .B first_of_week N For the last N weeks from now, keep the first file after Sunday midnight. .TP .B first_of_month N For the last N months from now, keep the first file after the start of the month. .TP .B first_of_year N For the last N years from now, keep the first file after the start of the year. .UNINDENT .IP \(bu 2 \fBstrptime_format\fP \-\- A python strptime format string used to first match the filenames of backups and then parse the filename to determine the datetime of the file. \fI\%https://docs.python.org/2/library/datetime.html#datetime.datetime.strptime\fP Defaults to None, which considers all files in the directory to be backups eligible for deletion and uses \fBos.path.getmtime()\fP to determine the datetime. .IP \(bu 2 \fBtimezone\fP \-\- The timezone to use when determining midnight. This is only used when datetime is pulled from \fBos.path.getmtime()\fP\&. Defaults to \fBNone\fP which uses the timezone from the locale. .UNINDENT .UNINDENT .sp Usage example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /var/backups/example_directory: file.retention_schedule: \- retain: most_recent: 5 first_of_hour: 4 first_of_day: 7 first_of_week: 6 # NotImplemented yet. first_of_month: 6 first_of_year: all \- strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2 \- timezone: None .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.serialize(name, dataset=None, dataset_pillar=None, user=None, group=None, mode=None, backup=\(aq\(aq, makedirs=False, show_changes=True, create=True, merge_if_exists=False, encoding=None, encoding_errors=\(aqstrict\(aq, serializer=None, serializer_opts=None, deserializer_opts=None, check_cmd=None, tmp_dir=\(aq\(aq, tmp_ext=\(aq\(aq, **kwargs) Serializes dataset and store it into managed file. Useful for sharing simple configuration files. .INDENT 7.0 .TP .B name The location of the file to create .TP .B dataset The dataset that will be serialized .TP .B dataset_pillar Operates like \fBdataset\fP, but draws from a value stored in pillar, using the pillar path syntax used in \fI\%pillar.get\fP\&. This is useful when the pillar value contains newlines, as referencing a pillar variable using a jinja/mako template can result in YAML formatting issues due to the newlines causing indentation mismatches. .sp New in version 2015.8.0. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For information on using Salt Slots and how to incorporate execution module returns into file content or data, refer to the \fI\%Salt Slots documentation\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B serializer (or formatter) Write the data as this format. See the list of \fI\%serializer modules\fP for supported output formats. .sp Changed in version 3002: \fBserializer\fP argument added as an alternative to \fBformatter\fP\&. Both are accepted, but using both will result in an error. .TP .B encoding If specified, then the specified encoding will be used. Otherwise, the file will be encoded using the system locale (usually UTF\-8). See \fI\%https://docs.python.org/3/library/codecs.html#standard\-encodings\fP for the list of available encodings. .sp New in version 2017.7.0. .TP .B encoding_errors Error encoding scheme. Default is \fB\(ga\(aqstrict\(aq\(ga\fP\&. See \fI\%https://docs.python.org/2/library/codecs.html#codec\-base\-classes\fP for the list of available schemes. .sp New in version 2017.7.0. .TP .B user The user to own the directory, this defaults to the user salt is running as on the minion .TP .B group The group ownership set for the directory, this defaults to the group salt is running as on the minion .TP .B mode The permissions to set on this file, e.g. \fB644\fP, \fB0775\fP, or \fB4664\fP\&. .sp The default mode for new files and directories corresponds umask of salt process. For existing files and directories it\(aqs not enforced. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is \fBnot\fP supported on Windows. .UNINDENT .UNINDENT .TP .B backup Overrides the default backup mode for this specific file. .TP .B makedirs Create parent directories for destination file. .sp New in version 2014.1.3. .TP .B show_changes Output a unified diff of the old file and the new file. If \fBFalse\fP return a boolean if any changes were made. .TP .B create Default is True, if create is set to False then the file will only be managed if the file already exists on the system. .TP .B merge_if_exists Default is False, if merge_if_exists is True then the existing file will be parsed and the dataset passed in will be merged with the existing content .sp New in version 2014.7.0. .TP .B serializer_opts Pass through options to serializer. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/dummy/package.yaml file.serialize: \- serializer: yaml \- serializer_opts: \- explicit_start: True \- default_flow_style: True \- indent: 4 .ft P .fi .UNINDENT .UNINDENT .sp The valid opts are the additional opts (i.e. not the data being serialized) for the function used to serialize the data. Documentation for the these functions can be found in the list below: .INDENT 7.0 .IP \(bu 2 For \fByaml\fP: \fI\%yaml.dump()\fP .IP \(bu 2 For \fBjson\fP: \fI\%json.dumps()\fP .IP \(bu 2 For \fBpython\fP: \fI\%pprint.pformat()\fP .IP \(bu 2 For \fBmsgpack\fP: Run \fBpython \-c \(aqimport msgpack; help(msgpack.Packer)\(aq\fP to see the available options (\fBencoding\fP, \fBunicode_errors\fP, etc.) .UNINDENT .TP .B deserializer_opts Like \fBserializer_opts\fP above, but only used when merging with an existing file (i.e. when \fBmerge_if_exists\fP is set to \fBTrue\fP). .sp The options specified here will be passed to the deserializer to load the existing data, before merging with the specified data and re\-serializing. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/dummy/package.yaml file.serialize: \- serializer: yaml \- serializer_opts: \- explicit_start: True \- default_flow_style: True \- indent: 4 \- deserializer_opts: \- encoding: latin\-1 \- merge_if_exists: True .ft P .fi .UNINDENT .UNINDENT .sp The valid opts are the additional opts (i.e. not the data being deserialized) for the function used to deserialize the data. Documentation for the these functions can be found in the list below: .INDENT 7.0 .IP \(bu 2 For \fByaml\fP: \fI\%yaml.load()\fP .IP \(bu 2 For \fBjson\fP: \fI\%json.loads()\fP .UNINDENT .sp However, note that not all arguments are supported. For example, when deserializing JSON, arguments like \fBparse_float\fP and \fBparse_int\fP which accept a callable object cannot be handled in an SLS file. .sp New in version 2019.2.0. .TP .B check_cmd The specified command will be run with an appended argument of a \fItemporary\fP file containing the new file contents. If the command exits with a zero status the new file contents will be written to the state output destination. If the command exits with a nonzero exit code, the state will fail and no changes will be made to the file. .sp For example, the following could be used to verify sudoers before making changes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/consul.d/my_config.json: file.serialize: \- dataset: datacenter: \(dqeast\-aws\(dq data_dir: \(dq/opt/consul\(dq log_level: \(dqINFO\(dq node_name: \(dqfoobar\(dq server: true watches: \- type: checks handler: \(dq/usr/bin/health\-check\-handler.sh\(dq telemetry: statsite_address: \(dq127.0.0.1:2180\(dq \- serializer: json \- check_cmd: consul validate .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE\fP: This \fBcheck_cmd\fP functions differently than the requisite \fBcheck_cmd\fP\&. .sp New in version 3007.0. .TP .B tmp_dir Directory for temp file created by \fBcheck_cmd\fP\&. Useful for checkers dependent on config file location (e.g. daemons restricted to their own config directories by an apparmor profile). .sp New in version 3007.0. .TP .B tmp_ext Suffix for temp file created by \fBcheck_cmd\fP\&. Useful for checkers dependent on config file extension. .sp New in version 3007.0. .UNINDENT .sp For example, this state: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/dummy/package.json: file.serialize: \- dataset: name: naive description: A package using naive versioning author: A confused individual <iam@confused.com> dependencies: express: \(aq>= 1.2.0\(aq optimist: \(aq>= 0.1.0\(aq engine: node 0.4.1 \- serializer: json .ft P .fi .UNINDENT .UNINDENT .sp will manage the file \fB/etc/dummy/package.json\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(dqauthor\(dq: \(dqA confused individual <iam@confused.com>\(dq, \(dqdependencies\(dq: { \(dqexpress\(dq: \(dq>= 1.2.0\(dq, \(dqoptimist\(dq: \(dq>= 0.1.0\(dq }, \(dqdescription\(dq: \(dqA package using naive versioning\(dq, \(dqengine\(dq: \(dqnode 0.4.1\(dq, \(dqname\(dq: \(dqnaive\(dq } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.shortcut(name, target, arguments=None, working_dir=None, description=None, icon_location=None, force=False, backupname=None, makedirs=False, user=None, **kwargs) Create a Windows shortcut .sp If the file already exists and is a shortcut pointing to any location other than the specified target, the shortcut will be replaced. If it is a regular file or directory then the state will return False. If the regular file or directory is desired to be replaced with a shortcut pass force: True, if it is to be renamed, pass a backupname. .INDENT 7.0 .TP .B name The location of the shortcut to create. Must end with either \(dq.lnk\(dq or \(dq.url\(dq .TP .B target The location that the shortcut points to .TP .B arguments Any arguments to pass in the shortcut .TP .B working_dir Working directory in which to execute target .TP .B description Description to set on shortcut .TP .B icon_location Location of shortcut\(aqs icon .TP .B force If the name of the shortcut exists and is not a file and force is set to False, the state will fail. If force is set to True, the link or directory in the way of the shortcut file will be deleted to make room for the shortcut, unless backupname is set, when it will be renamed .TP .B backupname If the name of the shortcut exists and is not a file, it will be renamed to the backupname. If the backupname already exists and force is False, the state will fail. Otherwise, the backupname will be removed first. .TP .B makedirs If the location of the shortcut does not already have a parent directory then the state will fail, setting makedirs to True will allow Salt to create the parent directory. Setting this to True will also create the parent for backupname if necessary. .TP .B user The user to own the file, this defaults to the user salt is running as on the minion .sp The default mode for new files and directories corresponds umask of salt process. For existing files and directories it\(aqs not enforced. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.symlink(name, target, force=False, backupname=None, makedirs=False, user=None, group=None, mode=None, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=None, atomic=False, disallow_copy_and_unlink=False, inherit_user_and_group=False, follow_symlinks=True, **kwargs) Create a symbolic link (symlink, soft link) .sp If the file already exists and is a symlink pointing to any location other than the specified target, the symlink will be replaced. If an entry with the same name exists then the state will return False. If the existing entry is desired to be replaced with a symlink pass force: True, if it is to be renamed, pass a backupname. .INDENT 7.0 .TP .B name The location of the symlink to create .TP .B target The location that the symlink points to .TP .B force If the name of the symlink exists and is not a symlink and force is set to False, the state will fail. If force is set to True, the existing entry in the way of the symlink file will be deleted to make room for the symlink, unless backupname is set, when it will be renamed .sp Changed in version 3000: Force will now remove all types of existing file system entries, not just files, directories and symlinks. .TP .B backupname If the name of the symlink exists and is not a symlink, it will be renamed to the backupname. If the backupname already exists and force is False, the state will fail. Otherwise, the backupname will be removed first. An absolute path OR a basename file/directory name must be provided. The latter will be placed relative to the symlink destination\(aqs parent directory. .TP .B makedirs If the location of the symlink does not already have a parent directory then the state will fail, setting makedirs to True will allow Salt to create the parent directory .TP .B user The user to own the file, this defaults to the user salt is running as on the minion unless the link already exists and \fBinherit_user_and_group\fP is set .TP .B group The group ownership set for the file, this defaults to the group salt is running as on the minion unless the link already exists and \fBinherit_user_and_group\fP is set. On Windows, this is ignored .TP .B mode The permissions to set on this file, aka 644, 0775, 4664. Not supported on Windows. .sp The default mode for new files and directories corresponds umask of salt process. For existing files and directories it\(aqs not enforced. .TP .B win_owner The owner of the symlink and directories if \fBmakedirs\fP is True. If this is not passed, \fBuser\fP will be used. If \fBuser\fP is not passed, the account under which Salt is running will be used. .sp New in version 2017.7.7. .TP .B win_perms A dictionary containing permissions to grant .sp New in version 2017.7.7. .TP .B win_deny_perms A dictionary containing permissions to deny .sp New in version 2017.7.7. .TP .B win_inheritance True to inherit permissions from parent, otherwise False .sp New in version 2017.7.7. .TP .B atomic Use atomic file operation to create the symlink. .sp New in version 3006.0. .TP .B disallow_copy_and_unlink Only used if \fBbackupname\fP is used and the name of the symlink exists and is not a symlink. If set to \fBTrue\fP, the operation is offloaded to the \fBfile.rename\fP execution module function. This will use \fBos.rename\fP underneath, which will fail in the event that \fBsrc\fP and \fBdst\fP are on different filesystems. If \fBFalse\fP (the default), \fBshutil.move\fP will be used in order to fall back on a \(dqcopy then unlink\(dq approach, which is required for moving across filesystems. .sp New in version 3006.0. .TP .B inherit_user_and_group If set to \fBTrue\fP, the link already exists, and either \fBuser\fP or \fBgroup\fP are not set, this parameter will inform Salt to pull the user and group information from the existing link and use it where \fBuser\fP or \fBgroup\fP is not set. The \fBuser\fP and \fBgroup\fP parameters will override this behavior. .sp New in version 3006.0. .TP .B follow_symlinks (bool): If set to \fBFalse\fP, the underlying \fBfile.symlink\fP execution module and any checks in this state will use \fBos.path.lexists()\fP for existence checks instead of \fBos.path.exists()\fP\&. .sp New in version 3007.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.tidied(name, age=0, matches=None, rmdirs=False, size=0, exclude=None, full_path_match=False, followlinks=False, time_comparison=\(aqatime\(aq, age_size_logical_operator=\(aqOR\(aq, age_size_only=None, rmlinks=True, **kwargs) Changed in version 3005,3006.0. .sp Remove unwanted files based on specific criteria. .sp The default operation uses an OR operation to evaluate age and size, so a file that is too large but is not old enough will still get tidied. If neither age nor size is given all files which match a pattern in matches will be removed. .sp NOTE: The regex patterns in this function are used in \fBre.match()\fP, so there is an implicit \(dqbeginning of string\(dq anchor (\fB^\fP) in the regex and it is unanchored at the other end unless explicitly entered (\fB$\fP). .INDENT 7.0 .TP .B name The directory tree that should be tidied .TP .B age Maximum age in days after which files are considered for removal .TP .B matches List of regular expressions to restrict what gets removed. Default: [\(aq.*\(aq] .TP .B rmdirs Whether or not it\(aqs allowed to remove directories .TP .B size Maximum allowed file size. Files greater or equal to this size are removed. Doesn\(aqt apply to directories or symbolic links .TP .B exclude List of regular expressions to filter the \fBmatches\fP parameter and better control what gets removed. .sp New in version 3005. .TP .B full_path_match Match the \fBmatches\fP and \fBexclude\fP regex patterns against the entire file path instead of just the file or directory name. Default: \fBFalse\fP .sp New in version 3005. .TP .B followlinks This module will not descend into subdirectories which are pointed to by symbolic links. If you wish to force it to do so, you may give this option the value \fBTrue\fP\&. Default: \fBFalse\fP .sp New in version 3005. .TP .B time_comparison Default: \fBatime\fP\&. Options: \fBatime\fP/\fBmtime\fP/\fBctime\fP\&. This value is used to set the type of time comparison made using \fBage\fP\&. The default is to compare access times (atime) or the last time the file was read. A comparison by modification time (mtime) uses the last time the contents of the file was changed. The ctime parameter is the last time the contents, owner, or permissions of the file were changed. .sp New in version 3005. .TP .B age_size_logical_operator This parameter can change the default operation (OR) to an AND operation to evaluate age and size. In that scenario, a file that is too large but is not old enough will NOT get tidied. A file will need to fulfill BOTH conditions in order to be tidied. Accepts \fBOR\fP or \fBAND\fP\&. .sp New in version 3006.0. .TP .B age_size_only This parameter can trigger the reduction of age and size conditions which need to be satisfied down to ONLY age or ONLY size. By default, this parameter is \fBNone\fP and both conditions will be evaluated using the logical operator defined in \fBage_size_logical_operator\fP\&. The parameter can be set to \fBage\fP or \fBsize\fP in order to restrict evaluation down to that specific condition. Path matching and exclusions still apply. .sp New in version 3006.0. .TP .B rmlinks Whether or not it\(aqs allowed to remove symbolic links .sp New in version 3006.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cleanup: file.tidied: \- name: /tmp/salt_test \- rmdirs: True \- matches: \- foo \- b.*r .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.touch(name, atime=None, mtime=None, makedirs=False) Replicate the \(aqnix \(dqtouch\(dq command to create a new empty file or update the atime and mtime of an existing file. .sp Note that if you just want to create a file and don\(aqt care about atime or mtime, you should use \fBfile.managed\fP instead, as it is more feature\-complete. (Just leave out the \fBsource\fP/\fBtemplate\fP/\fBcontents\fP arguments, and it will just create the file and/or check its permissions, without messing with contents) .INDENT 7.0 .TP .B name name of the file .TP .B atime atime of the file .TP .B mtime mtime of the file .TP .B makedirs whether we should create the parent directory/directories in order to touch the file .UNINDENT .sp Usage: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /var/log/httpd/logrotate.empty: file.touch .ft P .fi .UNINDENT .UNINDENT .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.states.file.uncomment(name, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Uncomment specified commented lines in a file .INDENT 7.0 .TP .B name The full path to the file to be edited .TP .B regex A regular expression used to find the lines that are to be uncommented. This regex should not include the comment character. A leading \fB^\fP character will be stripped for convenience (for easily switching between comment() and uncomment()). The regex will be searched for from the beginning of the line, ignoring leading spaces (we prepend \(aq^[ t]*\(aq) .TP .B char The character to remove in order to uncomment a line .TP .B backup The file will be backed up before edit with this file extension; .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This backup will be overwritten each time \fBsed\fP / \fBcomment\fP / \fBuncomment\fP is called. Meaning the backup will only be useful after the first invocation. .UNINDENT .UNINDENT .sp Set to False/None to not keep a backup. .UNINDENT .sp Usage: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /etc/adduser.conf: file.uncomment: \- regex: EXTRA_GROUPS .ft P .fi .UNINDENT .UNINDENT .sp New in version 0.9.5. .UNINDENT .SS salt.states.firewall .sp State to check firewall configurations .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.states.firewall.check(name, port=None, **kwargs) Checks if there is an open connection from the minion to the defined host on a specific port. .INDENT 7.0 .TP .B name host name or ip address to test connection to .TP .B port The port to test the connection on .TP .B kwargs .INDENT 7.0 .TP .B Additional parameters, parameters allowed are: proto (tcp or udp) family (ipv4 or ipv6) timeout .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C testgoogle: firewall.check: \- name: \(aqgoogle.com\(aq \- port: 80 \- proto: \(aqtcp\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.firewalld .sp Management of firewalld .sp New in version 2015.8.0. .sp The following example applies changes to the public zone, blocks echo\-reply and echo\-request packets, does not set the zone to be the default, enables masquerading, and allows ports 22/tcp and 25/tcp. It will be applied permanently and directly before restart/reload. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C public: firewalld.present: \- name: public \- block_icmp: \- echo\-reply \- echo\-request \- default: False \- masquerade: True \- ports: \- 22/tcp \- 25/tcp .ft P .fi .UNINDENT .UNINDENT .sp The following example applies changes to the public zone, enables masquerading and configures port forwarding TCP traffic from port 22 to 2222, and forwards TCP traffic from port 80 to 443 at 192.168.0.1. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_zone: firewalld.present: \- name: public \- masquerade: True \- port_fwd: \- 22:2222:tcp \- 80:443:tcp:192.168.0.1 .ft P .fi .UNINDENT .UNINDENT .sp The following example binds the public zone to interface eth0 and to all packets coming from the 192.168.1.0/24 subnet. It also removes the zone from all other interfaces or sources. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C public: firewalld.present: \- name: public \- interfaces: \- eth0 \- sources: \- 192.168.1.0/24 .ft P .fi .UNINDENT .UNINDENT .sp Here, we define a new service that encompasses TCP ports 4505 4506: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C saltmaster: firewalld.service: \- name: saltmaster \- ports: \- 4505/tcp \- 4506/tcp .ft P .fi .UNINDENT .UNINDENT .sp To make this new service available in a zone, the following can be used, which would allow access to the salt master from the 10.0.0.0/8 subnet: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C saltzone: firewalld.present: \- name: saltzone \- services: \- saltmaster \- sources: \- 10.0.0.0/8 .ft P .fi .UNINDENT .UNINDENT .sp Another way of implementing the same rule above using rich rules is demonstrated here: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C saltzone: firewalld.present: \- name: saltzone \- rich_rules: \- rule service name=\(dqsaltmaster\(dq accept \- sources: \- 10.0.0.0/8 .ft P .fi .UNINDENT .UNINDENT .sp The format of rich rules is the same as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C firewall\-cmd \-\-list\-rich\-rules .ft P .fi .UNINDENT .UNINDENT .sp with an example output of: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rule protocol value=\(dqicmp\(dq accept rule protocol value=\(dqipv6\-icmp\(dq accept rule service name=\(dqsnmp\(dq accept .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.states.firewalld.ForwardingMapping(srcport, destport, protocol, destaddr) Represents a port forwarding statement mapping a local port to a remote port for a specific protocol (TCP or UDP) .INDENT 7.0 .TP .B todict() Returns a pretty dictionary meant for command line output. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.firewalld.present(name, block_icmp=None, prune_block_icmp=False, default=None, masquerade=None, ports=None, prune_ports=False, port_fwd=None, prune_port_fwd=False, services=None, prune_services=False, interfaces=None, prune_interfaces=False, sources=None, prune_sources=False, rich_rules=None, prune_rich_rules=False) Ensure a zone has specific attributes. .INDENT 7.0 .TP .B name The zone to modify. .TP .B default None Set this zone as the default zone if \fBTrue\fP\&. .TP .B masquerade None Enable or disable masquerade for a zone. By default it will not change it. .TP .B block_icmp None List of ICMP types to block in the zone. .TP .B prune_block_icmp False If \fBTrue\fP, remove all but the specified block_icmp from the zone. .TP .B ports None List of ports to add to the zone. .TP .B prune_ports False If \fBTrue\fP, remove all but the specified ports from the zone. .TP .B port_fwd None List of port forwards to add to the zone. .TP .B prune_port_fwd False If \fBTrue\fP, remove all but the specified port_fwd from the zone. .TP .B services None List of services to add to the zone. .TP .B prune_services False If \fBTrue\fP, remove all but the specified services from the zone. \&.. note:: Currently defaults to True for compatibility, but will be changed to False in a future release. .TP .B interfaces None List of interfaces to add to the zone. .TP .B prune_interfaces False If \fBTrue\fP, remove all but the specified interfaces from the zone. .TP .B sources None List of sources to add to the zone. .TP .B prune_sources False If \fBTrue\fP, remove all but the specified sources from the zone. .TP .B rich_rules None List of rich rules to add to the zone. .TP .B prune_rich_rules False If \fBTrue\fP, remove all but the specified rich rules from the zone. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.firewalld.service(name, ports=None, protocols=None) Ensure the service exists and encompasses the specified ports and protocols. .sp New in version 2016.11.0. .UNINDENT .SS salt.states.gem .SS Installation of Ruby modules packaged as gems .sp A state module to manage rubygems. Gems can be set up to be installed or removed. This module will use RVM or rbenv if they are installed. In that case, you can specify what ruby version and gemset to target. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C addressable: gem.installed: \- user: rvm \- ruby: jruby@jgemset .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.gem.installed(name, ruby=None, gem_bin=None, user=None, version=None, rdoc=False, ri=False, pre_releases=False, proxy=None, source=None) Make sure that a gem is installed. .INDENT 7.0 .TP .B name The name of the gem to install .TP .B ruby: None Only for RVM or rbenv installations: the ruby version and gemset to target. .TP .B gem_bin: None Custom \fBgem\fP command to run instead of the default. Use this to install gems to a non\-default ruby install. If you are using rvm or rbenv use the ruby argument instead. .TP .B user: None The user under which to run the \fBgem\fP command .sp New in version 0.17.0. .TP .B version None Specify the version to install for the gem. Doesn\(aqt play nice with multiple gems at once .TP .B rdoc False Generate RDoc documentation for the gem(s). .TP .B ri False Generate RI documentation for the gem(s). .TP .B pre_releases False Install pre\-release version of gem(s) if available. .TP .B proxy None Use the specified HTTP proxy server for all outgoing traffic. Format: \fI\%http://hostname[:port\fP] .TP .B source None Use the specified HTTP gem source server to download gem. Format: \fI\%http://hostname[:port\fP] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.gem.removed(name, ruby=None, user=None, gem_bin=None) Make sure that a gem is not installed. .INDENT 7.0 .TP .B name The name of the gem to uninstall .TP .B gem_bin None Full path to \fBgem\fP binary to use. .TP .B ruby None If RVM or rbenv are installed, the ruby version and gemset to use. Ignored if \fBgem_bin\fP is specified. .TP .B user: None The user under which to run the \fBgem\fP command .sp New in version 0.17.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.gem.sources_add(name, ruby=None, user=None) Make sure that a gem source is added. .INDENT 7.0 .TP .B name The URL of the gem source to be added .TP .B ruby: None For RVM or rbenv installations: the ruby version and gemset to target. .TP .B user: None The user under which to run the \fBgem\fP command .sp New in version 0.17.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.gem.sources_remove(name, ruby=None, user=None) Make sure that a gem source is removed. .INDENT 7.0 .TP .B name The URL of the gem source to be removed .TP .B ruby: None For RVM or rbenv installations: the ruby version and gemset to target. .TP .B user: None The user under which to run the \fBgem\fP command .sp New in version 0.17.0. .UNINDENT .UNINDENT .SS salt.states.git .sp States to manage git repositories and git configuration .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 Before using git over ssh, make sure your remote host fingerprint exists in your \fB~/.ssh/known_hosts\fP file. .UNINDENT .UNINDENT .sp Changed in version 2015.8.8: This state module now requires git 1.6.5 (released 10 October 2009) or newer. .INDENT 0.0 .TP .B salt.states.git.cloned(name, target, branch=None, user=None, password=None, identity=None, https_user=None, https_pass=None, output_encoding=None) New in version 2018.3.3,2019.2.0. .sp Ensure that a repository has been cloned to the specified target directory. If not, clone that repository. No fetches will be performed once cloned. .INDENT 7.0 .TP .B name Address of the remote repository .TP .B target Name of the target directory where repository should be cloned .TP .B branch Remote branch to check out. If unspecified, the default branch (i.e. the one to the remote HEAD points) will be checked out. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The local branch name will match the remote branch name. If the branch name is changed, then that branch will be checked out locally, but keep in mind that remote repository will not be fetched. If your use case requires that you keep the clone up to date with the remote repository, then consider using \fI\%git.latest\fP\&. .UNINDENT .UNINDENT .TP .B user User under which to run git commands. By default, commands are run by the user under which the minion is running. .TP .B password Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .TP .B identity Path to a private key to use for ssh URLs. Works the same way as in \fI\%git.latest\fP, see that state\(aqs documentation for more information. .TP .B https_user HTTP Basic Auth username for HTTPS (only) clones .TP .B https_pass HTTP Basic Auth password for HTTPS (only) clones .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.git.config_set(name, value=None, multivar=None, repo=None, user=None, password=None, output_encoding=None, **kwargs) New in version 2014.7.0. .sp Changed in version 2015.8.0: Renamed from \fBgit.config\fP to \fBgit.config_set\fP\&. For earlier versions, use \fBgit.config\fP\&. .sp Ensure that a config value is set to the desired value(s) .INDENT 7.0 .TP .B name Name of the git config value to set .TP .B value Set a single value for the config item .TP .B multivar Set multiple values for the config item .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The order matters here, if the same parameters are set but in a different order, they will be removed and replaced in the order specified. .UNINDENT .UNINDENT .sp New in version 2015.8.0. .TP .B repo Location of the git repository for which the config value should be set. Required unless \fBglobal\fP is set to \fBTrue\fP\&. .TP .B user User under which to run git commands. By default, the commands are run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B global False If \fBTrue\fP, this will set a global git config option .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp \fBLocal Config Example:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Single value mylocalrepo: git.config_set: \- name: user.email \- value: foo@bar.net \- repo: /path/to/repo # Multiple values mylocalrepo: git.config_set: \- name: mysection.myattribute \- multivar: \- foo \- bar \- baz \- repo: /path/to/repo .ft P .fi .UNINDENT .UNINDENT .sp \fBGlobal Config Example (User \(ga\(gafoo\(ga\(ga):\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mylocalrepo: git.config_set: \- name: user.name \- value: Foo Bar \- user: foo \- global: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.git.config_unset(name, value_regex=None, repo=None, user=None, password=None, output_encoding=None, **kwargs) New in version 2015.8.0. .sp Ensure that the named config key is not present .INDENT 7.0 .TP .B name The name of the configuration key to unset. This value can be a regex, but the regex must match the entire key name. For example, \fBfoo\e.\fP would not match all keys in the \fBfoo\fP section, it would be necessary to use \fBfoo\e..+\fP to do so. .TP .B value_regex Regex indicating the values to unset for the matching key(s) .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option behaves differently depending on whether or not \fBall\fP is set to \fBTrue\fP\&. If it is, then all values matching the regex will be deleted (this is the only way to delete multiple values from a multivar). If \fBall\fP is set to \fBFalse\fP, then this state will fail if the regex matches more than one value in a multivar. .UNINDENT .UNINDENT .TP .B all False If \fBTrue\fP, unset all matches .TP .B repo Location of the git repository for which the config value should be set. Required unless \fBglobal\fP is set to \fBTrue\fP\&. .TP .B user User under which to run git commands. By default, commands are run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B global False If \fBTrue\fP, this will set a global git config option .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp \fBExamples:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Value matching \(aqbaz\(aq mylocalrepo: git.config_unset: \- name: foo.bar \- value_regex: \(aqbaz\(aq \- repo: /path/to/repo # Ensure entire multivar is unset mylocalrepo: git.config_unset: \- name: foo.bar \- all: True # Ensure all variables in \(aqfoo\(aq section are unset, including multivars mylocalrepo: git.config_unset: \- name: \(aqfoo\e..+\(aq \- all: True # Ensure that global config value is unset mylocalrepo: git.config_unset: \- name: foo.bar \- global: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.git.detached(name, rev, target, remote=\(aqorigin\(aq, user=None, password=None, force_clone=False, force_checkout=False, fetch_remote=True, hard_reset=False, submodules=False, identity=None, https_user=None, https_pass=None, output_encoding=None, **kwargs) New in version 2016.3.0. .sp Make sure a repository is cloned to the given target directory and is a detached HEAD checkout of the commit ID resolved from \fBrev\fP\&. .INDENT 7.0 .TP .B name Address of the remote repository. .TP .B rev The branch, tag, or commit ID to checkout after clone. If a branch or tag is specified it will be resolved to a commit ID and checked out. .TP .B target Name of the target directory where repository is about to be cloned. .TP .B remote origin Git remote to use. If this state needs to clone the repo, it will clone it using this value as the initial remote name. If the repository already exists, and a remote by this name is not present, one will be added. .TP .B user User under which to run git commands. By default, commands are run by the user under which the minion is running. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B force_clone False If the \fBtarget\fP directory exists and is not a git repository, then this state will fail. Set this argument to \fBTrue\fP to remove the contents of the target directory and clone the repo into it. .TP .B force_checkout False When checking out the revision ID, the state will fail if there are unwritten changes. Set this argument to \fBTrue\fP to discard unwritten changes when checking out. .TP .B fetch_remote True If \fBFalse\fP a fetch will not be performed and only local refs will be reachable. .TP .B hard_reset False If \fBTrue\fP a hard reset will be performed before the checkout and any uncommitted modifications to the working directory will be discarded. Untracked files will remain in place. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Changes resulting from a hard reset will not trigger requisites. .UNINDENT .UNINDENT .TP .B submodules False Update submodules .TP .B identity A path on the minion (or a SaltStack fileserver URL, e.g. \fBsalt://path/to/identity_file\fP) to a private key to use for SSH authentication. .TP .B https_user HTTP Basic Auth username for HTTPS (only) clones .TP .B https_pass HTTP Basic Auth password for HTTPS (only) clones .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.git.latest(name, target, rev=\(aqHEAD\(aq, branch=None, user=None, password=None, update_head=True, force_checkout=False, force_clone=False, force_fetch=False, force_reset=False, submodules=False, bare=False, mirror=False, remote=\(aqorigin\(aq, fetch_tags=True, sync_tags=True, depth=None, identity=None, https_user=None, https_pass=None, refspec_branch=\(aq*\(aq, refspec_tag=\(aq*\(aq, output_encoding=None, **kwargs) Make sure the repository is cloned to the given directory and is up\-to\-date. .INDENT 7.0 .TP .B name Address of the remote repository, as passed to \fBgit clone\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 From the \fI\%Git documentation\fP, there are two URL formats supported for SSH authentication. The below two examples are equivalent: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # ssh:// URL ssh://user@server/project.git # SCP\-like syntax user@server:project.git .ft P .fi .UNINDENT .UNINDENT .sp A common mistake is to use an \fBssh://\fP URL, but with a colon after the domain instead of a slash. This is invalid syntax in Git, and will therefore not work in Salt. When in doubt, confirm that a \fBgit clone\fP works for the URL before using it in Salt. .sp It has been reported by some users that SCP\-like syntax is incompatible with git repos hosted on \fI\%Atlassian Stash/BitBucket Server\fP\&. In these cases, it may be necessary to use \fBssh://\fP URLs for SSH authentication. .UNINDENT .UNINDENT .TP .B rev HEAD The remote branch, tag, or revision ID to checkout after clone / before update. If specified, then Salt will also ensure that the tracking branch is set to \fB<remote>/<rev>\fP, unless \fBrev\fP refers to a tag or SHA1, in which case Salt will ensure that the tracking branch is unset. .sp If \fBrev\fP is not specified, it will be assumed to be \fBHEAD\fP, and Salt will not manage the tracking branch at all. .sp Changed in version 2015.8.0: If not specified, \fBrev\fP now defaults to the remote repository\(aqs HEAD. .TP .B target Name of the target directory where repository is about to be cloned .TP .B branch Name of the local branch into which to checkout the specified rev. If not specified, then Salt will not care what branch is being used locally and will just use whatever branch is currently there. .sp New in version 2015.8.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If this argument is not specified, this means that Salt will not change the local branch if the repository is reset to another branch/tag/SHA1. For example, assume that the following state was run initially: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo_app: git.latest: \- name: https://mydomain.tld/apps/foo.git \- target: /var/www/foo \- user: www .ft P .fi .UNINDENT .UNINDENT .sp This would have cloned the HEAD of that repo (since a \fBrev\fP wasn\(aqt specified), and because \fBbranch\fP is not specified, the branch in the local clone at \fB/var/www/foo\fP would be whatever the default branch is on the remote repository (usually \fBmaster\fP, but not always). Now, assume that it becomes necessary to switch this checkout to the \fBdev\fP branch. This would require \fBrev\fP to be set, and probably would also require \fBforce_reset\fP to be enabled: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo_app: git.latest: \- name: https://mydomain.tld/apps/foo.git \- target: /var/www/foo \- user: www \- rev: dev \- force_reset: True .ft P .fi .UNINDENT .UNINDENT .sp The result of this state would be to perform a hard\-reset to \fBorigin/dev\fP\&. Since \fBbranch\fP was not specified though, while \fB/var/www/foo\fP would reflect the contents of the remote repo\(aqs \fBdev\fP branch, the local branch would still remain whatever it was when it was cloned. To make the local branch match the remote one, set \fBbranch\fP as well, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo_app: git.latest: \- name: https://mydomain.tld/apps/foo.git \- target: /var/www/foo \- user: www \- rev: dev \- branch: dev \- force_reset: True .ft P .fi .UNINDENT .UNINDENT .sp This may seem redundant, but Salt tries to support a wide variety of use cases, and doing it this way allows for the use case where the local branch doesn\(aqt need to be strictly managed. .UNINDENT .UNINDENT .TP .B user Local system user under which to run git commands. By default, commands are run by the user under which the minion is running. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is not to be confused with the username for http(s)/SSH authentication. .UNINDENT .UNINDENT .sp New in version 0.17.0. .TP .B password Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .sp New in version 2016.3.4. .TP .B update_head True If set to \fBFalse\fP, then the remote repository will be fetched (if necessary) to ensure that the commit to which \fBrev\fP points exists in the local checkout, but no changes will be made to the local HEAD. .sp New in version 2015.8.3. .TP .B force_checkout False When checking out the local branch, the state will fail if there are unwritten changes. Set this argument to \fBTrue\fP to discard unwritten changes when checking out. .TP .B force_clone False If the \fBtarget\fP directory exists and is not a git repository, then this state will fail. Set this argument to \fBTrue\fP to remove the contents of the target directory and clone the repo into it. .TP .B force_fetch False If a fetch needs to be performed, non\-fast\-forward fetches will cause this state to fail. Set this argument to \fBTrue\fP to force the fetch even if it is a non\-fast\-forward update. .sp New in version 2015.8.0. .TP .B force_reset False If the update is not a fast\-forward, this state will fail. Set this argument to \fBTrue\fP to force a hard\-reset to the remote revision in these cases. .sp Changed in version 2019.2.0: This option can now be set to \fBremote\-changes\fP, which will instruct Salt not to discard local changes if the repo is up\-to\-date with the remote repository. .TP .B submodules False Update submodules on clone or branch change .TP .B bare False Set to \fBTrue\fP if the repository is to be a bare clone of the remote repository. .TP .B mirror Set to \fBTrue\fP if the repository is to be a mirror of the remote repository. This implies that \fBbare\fP set to \fBTrue\fP, and thus is incompatible with \fBrev\fP\&. .TP .B remote origin Git remote to use. If this state needs to clone the repo, it will clone it using this value as the initial remote name. If the repository already exists, and a remote by this name is not present, one will be added. .TP .B fetch_tags True If \fBTrue\fP, then when a fetch is performed all tags will be fetched, even those which are not reachable by any branch on the remote. .TP .B sync_tags True If \fBTrue\fP, then Salt will delete tags which exist in the local clone but are not found on the remote repository. .sp New in version 2018.3.4. .TP .B depth Defines depth in history when git a clone is needed in order to ensure latest. E.g. \fBdepth: 1\fP is useful when deploying from a repository with a long history. Use rev to specify branch or tag. This is not compatible with revision IDs. .sp Changed in version 2019.2.0: This option now supports tags as well as branches, on Git 1.8.0 and newer. .TP .B identity Path to a private key to use for ssh URLs. This can be either a single string, or a list of strings. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Single key git@github.com:user/repo.git: git.latest: \- user: deployer \- identity: /home/deployer/.ssh/id_rsa # Two keys git@github.com:user/repo.git: git.latest: \- user: deployer \- identity: \- /home/deployer/.ssh/id_rsa \- /home/deployer/.ssh/id_rsa_alternate .ft P .fi .UNINDENT .UNINDENT .sp If multiple keys are specified, they will be tried one\-by\-one in order for each git command which needs to authenticate. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Unless Salt is invoked from the minion using \fBsalt\-call\fP, the key(s) must be passphraseless. For greater security with passphraseless private keys, see the \fI\%sshd(8)\fP manpage for information on securing the keypair from the remote side in the \fBauthorized_keys\fP file. .UNINDENT .UNINDENT .sp Changed in version 2015.8.7: Salt will no longer attempt to use passphrase\-protected keys unless invoked from the minion using \fBsalt\-call\fP, to prevent blocking waiting for user input. .sp Changed in version 2016.3.0: Key can now be specified as a SaltStack fileserver URL (e.g. \fBsalt://path/to/identity_file\fP). .TP .B https_user HTTP Basic Auth username for HTTPS (only) clones .sp New in version 2015.5.0. .TP .B https_pass HTTP Basic Auth password for HTTPS (only) clones .sp New in version 2015.5.0. .TP .B refspec_branch * A glob expression defining which branches to retrieve when fetching. See \fI\%git\-fetch(1)\fP for more information on how refspecs work. .sp New in version 2017.7.0. .TP .B refspec_tag * A glob expression defining which tags to retrieve when fetching. See \fI\%git\-fetch(1)\fP for more information on how refspecs work. .sp New in version 2017.7.0. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Clashing ID declarations can be avoided when including different branches from the same git repository in the same SLS file by using the \fBname\fP argument. The example below checks out the \fBgh\-pages\fP and \fBgh\-pages\-prod\fP branches from the same repository into separate directories. The example also sets up the \fBssh_known_hosts\fP ssh key required to perform the git checkout. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitlab.example.com: ssh_known_hosts: \- present \- user: root \- enc: ecdsa \- fingerprint: 4e:94:b0:54:c1:5b:29:a2:70:0e:e1:a3:51:ee:ee:e3 git\-website\-staging: git.latest: \- name: git@gitlab.example.com:user/website.git \- rev: gh\-pages \- target: /usr/share/nginx/staging \- identity: /root/.ssh/website_id_rsa \- require: \- pkg: git \- ssh_known_hosts: gitlab.example.com git\-website\-staging: git.latest: \- name: git@gitlab.example.com:user/website.git \- rev: gh\-pages \- target: /usr/share/nginx/staging \- identity: salt://website/id_rsa \- require: \- pkg: git \- ssh_known_hosts: gitlab.example.com git\-website\-prod: git.latest: \- name: git@gitlab.example.com:user/website.git \- rev: gh\-pages\-prod \- target: /usr/share/nginx/prod \- identity: /root/.ssh/website_id_rsa \- require: \- pkg: git \- ssh_known_hosts: gitlab.example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.git.present(name, force=False, bare=True, template=None, separate_git_dir=None, shared=None, user=None, password=None, output_encoding=None) Ensure that a repository exists in the given directory .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 If the minion has Git 2.5 or later installed, \fBname\fP points to a \fI\%worktree\fP, and \fBforce\fP is set to \fBTrue\fP, then the worktree will be deleted. This has been corrected in Salt 2015.8.0. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Path to the directory .sp Changed in version 2015.8.0: This path must now be absolute .TP .B force False If \fBTrue\fP, and if \fBname\fP points to an existing directory which does not contain a git repository, then the contents of that directory will be recursively removed and a new repository will be initialized in its place. .TP .B bare True If \fBTrue\fP, and a repository must be initialized, then the repository will be a bare repository. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This differs from the default behavior of \fI\%git.init\fP, make sure to set this value to \fBFalse\fP if a bare repo is not desired. .UNINDENT .UNINDENT .TP .B template If a new repository is initialized, this argument will specify an alternate template directory. .sp New in version 2015.8.0. .TP .B separate_git_dir If a new repository is initialized, this argument will specify an alternate \fB$GIT_DIR\fP .sp New in version 2015.8.0. .TP .B shared Set sharing permissions on git repo. See \fI\%git\-init(1)\fP for more details. .sp New in version 2015.5.0. .TP .B user User under which to run git commands. By default, commands are run by the user under which the minion is running. .sp New in version 0.17.0. .TP .B password .INDENT 7.0 .INDENT 3.5 Windows only. Required when specifying \fBuser\fP\&. This parameter will be ignored on non\-Windows platforms. .UNINDENT .UNINDENT .sp New in version 2016.3.4. .TP .B output_encoding Use this option to specify which encoding to use to decode the output from any git commands which are run. This should not be needed in most cases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This should only be needed if the files in the repository were created with filenames using an encoding other than UTF\-8 to handle Unicode characters. .UNINDENT .UNINDENT .sp New in version 2018.3.1. .UNINDENT .UNINDENT .SS salt.states.github .sp Github User State Module .sp New in version 2016.3.0. .sp This state is used to ensure presence of users in the Organization. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ensure user test is present in github: github.present: \- name: \(aqExample TestUser1\(aq \- email: example@domain.com \- username: \(aqgitexample\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.github.absent(name, profile=\(aqgithub\(aq, **kwargs) Ensure a github user is absent .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ensure user test is absent in github: github.absent: \- name: \(aqExample TestUser1\(aq \- email: example@domain.com \- username: \(aqgitexample\(aq .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B name Github handle of the user in organization .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.github.present(name, profile=\(aqgithub\(aq, **kwargs) Ensure a user is present .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ensure user test is present in github: github.present: \- name: \(aqgitexample\(aq .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B name This is the github handle of the user in the organization .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.github.repo_absent(name, profile=\(aqgithub\(aq, **kwargs) Ensure a repo is absent. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ensure repo test is absent in github: github.repo_absent: \- name: \(aqtest\(aq .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B name This is the name of the repository in the organization. .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.states.github.repo_present(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, auto_init=False, gitignore_template=None, license_template=None, teams=None, profile=\(aqgithub\(aq, **kwargs) Ensure a repository is present .INDENT 7.0 .TP .B name This is the name of the repository. .TP .B description The description of the repository. .TP .B homepage The URL with more information about the repository. .TP .B private The visiblity of the repository. Note that private repositories require a paid GitHub account. .TP .B has_issues Whether to enable issues for this repository. .TP .B has_wiki Whether to enable the wiki for this repository. .TP .B has_downloads Whether to enable downloads for this repository. .TP .B auto_init Whether to create an initial commit with an empty README. .TP .B gitignore_template The desired language or platform for a .gitignore, e.g \(dqHaskell\(dq. .TP .B license_template The desired LICENSE template to apply, e.g \(dqmit\(dq or \(dqmozilla\(dq. .TP .B teams The teams for which this repo should belong to, specified as a dict of team name to permission (\(aqpull\(aq, \(aqpush\(aq or \(aqadmin\(aq). .sp New in version 2017.7.0. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Ensure repo my\-repo is present in github: github.repo_present: \- name: \(aqmy\-repo\(aq \- description: \(aqMy very important repository\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.states.github.team_absent(name, profile=\(aqgithub\(aq, **kwargs) Ensure a team is absent. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ensure team test is present in github: github.team_absent: \- name: \(aqtest\(aq .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B name This is the name of the team in the organization. .UNINDENT .sp New in version 2016.11.0. .UNINDENT .INDENT 0.0 .TP .B salt.states.github.team_present(name, description=None, repo_names=None, privacy=\(aqsecret\(aq, permission=\(aqpull\(aq, members=None, enforce_mfa=False, no_mfa_grace_seconds=0, profile=\(aqgithub\(aq, **kwargs) Ensure a team is present .INDENT 7.0 .TP .B name This is the name of the team in the organization. .TP .B description The description of the team. .TP .B repo_names The names of repositories to add the team to. .TP .B privacy The level of privacy for the team, can be \(aqsecret\(aq or \(aqclosed\(aq. Defaults to secret. .TP .B permission The default permission for new repositories added to the team, can be \(aqpull\(aq, \(aqpush\(aq or \(aqadmin\(aq. Defaults to pull. .TP .B members The members belonging to the team, specified as a dict of member name to optional configuration. Options include \(aqenforce_mfa_from\(aq and \(aqmfa_exempt\(aq. .TP .B enforce_mfa Whether to enforce MFA requirements on members of the team. If True then all members without \fImfa_exempt: True\fP configured will be removed from the team. Note that \fIno_mfa_grace_seconds\fP may be set to allow members a grace period. .TP .B no_mfa_grace_seconds The number of seconds of grace time that a member will have to enable MFA before being removed from the team. The grace period will begin from \fIenforce_mfa_from\fP on the member configuration, which defaults to 1970/01/01. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Ensure team test is present in github: github.team_present: \- name: \(aqtest\(aq \- members: user1: {} user2: {} Ensure team test_mfa is present in github: github.team_present: \- name: \(aqtest_mfa\(aq \- members: user1: enforce_mfa_from: 2016/06/15 \- enforce_mfa: True .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .SS salt.states.glance_image .SS Management of OpenStack Glance Images .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.glanceng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create image: glance_image.present: \- name: cirros \- filename: cirros.raw \- image_format: raw delete image: glance_image.absent: \- name: cirros .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glance_image.absent(name, auth=None) Ensure image does not exist .INDENT 7.0 .TP .B name Name of the image .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glance_image.present(name, auth=None, **kwargs) Ensure image exists and is up\-to\-date .INDENT 7.0 .TP .B name Name of the image .TP .B enabled Boolean to control if image is enabled .TP .B description An arbitrary description of the image .UNINDENT .UNINDENT .SS salt.states.glassfish .sp Manage Glassfish/Payara server \&.. versionadded:: 2016.11.0 .sp Management of glassfish using its RESTful API You can setup connection parameters like this .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- server: \- ssl: true \- url: localhost \- port: 4848 \- user: admin \- password: changeit .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glassfish.connection_factory_absent(name, both=True, server=None) Ensures the transaction factory is absent. .INDENT 7.0 .TP .B name Name of the connection factory .TP .B both Delete both the pool and the resource, defaults to \fBtrue\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glassfish.connection_factory_present(name, restype=\(aqconnection_factory\(aq, description=\(aq\(aq, enabled=True, min_size=1, max_size=250, resize_quantity=2, idle_timeout=300, wait_timeout=60, reconnect_on_failure=False, transaction_support=\(aq\(aq, connection_validation=False, server=None) Ensures that the Connection Factory is present .INDENT 7.0 .TP .B name Name of the connection factory .TP .B restype Type of the connection factory, can be either \fBconnection_factory\fP, \fBqueue_connection_factory\(ga or \(ga\(gatopic_connection_factory\fP, defaults to \fBconnection_factory\fP .TP .B description Description of the connection factory .TP .B enabled Is the connection factory enabled? defaults to \fBtrue\fP .TP .B min_size Minimum and initial number of connections in the pool, defaults to \fB1\fP .TP .B max_size Maximum number of connections that can be created in the pool, defaults to \fB250\fP .TP .B resize_quantity Number of connections to be removed when idle_timeout expires, defaults to \fB2\fP .TP .B idle_timeout Maximum time a connection can remain idle in the pool, in seconds, defaults to \fB300\fP .TP .B wait_timeout Maximum time a caller can wait before timeout, in seconds, defaults to \fB60\fP .TP .B reconnect_on_failure Close all connections and reconnect on failure (or reconnect only when used), defaults to \fBfalse\fP .TP .B transaction_support Level of transaction support, can be either \fBXATransaction\fP, \fBLocalTransaction\fP or \fBNoTransaction\fP .TP .B connection_validation Connection validation is required, defaults to \fBfalse\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glassfish.destination_absent(name, server=None) Ensures that the JMS Destination doesn\(aqt exists .INDENT 7.0 .TP .B name Name of the JMS Destination .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glassfish.destination_present(name, physical, restype=\(aqqueue\(aq, description=\(aq\(aq, enabled=True, server=None) Ensures that the JMS Destination Resource (queue or topic) is present .INDENT 7.0 .TP .B name The JMS Queue/Topic name .TP .B physical The Physical destination name .TP .B restype The JMS Destination resource type, either \fBqueue\fP or \fBtopic\fP, defaults is \fBqueue\fP .TP .B description A description of the resource .TP .B enabled Defaults to \fBTrue\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glassfish.jdbc_datasource_absent(name, both=True, server=None) Ensures the JDBC Datasource doesn\(aqt exists .INDENT 7.0 .TP .B name Name of the datasource .TP .B both Delete both the pool and the resource, defaults to \fBtrue\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glassfish.jdbc_datasource_present(name, description=\(aq\(aq, enabled=True, restype=\(aqdatasource\(aq, vendor=\(aqmysql\(aq, sql_url=\(aq\(aq, sql_user=\(aq\(aq, sql_password=\(aq\(aq, min_size=8, max_size=32, resize_quantity=2, idle_timeout=300, wait_timeout=60, non_transactional=False, transaction_isolation=\(aq\(aq, isolation_guaranteed=True, server=None) Ensures that the JDBC Datasource exists .INDENT 7.0 .TP .B name Name of the datasource .TP .B description Description of the datasource .TP .B enabled Is the datasource enabled? defaults to \fBtrue\fP .TP .B restype Resource type, can be \fBdatasource\fP, \fBxa_datasource\fP, \fBconnection_pool_datasource\fP or \fBdriver\fP, defaults to \fBdatasource\fP .TP .B vendor SQL Server type, currently supports \fBmysql\fP, \fBpostgresql\fP and \fBmssql\fP, defaults to \fBmysql\fP .TP .B sql_url URL of the server in jdbc form .TP .B sql_user Username for the server .TP .B sql_password Password for that username .TP .B min_size Minimum and initial number of connections in the pool, defaults to \fB8\fP .TP .B max_size Maximum number of connections that can be created in the pool, defaults to \fB32\fP .TP .B resize_quantity Number of connections to be removed when idle_timeout expires, defaults to \fB2\fP .TP .B idle_timeout Maximum time a connection can remain idle in the pool, in seconds, defaults to \fB300\fP .TP .B wait_timeout Maximum time a caller can wait before timeout, in seconds, defaults to \fB60\fP .TP .B non_transactional Return non\-transactional connections .TP .B transaction_isolation Defaults to the JDBC driver default .TP .B isolation_guaranteed All connections use the same isolation level .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glassfish.system_properties_absent(name, server=None) Ensures that the system property doesn\(aqt exists .INDENT 7.0 .TP .B name Name of the system property .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glassfish.system_properties_present(server=None, **kwargs) Ensures that the system properties are present .INDENT 7.0 .TP .B properties The system properties .UNINDENT .UNINDENT .SS salt.states.glusterfs .sp Manage GlusterFS pool. .INDENT 0.0 .TP .B salt.states.glusterfs.add_volume_bricks(name, bricks) Add brick(s) to an existing volume .INDENT 7.0 .TP .B name Volume name .TP .B bricks List of bricks to add to the volume .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myvolume: glusterfs.add_volume_bricks: \- bricks: \- host1:/srv/gluster/drive1 \- host2:/srv/gluster/drive2 Replicated Volume: glusterfs.add_volume_bricks: \- name: volume2 \- bricks: \- host1:/srv/gluster/drive2 \- host2:/srv/gluster/drive3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glusterfs.max_op_version(name) New in version 2019.2.0. .sp Add brick(s) to an existing volume .INDENT 7.0 .TP .B name Volume name .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myvolume: glusterfs.max_op_version: \- name: volume1 \- version: 30707 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glusterfs.op_version(name, version) New in version 2019.2.0. .sp Add brick(s) to an existing volume .INDENT 7.0 .TP .B name Volume name .TP .B version Version to which the cluster.op\-version should be set .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myvolume: glusterfs.op_version: \- name: volume1 \- version: 30707 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glusterfs.peered(name) Check if node is peered. .INDENT 7.0 .TP .B name The remote host with which to peer. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C peer\-cluster: glusterfs.peered: \- name: two peer\-clusters: glusterfs.peered: \- names: \- one \- two \- three \- four .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glusterfs.started(name) Check if volume has been started .INDENT 7.0 .TP .B name name of the volume .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mycluster: glusterfs.started: [] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.glusterfs.volume_present(name, bricks, stripe=False, replica=False, device_vg=False, transport=\(aqtcp\(aq, start=False, force=False, arbiter=False) Ensure that the volume exists .INDENT 7.0 .TP .B name name of the volume .TP .B bricks list of brick paths .TP .B replica replica count for volume .TP .B arbiter use every third brick as arbiter (metadata only) .sp New in version 2019.2.0. .TP .B start ensure that the volume is also started .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C myvolume: glusterfs.volume_present: \- bricks: \- host1:/srv/gluster/drive1 \- host2:/srv/gluster/drive2 Replicated Volume: glusterfs.volume_present: \- name: volume2 \- bricks: \- host1:/srv/gluster/drive2 \- host2:/srv/gluster/drive3 \- replica: 2 \- start: True Replicated Volume with arbiter brick: glusterfs.volume_present: \- name: volume3 \- bricks: \- host1:/srv/gluster/drive2 \- host2:/srv/gluster/drive3 \- host3:/srv/gluster/drive4 \- replica: 3 \- arbiter: True \- start: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.gnomedesktop .SS Configuration of the GNOME desktop .sp Control the GNOME settings .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C localdesktop_wm_prefs: gnomedesktop.wm_preferences: \- user: username \- audible_bell: false \- action_double_click_titlebar: \(aqtoggle\-maximize\(aq \- visual_bell: true \- num_workspaces: 6 localdesktop_lockdown: gnomedesktop.desktop_lockdown: \- user: username \- disable_user_switching: true localdesktop_interface: gnomedesktop.desktop_interface: \- user: username \- clock_show_date: true \- clock_format: 12h .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.gnomedesktop.desktop_interface(name, user=None, automatic_mnemonics=None, buttons_have_icons=None, can_change_accels=None, clock_format=None, clock_show_date=None, clock_show_seconds=None, cursor_blink=None, cursor_blink_time=None, cursor_blink_timeout=None, cursor_size=None, cursor_theme=None, document_font_name=None, enable_animations=None, font_name=None, gtk_color_palette=None, gtk_color_scheme=None, gtk_im_module=None, gtk_im_preedit_style=None, gtk_im_status_style=None, gtk_key_theme=None, gtk_theme=None, gtk_timeout_initial=None, gtk_timeout_repeat=None, icon_theme=None, menubar_accel=None, menubar_detachable=None, menus_have_icons=None, menus_have_tearoff=None, monospace_font_name=None, show_input_method_menu=None, show_unicode_menu=None, text_scaling_factor=None, toolbar_detachable=None, toolbar_icons_size=None, toolbar_style=None, toolkit_accessibility=None, **kwargs) desktop_interface: sets values in the org.gnome.desktop.interface schema .UNINDENT .INDENT 0.0 .TP .B salt.states.gnomedesktop.desktop_lockdown(name, user=None, disable_application_handlers=None, disable_command_line=None, disable_lock_screen=None, disable_log_out=None, disable_print_setup=None, disable_printing=None, disable_save_to_disk=None, disable_user_switching=None, user_administration_disabled=None, **kwargs) desktop_lockdown: sets values in the org.gnome.desktop.lockdown schema .UNINDENT .INDENT 0.0 .TP .B salt.states.gnomedesktop.wm_preferences(name, user=None, action_double_click_titlebar=None, action_middle_click_titlebar=None, action_right_click_titlebar=None, application_based=None, audible_bell=None, auto_raise=None, auto_raise_delay=None, button_layout=None, disable_workarounds=None, focus_mode=None, focus_new_windows=None, mouse_button_modifier=None, num_workspaces=None, raise_on_click=None, resize_with_right_button=None, theme=None, titlebar_font=None, titlebar_uses_system_font=None, visual_bell=None, visual_bell_type=None, workspace_names=None, **kwargs) wm_preferences: sets values in the org.gnome.desktop.wm.preferences schema .UNINDENT .SS salt.states.gpg .SS Manage GPG keychains .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.states.gpg.absent(name, keys=None, user=None, gnupghome=None, keyring=None, keyring_absent_if_empty=False, **kwargs) Ensure a GPG public key is absent from the keychain. .INDENT 7.0 .TP .B name The key ID of the GPG public key. .TP .B keys The key ID or key IDs to remove from the GPG keychain. .TP .B user Remove GPG keys from the specified user\(aqs keychain. .TP .B gnupghome Override GnuPG home directory. .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .TP .B keyring_absent_if_empty Make sure to not leave behind an empty keyring file if \fBkeyring\fP was specified. Defaults to false. .sp New in version 3007.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.gpg.present(name, keys=None, user=None, keyserver=None, gnupghome=None, trust=None, keyring=None, **kwargs) Ensure a GPG public key is present in the GPG keychain. .INDENT 7.0 .TP .B name The key ID of the GPG public key. .TP .B keys The key ID or key IDs to add to the GPG keychain. .TP .B user Add GPG keys to the specified user\(aqs keychain. .TP .B keyserver The keyserver to retrieve the keys from. .TP .B gnupghome Override GnuPG home directory. .TP .B trust Trust level for the key in the keychain, ignored by default. Valid trust levels: expired, unknown, not_trusted, marginally, fully, ultimately .TP .B keyring Limit the operation to this specific keyring, specified as a local filesystem path. .sp New in version 3007.0. .UNINDENT .UNINDENT .SS salt.states.grafana .sp Manage Grafana Dashboards .sp This module uses \fBelasticsearch\fP, which can be installed via package, or pip. .sp You can specify elasticsearch hosts directly to the module, or you can use an elasticsearch profile via pillars: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mygrafanaprofile: hosts: \- es1.example.com:9200 \- es2.example.com:9200 index: grafana\-dash .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Basic usage (uses default pillar profile key \(aqgrafana\(aq) Ensure myservice dashboard is managed: grafana.dashboard_present: \- name: myservice \- dashboard_from_pillar: default \- rows_from_pillar: \- systemhealth \- requests # Passing hosts in Ensure myservice dashboard is managed: grafana.dashboard_present: \- name: myservice \- dashboard_from_pillar: default \- rows: \- collapse: false editable: true height: 150px title: System Health panels: \- aliasColors: {} id: 200000 annotate: enable: false bars: false datasource: null editable: true error: false fill: 7 grid: leftMax: 100 leftMin: null rightMax: null rightMin: null threshold1: 60 threshold1Color: rgb(216, 27, 27) threshold2: null threshold2Color: rgba(234, 112, 112, 0.22) leftYAxisLabel: \(aq\(aq legend: avg: false current: false max: false min: false show: false total: false values: false lines: true linewidth: 1 nullPointMode: connected percentage: false pointradius: 5 points: false renderer: flot resolution: 100 scale: 1 seriesOverrides: [] span: 4 stack: false steppedLine: false targets: \- target: cloudwatch.aws.ec2.mysrv.cpuutilization.average title: CPU (asg average) tooltip: query_as_alias: true shared: false value_type: cumulative type: graph x\-axis: true y\-axis: true y_formats: \- short \- short zerofill: true \- rows_from_pillar: \- systemhealth \- requests \- profile: hosts: \- es1.example.com:9200 \- es2.example.com:9200 index: grafana\-dash # Using a profile from pillars Ensure myservice dashboard is managed: grafana.dashboard_present: \- name: myservice \- dashboard: annotations: enable: true list: [] editable: true hideAllLegends: false hideControls: false nav: \- collapse: false enable: true notice: false now: true refresh_intervals: \- 10s \- 30s \- 1m \- 5m \- 15m \- 30m \- 1h \- 2h \- 1d status: Stable time_options: \- 5m \- 15m \- 1h \- 2h \- 3h \- 4h \- 6h \- 12h \- 1d \- 2d \- 4d \- 7d \- 16d \- 30d type: timepicker originalTitle: dockerregistry refresh: 1m rows: [] sharedCrosshair: false style: dark tags: [] templating: enable: true list: [] time: from: now\-2h to: now timezone: browser \- rows_from_pillars: \- systemhealth \- requests \- profile: mygrafanaprofile .ft P .fi .UNINDENT .UNINDENT .sp The behavior of this module is to create dashboards if they do not exist, to add rows if they do not exist in existing dashboards, and to update rows if they exist in dashboards. The module will not manage rows that are not defined, allowing users to manage their own custom rows. .INDENT 0.0 .TP .B salt.states.grafana.dashboard_absent(name, hosts=None, profile=\(aqgrafana\(aq) Ensure the named grafana dashboard is deleted. .INDENT 7.0 .TP .B name Name of the grafana dashboard. .TP .B profile A pillar key or dict that contains a list of hosts and an elasticsearch index to use. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grafana.dashboard_present(name, dashboard=None, dashboard_from_pillar=None, rows=None, rows_from_pillar=None, profile=\(aqgrafana\(aq) Ensure the grafana dashboard exists and is managed. .INDENT 7.0 .TP .B name Name of the grafana dashboard. .TP .B dashboard A dict that defines a dashboard that should be managed. .TP .B dashboard_from_pillar A pillar key that contains a grafana dashboard dict. Mutually exclusive with dashboard. .TP .B rows A list of grafana rows. .TP .B rows_from_pillar A list of pillar keys that contain lists of grafana dashboard rows. Rows defined in the pillars will be appended to the rows defined in the state. .TP .B profile A pillar key or dict that contains a list of hosts and an elasticsearch index to use. .UNINDENT .UNINDENT .SS salt.states.grafana4_dashboard .sp Manage Grafana v4.0 Dashboards .sp New in version 2017.7.0. .INDENT 0.0 .TP .B configuration This state requires a configuration profile to be configured in the minion config, minion pillar, or master config. The module will use the \(aqgrafana\(aq key by default, if defined. .sp Example configuration using basic authentication: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grafana: grafana_url: http://grafana.localhost grafana_user: admin grafana_password: admin grafana_timeout: 3 .ft P .fi .UNINDENT .UNINDENT .sp Example configuration using token based authentication: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grafana: grafana_url: http://grafana.localhost grafana_token: token grafana_timeout: 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp The behavior of this module is to create dashboards if they do not exist, to add rows if they do not exist in existing dashboards, and to update rows if they exist in dashboards. The module will not manage rows that are not defined, allowing users to manage their own custom rows. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure minimum dashboard is managed: grafana4_dashboard.present: \- name: insightful\-dashboard \- base_dashboards_from_pillar: \- default_dashboard \- base_rows_from_pillar: \- default_row \- base_panels_from_pillar: \- default_panel \- dashboard: rows: \- title: Usage panels: \- targets: \- target: alias(constantLine(50), \(aqmax\(aq) title: Imaginary type: graph .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grafana4_dashboard.absent(name, orgname=None, profile=\(aqgrafana\(aq) Ensure the named grafana dashboard is absent. .INDENT 7.0 .TP .B name Name of the grafana dashboard. .TP .B orgname Name of the organization in which the dashboard should be present. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grafana4_dashboard.present(name, base_dashboards_from_pillar=None, base_panels_from_pillar=None, base_rows_from_pillar=None, dashboard=None, orgname=None, profile=\(aqgrafana\(aq) Ensure the grafana dashboard exists and is managed. .INDENT 7.0 .TP .B name Name of the grafana dashboard. .TP .B base_dashboards_from_pillar A pillar key that contains a list of dashboards to inherit from .TP .B base_panels_from_pillar A pillar key that contains a list of panels to inherit from .TP .B base_rows_from_pillar A pillar key that contains a list of rows to inherit from .TP .B dashboard A dict that defines a dashboard that should be managed. .TP .B orgname Name of the organization in which the dashboard should be present. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .UNINDENT .SS salt.states.grafana4_datasource .sp Manage Grafana v4.0 data sources .sp New in version 2017.7.0. .INDENT 0.0 .TP .B configuration This state requires a configuration profile to be configured in the minion config, minion pillar, or master config. The module will use the \(aqgrafana\(aq key by default, if defined. .sp Example configuration using basic authentication: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grafana: grafana_url: http://grafana.localhost grafana_user: admin grafana_password: admin grafana_timeout: 3 .ft P .fi .UNINDENT .UNINDENT .sp Example configuration using token based authentication: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grafana: grafana_url: http://grafana.localhost grafana_token: token grafana_timeout: 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp The behavior of this module is to create data sources if the do not exists, and to update data sources if the already exists. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure influxdb data source is present: grafana4_datasource.present: \- name: influxdb \- type: influxdb \- url: http://localhost:8086 \- access: proxy \- basic_auth: true \- basic_auth_user: myuser \- basic_auth_password: mypass \- is_default: true .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grafana4_datasource.absent(name, orgname=None, profile=\(aqgrafana\(aq) Ensure that a data source is present. .INDENT 7.0 .TP .B name Name of the data source to remove. .TP .B orgname Name of the organization from which the data source should be absent. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grafana4_datasource.present(name, type, url, access=None, user=None, password=None, database=None, basic_auth=None, basic_auth_user=None, basic_auth_password=None, tls_auth=None, json_data=None, is_default=None, with_credentials=None, type_logo_url=None, orgname=None, profile=\(aqgrafana\(aq) Ensure that a data source is present. .INDENT 7.0 .TP .B name Name of the data source. .TP .B type Type of the datasource (\(aqgraphite\(aq, \(aqinfluxdb\(aq etc.). .TP .B access Use proxy or direct. Default: proxy .TP .B url The URL to the data source API. .TP .B user Optional \- user to authenticate with the data source. .TP .B password Optional \- password to authenticate with the data source. .TP .B database Optional \- database to use with the data source. .TP .B basic_auth Optional \- set to True to use HTTP basic auth to authenticate with the data source. .TP .B basic_auth_user Optional \- HTTP basic auth username. .TP .B basic_auth_password Optional \- HTTP basic auth password. .TP .B json_data Optional \- additional json data to post (eg. \(dqtimeInterval\(dq). .TP .B is_default Optional \- set data source as default. .TP .B with_credentials Optional \- Whether credentials such as cookies or auth headers should be sent with cross\-site requests. .TP .B type_logo_url Optional \- Logo to use for this datasource. .TP .B orgname Name of the organization in which the data source should be present. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .UNINDENT .SS salt.states.grafana4_org .sp Manage Grafana v4.0 orgs .sp New in version 2017.7.0. .INDENT 0.0 .TP .B configuration This state requires a configuration profile to be configured in the minion config, minion pillar, or master config. The module will use the \(aqgrafana\(aq key by default, if defined. .sp Example configuration using basic authentication: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grafana: grafana_url: http://grafana.localhost grafana_user: admin grafana_password: admin grafana_timeout: 3 .ft P .fi .UNINDENT .UNINDENT .sp Example configuration using token based authentication: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grafana: grafana_url: http://grafana.localhost grafana_token: token grafana_timeout: 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure foobar org is present: grafana4_org.present: \- name: foobar \- theme: \(dq\(dq \- home_dashboard_id: 0 \- timezone: \(dqutc\(dq \- address1: \(dq\(dq \- address2: \(dq\(dq \- city: \(dq\(dq \- zip_code: \(dq\(dq \- state: \(dq\(dq \- country: \(dq\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grafana4_org.absent(name, profile=\(aqgrafana\(aq) Ensure that a org is present. .INDENT 7.0 .TP .B name Name of the org to remove. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grafana4_org.present(name, users=None, theme=None, home_dashboard_id=None, timezone=None, address1=None, address2=None, city=None, zip_code=None, address_state=None, country=None, profile=\(aqgrafana\(aq) Ensure that an organization is present. .INDENT 7.0 .TP .B name Name of the org. .TP .B users Optional \- Dict of user/role associated with the org. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C users: foo: Viewer bar: Editor .ft P .fi .UNINDENT .UNINDENT .TP .B theme Optional \- Selected theme for the org. .TP .B home_dashboard_id Optional \- Home dashboard for the org. .TP .B timezone Optional \- Timezone for the org (one of: \(dqbrowser\(dq, \(dqutc\(dq, or \(dq\(dq). .TP .B address1 Optional \- address1 of the org. .TP .B address2 Optional \- address2 of the org. .TP .B city Optional \- city of the org. .TP .B zip_code Optional \- zip_code of the org. .TP .B address_state Optional \- state of the org. .TP .B country Optional \- country of the org. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .UNINDENT .SS salt.states.grafana4_user .sp Manage Grafana v4.0 users .sp New in version 2017.7.0. .INDENT 0.0 .TP .B configuration This state requires a configuration profile to be configured in the minion config, minion pillar, or master config. The module will use the \(aqgrafana\(aq key by default, if defined. .sp Example configuration using basic authentication: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grafana: grafana_url: http://grafana.localhost grafana_user: admin grafana_password: admin grafana_timeout: 3 .ft P .fi .UNINDENT .UNINDENT .sp Example configuration using token based authentication: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grafana: grafana_url: http://grafana.localhost grafana_token: token grafana_timeout: 3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure foobar user is present: grafana4_user.present: \- name: foobar \- password: mypass \- email: \(dqfoobar@localhost\(dq \- fullname: Foo Bar \- is_admin: true .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grafana4_user.absent(name, profile=\(aqgrafana\(aq) Ensure that a user is present. .INDENT 7.0 .TP .B name Name of the user to remove. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grafana4_user.present(name, password, email, is_admin=False, fullname=None, theme=None, profile=\(aqgrafana\(aq) Ensure that a user is present. .INDENT 7.0 .TP .B name Name of the user. .TP .B password Password of the user. .TP .B email Email of the user. .TP .B is_admin Optional \- Set user as admin user. Default: False .TP .B fullname Optional \- Full name of the user. .TP .B theme Optional \- Selected theme of the user. .TP .B profile Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .UNINDENT .SS salt.states.grafana_dashboard .sp Manage Grafana v2.0 Dashboards .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grafana: grafana_timeout: 3 grafana_token: qwertyuiop grafana_url: \(aqhttps://url.com\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure minimum dashboard is managed: grafana_dashboard.present: \- name: insightful\-dashboard \- base_dashboards_from_pillar: \- default_dashboard \- base_rows_from_pillar: \- default_row \- base_panels_from_pillar: \- default_panel \- dashboard: rows: \- title: Usage panels: \- targets: \- target: alias(constantLine(50), \(aqmax\(aq) title: Imaginary type: graph .ft P .fi .UNINDENT .UNINDENT .sp The behavior of this module is to create dashboards if they do not exist, to add rows if they do not exist in existing dashboards, and to update rows if they exist in dashboards. The module will not manage rows that are not defined, allowing users to manage their own custom rows. .INDENT 0.0 .TP .B salt.states.grafana_dashboard.absent(name, profile=\(aqgrafana\(aq) Ensure the named grafana dashboard is absent. .INDENT 7.0 .TP .B name Name of the grafana dashboard. .TP .B profile A pillar key or dict that contains grafana information .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grafana_dashboard.present(name, base_dashboards_from_pillar=None, base_panels_from_pillar=None, base_rows_from_pillar=None, dashboard=None, profile=\(aqgrafana\(aq) Ensure the grafana dashboard exists and is managed. .INDENT 7.0 .TP .B name Name of the grafana dashboard. .TP .B base_dashboards_from_pillar A pillar key that contains a list of dashboards to inherit from .TP .B base_panels_from_pillar A pillar key that contains a list of panels to inherit from .TP .B base_rows_from_pillar A pillar key that contains a list of rows to inherit from .TP .B dashboard A dict that defines a dashboard that should be managed. .TP .B profile A pillar key or dict that contains grafana information .UNINDENT .UNINDENT .SS salt.states.grafana_datasource .sp Manage Grafana v2.0 data sources .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grafana: grafana_timeout: 3 grafana_token: qwertyuiop grafana_url: \(aqhttps://url.com\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Ensure influxdb data source is present: grafana_datasource.present: \- name: influxdb \- type: influxdb \- url: http://localhost:8086 \- access: proxy \- basic_auth: true \- basic_auth_user: myuser \- basic_auth_password: mypass \- is_default: true .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grafana_datasource.absent(name, profile=\(aqgrafana\(aq) Ensure that a data source is present. .INDENT 7.0 .TP .B name Name of the data source to remove. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grafana_datasource.present(name, type, url, access=\(aqproxy\(aq, user=\(aq\(aq, password=\(aq\(aq, database=\(aq\(aq, basic_auth=False, basic_auth_user=\(aq\(aq, basic_auth_password=\(aq\(aq, is_default=False, json_data=None, profile=\(aqgrafana\(aq) Ensure that a data source is present. .INDENT 7.0 .TP .B name Name of the data source. .TP .B type Which type of data source it is (\(aqgraphite\(aq, \(aqinfluxdb\(aq etc.). .TP .B url The URL to the data source API. .TP .B user Optional \- user to authenticate with the data source .TP .B password Optional \- password to authenticate with the data source .TP .B basic_auth Optional \- set to True to use HTTP basic auth to authenticate with the data source. .TP .B basic_auth_user Optional \- HTTP basic auth username. .TP .B basic_auth_password Optional \- HTTP basic auth password. .TP .B is_default Default: False .UNINDENT .UNINDENT .SS salt.states.grains .SS Manage grains on the minion .sp This state allows for grains to be set. .sp Grains set or altered with this module are stored in the \(aqgrains\(aq file on the minions, By default, this file is located at: \fB/etc/salt/grains\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This does \fBNOT\fP override any grains set in the minion config file. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grains.absent(name, destructive=False, delimiter=\(aq:\(aq, force=False) New in version 2014.7.0. .sp Delete a grain from the grains config file .INDENT 7.0 .TP .B name The grain name .TP .B destructive If destructive is True, delete the entire grain. If destructive is False, set the grain\(aqs value to None. Defaults to False. .TP .B force If force is True, the existing grain will be overwritten regardless of its existing or provided value type. Defaults to False .sp New in version 2015.8.2. .TP .B delimiter A delimiter different from the default can be provided. .sp New in version 2015.8.2. .UNINDENT .sp Changed in version 2015.8.2. .sp This state now support nested grains and complex values. It is also more conservative: if a grain has a value that is a list or a dict, it will not be removed unless the \fIforce\fP parameter is True. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grain_name: grains.absent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grains.append(name, value, convert=False, delimiter=\(aq:\(aq) New in version 2014.7.0. .sp Append a value to a list in the grains config file. The grain that is being appended to (name) must exist before the new value can be added. .INDENT 7.0 .TP .B name The grain name .TP .B value The value to append .TP .B convert If convert is True, convert non\-list contents into a list. If convert is False and the grain contains non\-list contents, an error is given. Defaults to False. .TP .B delimiter A delimiter different from the default can be provided. .sp New in version 2015.8.2. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C grain_name: grains.append: \- value: to_be_appended .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grains.exists(name, delimiter=\(aq:\(aq) Ensure that a grain is set .INDENT 7.0 .TP .B name The grain name .TP .B delimiter A delimiter different from the default can be provided. .UNINDENT .sp Check whether a grain exists. Does not attempt to check or set the value. .UNINDENT .INDENT 0.0 .TP .B salt.states.grains.list_absent(name, value, delimiter=\(aq:\(aq) Delete a value from a grain formed as a list. .sp New in version 2014.1.0. .INDENT 7.0 .TP .B name The grain name. .TP .B value The value to delete from the grain list. .TP .B delimiter A delimiter different from the default \fB:\fP can be provided. .sp New in version 2015.8.2. .UNINDENT .sp The grain should be \fI\%list type\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C roles: grains.list_absent: \- value: db .ft P .fi .UNINDENT .UNINDENT .sp For multiple grains, the syntax looks like: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C roles: grains.list_absent: \- value: \- web \- dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grains.list_present(name, value, delimiter=\(aq:\(aq) New in version 2014.1.0. .sp Ensure the value is present in the list\-type grain. Note: If the grain that is provided in \fBname\fP is not present on the system, this new grain will be created with the corresponding provided value. .INDENT 7.0 .TP .B name The grain name. .TP .B value The value is present in the list type grain. .TP .B delimiter A delimiter different from the default \fB:\fP can be provided. .sp New in version 2015.8.2. .UNINDENT .sp The grain should be \fI\%list type\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C roles: grains.list_present: \- value: web .ft P .fi .UNINDENT .UNINDENT .sp For multiple grains, the syntax looks like: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C roles: grains.list_present: \- value: \- web \- dev .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.grains.make_hashable(list_grain, result=None) Ensure that a list grain is hashable. .INDENT 7.0 .TP .B list_grain The list grain that should be hashable .TP .B result This function is recursive, so it must be possible to use a sublist as parameter to the function. Should not be used by a caller outside of the function. .UNINDENT .sp Make it possible to compare two list grains to each other if the list contains complex objects. .UNINDENT .INDENT 0.0 .TP .B salt.states.grains.present(name, value, delimiter=\(aq:\(aq, force=False) Ensure that a grain is set .sp Changed in version 2015.8.2. .INDENT 7.0 .TP .B name The grain name .TP .B value The value to set on the grain .TP .B force If force is True, the existing grain will be overwritten regardless of its existing or provided value type. Defaults to False .sp New in version 2015.8.2. .TP .B delimiter A delimiter different from the default can be provided. .sp New in version 2015.8.2. .UNINDENT .sp It is now capable to set a grain to a complex value (ie. lists and dicts) and supports nested grains as well. .sp If the grain does not yet exist, a new grain is set to the given value. For a nested grain, the necessary keys are created if they don\(aqt exist. If a given key is an existing value, it will be converted, but an existing value different from the given key will fail the state. .sp If the grain with the given name exists, its value is updated to the new value unless its existing or provided value is complex (list or dict). Use \fIforce: True\fP to overwrite. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cheese: grains.present: \- value: edam nested_grain_with_complex_value: grains.present: \- name: icinga:Apache SSL \- value: \- command: check_https \- params: \-H localhost \-p 443 \-S with,a,custom,delimiter: grains.present: \- value: yay \- delimiter: \(aq,\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.group .SS Management of user groups .sp The group module is used to create and manage group settings, groups can be either present or absent. User/Group names can be passed to the \fBadduser\fP, \fBdeluser\fP, and \fBmembers\fP parameters. \fBadduser\fP and \fBdeluser\fP can be used together but not with \fBmembers\fP\&. .sp In Windows, if no domain is specified in the user or group name (i.e. \fBDOMAIN\eusername\fP) the module will assume a local user or group. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cheese: group.present: \- gid: 7648 \- system: True \- addusers: \- user1 \- users2 \- delusers: \- foo cheese: group.present: \- gid: 7648 \- system: True \- members: \- foo \- bar \- user1 \- user2 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.group.absent(name, local=False) Ensure that the named group is absent .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the group to remove .IP \(bu 2 \fBlocal\fP (\fIOnly on systems with lgroupdel available\fP) \-\- .sp Ensure the group account is removed locally ignoring global account management (default is False). .sp New in version 3007.0. .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Removes the local group \(gadb_admin\(ga db_admin: group.absent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.group.present(name, gid=None, system=False, addusers=None, delusers=None, members=None, non_unique=False, local=False) Changed in version 3006.0. .sp Ensure that a group is present .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the group to manage .IP \(bu 2 \fBgid\fP (\fI\%str\fP) \-\- The group id to assign to the named group; if left empty, then the next available group id will be assigned. Ignored on Windows .IP \(bu 2 \fBsystem\fP (\fI\%bool\fP) \-\- Whether or not the named group is a system group. This is essentially the \(aq\-r\(aq option of \(aqgroupadd\(aq. Ignored on Windows .IP \(bu 2 \fBaddusers\fP (\fI\%list\fP) \-\- List of additional users to be added as a group members. Cannot conflict with names in delusers. Cannot be used in conjunction with members. .IP \(bu 2 \fBdelusers\fP (\fI\%list\fP) \-\- Ensure these user are removed from the group membership. Cannot conflict with names in addusers. Cannot be used in conjunction with members. .IP \(bu 2 \fBmembers\fP (\fI\%list\fP) \-\- Replace existing group members with a list of new members. Cannot be used in conjunction with addusers or delusers. .IP \(bu 2 \fBnon_unique\fP (\fI\%bool\fP) \-\- .sp Allow creating groups with duplicate (non\-unique) GIDs .sp New in version 3006.0. .IP \(bu 2 \fBlocal\fP (\fIOnly on systems with lgroupadd available\fP) \-\- .sp Create the group account locally ignoring global account management (default is False). .sp New in version 3007.0. .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Adds DOMAIN\edb_admins and Administrators to the local db_admin group # Removes Users db_admin: group.present: \- addusers: \- DOMAIN\edb_admins \- Administrators \- delusers: \- Users # Ensures only DOMAIN\edomain_admins and the local Administrator are # members of the local Administrators group. All other users are # removed Administrators: group.present: \- members: \- DOMAIN\edomain_admins \- Administrator .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.heat .SS Management of Heat .sp New in version 2017.7.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 heat Python module .UNINDENT .TP .B configuration See \fI\%salt.modules.heat\fP for setup instructions. .UNINDENT .sp The heat module is used to create, show, list and delete Heat staks. Stack can be set as either absent or deploy. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C heat.deployed: \- name: \- template: #Required \- environment: \- params: {} \- poll: 5 \- rollback: False \- timeout: 60 heat.absent: \- name: \- poll: 5 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B mysql: .INDENT 7.0 .TP .B heat.deployed: .INDENT 7.0 .IP \(bu 2 template: salt://templates/mysql.heat.yaml .IP \(bu 2 params: image: Debian 7 .IP \(bu 2 rollback: True .UNINDENT .UNINDENT .UNINDENT .sp New in version 2017.7.5,2018.3.1: The spelling mistake in parameter \fIenviroment\fP was corrected to \fIenvironment\fP\&. The \fIenviroment\fP spelling mistake has been removed in Salt 3000. .INDENT 0.0 .TP .B salt.states.heat.absent(name, poll=5, timeout=60, profile=None) Ensure that the named stack is absent .INDENT 7.0 .TP .B name The name of the stack to remove .TP .B poll Poll(in sec.) and report events until stack complete .TP .B timeout Stack creation timeout in minutes .TP .B profile Profile to use .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.heat.deployed(name, template=None, environment=None, params=None, poll=5, rollback=False, timeout=60, update=False, profile=None, **connection_args) Deploy stack with the specified properties .INDENT 7.0 .TP .B name The name of the stack .TP .B template File of template .TP .B environment File of environment .TP .B params Parameter dict used to create the stack .TP .B poll Poll (in sec.) and report events until stack complete .TP .B rollback Enable rollback on create failure .TP .B timeout Stack creation timeout in minutes .TP .B profile Profile to use .UNINDENT .sp New in version 2017.7.5,2018.3.1: The spelling mistake in parameter \fIenviroment\fP was corrected to \fIenvironment\fP\&. The \fIenviroment\fP spelling mistake has been removed in Salt 3000. .UNINDENT .SS salt.states.helm .INDENT 0.0 .TP .B salt.states.helm.release_absent(name, namespace=None, flags=None, kvflags=None) Make sure the release name is absent. .INDENT 7.0 .TP .B name (string) The release name to uninstall. .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C helm_release_is_absent: helm.release_absent: \- name: release_name # In dry\-run mode. helm_release_is_absent_dry\-run: helm.release_absent: \- name: release_name \- flags: \- dry\-run .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.helm.release_present(name, chart, values=None, version=None, namespace=None, set=None, flags=None, kvflags=None) Make sure the release name is present. .INDENT 7.0 .TP .B name (string) The release name to install. .TP .B chart (string) The chart to install. .TP .B values (string) Absolute path to the values.yaml file. .TP .B version (string) The exact chart version to install. If this is not specified, the latest version is installed. .TP .B namespace (string) The namespace scope for this request. .TP .B set (string or list) Set a values on the command line. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C helm_release_is_present: helm.release_present: \- name: release_name \- chart: repo/chart # In dry\-run mode. helm_release_is_present_dry\-run: helm.release_present: \- name: release_name \- chart: repo/chart \- flags: \- dry\-run # With values.yaml file. helm_release_is_present_values: helm.release_present: \- name: release_name \- chart: repo/chart \- kvflags: values: /path/to/values.yaml .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.helm.repo_managed(name, present=None, absent=None, prune=False, repo_update=False, namespace=None, flags=None, kvflags=None) Make sure the repository is updated. .INDENT 7.0 .TP .B name (string) Not used. .TP .B present (list) List of repository to be present. It\(aqs a list of dict: [{\(aqname\(aq: \(aqlocal_name\(aq, \(aqurl\(aq: \(aqrepository_url\(aq}] .TP .B absent (list) List of local name repository to be absent. .TP .B prune (boolean \- default: False) If True, all repository already present but not in the present list would be removed. .TP .B repo_update (boolean \- default: False) If True, the Helm repository is updated after a repository add or remove. .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C helm_repository_is_managed: helm.repo_managed: \- present: \- name: local_name_1 url: repository_url \- absent: \- local_name_2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.helm.repo_updated(name, namespace=None, flags=None, kvflags=None) Make sure the repository is updated. To execute after a repository changes. .INDENT 7.0 .TP .B name (string) Not used. .TP .B namespace (string) The namespace scope for this request. .TP .B flags (list) Flags in argument of the command without values. ex: [\(aqhelp\(aq, \(aq\-\-help\(aq] .TP .B kvflags (dict) Flags in argument of the command with values. ex: {\(aqv\(aq: 2, \(aq\-\-v\(aq: 4} .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C helm_repository_is_updated: helm.repo_updated .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.hg .SS Interaction with Mercurial repositories .sp Before using hg over ssh, make sure the remote host fingerprint already exists in ~/.ssh/known_hosts, and the remote host has this host\(aqs public key. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C https://bitbucket.org/example_user/example_repo: hg.latest: \- rev: tip \- target: /tmp/example_repo .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.hg.latest(name, rev=None, target=None, clean=False, user=None, identity=None, force=False, opts=False, update_head=True) Make sure the repository is cloned to the given directory and is up to date .INDENT 7.0 .TP .B name Address of the remote repository as passed to \(dqhg clone\(dq .TP .B rev The remote branch, tag, or revision hash to clone/pull .TP .B target Target destination directory path on minion to clone into .TP .B clean Force a clean update with \-C (Default: False) .TP .B user Name of the user performing repository management operations .sp New in version 0.17.0. .TP .B identity Private SSH key on the minion server for authentication (\fI\%ssh://\fP) .sp New in version 2015.5.0. .TP .B force Force hg to clone into pre\-existing directories (deletes contents) .TP .B opts Include additional arguments and options to the hg command line .TP .B update_head Should we update the head if new changes are found? Defaults to True .sp New in version 2017.7.0. .UNINDENT .UNINDENT .SS salt.states.highstate_doc .sp To be used with processors in module \fIhighstate_doc\fP\&. .INDENT 0.0 .TP .B salt.states.highstate_doc.note(name, source=None, contents=None, **kwargs) Add content to a document generated using \fIhighstate_doc.render\fP\&. .sp This state does not preform any tasks on the host. It only is used in highstate_doc lowstate processors to include extra documents. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {{sls}} example note: highstate_doc.note: \- name: example note \- require_in: \- pkg: somepackage \- contents: | example \(gahighstate_doc.note\(ga \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- This state does not do anything to the system! It is only used by a \(gaprocessor\(ga you can use \(garequisites\(ga and \(gaorder\(ga to move your docs around the rendered file. .. this message appare above the \(gapkg: somepackage\(ga state. \- source: salt://{{tpldir}}/also_include_a_file.md {{sls}} extra help: highstate_doc.note: \- name: example \- order: 0 \- source: salt://{{tpldir}}/HELP.md .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.host .SS Management of addresses and names in hosts file .sp The \fB/etc/hosts\fP file can be managed to contain definitions for specific hosts: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-master: host.present: \- ip: 192.168.0.42 .ft P .fi .UNINDENT .UNINDENT .sp Or using the \fBnames\fP directive, you can put several names for the same IP. (Do not try one name with space\-separated values). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C server1: host.present: \- ip: 192.168.0.42 \- names: \- server1 \- florida .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changing the \fBnames\fP in \fBhost.present\fP does not cause an update to remove the old entry. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C server1: host.present: \- ip: \- 192.168.0.42 \- 192.168.0.43 \- 192.168.0.44 \- names: \- server1 .ft P .fi .UNINDENT .UNINDENT .sp You can replace all existing names for a particular IP address: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 127.0.1.1: host.only: \- hostnames: \- foo.example.com \- foo .ft P .fi .UNINDENT .UNINDENT .sp Or delete all existing names for an address: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 203.0.113.25: host.only: \- hostnames: [] .ft P .fi .UNINDENT .UNINDENT .sp You can also include comments: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C server1: host.present: \- ip: 192.168.0.42 \- names: \- server1 \- florida \- comment: A very important comment .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.host.absent(name, ip) Ensure that the named host is absent .INDENT 7.0 .TP .B name The host to remove .TP .B ip The ip addr(s) of the host to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.host.only(name, hostnames) Ensure that only the given hostnames are associated with the given IP address. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The IP address to associate with the given hostnames. .TP .B hostnames Either a single hostname or a list of hostnames to associate with the given IP address in the given order. Any other hostname associated with the IP address is removed. If no hostnames are specified, all hostnames associated with the given IP address are removed. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.host.present(name, ip, comment=\(aq\(aq, clean=False) Ensures that the named host is present with the given ip .INDENT 7.0 .TP .B name The host to assign an ip to .TP .B ip The ip addr(s) to apply to the host. Can be a single IP or a list of IP addresses. .TP .B comment A comment to include for the host entry .sp New in version 3001. .TP .B clean Remove any entries which don\(aqt match those configured in the \fBip\fP option. Default is \fBFalse\fP\&. .sp New in version 2018.3.4. .UNINDENT .UNINDENT .SS salt.states.http .sp HTTP monitoring states .sp Perform an HTTP query and statefully return the result .sp New in version 2015.5.0. .INDENT 0.0 .TP .B salt.states.http.query(name, match=None, match_type=\(aqstring\(aq, status=None, status_type=\(aqstring\(aq, wait_for=None, **kwargs) Perform an HTTP query and statefully return the result .sp Passes through all the parameters described in the \fI\%utils.http.query function\fP: .INDENT 7.0 .TP .B name The name of the query. .TP .B match 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. .TP .B match_type Specifies the type of pattern matching to use on match. Default is \fBstring\fP, but can also be set to \fBpcre\fP to use regular expression matching if a more complex pattern matching is required. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Despite the name of \fBmatch_type\fP for this argument, this setting actually uses Python\(aqs \fBre.search()\fP function rather than Python\(aqs \fBre.match()\fP function. .UNINDENT .UNINDENT .TP .B status The status code for a URL for which to be checked. Can be used instead of or in addition to the \fBmatch\fP setting. This can be passed as an individual status code or a list of status codes. .TP .B status_type Specifies the type of pattern matching to use for status. Default is \fBstring\fP, but can also be set to \fBpcre\fP to use regular expression matching if a more complex pattern matching is required. Additionally, if a list of strings representing statuses is given, the type \fBlist\fP can be used. .sp New in version 3000. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Despite the name of \fBmatch_type\fP for this argument, this setting actually uses Python\(aqs \fBre.search()\fP function rather than Python\(aqs \fBre.match()\fP function. .UNINDENT .UNINDENT .UNINDENT .sp If both \fBmatch\fP and \fBstatus\fP options are set, both settings will be checked. However, note that if only one option is \fBTrue\fP and the other is \fBFalse\fP, then \fBFalse\fP will be returned. If this case is reached, the comments in the return data will contain troubleshooting information. .sp For more information about the \fBhttp.query\fP state, refer to the \fI\%HTTP Tutorial\fP\&. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C query_example: http.query: \- name: \(aqhttp://example.com/\(aq \- status: 200 query_example2: http.query: \- name: \(aqhttp://example.com/\(aq \- status: \- 200 \- 201 \- status_type: list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.http.wait_for_successful_query(name, wait_for=300, **kwargs) Like query but, repeat and wait until match/match_type or status is fulfilled. State returns result from last query state in case of success or if no successful query was made within wait_for timeout. .INDENT 7.0 .TP .B name The name of the query. .TP .B wait_for Total time to wait for requests that succeed. .TP .B request_interval Optional interval to delay requests by N seconds to reduce the number of requests sent. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 All other arguments are passed to the http.query state. .UNINDENT .UNINDENT .UNINDENT .SS salt.states.icinga2 .SS Icinga2 state .sp New in version 2017.7.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 Icinga2 Python module .UNINDENT .TP .B configuration See \fI\%salt.modules.icinga2\fP for setup instructions. .UNINDENT .sp The icinga2 module is used to execute commands. Its output may be stored in a file or in a grain. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C command_id: icinga2.generate_ticket: \- name: domain.tld \- output: \(dq/tmp/query_id.txt\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.icinga2.generate_cert(name) Generate an icinga2 certificate and key on the client. .INDENT 7.0 .TP .B name The domain name for which this certificate and key will be generated .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.icinga2.generate_ticket(name, output=None, grain=None, key=None, overwrite=True) Generate an icinga2 ticket on the master. .INDENT 7.0 .TP .B name The domain name for which this ticket will be generated .TP .B output grain: output in a grain other: the file to store results None: output to the result comment (default) .TP .B grain: grain to store the output (need output=grain) .TP .B key: the specified grain will be treated as a dictionary, the result of this state will be stored under the specified key. .TP .B overwrite: The file or grain will be overwritten if it already exists (default) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.icinga2.node_setup(name, master, ticket) Setup the icinga2 node. .INDENT 7.0 .TP .B name The domain name for which this certificate will be saved .TP .B master Icinga2 master node for which this certificate will be saved .TP .B ticket Authentication ticket generated on icinga2 master .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.icinga2.request_cert(name, master, ticket, port=\(aq5665\(aq) Request CA certificate from master icinga2 node. .INDENT 7.0 .TP .B name The domain name for which this certificate will be saved .TP .B master Icinga2 master node for which this certificate will be saved .TP .B ticket Authentication ticket generated on icinga2 master .TP .B port Icinga2 port, defaults to 5665 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.icinga2.save_cert(name, master) Save the certificate on master icinga2 node. .INDENT 7.0 .TP .B name The domain name for which this certificate will be saved .TP .B master Icinga2 master node for which this certificate will be saved .UNINDENT .UNINDENT .SS salt.states.idem .SS Idem Support .sp This state provides access to idem states .sp New in version 3002. .INDENT 0.0 .TP .B salt.states.idem.state(name, sls, acct_file=None, acct_key=None, acct_profile=None, cache_dir=None, render=None, runtime=None, source_dir=None, test=False) Execute an idem sls file through a salt state .INDENT 7.0 .TP .B sls A list of idem sls files or sources .TP .B acct_file Path to the acct file used in generating idem ctx parameters. Defaults to the value in the ACCT_FILE environment variable. .TP .B acct_key Key used to decrypt the acct file. Defaults to the value in the ACCT_KEY environment variable. .TP .B acct_profile Name of the profile to add to idem\(aqs ctx.acct parameter Defaults to the value in the ACCT_PROFILE environment variable. .TP .B cache_dir The location to use for the cache directory .TP .B render The render pipe to use, this allows for the language to be specified (jinja|yaml) .TP .B runtime Select which execution runtime to use (serial|parallel) .TP .B source_dir The directory containing sls files .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cheese: idem.state: \- runtime: parallel \- sls: \- idem_state.sls \- sls_source .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Maturity new .TP .B Depends acct, pop, pop\-config, idem .TP .B Platform all .UNINDENT .UNINDENT .SS salt.states.ifttt .SS Trigger an event in IFTTT .sp This state is useful for trigging events in IFTTT. .sp New in version 2015.8.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ifttt\-event: ifttt.trigger_event: \- event: TestEvent \- value1: \(aqThis state was executed successfully.\(aq \- value2: \(aqAnother value we can send.\(aq \- value3: \(aqA third value we can send.\(aq .ft P .fi .UNINDENT .UNINDENT .sp The api key can be specified in the master or minion configuration like below: \&.. code\-block:: yaml .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B ifttt: secret_key: bzMRb\-KKIAaNOwKEEw792J7Eb\-B3z7muhdhYblJn4V6 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ifttt.trigger_event(name, event, value1=None, value2=None, value3=None) Trigger an event in IFTTT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ifttt\-event: ifttt.trigger_event: \- event: TestEvent \- value1: \(aqA value that we want to send.\(aq \- value2: \(aqA second value that we want to send.\(aq \- value3: \(aqA third value that we want to send.\(aq .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B name The unique name for this event. .TP .B event The name of the event to trigger in IFTTT. .UNINDENT .sp The following parameters are optional: .INDENT 7.0 .TP .B value1 One of the values that we can send to IFTT. .TP .B value2 One of the values that we can send to IFTT. .TP .B value3 One of the values that we can send to IFTT. .UNINDENT .UNINDENT .SS salt.states.incron .SS Management of incron, the inotify cron .sp The incron state module allows for user incrontabs to be cleanly managed. .sp Incron declarations require a number of parameters. The parameters needed to be declared: \fBpath\fP, \fBmask\fP, and \fBcmd\fP\&. The \fBuser\fP whose incrontab is to be edited also needs to be defined. .sp When making changes to an existing incron job, the \fBpath\fP declaration is the unique factor, so if an existing cron that looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Watch for modifications in /home/user: incron.present: \- user: root \- path: /home/user \- mask: \- IN_MODIFY \- cmd: \(aqecho \(dq$$ $@\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .sp Is changed to this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Watch for modifications and access in /home/user: incron.present: \- user: root \- path: /home/user \- mask: \- IN_MODIFY \- IN_ACCESS \- cmd: \(aqecho \(dq$$ $@\(dq\(aq .ft P .fi .UNINDENT .UNINDENT .sp Then the existing cron will be updated, but if the cron command is changed, then a new cron job will be added to the user\(aqs crontab. .sp New in version 0.17.0. .INDENT 0.0 .TP .B salt.states.incron.absent(name, path, mask, cmd, user=\(aqroot\(aq) Verifies that the specified incron job is absent for the specified user; only the name is matched when removing a incron job. .INDENT 7.0 .TP .B name Unique comment describing the entry .TP .B path The path that should be watched .TP .B user The name of the user who\(aqs crontab needs to be modified, defaults to the root user .TP .B mask The mask of events that should be monitored for .TP .B cmd The cmd that should be executed .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.incron.present(name, path, mask, cmd, user=\(aqroot\(aq) Verifies that the specified incron job is present for the specified user. For more advanced information about what exactly can be set in the cron timing parameters, check your incron system\(aqs documentation. Most Unix\-like systems\(aq incron documentation can be found via the incrontab man page: \fBman 5 incrontab\fP\&. .INDENT 7.0 .TP .B name Unique comment describing the entry .TP .B path The path that should be watched .TP .B user The name of the user who\(aqs crontab needs to be modified, defaults to the root user .TP .B mask The mask of events that should be monitored for .TP .B cmd The cmd that should be executed .UNINDENT .UNINDENT .SS salt.states.influxdb08_database .SS Management of Influxdb 0.8 databases .sp (compatible with InfluxDB version 0.5\-0.8) .sp New in version 2014.7.0. .INDENT 0.0 .TP .B salt.states.influxdb08_database.absent(name, user=None, password=None, host=None, port=None) Ensure that the named database is absent .INDENT 7.0 .TP .B name The name of the database to remove .TP .B user The user to connect as (must be able to remove the database) .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.influxdb08_database.present(name, user=None, password=None, host=None, port=None) Ensure that the named database is present .INDENT 7.0 .TP .B name The name of the database to create .TP .B user The user to connect as (must be able to remove the database) .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .UNINDENT .SS salt.states.influxdb08_user .SS Management of InfluxDB 0.8 users .sp (compatible with InfluxDB version 0.5\-0.8) .sp New in version 2014.7.0. .INDENT 0.0 .TP .B salt.states.influxdb08_user.absent(name, database=None, user=None, password=None, host=None, port=None) Ensure that the named cluster admin or database user is absent. .INDENT 7.0 .TP .B name The name of the user to remove .TP .B database The database to remove the user from .TP .B user The user to connect as (must be able to remove the user) .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.influxdb08_user.present(name, passwd, database=None, user=None, password=None, host=None, port=None) Ensure that the cluster admin or database user is present. .INDENT 7.0 .TP .B name The name of the user to manage .TP .B passwd The password of the user .TP .B database The database to create the user in .TP .B user The user to connect as (must be able to create the user) .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .UNINDENT .UNINDENT .SS salt.states.influxdb_continuous_query .SS Management of Influxdb continuous queries .sp New in version 2017.7.0. .sp (compatible with InfluxDB version 0.9+) .INDENT 0.0 .TP .B salt.states.influxdb_continuous_query.absent(name, database, **client_args) Ensure that given continuous query is absent. .INDENT 7.0 .TP .B name Name of the continuous query to remove. .TP .B database Name of the database that the continuous query was defined on. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.influxdb_continuous_query.present(name, database, query, resample_time=None, coverage_period=None, **client_args) Ensure that given continuous query is present. .INDENT 7.0 .TP .B name Name of the continuous query to create. .TP .B database Database to create continuous query on. .TP .B query The query content .TP .B resample_time None Duration between continuous query resampling. .TP .B coverage_period None Duration specifying time period per sample. .UNINDENT .UNINDENT .SS salt.states.influxdb_database .SS Management of Influxdb databases .sp (compatible with InfluxDB version 0.9+) .INDENT 0.0 .TP .B salt.states.influxdb_database.absent(name, **client_args) Ensure that given database is absent. .INDENT 7.0 .TP .B name Name of the database to remove. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.influxdb_database.present(name, **client_args) Ensure that given database is present. .INDENT 7.0 .TP .B name Name of the database to create. .UNINDENT .UNINDENT .SS salt.states.influxdb_retention_policy .SS Management of Influxdb retention policies .sp New in version 2017.7.0. .sp (compatible with InfluxDB version 0.9+) .INDENT 0.0 .TP .B salt.states.influxdb_retention_policy.absent(name, database, **client_args) Ensure that given retention policy is absent. .INDENT 7.0 .TP .B name Name of the retention policy to remove. .TP .B database Name of the database that the retention policy was defined on. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.influxdb_retention_policy.convert_duration(duration) Convert the a duration string into XXhYYmZZs format .INDENT 7.0 .TP .B duration Duration to convert .TP .B Returns: duration_string String representation of duration in XXhYYmZZs format .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.influxdb_retention_policy.present(name, database, duration=\(aq7d\(aq, replication=1, default=False, **client_args) Ensure that given retention policy is present. .INDENT 7.0 .TP .B name Name of the retention policy to create. .TP .B database Database to create retention policy on. .UNINDENT .UNINDENT .SS salt.states.influxdb_user .SS Management of InfluxDB users .sp (compatible with InfluxDB version 0.9+) .INDENT 0.0 .TP .B salt.states.influxdb_user.absent(name, **client_args) Ensure that given user is absent. .INDENT 7.0 .TP .B name The name of the user to manage .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.influxdb_user.present(name, passwd, admin=False, grants=None, **client_args) Ensure that given user is present. .INDENT 7.0 .TP .B name Name of the user to manage .TP .B passwd Password of the user .TP .B admin False Whether the user should have cluster administration privileges or not. .TP .B grants Optional \- Dict of database:privilege items associated with the user. Example: .INDENT 7.0 .TP .B grants: foo_db: read bar_db: all .UNINDENT .UNINDENT .sp \fBExample:\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C example user present in influxdb: influxdb_user.present: \- name: example \- passwd: somepassword \- admin: False \- grants: foo_db: read bar_db: all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.infoblox_a .sp Infoblox A record management. .sp functions accept api_opts: .INDENT 0.0 .INDENT 3.5 api_verifyssl: verify SSL [default to True or pillar value] api_url: server to connect to [default to pillar value] api_username: [default to pillar value] api_password: [default to pillar value] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.infoblox_a.absent(name=None, ipv4addr=None, **api_opts) Ensure infoblox A record is removed. .sp State example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C infoblox_a.absent: \- name: example\-ha\-0.domain.com infoblox_a.absent: \- name: \- ipv4addr: 127.0.23.23 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.infoblox_a.present(name=None, ipv4addr=None, data=None, ensure_data=True, **api_opts) Ensure infoblox A record. .sp When you wish to update a hostname ensure \fIname\fP is set to the hostname of the current record. You can give a new name in the \fIdata.name\fP\&. .sp State example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C infoblox_a.present: \- name: example\-ha\-0.domain.com \- data: name: example\-ha\-0.domain.com ipv4addr: 123.0.31.2 view: Internal .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.infoblox_cname .sp Infoblox CNAME management. .sp functions accept api_opts: .INDENT 0.0 .INDENT 3.5 api_verifyssl: verify SSL [default to True or pillar value] api_url: server to connect to [default to pillar value] api_username: [default to pillar value] api_password: [default to pillar value] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.infoblox_cname.absent(name=None, canonical=None, **api_opts) Ensure the CNAME with the given name or canonical name is removed .UNINDENT .INDENT 0.0 .TP .B salt.states.infoblox_cname.present(name=None, data=None, ensure_data=True, **api_opts) Ensure the CNAME with the given data is present. .INDENT 7.0 .TP .B name CNAME of record .TP .B data raw CNAME api data see: \fI\%https://INFOBLOX/wapidoc\fP .UNINDENT .sp State example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C infoblox_cname.present: \- name: example\-ha\-0.domain.com \- data: name: example\-ha\-0.domain.com canonical: example.domain.com zone: example.com view: Internal comment: Example comment infoblox_cname.present: \- name: example\-ha\-0.domain.com \- data: name: example\-ha\-0.domain.com canonical: example.domain.com zone: example.com view: Internal comment: Example comment \- api_url: https://INFOBLOX/wapi/v1.2.1 \- api_username: username \- api_password: passwd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.infoblox_host_record .sp Infoblox host record management. .sp functions accept api_opts: .INDENT 0.0 .INDENT 3.5 api_verifyssl: verify SSL [default to True or pillar value] api_url: server to connect to [default to pillar value] api_username: [default to pillar value] api_password: [default to pillar value] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.infoblox_host_record.absent(name=None, ipv4addr=None, mac=None, **api_opts) Ensure the host with the given Name ipv4addr or mac is removed. .sp State example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C infoblox_host_record.absent: \- name: hostname.of.record.to.remove infoblox_host_record.absent: \- name: \- ipv4addr: 192.168.0.1 infoblox_host_record.absent: \- name: \- mac: 12:02:12:31:23:43 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.infoblox_host_record.present(name=None, data=None, ensure_data=True, **api_opts) This will ensure that a host with the provided name exists. This will try to ensure that the state of the host matches the given data If the host is not found then one will be created. .sp When trying to update a hostname ensure \fIname\fP is set to the hostname of the current record. You can give a new name in the \fIdata.name\fP\&. .INDENT 7.0 .TP .B Avoid race conditions, use func:nextavailableip: .INDENT 7.0 .IP \(bu 2 func:nextavailableip:network/ZG54dfgsrDFEFfsfsLzA:10.0.0.0/8/default .IP \(bu 2 func:nextavailableip:10.0.0.0/8 .IP \(bu 2 func:nextavailableip:10.0.0.0/8,externalconfigure_for_dns .IP \(bu 2 func:nextavailableip:10.0.0.3\-10.0.0.10 .UNINDENT .UNINDENT .sp State Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # this would update \(gaoriginal_hostname.example.ca\(ga to changed \(gadata\(ga. infoblox_host_record.present: \- name: original_hostname.example.ca \- data: {\(aqnamhostname.example.cae\(aq: \(aqhostname.example.ca\(aq, \(aqaliases\(aq: [\(aqhostname.math.example.ca\(aq], \(aqextattrs\(aq: [{\(aqBusiness Contact\(aq: {\(aqvalue\(aq: \(aqEXAMPLE@example.ca\(aq}}], \(aqipv4addrs\(aq: [{\(aqconfigure_for_dhcp\(aq: True, \(aqipv4addr\(aq: \(aqfunc:nextavailableip:129.97.139.0/24\(aq, \(aqmac\(aq: \(aq00:50:56:84:6e:ae\(aq}], \(aqipv6addrs\(aq: [], } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.infoblox_range .sp Infoblox host record management. .sp functions accept api_opts: .INDENT 0.0 .INDENT 3.5 api_verifyssl: verify SSL [default to True or pillar value] api_url: server to connect to [default to pillar value] api_username: [default to pillar value] api_password: [default to pillar value] .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.infoblox_range.absent(name=None, start_addr=None, end_addr=None, data=None, **api_opts) Ensure the range is removed .sp Supplying the end of the range is optional. .sp State example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C infoblox_range.absent: \- name: \(aqvlan10\(aq infoblox_range.absent: \- name: \- start_addr: 127.0.1.20 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.infoblox_range.present(name=None, start_addr=None, end_addr=None, data=None, **api_opts) Ensure range record is present. .INDENT 7.0 .TP .B infoblox_range.present: start_addr: \(aq129.97.150.160\(aq, end_addr: \(aq129.97.150.170\(aq, .UNINDENT .sp Verbose state example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C infoblox_range.present: data: { \(aqalways_update_dns\(aq: False, \(aqauthority\(aq: False, \(aqcomment\(aq: \(aqrange of IP addresses used for salt.. was used for ghost images deployment\(aq, \(aqddns_generate_hostname\(aq: True, \(aqdeny_all_clients\(aq: False, \(aqdeny_bootp\(aq: False, \(aqdisable\(aq: False, \(aqemail_list\(aq: [], \(aqenable_ddns\(aq: False, \(aqenable_dhcp_thresholds\(aq: False, \(aqenable_email_warnings\(aq: False, \(aqenable_ifmap_publishing\(aq: False, \(aqenable_snmp_warnings\(aq: False, \(aqend_addr\(aq: \(aq129.97.150.169\(aq, \(aqexclude\(aq: [], \(aqextattrs\(aq: {}, \(aqfingerprint_filter_rules\(aq: [], \(aqhigh_water_mark\(aq: 95, \(aqhigh_water_mark_reset\(aq: 85, \(aqignore_dhcp_option_list_request\(aq: False, \(aqlease_scavenge_time\(aq: \-1, \(aqlogic_filter_rules\(aq: [], \(aqlow_water_mark\(aq: 0, \(aqlow_water_mark_reset\(aq: 10, \(aqmac_filter_rules\(aq: [], \(aqmember\(aq: {\(aq_struct\(aq: \(aqdhcpmember\(aq, \(aqipv4addr\(aq: \(aq129.97.128.9\(aq, \(aqname\(aq: \(aqcn\-dhcp\-mc.example.ca\(aq}, \(aqms_options\(aq: [], \(aqnac_filter_rules\(aq: [], \(aqname\(aq: \(aqghost\-range\(aq, \(aqnetwork\(aq: \(aq129.97.150.0/24\(aq, \(aqnetwork_view\(aq: \(aqdefault\(aq, \(aqoption_filter_rules\(aq: [], \(aqoptions\(aq: [{\(aqname\(aq: \(aqdhcp\-lease\-time\(aq, \(aqnum\(aq: 51, \(aquse_option\(aq: False, \(aqvalue\(aq: \(aq43200\(aq, \(aqvendor_class\(aq: \(aqDHCP\(aq}], \(aqrecycle_leases\(aq: True, \(aqrelay_agent_filter_rules\(aq: [], \(aqserver_association_type\(aq: \(aqMEMBER\(aq, \(aqstart_addr\(aq: \(aq129.97.150.160\(aq, \(aqupdate_dns_on_lease_renewal\(aq: False, \(aquse_authority\(aq: False, \(aquse_bootfile\(aq: False, \(aquse_bootserver\(aq: False, \(aquse_ddns_domainname\(aq: False, \(aquse_ddns_generate_hostname\(aq: True, \(aquse_deny_bootp\(aq: False, \(aquse_email_list\(aq: False, \(aquse_enable_ddns\(aq: False, \(aquse_enable_dhcp_thresholds\(aq: False, \(aquse_enable_ifmap_publishing\(aq: False, \(aquse_ignore_dhcp_option_list_request\(aq: False, \(aquse_known_clients\(aq: False, \(aquse_lease_scavenge_time\(aq: False, \(aquse_nextserver\(aq: False, \(aquse_options\(aq: False, \(aquse_recycle_leases\(aq: False, \(aquse_unknown_clients\(aq: False, \(aquse_update_dns_on_lease_renewal\(aq: False } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.ini_manage .SS Manage ini files .INDENT 0.0 .TP .B maintainer <\fI\%akilesh1597@gmail.com\fP> .TP .B maturity new .TP .B depends re .TP .B platform all .UNINDENT .INDENT 0.0 .TP .B salt.states.ini_manage.options_absent(name, sections=None, separator=\(aq=\(aq) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /home/saltminion/api\-paste.ini: ini.options_absent: \- separator: \(aq=\(aq \- sections: test: \- testkey \- secondoption test1: \- testkey1 .ft P .fi .UNINDENT .UNINDENT .sp options present in file and not specified in sections dict will be untouched .sp changes dict will contain the list of changes made .UNINDENT .INDENT 0.0 .TP .B salt.states.ini_manage.options_present(name, sections=None, separator=\(aq=\(aq, strict=False) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /home/saltminion/api\-paste.ini: ini.options_present: \- separator: \(aq=\(aq \- strict: True \- sections: test: testkey: \(aqtestval\(aq secondoption: \(aqsecondvalue\(aq test1: testkey1: \(aqtestval121\(aq .ft P .fi .UNINDENT .UNINDENT .sp options present in file and not specified in sections dict will be untouched, unless \fIstrict: True\fP flag is used .sp changes dict will contain the list of changes made .UNINDENT .INDENT 0.0 .TP .B salt.states.ini_manage.sections_absent(name, sections=None, separator=\(aq=\(aq) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /home/saltminion/api\-paste.ini: ini.sections_absent: \- separator: \(aq=\(aq \- sections: \- test \- test1 .ft P .fi .UNINDENT .UNINDENT .sp options present in file and not specified in sections will be deleted changes dict will contain the sections that changed .UNINDENT .INDENT 0.0 .TP .B salt.states.ini_manage.sections_present(name, sections=None, separator=\(aq=\(aq) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /home/saltminion/api\-paste.ini: ini.sections_present: \- separator: \(aq=\(aq \- sections: \- section_one \- section_two .ft P .fi .UNINDENT .UNINDENT .sp This will only create empty sections. To also create options, use options_present state .sp options present in file and not specified in sections will be deleted changes dict will contain the sections that changed .UNINDENT .SS salt.states.ipmi .SS Manage IPMI devices over LAN .sp The following configuration defaults can be defined in the minion, master config or pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ipmi.config: api_host: 127.0.0.1 api_user: admin api_pass: apassword api_port: 623 api_kg: None .ft P .fi .UNINDENT .UNINDENT .sp Every call can override the config defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ensure myipmi system is set to network boot: ipmi.boot_device: \- name: network \- api_host: myipmi.hostname.com \- api_user: root \- api_pass: apassword \- api_kg: None ensure myipmi system is powered on: ipmi.power: \- name: boot \- api_host: myipmi.hostname.com \- api_user: root \- api_pass: apassword .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ipmi.boot_device(name=\(aqdefault\(aq, **kwargs) Request power state change .INDENT 7.0 .TP .B name = \fBdefault\fP .INDENT 7.0 .IP \(bu 2 network \-\- Request network boot .IP \(bu 2 hd \-\- Boot from hard drive .IP \(bu 2 safe \-\- Boot from hard drive, requesting \(aqsafe mode\(aq .IP \(bu 2 optical \-\- boot from CD/DVD/BD drive .IP \(bu 2 setup \-\- Boot into setup utility .IP \(bu 2 default \-\- remove any IPMI directed boot device request .UNINDENT .TP .B kwargs .INDENT 7.0 .IP \(bu 2 api_host=localhost .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass= .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ipmi.power(name=\(aqpower_on\(aq, wait=300, **kwargs) Request power state change .INDENT 7.0 .TP .B name .INDENT 7.0 .TP .B Ensure power state one of: .INDENT 7.0 .IP \(bu 2 power_on \-\- system turn on .IP \(bu 2 power_off \-\- system turn off (without waiting for OS) .IP \(bu 2 shutdown \-\- request OS proper shutdown .IP \(bu 2 reset \-\- reset (without waiting for OS) .IP \(bu 2 boot \-\- If system is off, then \(aqon\(aq, else \(aqreset\(aq .UNINDENT .UNINDENT .TP .B wait wait X seconds for the job to complete before forcing. (defaults to 300 seconds) .TP .B kwargs .INDENT 7.0 .IP \(bu 2 api_host=localhost .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass= .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ipmi.user_absent(name, channel=14, **kwargs) Remove user Delete all user (uid) records having the matching name. .INDENT 7.0 .TP .B name string name of user to delete .TP .B channel channel to remove user access from defaults to 14 for auto. .TP .B kwargs .INDENT 7.0 .IP \(bu 2 api_host=localhost .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass= .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ipmi.user_present(name, uid, password, channel=14, callback=False, link_auth=True, ipmi_msg=True, privilege_level=\(aqadministrator\(aq, **kwargs) Ensure IPMI user and user privileges. .INDENT 7.0 .TP .B name name of user (limit 16 bytes) .TP .B uid user id number (1 to 7) .TP .B password user password (limit 16 bytes) .TP .B channel ipmi channel defaults to 14 for auto .TP .B callback User Restricted to Callback .INDENT 7.0 .TP .B False = User Privilege Limit is determined by the User Privilege Limit parameter privilege_level, for both callback and non\-callback connections. .TP .B True = User Privilege Limit is determined by the privilege_level parameter for callback connections, but is restricted to Callback level for non\-callback connections. Thus, a user can only initiate a Callback when they \(aqcall in\(aq to the BMC, but once the callback connection has been made, the user could potentially establish a session as an Operator. .UNINDENT .TP .B link_auth User Link authentication True/False user name and password information will be used for link authentication, e.g. PPP CHAP) for the given channel. Link authentication itself is a global setting for the channel and is enabled/disabled via the serial/modem configuration parameters. .TP .B ipmi_msg User IPMI Messaging True/False user name and password information will be used for IPMI Messaging. In this case, \(aqIPMI Messaging\(aq refers to the ability to execute generic IPMI commands that are not associated with a particular payload type. For example, if IPMI Messaging is disabled for a user, but that user is enabled for activating the SOL payload type, then IPMI commands associated with SOL and session management, such as Get SOL Configuration Parameters and Close Session are available, but generic IPMI commands such as Get SEL Time are unavailable.) ipmi_msg .TP .B privilege_level .INDENT 7.0 .IP \(bu 2 callback .IP \(bu 2 user .IP \(bu 2 operator .IP \(bu 2 administrator .IP \(bu 2 proprietary .IP \(bu 2 no_access .UNINDENT .TP .B kwargs .INDENT 7.0 .IP \(bu 2 api_host=localhost .IP \(bu 2 api_user=admin .IP \(bu 2 api_pass= .IP \(bu 2 api_port=623 .IP \(bu 2 api_kg=None .UNINDENT .UNINDENT .UNINDENT .SS salt.states.ipset .SS Management of ipsets .sp This is an ipset\-specific module designed to manage IPSets for use in IPTables Firewalls. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C setname: ipset.set_present: \- set_type: bitmap:ip \- range: 192.168.0.0/16 \- comment: True setname: ipset.set_absent: \- set_type: bitmap:ip \- range: 192.168.0.0/16 \- comment: True setname_entries: ipset.present: \- set_name: setname \- entry: 192.168.0.3 \- comment: Hello \- require: \- ipset: baz setname_entries: ipset.present: \- set_name: setname \- entry: \- 192.168.0.3 \- 192.168.1.3 \- comment: Hello \- require: \- ipset: baz setname_entries: ipset.absent: \- set_name: setname \- entry: \- 192.168.0.3 \- 192.168.1.3 \- comment: Hello \- require: \- ipset: baz setname: ipset.flush: .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ipset.absent(name, entry=None, entries=None, family=\(aqipv4\(aq, **kwargs) New in version 2014.7.0. .sp Remove a entry or entries from a chain .INDENT 7.0 .TP .B name A user\-defined name to call this entry by in another part of a state or formula. This should not be an actual entry. .TP .B family Network family, ipv4 or ipv6. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ipset.flush(name, family=\(aqipv4\(aq, **kwargs) New in version 2014.7.0. .sp Flush current ipset set .INDENT 7.0 .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ipset.present(name, entry=None, family=\(aqipv4\(aq, **kwargs) New in version 2014.7.0. .sp Append a entry to a set .INDENT 7.0 .TP .B name A user\-defined name to call this entry by in another part of a state or formula. This should not be an actual entry. .TP .B entry A single entry to add to a set or a list of entries to add to a set .TP .B family Network family, ipv4 or ipv6. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ipset.set_absent(name, family=\(aqipv4\(aq, **kwargs) New in version 2014.7.0. .sp Verify the set is absent. .INDENT 7.0 .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ipset.set_present(name, set_type, family=\(aqipv4\(aq, **kwargs) New in version 2014.7.0. .sp Verify the set exists. .INDENT 7.0 .TP .B name A user\-defined set name. .TP .B set_type The type for the set. .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .UNINDENT .SS salt.states.iptables .SS Management of iptables .sp This is an iptables\-specific module designed to manage Linux firewalls. It is expected that this state module, and other system\-specific firewall states, may at some point be deprecated in favor of a more generic \fBfirewall\fP state. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: iptables.append: \- table: filter \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- protocol: tcp \- sport: 1025:65535 \- save: True httpd: iptables.append: \- table: filter \- chain: INPUT \- jump: ACCEPT \- match: \- state \- comment \- comment: \(dqAllow HTTP\(dq \- connstate: NEW \- dport: 80 \- protocol: tcp \- sport: 1025:65535 \- save: True httpd: iptables.append: \- table: filter \- chain: INPUT \- jump: ACCEPT \- match: \- state \- comment \- comment: \(dqAllow HTTP\(dq \- connstate: NEW \- source: \(aq127.0.0.1\(aq \- dport: 80 \- protocol: tcp \- sport: 1025:65535 \- save: True \&.. Invert Rule httpd: iptables.append: \- table: filter \- chain: INPUT \- jump: ACCEPT \- match: \- state \- comment \- comment: \(dqAllow HTTP\(dq \- connstate: NEW \- source: \(aq! 127.0.0.1\(aq \- dport: 80 \- protocol: tcp \- sport: 1025:65535 \- save: True httpd: iptables.append: \- table: filter \- chain: INPUT \- jump: ACCEPT \- match: \- state \- comment \- comment: \(dqAllow HTTP\(dq \- connstate: NEW \- source: \(aqnot 127.0.0.1\(aq \- dport: 80 \- protocol: tcp \- sport: 1025:65535 \- save: True httpd: iptables.append: \- table: filter \- family: ipv6 \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- protocol: tcp \- sport: 1025:65535 \- save: True httpd: iptables.append: \- table: filter \- family: ipv4 \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dports: \- 80 \- 443 \- protocol: tcp \- sport: 1025:65535 \- save: True httpd: iptables.insert: \- position: 1 \- table: filter \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- protocol: tcp \- sport: 1025:65535 \- save: True httpd: iptables.insert: \- position: 1 \- table: filter \- family: ipv6 \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- protocol: tcp \- sport: 1025:65535 \- save: True httpd: iptables.delete: \- table: filter \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- protocol: tcp \- sport: 1025:65535 \- save: True httpd: iptables.delete: \- position: 1 \- table: filter \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- protocol: tcp \- sport: 1025:65535 \- save: True httpd: iptables.delete: \- table: filter \- family: ipv6 \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- protocol: tcp \- sport: 1025:65535 \- save: True default to accept: iptables.set_policy: \- chain: INPUT \- policy: ACCEPT .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Whereas iptables will accept \fB\-p\fP, \fB\-\-proto[c[o[l]]]\fP as synonyms of \fB\-\-protocol\fP, if \fB\-\-proto\fP appears in an iptables command after the appearance of \fB\-m policy\fP, it is interpreted as the \fB\-\-proto\fP option of the policy extension (see the iptables\-extensions(8) man page). .UNINDENT .UNINDENT .sp Example rules for IPSec policy: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C accept_esp_in: iptables.append: \- table: filter \- chain: INPUT \- jump: ACCEPT \- source: 10.20.0.0/24 \- destination: 10.10.0.0/24 \- in\-interface: eth0 \- match: policy \- dir: in \- pol: ipsec \- reqid: 1 \- proto: esp accept_esp_forward_in: iptables.append: \- use: \- iptables: accept_esp_in \- chain: FORWARD accept_esp_out: iptables.append: \- table: filter \- chain: OUTPUT \- jump: ACCEPT \- source: 10.10.0.0/24 \- destination: 10.20.0.0/24 \- out\-interface: eth0 \- match: policy \- dir: out \- pol: ipsec \- reqid: 1 \- proto: esp accept_esp_forward_out: iptables.append: \- use: \- iptables: accept_esp_out \- chain: FORWARD .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBname\fP is reserved for the Salt state name. To pass \fB\-\-name EXAMPLE\fP to iptables, provide it with \fB\- name_: EXAMPLE\fP\&. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Various functions of the \fBiptables\fP module use the \fB\-\-check\fP option. If the version of \fBiptables\fP on the target system does not include this option, an alternate version of this check will be performed using the output of iptables\-save. This may have unintended consequences on legacy releases of \fBiptables\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.iptables.append(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq, **kwargs) New in version 0.17.0. .sp Add a rule to the end of the specified chain. If the rule is already present anywhere in the chain, its position is not changed. .INDENT 7.0 .TP .B name A user\-defined name to call this rule by in another part of a state or formula. This should not be an actual rule. .TP .B table The table that owns the chain which should be modified .TP .B family Network family, ipv4 or ipv6. .TP .B save If set to a true value, the new iptables rules for the given family will be saved to a file. .sp If the value is True, rules are saved to an OS\-dependent file that will be loaded during system startup, resulting in the firewall rule remaining active across reboots if possible. .sp Note that loading the iptables rules during system startup may require non\-default packages to be installed. On Debian\-derived systems, the iptables\-persistent package is required. .sp If the value is a string, it is taken to be a filename to which the rules will be saved. Arranging for the rules to be loaded during system startup must be done separately. .UNINDENT .sp All other arguments are passed in with the same name as the long option that would normally be used for iptables, with one exception: \fB\-\-state\fP is specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with \fIctstate\fP). .sp Jump options that doesn\(aqt take arguments should be passed in with an empty string. .UNINDENT .INDENT 0.0 .TP .B salt.states.iptables.chain_absent(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq) New in version 2014.1.0. .sp Verify the chain is absent. .INDENT 7.0 .TP .B table The table to remove the chain from .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.iptables.chain_present(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq) New in version 2014.1.0. .sp Verify the chain is exist. .INDENT 7.0 .TP .B name A user\-defined chain name. .TP .B table The table to own the chain. .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.iptables.delete(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq, **kwargs) New in version 2014.1.0. .sp Delete a rule from a chain if present. If the rule is already absent, this is not an error and nothing is changed. .INDENT 7.0 .TP .B name A user\-defined name to call this rule by in another part of a state or formula. This should not be an actual rule. .TP .B table The table that owns the chain that should be modified .TP .B family Networking family, either ipv4 or ipv6 .TP .B save If set to a true value, the new iptables rules for the given family will be saved to a file. See the \fBappend\fP state for more details. .UNINDENT .sp All other arguments are passed in with the same name as the long option that would normally be used for iptables, with one exception: \fB\-\-state\fP is specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with \fIctstate\fP). .sp Jump options that doesn\(aqt take arguments should be passed in with an empty string. .UNINDENT .INDENT 0.0 .TP .B salt.states.iptables.flush(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq, **kwargs) New in version 2014.1.0. .sp Flush current iptables state .INDENT 7.0 .TP .B table The table that owns the chain that should be modified .TP .B family Networking family, either ipv4 or ipv6 .TP .B chain The chain to be flushed. All the chains in the table if none is given. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.iptables.insert(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq, **kwargs) New in version 2014.1.0. .sp Insert a rule into a chain. If the rule is already present anywhere in the chain, its position is not changed. .INDENT 7.0 .TP .B name A user\-defined name to call this rule by in another part of a state or formula. This should not be an actual rule. .TP .B table The table that owns the chain that should be modified .TP .B family Networking family, either ipv4 or ipv6 .TP .B position The numerical representation of where the rule should be inserted into the chain. Note that \fB\-1\fP is not a supported position value. .TP .B save If set to a true value, the new iptables rules for the given family will be saved to a file. See the \fBappend\fP state for more details. .UNINDENT .sp All other arguments are passed in with the same name as the long option that would normally be used for iptables, with one exception: \fB\-\-state\fP is specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with \fIctstate\fP). .sp Jump options that doesn\(aqt take arguments should be passed in with an empty string. .UNINDENT .INDENT 0.0 .TP .B salt.states.iptables.mod_aggregate(low, chunks, running) The mod_aggregate function which looks up all rules in the available low chunks and merges them into a single rules ref in the present low data .UNINDENT .INDENT 0.0 .TP .B salt.states.iptables.set_policy(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq, **kwargs) New in version 2014.1.0. .sp Sets the default policy for iptables firewall tables .INDENT 7.0 .TP .B table The table that owns the chain that should be modified .TP .B family Networking family, either ipv4 or ipv6 .TP .B policy The requested table policy .TP .B save If set to a true value, the new iptables rules for the given family will be saved to a file. See the \fBappend\fP state for more details. .UNINDENT .UNINDENT .SS salt.states.jboss7 .sp Manage JBoss 7 Application Server via CLI interface .sp New in version 2015.5.0. .sp This state uses the jboss\-cli.sh script from a JBoss or Wildfly installation and parses its output to determine the execution result. .sp In order to run each state, a jboss_config dictionary with the following properties must be passed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C jboss: cli_path: \(aq/opt/jboss/jboss\-7.0/bin/jboss\-cli.sh\(aq controller: 10.11.12.13:9999 cli_user: \(aqjbossadm\(aq cli_password: \(aqjbossadm\(aq .ft P .fi .UNINDENT .UNINDENT .sp If the controller doesn\(aqt require a password, then the cli_user and cli_password parameters are optional. .sp Since same dictionary with configuration will be used in all the states, it may be more convenient to move JBoss configuration and other properties to the pillar. .sp Example of application deployment from local filesystem: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C application_deployed: jboss7.deployed: \- salt_source: target_file: \(aq/tmp/webapp.war\(aq \- jboss_config: {{ pillar[\(aqjboss\(aq] }} .ft P .fi .UNINDENT .UNINDENT .sp For the sake of brevity, examples for each state assume that jboss_config is contained in the pillar. .INDENT 0.0 .TP .B salt.states.jboss7.bindings_exist(name, jboss_config, bindings, profile=None) Ensures that given JNDI binding are present on the server. If a binding doesn\(aqt exist on the server it will be created. If it already exists its value will be changed. .INDENT 7.0 .TP .B jboss_config: Dict with connection properties (see state description) .TP .B bindings: Dict with bindings to set. .TP .B profile: The profile name (domain mode only) .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C jndi_entries_created: jboss7.bindings_exist: \- bindings: \(aqjava:global/sampleapp/environment\(aq: \(aqDEV\(aq \(aqjava:global/sampleapp/configurationFile\(aq: \(aq/var/opt/sampleapp/config.properties\(aq \- jboss_config: {{ pillar[\(aqjboss\(aq] }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.jboss7.datasource_exists(name, jboss_config, datasource_properties, recreate=False, profile=None) Ensures that a datasource with given properties exist on the jboss instance. If datasource doesn\(aqt exist, it is created, otherwise only the properties that are different will be updated. .INDENT 7.0 .TP .B name Datasource property name .TP .B jboss_config Dict with connection properties (see state description) .TP .B datasource_properties Dict with datasource properties .TP .B recreate False If set to True and datasource exists it will be removed and created again. However, if there are deployments that depend on the datasource, it will not me possible to remove it. .TP .B profile None The profile name for this datasource (domain mode only) .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sampleDS: jboss7.datasource_exists: \- recreate: False \- datasource_properties: driver\-name: mysql connection\-url: \(aqjdbc:mysql://localhost:3306/sampleDatabase\(aq jndi\-name: \(aqjava:jboss/datasources/sampleDS\(aq user\-name: sampleuser password: secret min\-pool\-size: 3 use\-java\-context: True \- jboss_config: {{ pillar[\(aqjboss\(aq] }} \- profile: full\-ha .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.jboss7.deployed(name, jboss_config, salt_source=None) Ensures that the given application is deployed on server. .INDENT 7.0 .TP .B jboss_config: Dict with connection properties (see state description) .TP .B salt_source: .INDENT 7.0 .TP .B How to find the artifact to be deployed. .INDENT 7.0 .TP .B target_file: Where to look in the minion\(aqs file system for the artifact to be deployed (e.g. \(aq/tmp/application\-web\-0.39.war\(aq). When source is specified, also specifies where to save the retrieved file. .TP .B source: (optional) File on salt master (e.g. salt://application\-web\-0.39.war). If absent, no files will be retrieved and the artifact in target_file will be used for the deployment. .TP .B undeploy: (optional) Regular expression to match against existing deployments. When present, if there is a deployment that matches the regular expression, it will be undeployed before the new artifact is deployed. .TP .B undeploy_force: (optional) If True, the artifact will be undeployed although it has not changed. .UNINDENT .UNINDENT .UNINDENT .sp Examples: .sp Deployment of a file from minion\(aqs local file system: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C application_deployed: jboss7.deployed: \- salt_source: target_file: \(aq/tmp/webapp.war\(aq \- jboss_config: {{ pillar[\(aqjboss\(aq] }} .ft P .fi .UNINDENT .UNINDENT .sp It is assumed that /tmp/webapp.war was made available by some other means. No applications will be undeployed; if an existing deployment that shares that name exists, then it will be replaced with the updated version. .sp Deployment of a file from the Salt master\(aqs file system: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C application_deployed: jboss7.deployed: \- salt_source: source: salt://application\-web\-0.39.war target_file: \(aq/tmp/application\-web\-0.39.war\(aq undeploy: \(aqapplication\-web\-.*\(aq \- jboss_config: {{ pillar[\(aqjboss\(aq] }} .ft P .fi .UNINDENT .UNINDENT .sp Here, application\-web\-0.39.war file is downloaded from Salt file system to /tmp/application\-web\-0.39.war file on minion. Existing deployments are checked if any of them matches \(aqapplication\-web\-.*\(aq regular expression, and if so then it is undeployed before deploying the application. This is useful to automate deployment of new application versions. .sp If the source parameter of salt_source is specified, it can use any protocol that the file states use. This includes not only downloading from the master but also HTTP, HTTPS, FTP, Amazon S3, and OpenStack Swift. .UNINDENT .INDENT 0.0 .TP .B salt.states.jboss7.reloaded(name, jboss_config, timeout=60, interval=5) Reloads configuration of jboss server. .INDENT 7.0 .TP .B jboss_config: Dict with connection properties (see state description) .TP .B timeout: Time to wait until jboss is back in running state. Default timeout is 60s. .TP .B interval: Interval between state checks. Default interval is 5s. Decreasing the interval may slightly decrease waiting time but be aware that every status check is a call to jboss\-cli which is a java process. If interval is smaller than process cleanup time it may easily lead to excessive resource consumption. .UNINDENT .sp This step performs the following operations: .INDENT 7.0 .IP \(bu 2 Ensures that server is in running or reload\-required state (by reading server\-state attribute) .IP \(bu 2 Reloads configuration .IP \(bu 2 Waits for server to reload and be in running state .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C configuration_reloaded: jboss7.reloaded: \- jboss_config: {{ pillar[\(aqjboss\(aq] }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.jenkins .SS Management of Jenkins .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.states.jenkins.absent(name, **kwargs) Ensure the job is absent from the Jenkins configured jobs .INDENT 7.0 .TP .B name The name of the Jenkins job to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.jenkins.present(name, config=None, **kwargs) Ensure the job is present in the Jenkins configured jobs .INDENT 7.0 .TP .B name The unique name for the Jenkins job .TP .B config The Salt URL for the file to use for configuring the job .UNINDENT .UNINDENT .SS salt.states.junos .SS State modules to interact with Junos devices. .INDENT 0.0 .TP .B maturity new .TP .B dependencies junos\-eznc, jxmlease .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Those who wish to use junos\-eznc (PyEZ) version >= 2.1.0, must use the latest salt code from github until the next release. .UNINDENT .UNINDENT .sp Refer to \fI\%junos\fP for information on connecting to junos proxy. .INDENT 0.0 .TP .B salt.states.junos.cli(name, **kwargs) Executes the CLI commands and reuturns the text output. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C show version: junos.cli: \- format: xml get software version of device: junos.cli: \- name: show version \- format: text \- dest: /home/user/show_version.log .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBRequired\fP \-\- .INDENT 2.0 .IP \(bu 2 name: The command that need to be executed on Junos CLI. (default = None) .UNINDENT .IP \(bu 2 \fBOptional\fP \-\- .INDENT 2.0 .IP \(bu 2 .INDENT 2.0 .TP .B kwargs: Keyworded arguments which can be provided like\- .INDENT 7.0 .IP \(bu 2 format: Format in which to get the CLI output. (text or xml, default = \(aqtext\(aq) .IP \(bu 2 timeout: Set NETCONF RPC timeout. Can be used for commands which take a while to execute. (default = 30 seconds) .IP \(bu 2 dest: The destination file where the CLI output can be stored. (default = None) .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.commit(name, **kwargs) Commits the changes loaded into the candidate configuration. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C commit the changes: junos.commit: \- confirm: 10 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBOptional\fP \-\- .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B kwargs: Keyworded arguments which can be provided like\- .INDENT 7.0 .IP \(bu 2 timeout: Set NETCONF RPC timeout. Can be used for commands which take a while to execute. (default = 30 seconds) .IP \(bu 2 comment: Provide a comment to the commit. (default = None) .IP \(bu 2 confirm: Provide time in minutes for commit confirmation. If this option is specified, the commit will be rollbacked in the given time unless the commit is confirmed. .IP \(bu 2 sync: On dual control plane systems, requests that the candidate configuration on one control plane be copied to the other control plane,checked for correct syntax, and committed on both Routing Engines. (default = False) .IP \(bu 2 force_sync: On dual control plane systems, force the candidate configuration on one control plane to be copied to the other control plane. .IP \(bu 2 full: When set to True requires all the daemons to check and evaluate the new configuration. .IP \(bu 2 detail: When true return commit detail. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.commit_check(name) Perform a commit check on the configuration. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C perform commit check: junos.commit_check .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.diff(name, d_id=0, **kwargs) Changed in version 3001. .sp Gets the difference between the candidate and the current configuration. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C get the diff: junos.diff: \- d_id: 10 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBOptional\fP \-\- .INDENT 7.0 .IP \(bu 2 d_id: The rollback diff id (d_id) value [0\-49]. (default = 0) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.file_copy(name, dest=None, **kwargs) Copies the file from the local device to the junos device. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /home/m2/info.txt: junos.file_copy: \- dest: info_copy.txt .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBRequired\fP \-\- .INDENT 7.0 .IP \(bu 2 name: The sorce path where the file is kept. .IP \(bu 2 dest: The destination path where the file will be copied. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.get_table(name, table, table_file, **kwargs) New in version 3001. .sp Retrieve data from a Junos device using Tables/Views .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C get route details: junos.get_table: \- table: RouteTable \- table_file: routes.yml get interface details: junos.get_table: \- table: EthPortTable \- table_file: ethport.yml \- table_args: interface_name: ge\-0/0/0 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name (required) task definition .TP .B table (required) Name of PyEZ Table .TP .B file YAML file that has the table specified in table parameter .TP .B path: Path of location of the YAML file. defaults to op directory in jnpr.junos.op .TP .B target: if command need to run on FPC, can specify fpc target .TP .B key: To overwrite key provided in YAML .TP .B key_items: To select only given key items .TP .B filters: To select only filter for the dictionary from columns .TP .B template_args: key/value pair which should render Jinja template command .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.install_config(name, **kwargs) Loads and commits the configuration provided. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Install the mentioned config: junos.install_config: \- name: salt://configs/interface.set \- timeout: 100 \- diffs_file: \(aq/var/log/diff\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Install the mentioned config: junos.install_config: \- path: salt://configs/interface.set \- timeout: 100 \- template_vars: interface_name: lo0 description: Creating interface via SaltStack. .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Path where the configuration/template file is present. If the file has a \fB*.conf\fP extension, the content is treated as text format. If the file has a \fB*.xml\fP extension, the content is treated as XML format. If the file has a \fB*.set\fP extension, the content is treated as Junos OS \fBset\fP commands .TP .B template_vars The dictionary of data for the jinja variables present in the jinja template .TP .B timeout 30 Set NETCONF RPC timeout. Can be used for commands which take a while to execute. .TP .B overwrite False Set to \fBTrue\fP if you want this file is to completely replace the configuration file. Sets action to override .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option cannot be used if \fBformat\fP is \(dqset\(dq. .UNINDENT .UNINDENT .TP .B merge False If set to \fBTrue\fP will set the load\-config action to merge. the default load\-config action is \(aqreplace\(aq for xml/json/text config .TP .B comment Provide a comment to the commit. (default = None) .TP .B confirm Provide time in minutes for commit confirmation. If this option is specified, the commit will be rolled back in the given time unless the commit is confirmed. .TP .B diffs_file Path to the file where the diff (difference in old configuration and the committed configuration) will be stored. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The file will be stored on the proxy minion. To push the files to the master use \fI\%cp.push\fP\&. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.install_os(name, **kwargs) Installs the given image on the device. After the installation is complete the device is rebooted, if reboot=True is given as a keyworded argument. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt://images/junos_image.tgz: junos.install_os: \- timeout: 100 \- reboot: True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBRequired\fP \-\- .INDENT 2.0 .IP \(bu 2 name: Path where the image file is present on the pro xy minion. .UNINDENT .IP \(bu 2 \fBOptional\fP \-\- .INDENT 2.0 .IP \(bu 2 .INDENT 2.0 .TP .B kwargs: keyworded arguments to be given such as timeout, reboot etc .INDENT 7.0 .IP \(bu 2 timeout: Set NETCONF RPC timeout. Can be used to RPCs which take a while to execute. (default = 30 seconds) .IP \(bu 2 reboot: Whether to reboot after installation (default = False) .IP \(bu 2 no_copy: When True the software package will not be SCP’d to the device. (default = False) .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.load(name, **kwargs) Loads the configuration provided onto the junos device. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Install the mentioned config: junos.load: \- name: salt://configs/interface.set .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Install the mentioned config: junos.load: \- name: salt://configs/interface.set \- template_vars: interface_name: lo0 description: Creating interface via SaltStack. .ft P .fi .UNINDENT .UNINDENT .sp Sample template: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C set interfaces {{ interface_name }} unit 0 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Path where the configuration/template file is present. If the file has a \fB*.conf\fP extension, the content is treated as text format. If the file has a \fB*.xml\fP extension, the content is treated as XML format. If the file has a \fB*.set\fP extension, the content is treated as Junos OS \fBset\fP commands. .TP .B overwrite False Set to \fBTrue\fP if you want this file is to completely replace the configuration file. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option cannot be used if \fBformat\fP is \(dqset\(dq. .UNINDENT .UNINDENT .TP .B merge False If set to \fBTrue\fP will set the load\-config action to merge. the default load\-config action is \(aqreplace\(aq for xml/json/text config .TP .B update False Compare a complete loaded configuration against the candidate configuration. For each hierarchy level or configuration object that is different in the two configurations, the version in the loaded configuration replaces the version in the candidate configuration. When the configuration is later committed, only system processes that are affected by the changed configuration elements parse the new configuration. This action is supported from PyEZ 2.1 (default = False) .TP .B template_vars Variables to be passed into the template processing engine in addition to those present in __pillar__, __opts__, __grains__, etc. You may reference these variables in your template like so: {{ template_vars[\(dqvar_name\(dq] }} .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.lock(name) Attempts an exclusive lock on the candidate configuration. This is a non\-blocking call. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Any user who wishes to use lock, must necessarily unlock the configuration too. Ensure \fI\%unlock\fP is called in the same orchestration run in which the lock is called. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C lock the config: junos.lock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.resultdecorator(function) .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.rollback(name, d_id, **kwargs) Rollbacks the committed changes. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C rollback the changes: junos.rollback: \- id: 5 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBOptional\fP \-\- .INDENT 7.0 .IP \(bu 2 id: .IP \(bu 2 d_id: The rollback id value [0\-49]. (default = 0) (this variable cannot be named \fIid\fP, it conflicts with the state compiler\(aqs internal id) .IP \(bu 2 .INDENT 2.0 .TP .B kwargs: Keyworded arguments which can be provided like\- .INDENT 7.0 .IP \(bu 2 timeout: Set NETCONF RPC timeout. Can be used for commands which take a while to execute. (default = 30 seconds) .IP \(bu 2 comment: Provide a comment to the commit. (default = None) .IP \(bu 2 confirm: Provide time in minutes for commit confirmation. If this option is specified, the commit will be rollbacked in the given time unless the commit is confirmed. .IP \(bu 2 diffs_file: Path to the file where any diffs will be written. (default = None) .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.rpc(name, dest=None, format=\(aqxml\(aq, args=None, **kwargs) Executes the given rpc. The returned data can be stored in a file by specifying the destination path with dest as an argument .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C get\-interface\-information: junos.rpc: \- dest: /home/user/rpc.log \- interface_name: lo0 fetch interface information with terse: junos.rpc: \- name: get\-interface\-information \- terse: True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBRequired\fP \-\- .INDENT 2.0 .IP \(bu 2 name: The rpc to be executed. (default = None) .UNINDENT .IP \(bu 2 \fBOptional\fP \-\- .INDENT 2.0 .IP \(bu 2 dest: Destination file where the rpc output is stored. (default = None) Note that the file will be stored on the proxy minion. To push the files to the master use the salt\(aqs following execution module: \fI\%cp.push\fP .IP \(bu 2 format: The format in which the rpc reply must be stored in file specified in the dest (used only when dest is specified) (default = xml) .IP \(bu 2 .INDENT 2.0 .TP .B kwargs: keyworded arguments taken by rpc call like\- .INDENT 7.0 .IP \(bu 2 timeout: 30 Set NETCONF RPC timeout. Can be used for commands which take a while to execute. (default= 30 seconds) .IP \(bu 2 filter: Only to be used with \(aqget\-config\(aq rpc to get specific configuration. .IP \(bu 2 terse: Amount of information you want. .IP \(bu 2 interface_name: Name of the interface whose information you want. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.set_hostname(name, **kwargs) Changes the hostname of the device. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C device_name: junos.set_hostname: \- comment: \(dqHost\-name set via saltstack.\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBRequired\fP \-\- .INDENT 2.0 .IP \(bu 2 name: The name to be set. (default = None) .UNINDENT .IP \(bu 2 \fBOptional\fP \-\- .INDENT 2.0 .IP \(bu 2 .INDENT 2.0 .TP .B kwargs: Keyworded arguments which can be provided like\- .INDENT 7.0 .IP \(bu 2 timeout: Set NETCONF RPC timeout. Can be used for commands which take a while to execute. (default = 30 seconds) .IP \(bu 2 comment: Provide a comment to the commit. (default = None) .IP \(bu 2 confirm: Provide time in minutes for commit confirmation. If this option is specified, the commit will be rollbacked in the given time unless the commit is confirmed. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.shutdown(name, **kwargs) Shuts down the device. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C shut the device: junos.shutdown: \- in_min: 10 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBOptional\fP \-\- .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B kwargs: .INDENT 7.0 .IP \(bu 2 reboot: Whether to reboot instead of shutdown. (default=False) .IP \(bu 2 at: Specify time for reboot. (To be used only if reboot=yes) .IP \(bu 2 in_min: Specify delay in minutes for shutdown .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.unlock(name) Unlocks the candidate configuration. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C unlock the config: junos.unlock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.junos.zeroize(name) Resets the device to default factory settings. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C reset my device: junos.zeroize .ft P .fi .UNINDENT .UNINDENT .sp name: can be anything .UNINDENT .SS salt.states.kapacitor .sp Kapacitor state module. .INDENT 0.0 .TP .B configuration This module accepts connection configuration details either as parameters or as configuration settings in /etc/salt/minion on the relevant minions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C kapacitor.unsafe_ssl: \(aqfalse\(aq kapacitor.protocol: \(aqhttp\(aq kapacitor.host: \(aqlocalhost\(aq kapacitor.port: 9092 .ft P .fi .UNINDENT .UNINDENT .sp This data can also be passed into pillar. Options passed into opts will overwrite options passed into pillar. .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.states.kapacitor.task_absent(name) Ensure that a task is absent from Kapacitor. .INDENT 7.0 .TP .B name Name of the task. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kapacitor.task_present(name, tick_script, task_type=\(aqstream\(aq, database=None, retention_policy=\(aqdefault\(aq, enable=True, dbrps=None) Ensure that a task is present and up\-to\-date in Kapacitor. .INDENT 7.0 .TP .B name Name of the task. .TP .B tick_script Path to the TICK script for the task. Can be a salt:// source. .TP .B task_type Task type. Defaults to \(aqstream\(aq .TP .B dbrps A list of databases and retention policies in \(dqdbname\(dq.\(dqrpname\(dq format to fetch data from. For backward compatibility, the value of \(aqdatabase\(aq and \(aqretention_policy\(aq will be merged as part of dbrps. .sp New in version 2019.2.0. .TP .B database Which database to fetch data from. Defaults to None, which will use the default database in InfluxDB. .TP .B retention_policy Which retention policy to fetch data from. Defaults to \(aqdefault\(aq. .TP .B enable Whether to enable the task or not. Defaults to True. .UNINDENT .UNINDENT .SS salt.states.kernelpkg .SS Manage kernel packages and active kernel version .sp Example state to install the latest kernel from package repositories: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install\-latest\-kernel: kernelpkg.latest_installed: [] .ft P .fi .UNINDENT .UNINDENT .sp Example state to boot the system if a new kernel has been installed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C boot\-latest\-kernel: kernelpkg.latest_active: \- at_time: 1 .ft P .fi .UNINDENT .UNINDENT .sp Example state chaining the install and reboot operations: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install\-latest\-kernel: kernelpkg.latest_installed: [] boot\-latest\-kernel: kernelpkg.latest_active: \- at_time: 1 \- onchanges: \- kernelpkg: install\-latest\-kernel .ft P .fi .UNINDENT .UNINDENT .sp Chaining can also be achieved using wait/listen requisites: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install\-latest\-kernel: kernelpkg.latest_installed: [] boot\-latest\-kernel: kernelpkg.latest_wait: \- at_time: 1 \- listen: \- kernelpkg: install\-latest\-kernel .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kernelpkg.latest_active(name, at_time=None, **kwargs) Initiate a reboot if the running kernel is not the latest one installed. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state does not install any patches. It only compares the running kernel version number to other kernel versions also installed in the system. If the running version is not the latest one installed, this state will reboot the system. .sp See \fI\%kernelpkg.upgrade\fP and \fI\%latest_installed()\fP for ways to install new kernel packages. .sp This module does not attempt to understand or manage boot loader configurations it is possible to have a new kernel installed, but a boot loader configuration that will never activate it. For this reason, it would not be advisable to schedule this state to run automatically. .sp Because this state function may cause the system to reboot, it may be preferable to move it to the very end of the state run. See \fI\%latest_wait()\fP for a waitable state that can be called with the \fIlisten\fP requesite. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Arbitrary name for the state. Does not affect behavior. .TP .B at_time The wait time in minutes before the system will be rebooted. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kernelpkg.latest_installed(name, **kwargs) Ensure that the latest version of the kernel available in the repositories is installed. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state only installs the kernel, but does not activate it. The new kernel should become active at the next reboot. See \fI\%kernelpkg.needs_reboot\fP for details on how to detect this condition, and \fI\%latest_active()\fP to initiale a reboot when needed. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Arbitrary name for the state. Does not affect behavior. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kernelpkg.latest_wait(name, at_time=None, **kwargs) Initiate a reboot if the running kernel is not the latest one installed. This is the waitable version of \fI\%latest_active()\fP and will not take any action unless triggered by a watch or listen requesite. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Because this state function may cause the system to reboot, it may be preferable to move it to the very end of the state run using \fIlisten\fP or \fIlisten_in\fP requisites. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C system\-up\-to\-date: pkg.uptodate: \- refresh: true boot\-latest\-kernel: kernelpkg.latest_wait: \- at_time: 1 \- listen: \- pkg: system\-up\-to\-date .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Arbitrary name for the state. Does not affect behavior. .TP .B at_time The wait time in minutes before the system will be rebooted. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kernelpkg.mod_watch(name, sfun, **kwargs) Execute a kernelpkg state based on a watch or listen call .UNINDENT .SS salt.states.keyboard .SS Management of keyboard layouts .sp The keyboard layout can be managed for the system: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C us: keyboard.system .ft P .fi .UNINDENT .UNINDENT .sp Or it can be managed for XOrg: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C us: keyboard.xorg .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keyboard.system(name) Set the keyboard layout for the system .INDENT 7.0 .TP .B name The keyboard layout to use .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keyboard.xorg(name) Set the keyboard layout for XOrg .INDENT 7.0 .TP .B layout The keyboard layout to use .UNINDENT .UNINDENT .SS salt.states.keystone .SS Management of Keystone users .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 keystoneclient Python module .UNINDENT .TP .B configuration See \fI\%salt.modules.keystone\fP for setup instructions. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Keystone tenants: keystone.tenant_present: \- names: \- admin \- demo \- service Keystone roles: keystone.role_present: \- names: \- admin \- Member admin: keystone.user_present: \- password: R00T_4CC3SS \- email: admin@domain.com \- roles: admin: # tenants \- admin # roles service: \- admin \- Member \- require: \- keystone: Keystone tenants \- keystone: Keystone roles nova: keystone.user_present: \- password: \(aq$up3rn0v4\(aq \- email: nova@domain.com \- tenant: service \- roles: service: \- admin \- require: \- keystone: Keystone tenants \- keystone: Keystone roles demo: keystone.user_present: \- password: \(aqd3m0n$trati0n\(aq \- email: demo@domain.com \- tenant: demo \- roles: demo: \- Member \- require: \- keystone: Keystone tenants \- keystone: Keystone roles nova service: keystone.service_present: \- name: nova \- service_type: compute \- description: OpenStack Compute Service .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone.endpoint_absent(name, region=None, profile=None, interface=None, **connection_args) Ensure that the endpoint for a service doesn\(aqt exist in Keystone catalog .INDENT 7.0 .TP .B name The name of the service whose endpoints should not exist .TP .B region (optional) The region of the endpoint. Defaults to \fBRegionOne\fP\&. .TP .B interface The interface type, which describes the visibility of the endpoint. (for V3 API) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone.endpoint_present(name, publicurl=None, internalurl=None, adminurl=None, region=None, profile=None, url=None, interface=None, **connection_args) Ensure the specified endpoints exists for service .INDENT 7.0 .TP .B name The Service name .TP .B publicurl The public url of service endpoint (for V2 API) .TP .B internalurl The internal url of service endpoint (for V2 API) .TP .B adminurl The admin url of the service endpoint (for V2 API) .TP .B region The region of the endpoint .TP .B url The endpoint URL (for V3 API) .TP .B interface The interface type, which describes the visibility of the endpoint. (for V3 API) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone.project_absent(name, profile=None, **connection_args) Ensure that the keystone project is absent. Alias for tenant_absent from V2 API to fulfill V3 API naming convention. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B name The name of the project that should not exist .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C delete_nova: keystone.project_absent: \- name: nova .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone.project_present(name, description=None, enabled=True, profile=None, **connection_args) Ensures that the keystone project exists Alias for tenant_present from V2 API to fulfill V3 API naming convention. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B name The name of the project to manage .TP .B description The description to use for this project .TP .B enabled Availability state for this project .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C nova: keystone.project_present: \- enabled: True \- description: \(aqNova Compute Service\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone.role_absent(name, profile=None, **connection_args) Ensure that the keystone role is absent. .INDENT 7.0 .TP .B name The name of the role that should not exist .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone.role_present(name, profile=None, **connection_args) \(aq Ensures that the keystone role exists .INDENT 7.0 .TP .B name The name of the role that should be present .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone.service_absent(name, profile=None, **connection_args) Ensure that the service doesn\(aqt exist in Keystone catalog .INDENT 7.0 .TP .B name The name of the service that should not exist .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone.service_present(name, service_type, description=None, profile=None, **connection_args) Ensure service present in Keystone catalog .INDENT 7.0 .TP .B name The name of the service .TP .B service_type The type of Openstack Service .TP .B description (optional) Description of the service .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone.tenant_absent(name, profile=None, **connection_args) Ensure that the keystone tenant is absent. .INDENT 7.0 .TP .B name The name of the tenant that should not exist .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone.tenant_present(name, description=None, enabled=True, profile=None, **connection_args) Ensures that the keystone tenant exists .INDENT 7.0 .TP .B name The name of the tenant to manage .TP .B description The description to use for this tenant .TP .B enabled Availability state for this tenant .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone.user_absent(name, profile=None, **connection_args) Ensure that the keystone user is absent. .INDENT 7.0 .TP .B name The name of the user that should not exist .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone.user_present(name, password, email, tenant=None, enabled=True, roles=None, profile=None, password_reset=True, project=None, **connection_args) Ensure that the keystone user is present with the specified properties. .INDENT 7.0 .TP .B name The name of the user to manage .TP .B password The password to use for this user. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the user already exists and a different password was set for the user than the one specified here, the password for the user will be updated. Please set the \fBpassword_reset\fP option to \fBFalse\fP if this is not the desired behavior. .UNINDENT .UNINDENT .TP .B password_reset Whether or not to reset password after initial set. Defaults to \fBTrue\fP\&. .TP .B email The email address for this user .TP .B tenant The tenant (name) for this user .TP .B project The project (name) for this user (overrides tenant in api v3) .TP .B enabled Availability state for this user .TP .B roles The roles the user should have under given tenants. Passed as a dictionary mapping tenant names to a list of roles in this tenant, i.e.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C roles: admin: # tenant \- admin # role service: \- admin \- Member .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.states.keystone_domain .SS Management of OpenStack Keystone Domains .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.keystoneng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create domain: keystone_domain.present: \- name: domain1 create domain with optional params: keystone_domain.present: \- name: domain1 \- enabled: False \- description: \(aqmy domain\(aq delete domain: keystone_domain.absent: \- name: domain1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_domain.absent(name, auth=None) Ensure domain does not exist .INDENT 7.0 .TP .B name Name of the domain .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_domain.present(name, auth=None, **kwargs) Ensure domain exists and is up\-to\-date .INDENT 7.0 .TP .B name Name of the domain .TP .B enabled Boolean to control if domain is enabled .TP .B description An arbitrary description of the domain .UNINDENT .UNINDENT .SS salt.states.keystone_endpoint .SS Management of OpenStack Keystone Endpoints .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.keystoneng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create endpoint: keystone_endpoint.present: \- name: public \- url: https://example.org:9292 \- region: RegionOne \- service_name: glance destroy endpoint: keystone_endpoint.absent: \- name: public \- url: https://example.org:9292 \- region: RegionOne \- service_name: glance create multiple endpoints: keystone_endpoint.absent: \- names: \- public \- admin \- internal \- url: https://example.org:9292 \- region: RegionOne \- service_name: glance .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_endpoint.absent(name, service_name, auth=None, **kwargs) Ensure an endpoint does not exists .INDENT 7.0 .TP .B name Interface name .TP .B url URL of the endpoint .TP .B service_name Service name or ID .TP .B region The region name to assign the endpoint .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_endpoint.present(name, service_name, auth=None, **kwargs) Ensure an endpoint exists and is up\-to\-date .INDENT 7.0 .TP .B name Interface name .TP .B url URL of the endpoint .TP .B service_name Service name or ID .TP .B region The region name to assign the endpoint .TP .B enabled Boolean to control if endpoint is enabled .UNINDENT .UNINDENT .SS salt.states.keystone_group .SS Management of OpenStack Keystone Groups .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.keystoneng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create group: keystone_group.present: \- name: group1 delete group: keystone_group.absent: \- name: group1 create group with optional params: keystone_group.present: \- name: group1 \- domain: domain1 \- description: \(aqmy group\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_group.absent(name, auth=None, **kwargs) Ensure group does not exist .INDENT 7.0 .TP .B name Name of the group .TP .B domain The name or id of the domain .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_group.present(name, auth=None, **kwargs) Ensure an group exists and is up\-to\-date .INDENT 7.0 .TP .B name Name of the group .TP .B domain The name or id of the domain .TP .B description An arbitrary description of the group .UNINDENT .UNINDENT .SS salt.states.keystone_project .SS Management of OpenStack Keystone Projects .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.keystoneng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create project: keystone_project.present: \- name: project1 delete project: keystone_project.absent: \- name: project1 create project with optional params: keystone_project.present: \- name: project1 \- domain: domain1 \- enabled: False \- description: \(aqmy project\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_project.absent(name, auth=None, **kwargs) Ensure a project does not exists .INDENT 7.0 .TP .B name Name of the project .TP .B domain The name or id of the domain .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_project.present(name, auth=None, **kwargs) Ensure a project exists and is up\-to\-date .INDENT 7.0 .TP .B name Name of the project .TP .B domain The name or id of the domain .TP .B description An arbitrary description of the project .UNINDENT .UNINDENT .SS salt.states.keystone_role .SS Management of OpenStack Keystone Roles .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.keystoneng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create role: keystone_role.present: \- name: role1 delete role: keystone_role.absent: \- name: role1 create role with optional params: keystone_role.present: \- name: role1 \- description: \(aqmy group\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_role.absent(name, auth=None, **kwargs) Ensure role does not exist .INDENT 7.0 .TP .B name Name of the role .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_role.present(name, auth=None, **kwargs) Ensure an role exists .INDENT 7.0 .TP .B name Name of the role .TP .B description An arbitrary description of the role .UNINDENT .UNINDENT .SS salt.states.keystone_role_grant .SS Management of OpenStack Keystone Role Grants .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.keystoneng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create group: keystone_group.present: \- name: group1 delete group: keystone_group.absent: \- name: group1 create group with optional params: keystone_group.present: \- name: group1 \- domain: domain1 \- description: \(aqmy group\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_role_grant.absent(name, auth=None, **kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_role_grant.present(name, auth=None, **kwargs) .UNINDENT .SS salt.states.keystone_service .SS Management of OpenStack Keystone Services .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.keystoneng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create service: keystone_service.present: \- name: glance \- type: image delete service: keystone_service.absent: \- name: glance create service with optional params: keystone_service.present: \- name: glance \- type: image \- enabled: False \- description: \(aqOpenStack Image\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_service.absent(name, auth=None) Ensure service does not exist .INDENT 7.0 .TP .B name Name of the service .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_service.present(name, auth=None, **kwargs) Ensure an service exists and is up\-to\-date .INDENT 7.0 .TP .B name Name of the group .TP .B type Service type .TP .B enabled Boolean to control if service is enabled .TP .B description An arbitrary description of the service .UNINDENT .UNINDENT .SS salt.states.keystone_user .SS Management of OpenStack Keystone Users .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.keystoneng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create user: keystone_user.present: \- name: user1 delete user: keystone_user.absent: \- name: user1 create user with optional params: keystone_user.present: \- name: user1 \- domain: domain1 \- enabled: False \- password: password123 \- email: \(dquser1@example.org\(dq \- description: \(aqmy user\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_user.absent(name, auth=None, **kwargs) Ensure user does not exists .INDENT 7.0 .TP .B name Name of the user .TP .B domain The name or id of the domain .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.keystone_user.present(name, auth=None, **kwargs) Ensure domain exists and is up\-to\-date .INDENT 7.0 .TP .B name Name of the domain .TP .B domain The name or id of the domain .TP .B enabled Boolean to control if domain is enabled .TP .B description An arbitrary description of the domain .TP .B password The user password .TP .B email The users email address .UNINDENT .UNINDENT .SS salt.states.keystore .sp State management of a java keystore .INDENT 0.0 .TP .B salt.states.keystore.managed(name, passphrase, entries, force_remove=False) Create or manage a java keystore. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The path to the keystore file .IP \(bu 2 \fBpassphrase\fP \-\- The password to the keystore .IP \(bu 2 \fBentries\fP \-\- .sp A list containing an alias, certificate, and optional private_key. The certificate and private_key can be a file or a string .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- entries: \- alias: hostname2 certificate: /path/to/cert.crt private_key: /path/to/key.key \- alias: stringhost certificate: | \-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\- MIICEjCCAXsCAg36MA0GCSqGSIb3DQEBBQUAMIGbMQswCQYDVQQGEwJKUDEOMAwG 2VguKv4SWjRFoRkIfIlHX0qVviMhSlNy2ioFLy7JcPZb+v3ftDGywUqcBiVDoea0 \-\-\-\-\-END CERTIFICATE\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBforce_remove\fP \-\- .sp If True will cause the state to remove any entries found in the keystore which are not defined in the state. The default is False. Example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C define_keystore: keystore.managed: \- name: /path/to/keystore \- passphrase: changeit \- force_remove: True \- entries: \- alias: hostname1 certificate: /path/to/cert.crt \- alias: remotehost certificate: /path/to/cert2.crt private_key: /path/to/key2.key \- alias: pillarhost certificate: {{ salt.pillar.get(\(aqpath:to:cert\(aq) }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.states.kmod .SS Loading and unloading of kernel modules .sp The Kernel modules on a system can be managed cleanly with the kmod state module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C add_kvm: kmod.present: \- name: kvm_amd remove_beep: kmod.absent: \- name: pcspkr .ft P .fi .UNINDENT .UNINDENT .sp Multiple modules can be specified for both kmod.present and kmod.absent. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C add_sound: kmod.present: \- mods: \- snd_hda_codec_hdmi \- snd_hda_codec \- snd_hwdep \- snd_hda_core \- snd_pcm \- snd_timer \- snd .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kmod.absent(name, persist=False, comment=True, mods=None) Verify that the named kernel module is not loaded .INDENT 7.0 .TP .B name The name of the kernel module to verify is not loaded .TP .B persist Remove module from \fB/etc/modules\fP (or \fB/etc/modules\-load.d/salt_managed.conf\fP if the \fBsystemd\fP key is present in Grains. .TP .B comment Comment out module in \fB/etc/modules\fP rather than remove it .TP .B mods A list of modules to verify are unloaded. If this argument is used, the \fBname\fP argument, although still required, is not used, and becomes a placeholder .sp New in version 2016.3.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kmod.present(name, persist=False, mods=None) Ensure that the specified kernel module is loaded .INDENT 7.0 .TP .B name The name of the kernel module to verify is loaded .TP .B persist Also add module to \fB/etc/modules\fP (or \fB/etc/modules\-load.d/salt_managed.conf\fP if the \fBsystemd\fP key is present in Grains. .TP .B mods A list of modules to verify are loaded. If this argument is used, the \fBname\fP argument, although still required, is not used, and becomes a placeholder .sp New in version 2016.3.0. .UNINDENT .UNINDENT .SS salt.states.kubernetes .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%kubernetes Salt Extension\fP\&. .UNINDENT .UNINDENT .SS Manage kubernetes resources as salt states .sp NOTE: This module requires the proper pillar values set. See salt.modules.kubernetesmod for more information. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Configuration options will change in 2019.2.0. .UNINDENT .UNINDENT .sp The kubernetes module is used to manage different kubernetes resources. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-nginx: kubernetes.deployment_present: \- namespace: default metadata: app: frontend spec: replicas: 1 template: metadata: labels: run: my\-nginx spec: containers: \- name: my\-nginx image: nginx ports: \- containerPort: 80 my\-mariadb: kubernetes.deployment_absent: \- namespace: default # kubernetes deployment as specified inside of # a file containing the definition of the the # deployment using the official kubernetes format redis\-master\-deployment: kubernetes.deployment_present: \- name: redis\-master \- source: salt://k8s/redis\-master\-deployment.yml require: \- pip: kubernetes\-python\-module # kubernetes service as specified inside of # a file containing the definition of the the # service using the official kubernetes format redis\-master\-service: kubernetes.service_present: \- name: redis\-master \- source: salt://k8s/redis\-master\-service.yml require: \- kubernetes.deployment_present: redis\-master # kubernetes deployment as specified inside of # a file containing the definition of the the # deployment using the official kubernetes format # plus some jinja directives nginx\-source\-template: kubernetes.deployment_present: \- source: salt://k8s/nginx.yml.jinja \- template: jinja require: \- pip: kubernetes\-python\-module # Kubernetes secret k8s\-secret: kubernetes.secret_present: \- name: top\-secret data: key1: value1 key2: value2 key3: value3 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.states.kubernetes.configmap_absent(name, namespace=\(aqdefault\(aq, **kwargs) Ensures that the named configmap is absent from the given namespace. .INDENT 7.0 .TP .B name The name of the configmap .TP .B namespace The namespace holding the configmap. The \(aqdefault\(aq one is going to be used unless a different one is specified. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.configmap_present(name, namespace=\(aqdefault\(aq, data=None, source=None, template=None, **kwargs) Ensures that the named configmap is present inside of the specified namespace with the given data. If the configmap exists it will be replaced. .INDENT 7.0 .TP .B name The name of the configmap. .TP .B namespace The namespace holding the configmap. The \(aqdefault\(aq one is going to be used unless a different one is specified. .TP .B data The dictionary holding the configmaps. .TP .B source A file containing the data of the configmap in plain format. .TP .B template Template engine to be used to render the source file. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.deployment_absent(name, namespace=\(aqdefault\(aq, **kwargs) Ensures that the named deployment is absent from the given namespace. .INDENT 7.0 .TP .B name The name of the deployment .TP .B namespace The name of the namespace .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.deployment_present(name, namespace=\(aqdefault\(aq, metadata=None, spec=None, source=\(aq\(aq, template=\(aq\(aq, **kwargs) Ensures that the named deployment is present inside of the specified namespace with the given metadata and spec. If the deployment exists it will be replaced. .INDENT 7.0 .TP .B name The name of the deployment. .TP .B namespace The namespace holding the deployment. The \(aqdefault\(aq one is going to be used unless a different one is specified. .TP .B metadata The metadata of the deployment object. .TP .B spec The spec of the deployment object. .TP .B source A file containing the definition of the deployment (metadata and spec) in the official kubernetes format. .TP .B template Template engine to be used to render the source file. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.namespace_absent(name, **kwargs) Ensures that the named namespace is absent. .INDENT 7.0 .TP .B name The name of the namespace .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.namespace_present(name, **kwargs) Ensures that the named namespace is present. .INDENT 7.0 .TP .B name The name of the namespace. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.node_label_absent(name, node, **kwargs) Ensures that the named label is absent from the node. .INDENT 7.0 .TP .B name The name of the label .TP .B node The name of the node .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.node_label_folder_absent(name, node, **kwargs) Ensures the label folder doesn\(aqt exist on the specified node. .INDENT 7.0 .TP .B name The name of label folder .TP .B node The name of the node .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.node_label_present(name, node, value, **kwargs) Ensures that the named label is set on the named node with the given value. If the label exists it will be replaced. .INDENT 7.0 .TP .B name The name of the label. .TP .B value Value of the label. .TP .B node Node to change. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.pod_absent(name, namespace=\(aqdefault\(aq, **kwargs) Ensures that the named pod is absent from the given namespace. .INDENT 7.0 .TP .B name The name of the pod .TP .B namespace The name of the namespace .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.pod_present(name, namespace=\(aqdefault\(aq, metadata=None, spec=None, source=\(aq\(aq, template=\(aq\(aq, **kwargs) Ensures that the named pod is present inside of the specified namespace with the given metadata and spec. If the pod exists it will be replaced. .INDENT 7.0 .TP .B name The name of the pod. .TP .B namespace The namespace holding the pod. The \(aqdefault\(aq one is going to be used unless a different one is specified. .TP .B metadata The metadata of the pod object. .TP .B spec The spec of the pod object. .TP .B source A file containing the definition of the pod (metadata and spec) in the official kubernetes format. .TP .B template Template engine to be used to render the source file. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.secret_absent(name, namespace=\(aqdefault\(aq, **kwargs) Ensures that the named secret is absent from the given namespace. .INDENT 7.0 .TP .B name The name of the secret .TP .B namespace The name of the namespace .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.secret_present(name, namespace=\(aqdefault\(aq, data=None, source=None, template=None, **kwargs) Ensures that the named secret is present inside of the specified namespace with the given data. If the secret exists it will be replaced. .INDENT 7.0 .TP .B name The name of the secret. .TP .B namespace The namespace holding the secret. The \(aqdefault\(aq one is going to be used unless a different one is specified. .TP .B data The dictionary holding the secrets. .TP .B source A file containing the data of the secret in plain format. .TP .B template Template engine to be used to render the source file. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.service_absent(name, namespace=\(aqdefault\(aq, **kwargs) Ensures that the named service is absent from the given namespace. .INDENT 7.0 .TP .B name The name of the service .TP .B namespace The name of the namespace .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kubernetes.service_present(name, namespace=\(aqdefault\(aq, metadata=None, spec=None, source=\(aq\(aq, template=\(aq\(aq, **kwargs) Ensures that the named service is present inside of the specified namespace with the given metadata and spec. If the deployment exists it will be replaced. .INDENT 7.0 .TP .B name The name of the service. .TP .B namespace The namespace holding the service. The \(aqdefault\(aq one is going to be used unless a different one is specified. .TP .B metadata The metadata of the service object. .TP .B spec The spec of the service object. .TP .B source A file containing the definition of the service (metadata and spec) in the official kubernetes format. .TP .B template Template engine to be used to render the source file. .UNINDENT .UNINDENT .SS salt.states.layman .SS Management of Gentoo Overlays using layman .sp A state module to manage Gentoo package overlays via layman .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sunrise: layman.present .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.layman.absent(name) Verify that the overlay is absent .INDENT 7.0 .TP .B name The name of the overlay to delete .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.layman.present(name) Verify that the overlay is present .INDENT 7.0 .TP .B name The name of the overlay to add .UNINDENT .UNINDENT .SS salt.states.ldap .SS Manage entries in an LDAP database .sp New in version 2016.3.0. .sp The \fBstates.ldap\fP state module allows you to manage LDAP entries and their attributes. .INDENT 0.0 .TP .B salt.states.ldap.managed(name, entries, connect_spec=None) Ensure the existence (or not) of LDAP entries and their attributes .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ldapi:///: ldap.managed: \- connect_spec: bind: method: sasl \- entries: # make sure the entry doesn\(aqt exist \- cn=foo,ou=users,dc=example,dc=com: \- delete_others: True # make sure the entry exists with only the specified # attribute values \- cn=admin,dc=example,dc=com: \- delete_others: True \- replace: cn: \- admin description: \- LDAP administrator objectClass: \- simpleSecurityObject \- organizationalRole userPassword: \- {{pillar.ldap_admin_password}} # make sure the entry exists, its olcRootDN attribute # has only the specified value, the olcRootDN attribute # doesn\(aqt exist, and all other attributes are ignored \- \(aqolcDatabase={1}hdb,cn=config\(aq: \- replace: olcRootDN: \- cn=admin,dc=example,dc=com # the admin entry has its own password attribute olcRootPW: [] # note the use of \(aqdefault\(aq. also note how you don\(aqt # have to use list syntax if there is only one attribute # value \- cn=foo,ou=users,dc=example,dc=com: \- delete_others: True \- default: userPassword: changeme shadowLastChange: 0 # keep sshPublicKey if present, but don\(aqt create # the attribute if it is missing sshPublicKey: [] \- replace: cn: foo uid: foo uidNumber: 1000 gidNumber: 1000 gecos: Foo Bar givenName: Foo sn: Bar homeDirectory: /home/foo loginShell: /bin/bash objectClass: \- inetOrgPerson \- posixAccount \- top \- ldapPublicKey \- shadowAccount .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The URL of the LDAP server. This is ignored if \fBconnect_spec\fP is either a connection object or a dict with a \fB\(aqurl\(aq\fP entry. .IP \(bu 2 \fBentries\fP \-\- .sp A description of the desired state of zero or more LDAP entries. .sp \fBentries\fP is an iterable of dicts. Each of these dict\(aqs keys are the distinguished names (DNs) of LDAP entries to manage. Each of these dicts is processed in order. A later dict can reference an LDAP entry that was already mentioned in an earlier dict, which makes it possible for later dicts to enhance or alter the desired state of an LDAP entry. .sp The DNs are mapped to a description of the LDAP entry\(aqs desired state. These LDAP entry descriptions are themselves iterables of dicts. Each dict in the iterable is processed in order. They contain directives controlling the entry\(aqs state. The key names the directive type and the value is state information for the directive. The specific structure of the state information depends on the directive type. .sp The structure of \fBentries\fP looks like this: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C [{dn1: [{directive1: directive1_state, directive2: directive2_state}, {directive3: directive3_state}], dn2: [{directive4: directive4_state, directive5: directive5_state}]}, {dn3: [{directive6: directive6_state}]}] .ft P .fi .UNINDENT .UNINDENT .sp These are the directives: .INDENT 2.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqdelete_others\(aq\fP Boolean indicating whether to delete attributes not mentioned in this dict or any of the other directive dicts for this DN. Defaults to \fBFalse\fP\&. .sp If you don\(aqt want to delete an attribute if present, but you also don\(aqt want to add it if it is missing or modify it if it is present, you can use either the \fB\(aqdefault\(aq\fP directive or the \fB\(aqadd\(aq\fP directive with an empty value list. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqdefault\(aq\fP A dict mapping an attribute name to an iterable of default values for that attribute. If the attribute already exists, it is left alone. If not, it is created using the given list of values. .sp An empty value list is useful when you don\(aqt want to create an attribute if it is missing but you do want to preserve it if the \fB\(aqdelete_others\(aq\fP key is \fBTrue\fP\&. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqadd\(aq\fP Attribute values to add to the entry. This is a dict mapping an attribute name to an iterable of values to add. .sp An empty value list is useful when you don\(aqt want to create an attribute if it is missing but you do want to preserve it if the \fB\(aqdelete_others\(aq\fP key is \fBTrue\fP\&. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqdelete\(aq\fP Attribute values to remove from the entry. This is a dict mapping an attribute name to an iterable of values to delete from the attribute. If the iterable is empty, all of the attribute\(aqs values are deleted. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqreplace\(aq\fP Attributes to replace. This is a dict mapping an attribute name to an iterable of values. Any existing values for the attribute are deleted, then the given values are added. The iterable may be empty. .UNINDENT .UNINDENT .sp In the above directives, the iterables of attribute values may instead be \fBNone\fP, in which case an empty list is used, or a scalar such as a string or number, in which case a new list containing the scalar is used. .sp Note that if all attribute values are removed from an entry, the entire entry is deleted. .IP \(bu 2 \fBconnect_spec\fP \-\- See the description of the \fBconnect_spec\fP parameter of the \fI\%ldap3.connect\fP function in the \fI\%ldap3\fP execution module. If this is a dict and the \fB\(aqurl\(aq\fP entry is not specified, the \fB\(aqurl\(aq\fP entry is set to the value of the \fBname\fP parameter. .UNINDENT .TP .B Returns A dict with the following keys: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqname\(aq\fP This is the same object passed to the \fBname\fP parameter. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqchanges\(aq\fP This is a dict describing the changes made (or, in test mode, the changes that would have been attempted). If no changes were made (or no changes would have been attempted), then this dict is empty. Only successful changes are included. .sp Each key is a DN of an entry that was changed (or would have been changed). Entries that were not changed (or would not have been changed) are not included. The value is a dict with two keys: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqold\(aq\fP The state of the entry before modification. If the entry did not previously exist, this key maps to \fBNone\fP\&. Otherwise, the value is a dict mapping each of the old entry\(aqs attributes to a list of its values before any modifications were made. Unchanged attributes are excluded from this dict. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqnew\(aq\fP The state of the entry after modification. If the entry was deleted, this key maps to \fBNone\fP\&. Otherwise, the value is a dict mapping each of the entry\(aqs attributes to a list of its values after the modifications were made. Unchanged attributes are excluded from this dict. .UNINDENT .UNINDENT .sp Example \fB\(aqchanges\(aq\fP dict where a new entry was created with a single attribute containing two values: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqdn1\(aq: {\(aqold\(aq: None, \(aqnew\(aq: {\(aqattr1\(aq: [\(aqval1\(aq, \(aqval2\(aq]}}} .ft P .fi .UNINDENT .UNINDENT .sp Example \fB\(aqchanges\(aq\fP dict where a new attribute was added to an existing entry: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqdn1\(aq: {\(aqold\(aq: {}, \(aqnew\(aq: {\(aqattr2\(aq: [\(aqval3\(aq]}}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fB\(aqresult\(aq\fP One of the following values: .INDENT 7.0 .IP \(bu 2 \fBTrue\fP if no changes were necessary or if all changes were applied successfully. .IP \(bu 2 \fBFalse\fP if at least one change was unable to be applied. .IP \(bu 2 \fBNone\fP if changes would be applied but it is in test mode. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.states.libcloud_dns .sp Manage DNS records and zones using libcloud .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B codeauthor Anthony Shaw <\fI\%anthonyshaw@apache.org\fP> .UNINDENT .UNINDENT .UNINDENT .sp New in version 2016.11.0. .sp Create and delete DNS records or zones through Libcloud. Libcloud\(aqs DNS system supports over 20 DNS providers including Amazon, Google, GoDaddy, Softlayer .sp This module uses \fBlibcloud\fP, which can be installed via package, or pip. .INDENT 0.0 .TP .B configuration This module uses a configuration profile for one or multiple DNS providers .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C libcloud_dns: profile1: driver: godaddy key: 2orgk34kgk34g profile2: driver: route53 key: blah secret: blah .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-zone: libcloud_dns.zone_present: \- name: mywebsite.com \- profile: profile1 my\-website: libcloud_dns.record_present: \- name: www \- zone: mywebsite.com \- type: A \- data: 12.34.32.3 \- profile: profile1 \- require: \- libcloud_dns: my\-zone .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends apache\-libcloud .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_dns.record_absent(name, zone, type, data, profile) Ensures a record is absent. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Record name without the domain name (e.g. www). Note: If you want to create a record for a base domain name, you should specify empty string (\(aq\(aq) for this argument. .IP \(bu 2 \fBzone\fP (\fBstr\fP) \-\- Zone where the requested record is created, the domain name .IP \(bu 2 \fBtype\fP (\fBstr\fP) \-\- DNS record type (A, AAAA, ...). .IP \(bu 2 \fBdata\fP (\fBstr\fP) \-\- Data for the record (depends on the record type). .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_dns.record_present(name, zone, type, data, profile) Ensures a record is present. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Record name without the domain name (e.g. www). Note: If you want to create a record for a base domain name, you should specify empty string (\(aq\(aq) for this argument. .IP \(bu 2 \fBzone\fP (\fBstr\fP) \-\- Zone where the requested record is created, the domain name .IP \(bu 2 \fBtype\fP (\fBstr\fP) \-\- DNS record type (A, AAAA, ...). .IP \(bu 2 \fBdata\fP (\fBstr\fP) \-\- Data for the record (depends on the record type). .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_dns.state_result(result, message, name, changes=None) .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_dns.zone_absent(domain, profile) Ensures a record is absent. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain\fP (\fBstr\fP) \-\- Zone name, i.e. the domain name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_dns.zone_present(domain, type, profile) Ensures a record is present. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain\fP (\fBstr\fP) \-\- Zone name, i.e. the domain name .IP \(bu 2 \fBtype\fP (\fBstr\fP) \-\- Zone type (master / slave), defaults to master .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .UNINDENT .SS salt.states.libcloud_loadbalancer .SS Apache Libcloud Load Balancer State .sp Manage load balancers using libcloud .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B codeauthor \fBAnthony Shaw <anthonyshaw@apache.org>\fP .UNINDENT .UNINDENT .UNINDENT .sp Apache Libcloud load balancer management for a full list of supported clouds, see \fI\%http://libcloud.readthedocs.io/en/latest/loadbalancer/supported_providers.html\fP .sp Clouds include Amazon ELB, ALB, Google, Aliyun, CloudStack, Softlayer .sp New in version 2018.3.0. .INDENT 0.0 .TP .B configuration This module uses a configuration profile for one or multiple Cloud providers .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C libcloud_loadbalancer: profile_test1: driver: gce key: GOOG0123456789ABCXYZ secret: mysecret profile_test2: driver: alb key: 12345 secret: mysecret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Example: .sp Using States to deploy a load balancer with extended arguments to specify region .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lb_test: libcloud_loadbalancer.balancer_present: \- name: example \- port: 80 \- protocol: http \- profile: google \- ex_region: us\-east1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends apache\-libcloud .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_loadbalancer.balancer_absent(name, profile, **libcloud_kwargs) Ensures a load balancer is absent. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Load Balancer name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_loadbalancer.balancer_present(name, port, protocol, profile, algorithm=None, members=None, **libcloud_kwargs) Ensures a load balancer is present. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Load Balancer name .IP \(bu 2 \fBport\fP (\fBstr\fP) \-\- Port the load balancer should listen on, defaults to 80 .IP \(bu 2 \fBprotocol\fP (\fBstr\fP) \-\- Loadbalancer protocol, defaults to http. .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBalgorithm\fP (\fBstr\fP) \-\- Load balancing algorithm, defaults to ROUND_ROBIN. See Algorithm type in Libcloud documentation for a full listing. .IP \(bu 2 \fBmembers\fP (\fBlist\fP of \fBdict\fP (ip, port)) \-\- An optional list of members to create on deployment .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_loadbalancer.member_absent(ip, port, balancer_id, profile, **libcloud_kwargs) Ensure a load balancer member is absent, based on IP and Port .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBip\fP (\fBstr\fP) \-\- IP address for the member .IP \(bu 2 \fBport\fP (\fBint\fP) \-\- Port for the member .IP \(bu 2 \fBbalancer_id\fP (\fBstr\fP) \-\- id of a load balancer you want to detach the member from .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_loadbalancer.member_present(ip, port, balancer_id, profile, **libcloud_kwargs) Ensure a load balancer member is present .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBip\fP (\fBstr\fP) \-\- IP address for the new member .IP \(bu 2 \fBport\fP (\fBint\fP) \-\- Port for the new member .IP \(bu 2 \fBbalancer_id\fP (\fBstr\fP) \-\- id of a load balancer you want to attach the member to .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_loadbalancer.state_result(result, message, name, changes=None) .UNINDENT .SS salt.states.libcloud_storage .SS Apache Libcloud Storage State .sp Manage cloud storage using libcloud .INDENT 0.0 .TP .B codeauthor \fBAnthony Shaw <anthonyshaw@apache.org>\fP .UNINDENT .sp Apache Libcloud Storage (object/blob) management for a full list of supported clouds, see \fI\%http://libcloud.readthedocs.io/en/latest/storage/supported_providers.html\fP .sp Clouds include Amazon S3, Google Storage, Aliyun, Azure Blobs, Ceph, OpenStack swift .sp New in version 2018.3.0. .INDENT 0.0 .TP .B configuration This module uses a configuration profile for one or multiple Storage providers .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C libcloud_storage: profile_test1: driver: google_storage key: GOOG0123456789ABCXYZ secret: mysecret profile_test2: driver: s3 key: 12345 secret: mysecret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Examples .SS Creating a container and uploading a file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C web_things: libcloud_storage.container_present: name: my_container_name profile: profile1 libcloud_storage.object_present: name: my_file.jpg container: my_container_name path: /path/to/local/file.jpg profile: profile1 .ft P .fi .UNINDENT .UNINDENT .SS Downloading a file .sp This example will download the file from the remote cloud and keep it locally .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C web_things: libcloud_storage.file_present: name: my_file.jpg container: my_container_name path: /path/to/local/file.jpg profile: profile1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends apache\-libcloud .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_storage.container_absent(name, profile) Ensures a container is absent. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Container name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_storage.container_present(name, profile) Ensures a container is present. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Container name .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_storage.file_present(container, name, path, profile, overwrite_existing=False) Ensures a object is downloaded locally. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontainer\fP (\fBstr\fP) \-\- Container name .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Object name in cloud .IP \(bu 2 \fBpath\fP (\fBstr\fP) \-\- Local path to file .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .IP \(bu 2 \fBoverwrite_existing\fP (\fBbool\fP) \-\- Replace if already exists .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_storage.object_absent(container, name, profile) Ensures a object is absent. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontainer\fP (\fBstr\fP) \-\- Container name .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Object name in cloud .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_storage.object_present(container, name, path, profile) Ensures a object is presnt. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontainer\fP (\fBstr\fP) \-\- Container name .IP \(bu 2 \fBname\fP (\fBstr\fP) \-\- Object name in cloud .IP \(bu 2 \fBpath\fP (\fBstr\fP) \-\- Local path to file .IP \(bu 2 \fBprofile\fP (\fBstr\fP) \-\- The profile key .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.libcloud_storage.state_result(result, message, name, changes) .UNINDENT .SS salt.states.linux_acl .sp Linux File Access Control Lists .sp The Linux ACL state module requires the \fIgetfacl\fP and \fIsetfacl\fP binaries. .sp Ensure a Linux ACL is present .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root: acl.present: \- name: /root \- acl_type: user \- acl_name: damian \- perms: rwx .ft P .fi .UNINDENT .UNINDENT .sp Ensure a Linux ACL is present as a default for all new objects .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root: acl.present: \- name: /root \- acl_type: \(dqdefault:user\(dq \- acl_name: damian \- perms: rwx .ft P .fi .UNINDENT .UNINDENT .sp Ensure a Linux ACL does not exist .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root: acl.absent: \- name: /root \- acl_type: user \- acl_name: damian \- perms: rwx .ft P .fi .UNINDENT .UNINDENT .sp Ensure a Linux ACL list is present .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root: acl.list_present: \- name: /root \- acl_type: user \- acl_names: \- damian \- homer \- perms: rwx .ft P .fi .UNINDENT .UNINDENT .sp Ensure a Linux ACL list does not exist .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root: acl.list_absent: \- name: /root \- acl_type: user \- acl_names: \- damian \- homer \- perms: rwx .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The effective permissions of Linux file access control lists (ACLs) are governed by the \(dqeffective rights mask\(dq (the \fImask\fP line in the output of the \fIgetfacl\fP command) combined with the \fIperms\fP set by this module: any permission bits (for example, r=read) present in an ACL but not in the mask are ignored. The mask is automatically recomputed when setting an ACL, so normally this isn\(aqt important. However, if the file permissions are changed (with \fIchmod\fP or \fIfile.managed\fP, for example), the mask will generally be set based on just the group bits of the file permissions. .sp As a result, when using \fIfile.managed\fP or similar to control file permissions as well as this module, you should set your group permissions to be at least as broad as any permissions in your ACL. Otherwise, the two state declarations will each register changes each run, and if the \fIfile\fP declaration runs later, your ACL will be ineffective. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.linux_acl.absent(name, acl_type, acl_name=\(aq\(aq, perms=\(aq\(aq, recurse=False) Ensure a Linux ACL does not exist .INDENT 7.0 .TP .B name The acl path .TP .B acl_type The type of the acl is used for, it can be \(aquser\(aq or \(aqgroup\(aq .TP .B acl_name The user or group .TP .B perms Remove the permissions eg.: rwx .TP .B recurse Set the permissions recursive in the path .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.linux_acl.list_absent(name, acl_type, acl_names=None, recurse=False) Ensure a Linux ACL list does not exist .sp Takes a list of acl names and remove them from the given path .INDENT 7.0 .TP .B name The acl path .TP .B acl_type The type of the acl is used for, it can be \(aquser\(aq or \(aqgroup\(aq .TP .B acl_names The list of users or groups .TP .B perms Remove the permissions eg.: rwx .TP .B recurse Set the permissions recursive in the path .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.linux_acl.list_present(name, acl_type, acl_names=None, perms=\(aq\(aq, recurse=False, force=False) Ensure a Linux ACL list is present .sp Takes a list of acl names and add them to the given path .INDENT 7.0 .TP .B name The acl path .TP .B acl_type The type of the acl is used for it can be \(aquser\(aq or \(aqgroup\(aq .TP .B acl_names The list of users or groups .TP .B perms Set the permissions eg.: rwx .TP .B recurse Set the permissions recursive in the path .TP .B force Wipe out old permissions and ensure only the new permissions are set .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.linux_acl.present(name, acl_type, acl_name=\(aq\(aq, perms=\(aq\(aq, recurse=False, force=False) Ensure a Linux ACL is present .INDENT 7.0 .TP .B name The acl path .TP .B acl_type The type of the acl is used for it can be \(aquser\(aq or \(aqgroup\(aq .TP .B acl_name The user or group .TP .B perms Set the permissions eg.: rwx .TP .B recurse Set the permissions recursive in the path .TP .B force Wipe out old permissions and ensure only the new permissions are set .UNINDENT .UNINDENT .SS salt.states.locale .SS Management of languages/locales .sp Manage the available locales and the system default: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C us_locale: locale.present: \- name: en_US.UTF\-8 default_locale: locale.system: \- name: en_US.UTF\-8 \- require: \- locale: us_locale .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.locale.present(name) Generate a locale if it is not present .sp New in version 2014.7.0. .INDENT 7.0 .TP .B name The name of the locale to be present. Some distributions require the charmap to be specified as part of the locale at this point. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.locale.system(name) Set the locale for the system .INDENT 7.0 .TP .B name The name of the locale to use .UNINDENT .UNINDENT .SS salt.states.logadm .sp Management of logs using Solaris logadm. .INDENT 0.0 .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B depends salt.modulus.logadm .TP .B platform Oracle Solaris, Sun Solaris, illumos .UNINDENT .sp New in version 2017.7.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&.. note:: TODO .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.logadm.remove(name, log_file=None) Remove a log from the logadm configuration .INDENT 7.0 .TP .B name string entryname .TP .B log_file string (optional) log file path .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If log_file is specified it will be used instead of the entry name. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.logadm.rotate(name, **kwargs) Add a log to the logadm configuration .INDENT 7.0 .TP .B name string alias for entryname .TP .B kwargs boolean|string|int optional additional flags and parameters .UNINDENT .UNINDENT .SS salt.states.logrotate .sp Module for managing logrotate. .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.states.logrotate.set_(name, key, value, setting=None, conf_file=\(aq/etc/logrotate.conf\(aq) Set a new value for a specific configuration line. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBkey\fP (\fI\%str\fP) \-\- The command or block to configure. .IP \(bu 2 \fBvalue\fP (\fI\%str\fP) \-\- The command value or command of the block specified by the key parameter. .IP \(bu 2 \fBsetting\fP (\fI\%str\fP) \-\- The command value for the command specified by the value parameter. .IP \(bu 2 \fBconf_file\fP (\fI\%str\fP) \-\- The logrotate configuration file. .UNINDENT .UNINDENT .sp Example of usage with only the required arguments: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C logrotate\-rotate: logrotate.set: \- key: rotate \- value: 2 .ft P .fi .UNINDENT .UNINDENT .sp Example of usage specifying all available arguments: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C logrotate\-wtmp\-rotate: logrotate.set: \- key: /var/log/wtmp \- value: rotate \- setting: 2 \- conf_file: /etc/logrotate.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.loop .sp Loop state .sp Allows for looping over execution modules. .sp New in version 2017.7.0. .sp In both examples below, the execution module function \fBboto_elb.get_instance_health\fP returns a list of dicts. The condition checks the \fBstate\fP\-key of the first dict in the returned list and compares its value to the string \fIInService\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wait_for_service_to_be_healthy: loop.until: \- name: boto_elb.get_instance_health \- condition: m_ret[0][\(aqstate\(aq] == \(aqInService\(aq \- period: 5 \- timeout: 20 \- m_args: \- {{ elb }} \- m_kwargs: keyid: {{ access_key }} key: {{ secret_key }} instances: \(dq{{ instance }}\(dq .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This state allows arbitrary python code to be executed through the condition parameter which is literally evaluated within the state. Please use caution. .UNINDENT .UNINDENT .sp Changed in version 3000. .sp A version that does not use eval is now available. It uses either the python \fBoperator\fP to compare the result of the function called in \fBname\fP, which can be one of the following: lt, le, eq (default), ne, ge, gt. Alternatively, \fIcompare_operator\fP can be filled with a function from an execution module in \fB__salt__\fP or \fB__utils__\fP like the example below. The function \fBdata.subdict_match\fP checks if the \fBexpected\fP expression matches the data returned by calling the \fBname\fP function (with passed \fBargs\fP and \fBkwargs\fP). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Wait for service to be healthy: loop.until_no_eval: \- name: boto_elb.get_instance_health \- expected: \(aq0:state:InService\(aq \- compare_operator: data.subdict_match \- period: 5 \- timeout: 20 \- args: \- {{ elb }} \- kwargs: keyid: {{ access_key }} key: {{ secret_key }} instances: \(dq{{ instance }}\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.loop.until(name, m_args=None, m_kwargs=None, condition=None, period=1, timeout=60) Loop over an execution module until a condition is met. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the execution module .IP \(bu 2 \fBm_args\fP (\fI\%list\fP) \-\- The execution module\(aqs positional arguments .IP \(bu 2 \fBm_kwargs\fP (\fI\%dict\fP) \-\- The execution module\(aqs keyword arguments .IP \(bu 2 \fBcondition\fP (\fI\%str\fP) \-\- The condition which must be met for the loop to break. This should contain \fBm_ret\fP which is the return from the execution module. .IP \(bu 2 \fBperiod\fP (\fI\%int\fP\fI or \fP\fI\%float\fP) \-\- The number of seconds to wait between executions .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP\fI or \fP\fI\%float\fP) \-\- The timeout in seconds .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.loop.until_no_eval(name, expected, compare_operator=\(aqeq\(aq, timeout=60, period=1, init_wait=0, args=None, kwargs=None) Generic waiter state that waits for a specific salt function to produce an expected result. The state fails if the function does not exist or raises an exception, or does not produce the expected result within the allotted retries. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name of the module.function to call .IP \(bu 2 \fBexpected\fP \-\- Expected return value. This can be almost anything. .IP \(bu 2 \fBcompare_operator\fP (\fI\%str\fP) \-\- Operator to use to compare the result of the module.function call with the expected value. This can be anything present in __salt__ or __utils__. Will be called with 2 args: result, expected. .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP\fI or \fP\fI\%float\fP) \-\- Abort after this amount of seconds (excluding init_wait). .IP \(bu 2 \fBperiod\fP (\fI\%int\fP\fI or \fP\fI\%float\fP) \-\- Time (in seconds) to wait between attempts. .IP \(bu 2 \fBinit_wait\fP (\fI\%int\fP\fI or \fP\fI\%float\fP) \-\- Time (in seconds) to wait before trying anything. .IP \(bu 2 \fBargs\fP (\fI\%list\fP) \-\- args to pass to the salt module.function. .IP \(bu 2 \fBkwargs\fP (\fI\%dict\fP) \-\- kwargs to pass to the salt module.function. .UNINDENT .UNINDENT .sp New in version 3000. .UNINDENT .SS salt.states.lvm .SS Management of Linux logical volumes .sp A state module to manage LVMs .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /dev/sda: lvm.pv_present my_vg: lvm.vg_present: \- devices: /dev/sda lvroot: lvm.lv_present: \- vgname: my_vg \- size: 10G \- stripes: 5 \- stripesize: 8K .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lvm.lv_absent(name, vgname=None) Remove a given existing Logical Volume from a named existing volume group .INDENT 7.0 .TP .B name The Logical Volume to remove .TP .B vgname The name of the Volume Group on which the Logical Volume resides .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lvm.lv_present(name, vgname=None, size=None, extents=None, snapshot=None, pv=\(aq\(aq, thinvolume=False, thinpool=False, force=False, resizefs=False, **kwargs) Ensure that a Logical Volume is present, creating it if absent. .INDENT 7.0 .TP .B name The name of the Logical Volume .TP .B vgname The name of the Volume Group on which the Logical Volume resides .TP .B size The size of the Logical Volume in megabytes, or use a suffix such as S, M, G, T, P for 512 byte sectors, megabytes, gigabytes or terabytes respectively. The suffix is case insensitive. .TP .B extents The number of logical extents allocated to the Logical Volume It can be a percentage allowed by lvcreate\(aqs syntax, in this case it will set the Logical Volume initial size and won\(aqt be resized. .TP .B snapshot The name of the snapshot .TP .B pv The Physical Volume to use .TP .B kwargs Any supported options to lvcreate. See \fI\%linux_lvm\fP for more details. .UNINDENT .sp New in version 2016.11.0. .INDENT 7.0 .TP .B thinvolume Logical Volume is thinly provisioned .TP .B thinpool Logical Volume is a thin pool .UNINDENT .sp New in version 2018.3.0. .INDENT 7.0 .TP .B force Assume yes to all prompts .UNINDENT .sp New in version 3002. .INDENT 7.0 .TP .B resizefs Use fsadm to resize the logical volume filesystem if needed .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lvm.pv_absent(name) Ensure that a Physical Device is not being used by lvm .INDENT 7.0 .TP .B name The device name to initialize. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lvm.pv_present(name, **kwargs) Set a Physical Device to be used as an LVM Physical Volume .INDENT 7.0 .TP .B name The device name to initialize. .TP .B kwargs Any supported options to pvcreate. See \fI\%linux_lvm\fP for more details. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lvm.vg_absent(name) Remove an LVM volume group .INDENT 7.0 .TP .B name The volume group to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lvm.vg_present(name, devices=None, **kwargs) Create an LVM Volume Group .INDENT 7.0 .TP .B name The Volume Group name to create .TP .B devices A list of devices that will be added to the Volume Group .TP .B kwargs Any supported options to vgcreate. See \fI\%linux_lvm\fP for more details. .UNINDENT .UNINDENT .SS salt.states.lvs_server .SS Management of LVS (Linux Virtual Server) Real Server .INDENT 0.0 .TP .B salt.states.lvs_server.absent(name, protocol=None, service_address=None, server_address=None) Ensure the LVS Real Server in specified service is absent. .INDENT 7.0 .TP .B name The name of the LVS server. .TP .B protocol The service protocol(only support \fBtcp\fP, \fBudp\fP and \fBfwmark\fP service). .TP .B service_address The LVS service address. .TP .B server_address The LVS real server address. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lvs_server.present(name, protocol=None, service_address=None, server_address=None, packet_forward_method=\(aqdr\(aq, weight=1) Ensure that the named service is present. .INDENT 7.0 .TP .B name The LVS server name .TP .B protocol The service protocol .TP .B service_address The LVS service address .TP .B server_address The real server address. .TP .B packet_forward_method The LVS packet forwarding method(\fBdr\fP for direct routing, \fBtunnel\fP for tunneling, \fBnat\fP for network access translation). .TP .B weight The capacity of a server relative to the others in the pool. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C lvsrs: lvs_server.present: \- protocol: tcp \- service_address: 1.1.1.1:80 \- server_address: 192.168.0.11:8080 \- packet_forward_method: dr \- weight: 10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.lvs_service .SS Management of LVS (Linux Virtual Server) Service .INDENT 0.0 .TP .B salt.states.lvs_service.absent(name, protocol=None, service_address=None) Ensure the LVS service is absent. .INDENT 7.0 .TP .B name The name of the LVS service .TP .B protocol The service protocol .TP .B service_address The LVS service address .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lvs_service.present(name, protocol=None, service_address=None, scheduler=\(aqwlc\(aq) Ensure that the named service is present. .INDENT 7.0 .TP .B name The LVS service name .TP .B protocol The service protocol .TP .B service_address The LVS service address .TP .B scheduler Algorithm for allocating TCP connections and UDP datagrams to real servers. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C lvstest: lvs_service.present: \- service_address: 1.1.1.1:80 \- protocol: tcp \- scheduler: rr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.lxc .SS Manage Linux Containers .INDENT 0.0 .TP .B salt.states.lxc.absent(name, stop=False, path=None) Ensure a container is not present, destroying it if present .INDENT 7.0 .TP .B name Name of the container to destroy .TP .B stop stop before destroying default: false .sp New in version 2015.5.2. .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C web01: lxc.absent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxc.edited_conf(name, lxc_conf=None, lxc_conf_unset=None) .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This state is unsuitable for setting parameters that appear more than once in an LXC config file, or parameters which must appear in a certain order (such as when configuring more than one network interface). .sp \fI\%Issue #35523\fP was opened to track the addition of a suitable replacement or fix. .UNINDENT .UNINDENT .sp Edit LXC configuration options .sp Deprecated since version 2015.5.0. .INDENT 7.0 .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C setconf: lxc.edited_conf: \- name: ubuntu \- lxc_conf: \- network.ipv4.ip: 10.0.3.6 \- lxc_conf_unset: \- lxc.utsname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxc.frozen(name, start=True, path=None) New in version 2015.5.0. .sp Ensure that a container is frozen .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state does not enforce the existence of the named container, it just freezes the container if it is running. To ensure that the named container exists, use \fI\%lxc.present\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the container .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B start True Start container first, if necessary. If \fBFalse\fP, then this state will fail if the container is not running. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C web01: lxc.frozen web02: lxc.frozen: \- start: False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxc.present(name, running=None, clone_from=None, snapshot=False, profile=None, network_profile=None, template=None, options=None, image=None, config=None, fstype=None, size=None, backing=None, vgname=None, lvname=None, thinpool=None, path=None) Changed in version 2015.8.0: The \fBlxc.created\fP state has been renamed to \fBlxc.present\fP, and the \fBlxc.cloned\fP state has been merged into this state. .sp Create the named container if it does not exist .INDENT 7.0 .TP .B name The name of the container to be created .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B running False.INDENT 7.0 .IP \(bu 2 If \fBTrue\fP, ensure that the container is running .IP \(bu 2 If \fBFalse\fP, ensure that the container is stopped .IP \(bu 2 If \fBNone\fP, do nothing with regards to the running state of the container .UNINDENT .sp New in version 2015.8.0. .TP .B clone_from Create named container as a clone of the specified container .TP .B snapshot False Use Copy On Write snapshots (LVM). Only supported with \fBclone_from\fP\&. .TP .B profile Profile to use in container creation (see the \fI\%LXC Tutorial\fP for more information). Values in a profile will be overridden by the parameters listed below. .TP .B network_profile Network Profile to use in container creation (see the \fI\%LXC Tutorial\fP for more information). Values in a profile will be overridden by the parameters listed below. .sp New in version 2015.5.2. .UNINDENT .sp \fBContainer Creation Arguments\fP .INDENT 7.0 .TP .B template The template to use. For example, \fBubuntu\fP or \fBfedora\fP\&. For a full list of available templates, check out the \fI\%lxc.templates\fP function. .sp Conflicts with the \fBimage\fP argument. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fBdownload\fP template requires the following three parameters to be defined in \fBoptions\fP: .INDENT 0.0 .IP \(bu 2 \fBdist\fP \- The name of the distribution .IP \(bu 2 \fBrelease\fP \- Release name/version .IP \(bu 2 \fBarch\fP \- Architecture of the container .UNINDENT .sp The available images can be listed using the \fI\%lxc.images\fP function. .UNINDENT .UNINDENT .UNINDENT .sp options .INDENT 7.0 .INDENT 3.5 New in version 2015.5.0. .sp Template\-specific options to pass to the lxc\-create command. These correspond to the long options (ones beginning with two dashes) that the template script accepts. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C web01: lxc.present: \- template: download \- options: dist: centos release: 6 arch: amd64 .ft P .fi .UNINDENT .UNINDENT .sp Remember to double\-indent the options, due to \fI\%how PyYAML works\fP\&. .sp For available template options, refer to the lxc template scripts which are usually located under \fB/usr/share/lxc/templates\fP, or run \fBlxc\-create \-t <template> \-h\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B image A tar archive to use as the rootfs for the container. Conflicts with the \fBtemplate\fP argument. .TP .B backing The type of storage to use. Set to \fBlvm\fP to use an LVM group. Defaults to filesystem within /var/lib/lxc. .TP .B fstype Filesystem type to use on LVM logical volume .TP .B size Size of the volume to create. Only applicable if \fBbacking\fP is set to \fBlvm\fP\&. .TP .B vgname lxc Name of the LVM volume group in which to create the volume for this container. Only applicable if \fBbacking\fP is set to \fBlvm\fP\&. .TP .B lvname Name of the LVM logical volume in which to create the volume for this container. Only applicable if \fBbacking\fP is set to \fBlvm\fP\&. .TP .B thinpool Name of a pool volume that will be used for thin\-provisioning this container. Only applicable if \fBbacking\fP is set to \fBlvm\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxc.running(name, restart=False, path=None) Changed in version 2015.5.0: The \fBlxc.started\fP state has been renamed to \fBlxc.running\fP .sp Ensure that a container is running .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state does not enforce the existence of the named container, it just starts the container if it is not running. To ensure that the named container exists, use \fI\%lxc.present\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the container .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B restart False Restart container if it is already running .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C web01: lxc.running web02: lxc.running: \- restart: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxc.set_pass(name, **kwargs) Deprecated since version 2015.5.0. .sp This state function has been disabled, as it did not conform to design guidelines. Specifically, due to the fact that \fI\%lxc.set_password\fP uses \fBchpasswd(8)\fP to set the password, there was no method to make this action idempotent (in other words, the password would be changed every time). This makes this state redundant, since the following state will do the same thing: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C setpass: module.run: \- name: set_pass \- m_name: root \- password: secret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxc.stopped(name, kill=False, path=None) Ensure that a container is stopped .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state does not enforce the existence of the named container, it just stops the container if it running or frozen. To ensure that the named container exists, use \fI\%lxc.present\fP, or use the \fI\%lxc.absent\fP state to ensure that the container does not exist. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the container .TP .B path path to the container parent default: /var/lib/lxc (system default) .sp New in version 2015.8.0. .TP .B kill False Do not wait for the container to stop, kill all tasks in the container. Older LXC versions will stop containers like this irrespective of this argument. .sp New in version 2015.5.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C web01: lxc.stopped .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.lxd .sp Manage LXD profiles. .sp New in version 2019.2.0. .INDENT 0.0 .TP .B maintainer René Jochum <\fI\%rene@jochums.at\fP> .TP .B maturity new .TP .B depends python\-pylxd .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd.authenticate(name, remote_addr, password, cert, key, verify_cert=True) Authenticate with a remote peer. .INDENT 7.0 .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B password : The PaSsW0rD .TP .B cert : PEM Formatted SSL Zertifikate. .INDENT 7.0 .TP .B Examples: /root/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: /root/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .TP .B name: Ignore this. This is just here for salt. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd.config_managed(name, value, force_password=False) Manage a LXD Server config setting. .INDENT 7.0 .TP .B name : The name of the config key. .TP .B value : Its value. .TP .B force_password False Set this to True if you want to set the password on every run. .sp As we can\(aqt retrieve the password from LXD we can\(aqt check if the current one is the same as the given one. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd.init(name, storage_backend=\(aqdir\(aq, trust_password=None, network_address=None, network_port=None, storage_create_device=None, storage_create_loop=None, storage_pool=None, done_file=\(aq%SALT_CONFIG_DIR%/lxd_initialized\(aq) Initializes the LXD Daemon, as LXD doesn\(aqt tell if its initialized we touch the done_file and check if it exist. .sp This can only be called once per host unless you remove the done_file. .INDENT 7.0 .TP .B name : Ignore this. This is just here for salt. .TP .B storage_backend : Storage backend to use (zfs or dir, default: dir) .TP .B trust_password : Password required to add new clients .TP .B network_address None Address to bind LXD to (default: none) .TP .B network_port None Port to bind LXD to (Default: 8443) .TP .B storage_create_device None Setup device based storage using this DEVICE .TP .B storage_create_loop None Setup loop based storage with this SIZE in GB .TP .B storage_pool None Storage pool to use or create .TP .B done_file : Path where we check that this method has been called, as it can run only once and there\(aqs currently no way to ask LXD if init has been called. .UNINDENT .UNINDENT .SS salt.states.lxd_container .sp Manage LXD containers. .sp New in version 2019.2.0. .INDENT 0.0 .TP .B maintainer René Jochum <\fI\%rene@jochums.at\fP> .TP .B maturity new .TP .B depends python\-pylxd .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd_container.absent(name, stop=False, remote_addr=None, cert=None, key=None, verify_cert=True) Ensure a LXD container is not present, destroying it if present .INDENT 7.0 .TP .B name : The name of the container to destroy .TP .B stop : stop before destroying default: false .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Zertifikate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd_container.frozen(name, start=True, remote_addr=None, cert=None, key=None, verify_cert=True) Ensure a LXD container is frozen, start and freeze it if start is true .INDENT 7.0 .TP .B name : The name of the container to freeze .TP .B start : start and freeze it .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Zertifikate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd_container.migrated(name, remote_addr, cert, key, verify_cert, src_remote_addr, stop_and_start=False, src_cert=None, src_key=None, src_verify_cert=None) Ensure a container is migrated to another host .sp If the container is running, it either must be shut down first (use stop_and_start=True) or criu must be installed on the source and destination machines. .sp For this operation both certs need to be authenticated, use \fBlxd.authenticate <salt.states.lxd.authenticate\fP to authenticate your cert(s). .INDENT 7.0 .TP .B name : The container to migrate .TP .B remote_addr : An URL to the destination remote Server .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Zertifikate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .TP .B src_remote_addr : An URL to the source remote Server .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B stop_and_start: Stop before migrating and start after .TP .B src_cert : PEM Formatted SSL Zertifikate, if None we copy \(dqcert\(dq .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B src_key : PEM Formatted SSL Key, if None we copy \(dqkey\(dq .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B src_verify_cert : Wherever to verify the cert, if None we copy \(dqverify_cert\(dq .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd_container.present(name, running=None, source=None, profiles=None, config=None, devices=None, architecture=\(aqx86_64\(aq, ephemeral=False, restart_on_change=False, remote_addr=None, cert=None, key=None, verify_cert=True) Create the named container if it does not exist .INDENT 7.0 .TP .B name The name of the container to be created .TP .B running None.INDENT 7.0 .IP \(bu 2 If \fBTrue\fP, ensure that the container is running .IP \(bu 2 If \fBFalse\fP, ensure that the container is stopped .IP \(bu 2 If \fBNone\fP, do nothing with regards to the running state of the container .UNINDENT .TP .B source None Can be either a string containing an image alias: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \(dqxenial/amd64\(dq .ft P .fi .UNINDENT .UNINDENT .sp or an dict with type \(dqimage\(dq with alias: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(dqtype\(dq: \(dqimage\(dq, \(dqalias\(dq: \(dqxenial/amd64\(dq} .ft P .fi .UNINDENT .UNINDENT .sp or image with \(dqfingerprint\(dq: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(dqtype\(dq: \(dqimage\(dq, \(dqfingerprint\(dq: \(dqSHA\-256\(dq} .ft P .fi .UNINDENT .UNINDENT .sp or image with \(dqproperties\(dq: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(dqtype\(dq: \(dqimage\(dq, \(dqproperties\(dq: { \(dqos\(dq: \(dqubuntu\(dq, \(dqrelease\(dq: \(dq14.04\(dq, \(dqarchitecture\(dq: \(dqx86_64\(dq }} .ft P .fi .UNINDENT .UNINDENT .sp or none: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(dqtype\(dq: \(dqnone\(dq} .ft P .fi .UNINDENT .UNINDENT .sp or copy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(dqtype\(dq: \(dqcopy\(dq, \(dqsource\(dq: \(dqmy\-old\-container\(dq} .ft P .fi .UNINDENT .UNINDENT .TP .B profiles [\(aqdefault\(aq] List of profiles to apply on this container .TP .B config : A config dict or None (None = unset). .sp Can also be a list: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [{\(aqkey\(aq: \(aqboot.autostart\(aq, \(aqvalue\(aq: 1}, {\(aqkey\(aq: \(aqsecurity.privileged\(aq, \(aqvalue\(aq: \(aq1\(aq}] .ft P .fi .UNINDENT .UNINDENT .TP .B devices : A device dict or None (None = unset). .TP .B architecture \(aqx86_64\(aq Can be one of the following: .INDENT 7.0 .IP \(bu 2 unknown .IP \(bu 2 i686 .IP \(bu 2 x86_64 .IP \(bu 2 armv7l .IP \(bu 2 aarch64 .IP \(bu 2 ppc .IP \(bu 2 ppc64 .IP \(bu 2 ppc64le .IP \(bu 2 s390x .UNINDENT .TP .B ephemeral False Destroy this container after stop? .TP .B restart_on_change False Restart the container when we detect changes on the config or its devices? .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Zertifikate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd_container.running(name, restart=False, remote_addr=None, cert=None, key=None, verify_cert=True) Ensure a LXD container is running and restart it if restart is True .INDENT 7.0 .TP .B name : The name of the container to start/restart. .TP .B restart : restart the container if it is already started. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Zertifikate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd_container.stopped(name, kill=False, remote_addr=None, cert=None, key=None, verify_cert=True) Ensure a LXD container is stopped, kill it if kill is true else stop it .INDENT 7.0 .TP .B name : The name of the container to stop .TP .B kill : kill if true .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Zertifikate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .SS salt.states.lxd_image .sp Manage LXD images. .sp New in version 2019.2.0. .INDENT 0.0 .TP .B maintainer René Jochum <\fI\%rene@jochums.at\fP> .TP .B maturity new .TP .B depends python\-pylxd .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd_image.absent(name, remote_addr=None, cert=None, key=None, verify_cert=True) .INDENT 7.0 .TP .B name : An alias or fingerprint of the image to check and delete. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Zertifikate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd_image.present(name, source, aliases=None, public=None, auto_update=None, remote_addr=None, cert=None, key=None, verify_cert=True) Ensure an image exists, copy it else from source .INDENT 7.0 .TP .B name : An alias of the image, this is used to check if the image exists and it will be added as alias to the image on copy/create. .TP .B source : Source dict. .sp For an LXD to LXD copy: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C source: type: lxd name: ubuntu/xenial/amd64 # This can also be a fingerprint. remote_addr: https://images.linuxcontainers.org:8443 cert: ~/.config/lxd/client.crt key: ~/.config/lxd/client.key verify_cert: False .ft P .fi .UNINDENT .UNINDENT .sp From file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C source: type: file filename: salt://lxd/files/busybox.tar.xz saltenv: base .ft P .fi .UNINDENT .UNINDENT .sp From simplestreams: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C source: type: simplestreams server: https://cloud\-images.ubuntu.com/releases name: xenial/amd64 .ft P .fi .UNINDENT .UNINDENT .sp From an URL: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C source: type: url url: https://dl.stgraber.org/lxd .ft P .fi .UNINDENT .UNINDENT .TP .B aliases : List of aliases to append, can be empty. .TP .B public : .INDENT 7.0 .TP .B Make this image public available on this instance? None on source_type LXD means copy source None on source_type file means False .UNINDENT .TP .B auto_update : .INDENT 7.0 .TP .B Try to auto\-update from the original source? None on source_type LXD means copy source source_type file does not have auto\-update. .UNINDENT .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Zertifikate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .UNINDENT .SS salt.states.lxd_profile .sp Manage LXD profiles. .sp New in version 2019.2.0. .INDENT 0.0 .TP .B maintainer René Jochum <\fI\%rene@jochums.at\fP> .TP .B maturity new .TP .B depends python\-pylxd .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd_profile.absent(name, remote_addr=None, cert=None, key=None, verify_cert=True) Ensure a LXD profile is not present, removing it if present. .INDENT 7.0 .TP .B name : The name of the profile to remove. .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Zertifikate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp See the \fIrequests\-docs\fP for the SSL stuff. .UNINDENT .INDENT 0.0 .TP .B salt.states.lxd_profile.present(name, description=None, config=None, devices=None, remote_addr=None, cert=None, key=None, verify_cert=True) Creates or updates LXD profiles .INDENT 7.0 .TP .B name : The name of the profile to create/update .TP .B description : A description string .TP .B config : A config dict or None (None = unset). .INDENT 7.0 .TP .B Can also be a list: .INDENT 7.0 .TP .B [{\(aqkey\(aq: \(aqboot.autostart\(aq, \(aqvalue\(aq: 1}, {\(aqkey\(aq: \(aqsecurity.privileged\(aq, \(aqvalue\(aq: \(aq1\(aq}] .UNINDENT .UNINDENT .TP .B devices : A device dict or None (None = unset). .TP .B remote_addr : An URL to a remote Server, you also have to give cert and key if you provide remote_addr! .INDENT 7.0 .TP .B Examples: \fI\%https://myserver.lan:8443\fP /var/lib/mysocket.sock .UNINDENT .TP .B cert : PEM Formatted SSL Zertifikate. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.crt .UNINDENT .TP .B key : PEM Formatted SSL Key. .INDENT 7.0 .TP .B Examples: ~/.config/lxc/client.key .UNINDENT .TP .B verify_cert True Wherever to verify the cert, this is by default True but in the most cases you want to set it off as LXD normally uses self\-signed certificates. .UNINDENT .sp See the \fI\%lxd\-docs\fP for the details about the config and devices dicts. See the \fIrequests\-docs\fP for the SSL stuff. .UNINDENT .SS salt.states.mac_assistive .SS Allows you to manage assistive access on macOS minions with 10.9+ .sp Install, enable and disable assistive access on macOS minions .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /usr/bin/osacript: assistive.installed: \- enabled: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mac_assistive.installed(name, enabled=True) Make sure that we have the given bundle ID or path to command installed in the assistive access panel. .INDENT 7.0 .TP .B name The bundle ID or path to command .TP .B enable Should assistive access be enabled on this application? .UNINDENT .UNINDENT .SS salt.states.mac_keychain .SS Installing of certificates to the keychain .sp Install certificats to the macOS keychain .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /mnt/test.p12: keychain.installed: \- password: test123 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mac_keychain.default_keychain(name, domain=\(aquser\(aq, user=None) Set the default keychain to use .INDENT 7.0 .TP .B name The chain in which to use as the default .TP .B domain The domain to use valid values are user|system|common|dynamic, the default is user .TP .B user The user to run as .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mac_keychain.installed(name, password, keychain=\(aq/Library/Keychains/System.keychain\(aq, **kwargs) Install a p12 certificate file into the macOS keychain .INDENT 7.0 .TP .B name The certificate to install .TP .B password The password for the certificate being installed formatted in the way described for openssl command in the PASS PHRASE ARGUMENTS section .TP .B keychain The keychain to install the certificate to, this defaults to /Library/Keychains/System.keychain .TP .B allow_any Allow any application to access the imported certificate without warning .TP .B keychain_password If your keychain is likely to be locked pass the password and it will be unlocked before running the import .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mac_keychain.uninstalled(name, password, keychain=\(aq/Library/Keychains/System.keychain\(aq, keychain_password=None) Uninstall a p12 certificate file from the macOS keychain .INDENT 7.0 .TP .B name The certificate to uninstall, this can be a path for a .p12 or the friendly name .TP .B password The password for the certificate being installed formatted in the way described for openssl command in the PASS PHRASE ARGUMENTS section .TP .B cert_name The friendly name of the certificate, this can be used instead of giving a certificate .TP .B keychain The keychain to remove the certificate from, this defaults to /Library/Keychains/System.keychain .TP .B keychain_password If your keychain is likely to be locked pass the password and it will be unlocked before running the import .UNINDENT .UNINDENT .SS salt.states.mac_xattr .SS Allows you to manage extended attributes on files or directories .sp Install, enable and disable assistive access on macOS minions .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /path/to/file: xattr.exists: \- attributes: \- com.file.attr=test \- com.apple.quarantine=0x00001111 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mac_xattr.delete(name, attributes) Make sure the given attributes are deleted from the file/directory .INDENT 7.0 .TP .B name The path to the file/directory .TP .B attributes The attributes that should be removed from the file/directory, this is accepted as an array. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mac_xattr.exists(name, attributes) Make sure the given attributes exist on the file/directory .INDENT 7.0 .TP .B name The path to the file/directory .TP .B attributes The attributes that should exist on the file/directory, this is accepted as an array, with key and value split with an equals sign, if you want to specify a hex value then add 0x to the beginning of the value. .UNINDENT .UNINDENT .SS salt.states.macdefaults .SS Writing/reading defaults from a macOS minion .INDENT 0.0 .TP .B salt.states.macdefaults.absent(name, domain, user=None) Make sure the defaults value is absent .INDENT 7.0 .TP .B name The key of the given domain to remove .TP .B domain The name of the domain to remove from .TP .B user The user to write the defaults to .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.macdefaults.write(name, domain, value, vtype=\(aqstring\(aq, user=None) Write a default to the system .INDENT 7.0 .TP .B name The key of the given domain to write to .TP .B domain The name of the domain to write to .TP .B value The value to write to the given key .TP .B vtype The type of value to be written, valid types are string, data, int[eger], float, bool[ean], date, array, array\-add, dict, dict\-add .TP .B user The user to write the defaults to .UNINDENT .UNINDENT .SS salt.states.macpackage .SS Installing of mac pkg files .sp Install any kind of pkg, dmg or app file on macOS: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /mnt/test.pkg: macpackage.installed: \- store: True /mnt/test.dmg: macpackage.installed: \- dmg: True /mnt/xcode.dmg: macpackage.installed: \- dmg: True \- app: True \- target: /Applications/Xcode.app \- version_check: xcodebuild \-version=Xcode 7.1\en.*7B91b .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.macpackage.installed(name, target=\(aqLocalSystem\(aq, dmg=False, store=False, app=False, mpkg=False, force=False, allow_untrusted=False, version_check=None) Install a Mac OS Package from a pkg or dmg file, if given a dmg file it will first be mounted in a temporary location .INDENT 7.0 .TP .B name The pkg or dmg file to install .TP .B target The location in which to install the package. This can be a path or LocalSystem .TP .B dmg Is the given file a dmg file? .TP .B store Should the pkg be installed as if it was from the Mac OS Store? .TP .B app Is the file a .app? If so then we\(aqll just copy that to /Applications/ or the given target .TP .B mpkg Is the file a .mpkg? If so then we\(aqll check all of the .pkg files found are installed .TP .B force Force the package to be installed even if its already been found installed .TP .B allow_untrusted Allow the installation of untrusted packages .TP .B version_check The command and version that we want to check against, the version number can use regex. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C version_check: python \-\-version_check=2.7.[0\-9] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.states.makeconf .SS Management of Gentoo make.conf .sp A state module to manage Gentoo\(aqs \fBmake.conf\fP file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C makeopts: makeconf.present: \- value: \(aq\-j3\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.makeconf.absent(name) Verify that the variable is not in the \fBmake.conf\fP\&. .INDENT 7.0 .TP .B name The variable name. This will automatically be converted to upper case since variables in \fBmake.conf\fP are in upper case .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.makeconf.present(name, value=None, contains=None, excludes=None) Verify that the variable is in the \fBmake.conf\fP and has the provided settings. If value is set, contains and excludes will be ignored. .INDENT 7.0 .TP .B name The variable name. This will automatically be converted to upper case since variables in \fBmake.conf\fP are in upper case .TP .B value Enforce that the value of the variable is set to the provided value .TP .B contains Enforce that the value of the variable contains the provided value .TP .B excludes Enforce that the value of the variable does not contain the provided value. .UNINDENT .UNINDENT .SS salt.states.marathon_app .sp Configure Marathon apps via a salt proxy. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_app: marathon_app.config: \- config: cmd: \(dqwhile [ true ] ; do echo \(aqHello Marathon\(aq ; sleep 5 ; done\(dq cpus: 0.1 mem: 10 instances: 3 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.2. .INDENT 0.0 .TP .B salt.states.marathon_app.absent(name) Ensure that the marathon app with the given id is not present. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The app name/id .TP .B Returns A standard Salt changes dictionary .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.marathon_app.config(name, config) Ensure that the marathon app with the given id is present and is configured to match the given config values. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The app name/id .IP \(bu 2 \fBconfig\fP \-\- The configuration to apply (dict) .UNINDENT .TP .B Returns A standard Salt changes dictionary .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.marathon_app.running(name, restart=False, force=True) Ensure that the marathon app with the given id is present and restart if set. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The app name/id .IP \(bu 2 \fBrestart\fP \-\- Restart the app .IP \(bu 2 \fBforce\fP \-\- Override the current deployment .UNINDENT .TP .B Returns A standard Salt changes dictionary .UNINDENT .UNINDENT .SS salt.states.mdadm_raid .SS Managing software RAID with mdadm .INDENT 0.0 .TP .B depends mdadm .UNINDENT .sp A state module for creating or destroying software RAID devices. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /dev/md0: raid.present: \- level: 5 \- devices: \- /dev/xvdd \- /dev/xvde \- /dev/xvdf \- chunk: 256 \- run: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mdadm_raid.absent(name) Verify that the raid is absent .INDENT 7.0 .TP .B name The name of raid device to be destroyed .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /dev/md0: raid: \- absent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mdadm_raid.present(name, level, devices, **kwargs) Verify that the raid is present .sp Changed in version 2014.7.0. .INDENT 7.0 .TP .B name The name of raid device to be created .TP .B level The RAID level to use when creating the raid. .TP .B devices A list of devices used to build the array. .TP .B kwargs Optional arguments to be passed to mdadm. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /dev/md0: raid.present: \- level: 5 \- devices: \- /dev/xvdd \- /dev/xvde \- /dev/xvdf \- chunk: 256 \- run: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.memcached .SS States for Management of Memcached Keys .sp New in version 2014.1.0. .INDENT 0.0 .TP .B salt.states.memcached.absent(name, value=None, host=\(aq127.0.0.1\(aq, port=11211, time=0) Ensure that a memcached key is not present. .INDENT 7.0 .TP .B name The key .TP .B value None If specified, only ensure that the key is absent if it matches the specified value. .TP .B host The memcached server IP address .TP .B port The memcached server port .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: memcached.absent bar: memcached.absent: \- host: 10.0.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.memcached.managed(name, value=None, host=\(aq127.0.0.1\(aq, port=11211, time=0, min_compress_len=0) Manage a memcached key. .INDENT 7.0 .TP .B name The key to manage .TP .B value The value to set for that key .TP .B host The memcached server IP address .TP .B port The memcached server port .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: memcached.managed: \- value: bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.modjk .sp State to control Apache modjk .INDENT 0.0 .TP .B salt.states.modjk.worker_activated(name, workers=None, profile=\(aqdefault\(aq) Activate all the workers in the modjk load balancer .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C loadbalancer: modjk.worker_activated: \- workers: \- app1 \- app2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.modjk.worker_disabled(name, workers=None, profile=\(aqdefault\(aq) Disable all the workers in the modjk load balancer .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C loadbalancer: modjk.worker_disabled: \- workers: \- app1 \- app2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.modjk.worker_recover(name, workers=None, profile=\(aqdefault\(aq) Recover all the workers in the modjk load balancer .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C loadbalancer: modjk.worker_recover: \- workers: \- app1 \- app2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.modjk.worker_stopped(name, workers=None, profile=\(aqdefault\(aq) Stop all the workers in the modjk load balancer .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C loadbalancer: modjk.worker_stopped: \- workers: \- app1 \- app2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.modjk_worker .SS Manage modjk workers .sp Send commands to a \fBmodjk\fP load balancer via the peer system. .sp This module can be used with the \fI\%prereq\fP requisite to remove/add the worker from the load balancer before deploying/restarting service. .sp Mandatory Settings: .INDENT 0.0 .IP \(bu 2 The minion needs to have permission to publish the \fBmodjk.*\fP functions (see \fI\%here\fP for information on configuring peer publishing permissions) .IP \(bu 2 The modjk load balancer must be configured as stated in the \fBmodjk\fP execution module \fI\%documentation\fP .UNINDENT .INDENT 0.0 .TP .B salt.states.modjk_worker.activate(name, lbn, target, profile=\(aqdefault\(aq, tgt_type=\(aqglob\(aq) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Activate the named worker from the lbn load balancers at the targeted minions .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C disable\-before\-deploy: modjk_worker.activate: \- name: {{ grains[\(aqid\(aq] }} \- lbn: application \- target: \(aqroles:balancer\(aq \- tgt_type: grain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.modjk_worker.disable(name, lbn, target, profile=\(aqdefault\(aq, tgt_type=\(aqglob\(aq) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Disable the named worker from the lbn load balancers at the targeted minions. The worker will get traffic only for current sessions and won\(aqt get new ones. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C disable\-before\-deploy: modjk_worker.disable: \- name: {{ grains[\(aqid\(aq] }} \- lbn: application \- target: \(aqroles:balancer\(aq \- tgt_type: grain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.modjk_worker.stop(name, lbn, target, profile=\(aqdefault\(aq, tgt_type=\(aqglob\(aq) Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier releases must use \fBexpr_form\fP\&. .sp Stop the named worker from the lbn load balancers at the targeted minions The worker won\(aqt get any traffic from the lbn .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C disable\-before\-deploy: modjk_worker.stop: \- name: {{ grains[\(aqid\(aq] }} \- lbn: application \- target: \(aqroles:balancer\(aq \- tgt_type: grain .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.module .SS Execution of Salt modules from within states .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As of the 3005 release, you no longer need to opt\-in to the new style of calling \fBmodule.run\fP\&. The following config can be removed from \fB/etc/salt/minion\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C use_superseded: \- module.run .ft P .fi .UNINDENT .UNINDENT .sp Both \(aqnew\(aq and \(aqlegacy\(aq styles of calling \fBmodule.run\fP are supported. .UNINDENT .UNINDENT .sp With \fImodule.run\fP these states allow individual execution module calls to be made via states. Here\(aqs a contrived example, to show you how it\(aqs done: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # New Style test.random_hash: module.run: \- test.random_hash: \- size: 42 \- hash_type: sha256 # Legacy Style test.random_hash: module.run: \- size: 42 \- hash_type: sha256 .ft P .fi .UNINDENT .UNINDENT .sp In the new style, the state ID (\fBtest.random_hash\fP, in this case) is irrelevant when using \fBmodule.run\fP\&. It could have very well been written: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Generate a random hash: module.run: \- test.random_hash: \- size: 42 \- hash_type: sha256 .ft P .fi .UNINDENT .UNINDENT .sp For a simple state like that it\(aqs not a big deal, but if the module you\(aqre using has certain parameters, things can get cluttered, fast. Using the contrived custom module (stuck in \fB/srv/salt/_modules/foo.py\fP, or your configured \fI\%file_roots\fP): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def bar(name, names, fun, state, saltenv): return \(dqName: {name} Names: {names} Fun: {fun} State: {state} Saltenv: {saltenv}\(dq.format(**locals()) .ft P .fi .UNINDENT .UNINDENT .sp Your legacy state has to look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Legacy style Unfortunate example: module.run: \- name: foo.bar \- m_name: Some name \- m_names: \- Such names \- very wow \- m_state: Arkansas \- m_fun: Such fun \- m_saltenv: Salty .ft P .fi .UNINDENT .UNINDENT .sp With the new style it\(aqs much cleaner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # New style Better: module.run: \- foo.bar: \- name: Some name \- names: \- Such names \- very wow \- state: Arkansas \- fun: Such fun \- saltenv: Salty .ft P .fi .UNINDENT .UNINDENT .sp The new style also allows multiple modules in one state. For instance, you can do this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Do many things: module.run: \- test.random_hash: \- size: 10 \- hash_type: md5 # Note the \(ga:\(ga at the end \- test.true: \- test.arg: \- this \- has \- args \- and: kwargs \- isn\(aqt: that neat? # Note the \(ga:\(ga at the end, too \- test.version: \- test.fib: \- 4 .ft P .fi .UNINDENT .UNINDENT .sp Where in the legacy style you would have had to split your states like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C test.random_hash: module.run: \- size: 10 \- hash_type: md5 test.nop: module.run test.arg: module.run: \- args: \- this \- has \- args \- kwargs: and: kwargs isn\(aqt: that neat? test.version: module.run .ft P .fi .UNINDENT .UNINDENT .sp Another difference is that in the legacy style, unconsumed arguments to the \fBmodule\fP state were simply passed into the module function being executed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C show off module.run with args: module.run: \- name: test.random_hash \- size: 42 \- hash_type: sha256 .ft P .fi .UNINDENT .UNINDENT .sp The new style is much more explicit, with the arguments and keyword arguments being nested under the name of the function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C show off module.run with args: module.run: # Note the lack of \(ganame: \(ga, and trailing \(ga:\(ga \- test.random_hash: \- size: 42 \- hash_type: sha256 .ft P .fi .UNINDENT .UNINDENT .sp If the function takes \fB*args\fP, they can be passed in as well: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C args and kwargs: module.run: \- test.arg: \- isn\(aqt \- this \- fun \- this: that \- salt: stack .ft P .fi .UNINDENT .UNINDENT .SS Modern Examples .sp Here are some other examples using the modern \fBmodule.run\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fetch_out_of_band: module.run: \- git.fetch: \- cwd: /path/to/my/repo \- user: myuser \- opts: \(aq\-\-all\(aq .ft P .fi .UNINDENT .UNINDENT .sp A more complex example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C eventsviewer: module.run: \- task.create_task: \- name: events\-viewer \- user_name: System \- action_type: Execute \- cmd: \(aqc:\enetops\escripts\eevents_viewer.bat\(aq \- trigger_type: \(aqDaily\(aq \- start_date: \(aq2017\-1\-20\(aq \- start_time: \(aq11:59PM\(aq .ft P .fi .UNINDENT .UNINDENT .sp It is sometimes desirable to trigger a function call after a state is executed, for this the \fI\%module.wait\fP state can be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C add example to hosts: file.append: \- name: /etc/hosts \- text: 203.0.113.13 example.com # New Style mine.send: module.wait: # Again, note the trailing \(ga:\(ga \- hosts.list_hosts: \- watch: \- file: add example to hosts .ft P .fi .UNINDENT .UNINDENT .SS Legacy (Default) Examples .sp If you\(aqre using the legacy \fBmodule.run\fP, due to how the state system works, if a module function accepts an argument called, \fBname\fP, then \fBm_name\fP must be used to specify that argument, to avoid a collision with the \fBname\fP argument. .sp Here is a list of keywords hidden by the state system, which must be prefixed with \fBm_\fP: .INDENT 0.0 .IP \(bu 2 fun .IP \(bu 2 name .IP \(bu 2 names .IP \(bu 2 state .IP \(bu 2 saltenv .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C disable_nfs: module.run: \- name: service.disable \- m_name: nfs .ft P .fi .UNINDENT .UNINDENT .sp Note that some modules read all or some of the arguments from a list of keyword arguments. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine.send: module.run: \- func: network.ip_addrs \- kwargs: interface: eth0 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cloud.create: module.run: \- func: cloud.create \- provider: test\-provider \- m_names: \- test\-vlad \- kwargs: { ssh_username: \(aqubuntu\(aq, image: \(aqami\-8d6d9daa\(aq, securitygroup: \(aqdefault\(aq, size: \(aqc3.large\(aq, location: \(aqap\-northeast\-1\(aq, delvol_on_destroy: \(aqTrue\(aq } .ft P .fi .UNINDENT .UNINDENT .sp Other modules take the keyword arguments using this style: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mac_enable_ssh: module.run: \- name: system.set_remote_login \- enable: True .ft P .fi .UNINDENT .UNINDENT .sp Another example that creates a recurring task that runs a batch file on a Windows system: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C eventsviewer: module.run: \- name: task.create_task \- m_name: \(aqevents\-viewer\(aq \- user_name: System \- kwargs: { action_type: \(aqExecute\(aq, cmd: \(aqc:\enetops\escripts\eevents_viewer.bat\(aq, trigger_type: \(aqDaily\(aq, start_date: \(aq2017\-1\-20\(aq, start_time: \(aq11:59PM\(aq } .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.module.mod_watch(**kwargs) This function is an alias of \fBrun\fP\&. .INDENT 7.0 .INDENT 3.5 Run a single module function or a range of module functions in a batch. Supersedes \fBmodule.run\fP function, which requires \fBm_\fP prefix to function\-specific parameters. .INDENT 0.0 .TP .B param returner Specify a common returner for the whole batch to send the return data .TP .B param kwargs Pass any arguments needed to execute the function(s) .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C some_id_of_state: module.run: \- network.ip_addrs: \- interface: eth0 \- cloud.create: \- names: \- test\-isbm\-1 \- test\-isbm\-2 \- ssh_username: sles \- image: sles12sp2 \- securitygroup: default \- size: \(aqc3.large\(aq \- location: ap\-northeast\-1 \- delvol_on_destroy: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B return .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.module.run(**kwargs) Run a single module function or a range of module functions in a batch. Supersedes \fBmodule.run\fP function, which requires \fBm_\fP prefix to function\-specific parameters. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBreturner\fP \-\- Specify a common returner for the whole batch to send the return data .IP \(bu 2 \fBkwargs\fP \-\- Pass any arguments needed to execute the function(s) .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C some_id_of_state: module.run: \- network.ip_addrs: \- interface: eth0 \- cloud.create: \- names: \- test\-isbm\-1 \- test\-isbm\-2 \- ssh_username: sles \- image: sles12sp2 \- securitygroup: default \- size: \(aqc3.large\(aq \- location: ap\-northeast\-1 \- delvol_on_destroy: True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.module.wait(name, **kwargs) Run a single module function only if the watch statement calls it .INDENT 7.0 .TP .B \fBname\fP The module function to execute .TP .B \fB**kwargs\fP Pass any arguments needed to execute the function .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Like the \fI\%cmd.run\fP state, this state will return \fBTrue\fP but not actually execute, unless one of the following two things happens: .INDENT 0.0 .IP 1. 3 The state has a \fI\%watch requisite\fP, and the state which it is watching changes. .IP 2. 3 Another state has a \fI\%watch_in requisite\fP which references this state, and the state wth the \fBwatch_in\fP changes. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.module.watch(name, **kwargs) This function is an alias of \fBwait\fP\&. .INDENT 7.0 .INDENT 3.5 Run a single module function only if the watch statement calls it .INDENT 0.0 .TP .B \fBname\fP The module function to execute .TP .B \fB**kwargs\fP Pass any arguments needed to execute the function .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Like the \fI\%cmd.run\fP state, this state will return \fBTrue\fP but not actually execute, unless one of the following two things happens: .INDENT 0.0 .IP 1. 3 The state has a \fI\%watch requisite\fP, and the state which it is watching changes. .IP 2. 3 Another state has a \fI\%watch_in requisite\fP which references this state, and the state wth the \fBwatch_in\fP changes. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.states.mongodb_database .SS Management of MongoDB Databases .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 pymongo Python module .UNINDENT .UNINDENT .sp Only deletion is supported, creation doesn\(aqt make sense and can be done using \fI\%mongodb_user.present\fP\&. .INDENT 0.0 .TP .B salt.states.mongodb_database.absent(name, user=None, password=None, host=None, port=None, authdb=None) Ensure that the named database is absent. Note that creation doesn\(aqt make sense in MongoDB. .INDENT 7.0 .TP .B name The name of the database to remove .TP .B user The user to connect as (must be able to create the user) .TP .B password The password of the user .TP .B host The host to connect to .TP .B port The port to connect to .TP .B authdb The database in which to authenticate .UNINDENT .UNINDENT .SS salt.states.mongodb_user .SS Management of MongoDB Users .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 pymongo Python module .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mongodb_user.absent(name, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq, authdb=None) Ensure that the named user is absent .INDENT 7.0 .TP .B name The name of the user to remove .TP .B user MongoDB user with sufficient privilege to create the user .TP .B password Password for the admin user specified by the \fBuser\fP parameter .TP .B host The hostname/IP address of the MongoDB server .TP .B port The port on which MongoDB is listening .TP .B database The database from which to remove the user specified by the \fBname\fP parameter .TP .B authdb The database in which to authenticate .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mongodb_user.present(name, passwd, database=\(aqadmin\(aq, user=None, password=None, host=\(aqlocalhost\(aq, port=27017, authdb=None, roles=None) Ensure that the user is present with the specified properties .INDENT 7.0 .TP .B name The name of the user to manage .TP .B passwd The password of the user to manage .TP .B user MongoDB user with sufficient privilege to create the user .TP .B password Password for the admin user specified with the \fBuser\fP parameter .TP .B host The hostname/IP address of the MongoDB server .TP .B port The port on which MongoDB is listening .TP .B database The database in which to create the user .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the database doesn\(aqt exist, it will be created. .UNINDENT .UNINDENT .TP .B authdb The database in which to authenticate .TP .B roles The roles assigned to user specified with the \fBname\fP parameter .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mongouser\-myapp: mongodb_user.present: \- name: myapp \- passwd: password\-of\-myapp \- database: admin # Connect as admin:sekrit \- user: admin \- password: sekrit \- roles: \- readWrite \- userAdmin \- dbOwner .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.monit .SS Monit state .sp Manage monit states .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C monit_enable_service_monitoring: monit.monitor: \- name: service monit_disable_service_monitoring: monit.unmonitor: \- name: service .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Use of these states require that the \fI\%monit\fP execution module is available. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.monit.monitor(name) Get the summary from module monit and try to see if service is being monitored. If not then monitor the service. .UNINDENT .INDENT 0.0 .TP .B salt.states.monit.unmonitor(name) Get the summary from module monit and try to see if service is being monitored. If it is then stop monitoring the service. .UNINDENT .SS salt.states.mount .SS Mounting of filesystems .sp Mount any type of mountable filesystem with the mounted function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /mnt/sdb: mount.mounted: \- device: /dev/sdb1 \- fstype: ext4 \- mkmnt: True \- opts: \- defaults /srv/bigdata: mount.mounted: \- device: UUID=066e0200\-2867\-4ebe\-b9e6\-f30026ca2314 \- fstype: xfs \- opts: nobootwait,noatime,nodiratime,nobarrier,logbufs=8 \- dump: 0 \- pass_num: 2 \- persist: True \- mkmnt: True /var/lib/bigdata: mount.mounted: \- device: /srv/bigdata \- fstype: none \- opts: bind \- dump: 0 \- pass_num: 0 \- persist: True \- mkmnt: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mount.fstab_absent(name, fs_file, mount_by=None, config=\(aq/etc/fstab\(aq) Makes sure that a fstab mount point is absent. .INDENT 7.0 .TP .B name The name of block device. Can be any valid fs_spec value. .TP .B fs_file Mount point (target) for the filesystem. .TP .B mount_by Select the final value for fs_spec. Can be [\fBNone\fP, \fBdevice\fP, \fBlabel\fP, \fBuuid\fP, \fBpartlabel\fP, \fBpartuuid\fP]. If \fBNone\fP, the value for fs_spect will be the parameter \fBname\fP, in other case will search the correct value based on the device name. For example, for \fBuuid\fP, the value for fs_spec will be of type \(aqUUID=xxx\(aq instead of the device name set in \fBname\fP\&. .TP .B config Place where the fstab file lives .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mount.fstab_present(name, fs_file, fs_vfstype, fs_mntops=\(aqdefaults\(aq, fs_freq=0, fs_passno=0, mount_by=None, config=\(aq/etc/fstab\(aq, mount=True, match_on=\(aqauto\(aq, not_change=False, fs_mount=True) Makes sure that a fstab mount point is present. .INDENT 7.0 .TP .B name The name of block device. Can be any valid fs_spec value. .TP .B fs_file Mount point (target) for the filesystem. .TP .B fs_vfstype The type of the filesystem (e.g. ext4, xfs, btrfs, ...) .TP .B fs_mntops The mount options associated with the filesystem. Default is \fBdefaults\fP\&. .TP .B fs_freq Field is used by dump to determine which fs need to be dumped. Default is \fB0\fP .TP .B fs_passno Field is used by fsck to determine the order in which filesystem checks are done at boot time. Default is \fB0\fP .TP .B fs_mount Field is used only in AIX systems to determine if the filesystem will be mounted by \fBmount all\fP .TP .B mount_by Select the final value for fs_spec. Can be [\fBNone\fP, \fBdevice\fP, \fBlabel\fP, \fBuuid\fP, \fBpartlabel\fP, \fBpartuuid\fP]. If \fBNone\fP, the value for fs_spect will be the parameter \fBname\fP, in other case will search the correct value based on the device name. For example, for \fBuuid\fP, the value for fs_spec will be of type \(aqUUID=xxx\(aq instead of the device name set in \fBname\fP\&. .TP .B config Place where the fstab file lives. Default is \fB/etc/fstab\fP .TP .B mount Set if the mount should be mounted immediately. Default is \fBTrue\fP .TP .B match_on A name or list of fstab properties on which this state should be applied. Default is \fBauto\fP, a special value indicating to guess based on fstype. In general, \fBauto\fP matches on name for recognized special devices and device otherwise. .TP .B not_change By default, if the entry is found in the fstab file but is different from the expected content (like different options), the entry will be replaced with the correct content. If this parameter is set to \fBTrue\fP and the line is found, the original content will be preserved. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mount.mod_watch(name, user=None, **kwargs) The mounted watcher, called to invoke the watch command. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBwatch\fP \fI\%requisite\fP\&. It should not be called directly. .sp Parameters for this function should be set by the state being triggered. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the mount point .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mount.mounted(name, device, fstype, mkmnt=False, opts=\(aqdefaults\(aq, dump=0, pass_num=0, config=\(aq/etc/fstab\(aq, persist=True, mount=True, user=None, match_on=\(aqauto\(aq, device_name_regex=None, extra_mount_invisible_options=None, extra_mount_invisible_keys=None, extra_mount_ignore_fs_keys=None, extra_mount_translate_options=None, hidden_opts=None, bind_mount_copy_active_opts=True, **kwargs) Verify that a device is mounted .INDENT 7.0 .TP .B name The path to the location where the device is to be mounted .TP .B device The device name, typically the device node, such as \fB/dev/sdb1\fP or \fBUUID=066e0200\-2867\-4ebe\-b9e6\-f30026ca2314\fP or \fBLABEL=DATA\fP .TP .B fstype The filesystem type, this will be \fBxfs\fP, \fBext2/3/4\fP in the case of classic filesystems, \fBfuse\fP in the case of fuse mounts, and \fBnfs\fP in the case of nfs mounts .TP .B mkmnt If the mount point is not present then the state will fail, set \fBmkmnt: True\fP to create the mount point if it is otherwise not present .TP .B opts A list object of options or a comma delimited list .TP .B dump The dump value to be passed into the fstab, Default is \fB0\fP .TP .B pass_num The pass value to be passed into the fstab, Default is \fB0\fP .TP .B config Set an alternative location for the fstab, Default is \fB/etc/fstab\fP .TP .B persist Set if the mount should be saved in the fstab, Default is \fBTrue\fP .TP .B mount Set if the mount should be mounted immediately, Default is \fBTrue\fP .TP .B user The account used to execute the mount; this defaults to the user salt is running as on the minion .TP .B match_on A name or list of fstab properties on which this state should be applied. Default is \fBauto\fP, a special value indicating to guess based on fstype. In general, \fBauto\fP matches on name for recognized special devices and device otherwise. .TP .B device_name_regex A list of device exact names or regular expressions which should not force a remount. For example, glusterfs may be mounted with a comma\-separated list of servers in fstab, but the /proc/self/mountinfo will show only the first available server. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set glusterfs_ip_list = [\(aq10.0.0.1\(aq, \(aq10.0.0.2\(aq, \(aq10.0.0.3\(aq] %} mount glusterfs volume: mount.mounted: \- name: /mnt/glusterfs_mount_point \- device: {{ glusterfs_ip_list|join(\(aq,\(aq) }}:/volume_name \- fstype: glusterfs \- opts: _netdev,rw,defaults,direct\-io\-mode=disable \- mkmnt: True \- persist: True \- dump: 0 \- pass_num: 0 \- device_name_regex: \- ({{ glusterfs_ip_list|join(\(aq|\(aq) }}):/volume_name .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .TP .B extra_mount_invisible_options A list of extra options that are not visible through the \fB/proc/self/mountinfo\fP interface. .sp If a option is not visible through this interface it will always remount the device. This option extends the builtin \fBmount_invisible_options\fP list. .TP .B extra_mount_invisible_keys A list of extra key options that are not visible through the \fB/proc/self/mountinfo\fP interface. .sp If a key option is not visible through this interface it will always remount the device. This option extends the builtin \fBmount_invisible_keys\fP list. .sp A good example for a key option is the password option: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C password=badsecret .ft P .fi .UNINDENT .UNINDENT .TP .B extra_mount_ignore_fs_keys A dict of filesystem options which should not force a remount. This will update the internal dictionary. The dict should look like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqramfs\(aq: [\(aqsize\(aq] } .ft P .fi .UNINDENT .UNINDENT .TP .B extra_mount_translate_options A dict of mount options that gets translated when mounted. To prevent a remount add additional options to the default dictionary. This will update the internal dictionary. The dictionary should look like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqtcp\(aq: \(aqproto=tcp\(aq, \(aqudp\(aq: \(aqproto=udp\(aq } .ft P .fi .UNINDENT .UNINDENT .TP .B hidden_opts A list of mount options that will be ignored when considering a remount as part of the state application .sp New in version 2015.8.2. .TP .B bind_mount_copy_active_opts If set to \fBFalse\fP, this option disables the default behavior of copying the options from the bind mount if it was found to be active. .sp New in version 3006.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mount.swap(name, persist=True, config=\(aq/etc/fstab\(aq) Activates a swap device .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /root/swapfile: mount.swap .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBswap\fP does not currently support LABEL .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mount.unmounted(name, device=None, config=\(aq/etc/fstab\(aq, persist=False, user=None, **kwargs) New in version 0.17.0. .sp Verify that a device is not mounted .INDENT 7.0 .TP .B name The path to the location where the device is to be unmounted from .TP .B device The device to be unmounted. This is optional because the device could be mounted in multiple places. .sp New in version 2015.5.0. .TP .B config Set an alternative location for the fstab, Default is \fB/etc/fstab\fP .TP .B persist Set if the mount should be purged from the fstab, Default is \fBFalse\fP .TP .B user The user to own the mount; this defaults to the user salt is running as on the minion .UNINDENT .UNINDENT .SS salt.states.mssql_database .SS Management of Microsoft SQLServer Databases .sp The mssql_database module is used to create and manage SQL Server Databases .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yolo: mssql_database.present .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mssql_database.absent(name, **kwargs) Ensure that the named database is absent .INDENT 7.0 .TP .B name The name of the database to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mssql_database.present(name, containment=\(aqNONE\(aq, options=None, **kwargs) Ensure that the named database is present with the specified options .INDENT 7.0 .TP .B name The name of the database to manage .TP .B containment Defaults to NONE .TP .B options Can be a list of strings, a dictionary, or a list of dictionaries .UNINDENT .UNINDENT .SS salt.states.mssql_login .SS Management of Microsoft SQLServer Logins .sp The mssql_login module is used to create and manage SQL Server Logins .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C frank: mssql_login.present \- domain: mydomain .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mssql_login.absent(name, **kwargs) Ensure that the named login is absent .INDENT 7.0 .TP .B name The name of the login to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mssql_login.present(name, password=None, domain=None, server_roles=None, options=None, **kwargs) Checks existence of the named login. If not present, creates the login with the specified roles and options. .INDENT 7.0 .TP .B name The name of the login to manage .TP .B password Creates a SQL Server authentication login Since hashed passwords are varbinary values, if the new_login_password is \(aqlong\(aq, it will be considered to be HASHED. .TP .B domain Creates a Windows authentication login. Needs to be NetBIOS domain or hostname .TP .B server_roles Add this login to all the server roles in the list .TP .B options Can be a list of strings, a dictionary, or a list of dictionaries .UNINDENT .UNINDENT .SS salt.states.mssql_role .SS Management of Microsoft SQLServer Databases .sp The mssql_role module is used to create and manage SQL Server Roles .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yolo: mssql_role.present .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mssql_role.absent(name, **kwargs) Ensure that the named database is absent .INDENT 7.0 .TP .B name The name of the database to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mssql_role.present(name, owner=None, grants=None, **kwargs) Ensure that the named database is present with the specified options .INDENT 7.0 .TP .B name The name of the database to manage .TP .B owner Adds owner using AUTHORIZATION option .TP .B Grants Can only be a list of strings .UNINDENT .UNINDENT .SS salt.states.mssql_user .SS Management of Microsoft SQLServer Users .sp The mssql_user module is used to create and manage SQL Server Users .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C frank: mssql_user.present: \- database: yolo .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mssql_user.absent(name, **kwargs) Ensure that the named user is absent .INDENT 7.0 .TP .B name The username of the user to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mssql_user.present(name, login=None, domain=None, database=None, roles=None, options=None, **kwargs) Checks existence of the named user. If not present, creates the user with the specified roles and options. .INDENT 7.0 .TP .B name The name of the user to manage .TP .B login If not specified, will be created WITHOUT LOGIN .TP .B domain Creates a Windows authentication user. Needs to be NetBIOS domain or hostname .TP .B database The database of the user (not the login) .TP .B roles Add this user to all the roles in the list .TP .B options Can be a list of strings, a dictionary, or a list of dictionaries .UNINDENT .UNINDENT .SS salt.states.msteams .SS Send a message card to Microsoft Teams .sp This state is useful for sending messages to Teams during state runs. .sp New in version 2017.7.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C teams\-message: msteams.post_card: \- message: \(aqThis state was executed successfully.\(aq \- hook_url: https://outlook.office.com/webhook/837 .ft P .fi .UNINDENT .UNINDENT .sp The hook_url can be specified in the master or minion configuration like below: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C msteams: hook_url: https://outlook.office.com/webhook/837 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.msteams.post_card(name, message, hook_url=None, title=None, theme_color=None) Send a message to a Microsft Teams channel .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C send\-msteams\-message: msteams.post_card: \- message: \(aqThis state was executed successfully.\(aq \- hook_url: https://outlook.office.com/webhook/837 .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B message The message that is to be sent to the MS Teams channel. .UNINDENT .sp The following parameters are optional: .INDENT 7.0 .TP .B hook_url The webhook URL given configured in Teams interface, if not specified in the configuration options of master or minion. .TP .B title The title for the card posted to the channel .TP .B theme_color A hex code for the desired highlight color .UNINDENT .UNINDENT .SS salt.states.mysql_database .SS Management of MySQL databases (schemas) .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 MySQLdb Python module .UNINDENT .TP .B configuration See \fI\%salt.modules.mysql\fP for setup instructions. .UNINDENT .sp The mysql_database module is used to create and manage MySQL databases. Databases can be set as either absent or present. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C frank: mysql_database.present .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mysql_database.absent(name, **connection_args) Ensure that the named database is absent .INDENT 7.0 .TP .B name The name of the database to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mysql_database.present(name, character_set=None, collate=None, **connection_args) Ensure that the named database is present with the specified properties .INDENT 7.0 .TP .B name The name of the database to manage .UNINDENT .UNINDENT .SS salt.states.mysql_grants .SS Management of MySQL grants (user permissions) .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 MySQLdb Python module .UNINDENT .TP .B configuration See \fI\%salt.modules.mysql\fP for setup instructions. .UNINDENT .sp The mysql_grants module is used to grant and revoke MySQL permissions. .sp The \fBname\fP you pass in purely symbolic and does not have anything to do with the grant itself. .sp The \fBdatabase\fP parameter needs to specify a \(aqpriv_level\(aq in the same specification as defined in the MySQL documentation: .INDENT 0.0 .IP \(bu 2 * .IP \(bu 2 *.* .IP \(bu 2 db_name.* .IP \(bu 2 db_name.tbl_name .IP \(bu 2 etc... .UNINDENT .sp This state is not able to set password for the permission from the specified host. See \fI\%salt.states.mysql_user\fP for further instructions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C frank_exampledb: mysql_grants.present: \- grant: select,insert,update \- database: exampledb.* \- user: frank \- host: localhost frank_otherdb: mysql_grants.present: \- grant: all privileges \- database: otherdb.* \- user: frank restricted_singletable: mysql_grants.present: \- grant: select \- database: somedb.sometable \- user: joe .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mysql_grants.absent(name, grant=None, database=None, user=None, host=\(aqlocalhost\(aq, grant_option=False, escape=True, **connection_args) Ensure that the grant is absent .INDENT 7.0 .TP .B name The name (key) of the grant to add .TP .B grant The grant priv_type (i.e. select,insert,update OR all privileges) .TP .B database The database priv_level (i.e. db.tbl OR db.*) .TP .B user The user to apply the grant to .TP .B host The network/host that the grant should apply to .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mysql_grants.present(name, grant=None, database=None, user=None, host=\(aqlocalhost\(aq, grant_option=False, escape=True, revoke_first=False, ssl_option=False, **connection_args) Ensure that the grant is present with the specified properties .INDENT 7.0 .TP .B name The name (key) of the grant to add .TP .B grant The grant priv_type (i.e. select,insert,update OR all privileges) .TP .B database The database priv_level (i.e. db.tbl OR db.*) .TP .B user The user to apply the grant to .TP .B host The network/host that the grant should apply to .TP .B grant_option Adds the WITH GRANT OPTION to the defined grant. Default is \fBFalse\fP .TP .B escape Defines if the database value gets escaped or not. Default is \fBTrue\fP .TP .B revoke_first By default, MySQL will not do anything if you issue a command to grant privileges that are more restrictive than what\(aqs already in place. This effectively means that you cannot downgrade permissions without first revoking permissions applied to a db.table/user pair first. .sp To have Salt forcibly revoke perms before applying a new grant, enable the \(aqrevoke_first options. .sp WARNING: This will \fIremove\fP permissions for a database before attempting to apply new permissions. There is no guarantee that new permissions will be applied correctly which can leave your database security in an unknown and potentially dangerous state. Use with caution! .sp Default is \fBFalse\fP .TP .B ssl_option Adds the specified ssl options for the connecting user as requirements for this grant. Value is a list of single\-element dicts corresponding to the list of ssl options to use. .sp Possible key/value pairings for the dicts in the value: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- SSL: True \- X509: True \- SUBJECT: <subject> \- ISSUER: <issuer> \- CIPHER: <cipher> .ft P .fi .UNINDENT .UNINDENT .sp The non\-boolean ssl options take a string as their values, which should be an appropriate value as specified by the MySQL documentation for these options. .sp Default is \fBFalse\fP (no ssl options will be used) .UNINDENT .UNINDENT .SS salt.states.mysql_query .SS Execution of MySQL queries .sp New in version 2014.7.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 MySQLdb Python module .UNINDENT .TP .B configuration See \fI\%salt.modules.mysql\fP for setup instructions. .UNINDENT .sp The mysql_query module is used to execute queries on MySQL databases. Its output may be stored in a file or in a grain. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C query_id: mysql_query.run \- database: my_database \- query: \(dqSELECT * FROM table;\(dq \- output: \(dq/tmp/query_id.txt\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mysql_query.run(name, database, query, output=None, grain=None, key=None, overwrite=True, check_db_exists=True, client_flags=None, **connection_args) Execute an arbitrary query on the specified database .INDENT 7.0 .TP .B name Used only as an ID .TP .B database The name of the database to execute the query on .TP .B query The query to execute .TP .B output grain: output in a grain other: the file to store results None: output to the result comment (default) .TP .B grain: grain to store the output (need output=grain) .TP .B key: the specified grain will be treated as a dictionary, the result of this state will be stored under the specified key. .TP .B overwrite: The file or grain will be overwritten if it already exists (default) .TP .B check_db_exists: The state run will check that the specified database exists (default=True) before running any queries .TP .B client_flags: A list of client flags to pass to the MySQL connection. \fI\%https://dev.mysql.com/doc/internals/en/capability\-flags.html\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mysql_query.run_file(name, database, query_file=None, output=None, grain=None, key=None, overwrite=True, saltenv=None, check_db_exists=True, client_flags=None, **connection_args) Execute an arbitrary query on the specified database .sp New in version 2017.7.0. .INDENT 7.0 .TP .B name Used only as an ID .TP .B database The name of the database to execute the query_file on .TP .B query_file The file of mysql commands to run .TP .B output grain: output in a grain other: the file to store results None: output to the result comment (default) .TP .B grain: grain to store the output (need output=grain) .TP .B key: the specified grain will be treated as a dictionary, the result of this state will be stored under the specified key. .TP .B overwrite: The file or grain will be overwritten if it already exists (default) .TP .B saltenv: The saltenv to pull the query_file from .TP .B check_db_exists: The state run will check that the specified database exists (default=True) before running any queries .TP .B client_flags: A list of client flags to pass to the MySQL connection. \fI\%https://dev.mysql.com/doc/internals/en/capability\-flags.html\fP .UNINDENT .UNINDENT .SS salt.states.mysql_user .SS Management of MySQL users .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 MySQLdb Python module .UNINDENT .TP .B configuration See \fI\%salt.modules.mysql\fP for setup instructions. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C frank: mysql_user.present: \- host: localhost \- password: bobcat .ft P .fi .UNINDENT .UNINDENT .sp New in version 0.16.2: Authentication overrides have been added. .sp The MySQL authentication information specified in the minion config file can be overridden in states using the following arguments: \fBconnection_host\fP, \fBconnection_port\fP, \fBconnection_user\fP, \fBconnection_pass\fP, \fBconnection_db\fP, \fBconnection_unix_socket\fP, \fBconnection_default_file\fP and \fBconnection_charset\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C frank: mysql_user.present: \- host: localhost \- password: \(dqbob@cat\(dq \- connection_user: someuser \- connection_pass: somepass \- connection_charset: utf8 \- saltenv: \- LC_ALL: \(dqen_US.utf8\(dq .ft P .fi .UNINDENT .UNINDENT .sp This state is not able to grant permissions for the user. See \fI\%salt.states.mysql_grants\fP for further instructions. .INDENT 0.0 .TP .B salt.states.mysql_user.absent(name, host=\(aqlocalhost\(aq, **connection_args) Ensure that the named user is absent .INDENT 7.0 .TP .B name The name of the user to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mysql_user.present(name, host=\(aqlocalhost\(aq, password=None, password_hash=None, allow_passwordless=False, unix_socket=False, password_column=None, auth_plugin=\(aqmysql_native_password\(aq, **connection_args) Ensure that the named user is present with the specified properties. A passwordless user can be configured by omitting \fBpassword\fP and \fBpassword_hash\fP, and setting \fBallow_passwordless\fP to \fBTrue\fP\&. .INDENT 7.0 .TP .B name The name of the user to manage .TP .B host Host for which this user/password combo applies .TP .B password The password to use for this user. Will take precedence over the \fBpassword_hash\fP option if both are specified. .TP .B password_hash The password in hashed form. Be sure to quote the password because YAML doesn\(aqt like the \fB*\fP\&. A password hash can be obtained from the mysql command\-line client like so: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mysql> SELECT PASSWORD(\(aqmypass\(aq); +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | PASSWORD(\(aqmypass\(aq) | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4 | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ 1 row in set (0.00 sec) .ft P .fi .UNINDENT .UNINDENT .TP .B allow_passwordless If \fBTrue\fP, then \fBpassword\fP and \fBpassword_hash\fP can be omitted to permit a passwordless login. .sp New in version 0.16.2. .TP .B unix_socket If \fBTrue\fP and allow_passwordless is \fBTrue\fP, the unix_socket auth plugin will be used. .UNINDENT .UNINDENT .SS salt.states.net_napalm_yang .SS NAPALM YANG state .sp Manage the configuration of network devices according to the YANG models (OpenConfig/IETF). .sp New in version 2017.7.0. .SS Dependencies .INDENT 0.0 .IP \(bu 2 napalm\-yang .IP \(bu 2 pyangbing > 0.5.11 .UNINDENT .sp To be able to load configuration on network devices, it requires \fI\%NAPALM\fP library to be installed: \fBpip install napalm\fP\&. Please check \fI\%Installation\fP for complete details. .INDENT 0.0 .TP .B salt.states.net_napalm_yang.configured(name, data, **kwargs) Configure the network device, given the input data strucuted according to the YANG models. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The main difference between this function and \fBmanaged\fP is that the later generates and loads the configuration only when there are differences between the existing configuration on the device and the expected configuration. Depending on the platform and hardware capabilities, one could be more optimal than the other. Additionally, the output of the \fBmanaged\fP is different, in such a way that the \fBpchange\fP field in the output contains structured data, rather than text. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B data YANG structured data. .TP .B models A list of models to be used when generating the config. .TP .B profiles: \fBNone\fP Use certain profiles to generate the config. If not specified, will use the platform default profile(s). .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: \fBTrue\fP Commit? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key under the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .TP .B replace: \fBFalse\fP Should replace the config with the new generate one? .UNINDENT .sp State SLS example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set expected_config = pillar.get(\(aqopenconfig_interfaces_cfg\(aq) \-%} interfaces_config: napalm_yang.configured: \- data: {{ expected_config | json }} \- models: \- models.openconfig_interfaces \- debug: true .ft P .fi .UNINDENT .UNINDENT .sp Pillar example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C openconfig_interfaces_cfg: _kwargs: filter: true interfaces: interface: Et1: config: mtu: 9000 Et2: config: description: \(dqdescription example\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.net_napalm_yang.managed(name, data, **kwargs) Manage the device configuration given the input data structured according to the YANG models. .INDENT 7.0 .TP .B data YANG structured data. .TP .B models A list of models to be used when generating the config. .TP .B profiles: \fBNone\fP Use certain profiles to generate the config. If not specified, will use the platform default profile(s). .TP .B compliance_report: \fBFalse\fP Return the compliance report in the comment. .sp New in version 2017.7.3. .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: \fBTrue\fP Commit? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key under the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .TP .B replace: \fBFalse\fP Should replace the config with the new generate one? .UNINDENT .sp State SLS example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set expected_config = pillar.get(\(aqopenconfig_interfaces_cfg\(aq) \-%} interfaces_config: napalm_yang.managed: \- data: {{ expected_config | json }} \- models: \- models.openconfig_interfaces \- debug: true .ft P .fi .UNINDENT .UNINDENT .sp Pillar example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C openconfig_interfaces_cfg: _kwargs: filter: true interfaces: interface: Et1: config: mtu: 9000 Et2: config: description: \(dqdescription example\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.netacl .SS Network ACL .sp Manage the firewall configuration on the network device managed through NAPALM. The firewall configuration is generated by \fI\%Capirca\fP\&. .sp New in version 2017.7.0. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> .TP .B maturity new .TP .B depends capirca, napalm .TP .B platform unix .UNINDENT .SS Dependencies .SS Capirca .sp To install Capirca, execute: \fBpip install capirca\fP\&. .SS NAPALM .sp To be able to load configuration on network devices, it requires \fI\%NAPALM\fP library to be installed: \fBpip install napalm\fP\&. Please check \fI\%Installation\fP for complete details. .INDENT 0.0 .TP .B salt.states.netacl.filter(name, filter_name, filter_options=None, terms=None, prepend=True, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None, merge_pillar=False, only_lower_merge=False, revision_id=None, revision_no=None, revision_date=True, revision_date_format=\(aq%Y/%m/%d\(aq, test=False, commit=True, debug=False) Generate and load the configuration of a policy filter. .INDENT 7.0 .TP .B filter_name The name of the policy filter. .TP .B filter_options Additional filter options. These options are platform\-specific. See the complete list of \fI\%options\fP\&. .TP .B terms Dictionary of terms for this policy filter. If not specified or empty, will try to load the configuration from the pillar, unless \fBmerge_pillar\fP is set as \fBFalse\fP\&. .TP .B prepend: \fBTrue\fP When \fBmerge_pillar\fP is set as \fBTrue\fP, the final list of terms generated by merging the terms from \fBterms\fP with those defined in the pillar (if any): new terms are prepended at the beginning, while existing ones will preserve the position. To add the new terms at the end of the list, set this argument to \fBFalse\fP\&. .TP .B pillar_key: \fBacl\fP The key in the pillar containing the default attributes values. Default: \fBacl\fP\&. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .TP .B merge_pillar: \fBFalse\fP Merge \fBterms\fP with the corresponding value from the pillar. Default: \fBFalse\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 By default this state does not merge, to avoid any unexpected behaviours. .sp The merge logic depends on the \fBprepend\fP argument. .sp The terms specified through the \fBterms\fP argument have higher priority than the pillar. .UNINDENT .UNINDENT .TP .B only_lower_merge: \fBFalse\fP Specify if it should merge only the terms fields. Otherwise it will try to merge also filters fields. Default: \fBFalse\fP\&. This option requires \fBmerge_pillar\fP, otherwise it is ignored. .TP .B revision_id Add a comment in the filter config having the description for the changes applied. .TP .B revision_no The revision count. .TP .B revision_date: \fBTrue\fP Boolean flag: display the date when the filter configuration was generated. Default: \fBTrue\fP\&. .TP .B revision_date_format: \fB%Y/%m/%d\fP The date format to be used when generating the perforce data. Default: \fB%Y/%m/%d\fP (<year>/<month>/<day>). .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: \fBTrue\fP Commit? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key under the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqedge01.flw01\(aq state.sls router.acl test=True .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C edge01.flw01: \-\-\-\-\-\-\-\-\-\- ID: my\-filter Function: netacl.filter Result: None Comment: Testing mode: Configuration discarded. Started: 12:24:40.598232 Duration: 2437.139 ms Changes: \-\-\-\-\-\-\-\-\-\- diff: \-\-\- +++ @@ \-1228,9 +1228,24 @@ ! +ipv4 access\-list my\-filter + 10 remark $Id: my\-filter_state $ + 20 remark $Revision: 5 $ + 30 remark my\-other\-term + 40 permit tcp any range 5678 5680 any +! +! loaded: ! $Id: my\-filter_state $ ! $Revision: 5 $ no ipv6 access\-list my\-filter ipv6 access\-list my\-filter remark $Id: my\-filter_state $ remark $Revision: 5 $ remark my\-other\-term permit tcp any range 5678 5680 any exit Summary for edge01.flw01 \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 1 (unchanged=1, changed=1) Failed: 0 \-\-\-\-\-\-\-\-\-\-\-\- Total states run: 1 Total run time: 2.437 s .ft P .fi .UNINDENT .UNINDENT .sp Pillar example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C acl: \- my\-filter: options: \- inet6 terms: \- my\-term: source_port: [1234, 1235] protocol: \- tcp \- udp source_address: 1.2.3.4 action: reject \- my\-other\-term: source_port: \- [5678, 5680] protocol: tcp action: accept .ft P .fi .UNINDENT .UNINDENT .sp State SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set filter_name = \(aqmy\-filter\(aq \-%} {%\- set my_filter_cfg = salt.netacl.get_filter_pillar(filter_name, pillar_key=\(aqfirewall\(aq) \-%} my_first_filter_state: netacl.filter: \- filter_name: {{ filter_name }} \- options: {{ my_filter_cfg[\(aqoptions\(aq] | json }} \- terms: {{ my_filter_cfg[\(aqterms\(aq] | json }} \- revision_date: false \- revision_no: 5 \- debug: true .ft P .fi .UNINDENT .UNINDENT .sp Or: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my_first_filter_state: netacl.filter: \- filter_name: my\-filter \- merge_pillar: true \- pillar_key: firewall \- revision_date: false \- revision_no: 5 \- debug: true .ft P .fi .UNINDENT .UNINDENT .sp In the example above, as \fBinet6\fP has been specified in the \fBfilter_options\fP, the configuration chunk referring to \fBmy\-term\fP has been ignored as it referred to IPv4 only (from \fBsource_address\fP field). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The first method allows the user to eventually apply complex manipulation and / or retrieve the data from external services before passing the data to the state. The second one is more straightforward, for less complex cases when loading the data directly from the pillar is sufficient. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When passing retrieved pillar data into the state file, it is strongly recommended to use the json serializer explicitly (\(ga\(ga | json\(ga\(ga), instead of relying on the default Python serializer. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.netacl.managed(name, filters=None, prepend=True, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None, merge_pillar=False, only_lower_merge=False, revision_id=None, revision_no=None, revision_date=True, revision_date_format=\(aq%Y/%m/%d\(aq, test=False, commit=True, debug=False) Manage the whole firewall configuration. .INDENT 7.0 .TP .B filters Dictionary of filters for this policy. If not specified or empty, will try to load the configuration from the pillar, unless \fBmerge_pillar\fP is set as \fBFalse\fP\&. .TP .B prepend: \fBTrue\fP When \fBmerge_pillar\fP is set as \fBTrue\fP, the final list of filters generated by merging the filters from \fBfilters\fP with those defined in the pillar (if any): new filters are prepended at the beginning, while existing ones will preserve the position. To add the new filters at the end of the list, set this argument to \fBFalse\fP\&. .TP .B pillar_key: \fBacl\fP The key in the pillar containing the default attributes values. Default: \fBacl\fP\&. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .TP .B merge_pillar: \fBFalse\fP Merge the \fBfilters\fP will the corresponding values from the pillar. Default: \fBFalse\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 By default this state does not merge, to avoid any unexpected behaviours. .sp The merge logic depends on the \fBprepend\fP argument. .sp The filters specified through the \fBfilters\fP argument have higher priority than the pillar. .UNINDENT .UNINDENT .TP .B only_lower_merge: \fBFalse\fP Specify if it should merge only the filters and terms fields. Otherwise it will try to merge everything at the policy level. Default: \fBFalse\fP\&. This option requires \fBmerge_pillar\fP, otherwise it is ignored. .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B revision_id Add a comment in the policy config having the description for the changes applied. .TP .B revision_no The revision count. .TP .B revision_date: \fBTrue\fP Boolean flag: display the date when the policy configuration was generated. Default: \fBTrue\fP\&. .TP .B revision_date_format: \fB%Y/%m/%d\fP The date format to be used when generating the perforce data. Default: \fB%Y/%m/%d\fP (<year>/<month>/<day>). .TP .B commit: \fBTrue\fP Commit? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key under the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqedge01.bjm01\(aq state.sls router.acl test=True .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C edge01.bjm01: \-\-\-\-\-\-\-\-\-\-\-\-\- ID: netacl_example Function: netacl.managed Result: None Comment: Testing mode: Configuration discarded. Started: 12:03:24.807023 Duration: 5569.453 ms Changes: \-\-\-\-\-\-\-\-\-\- diff: [edit firewall] + family inet { + /* + ** $Id: netacl_example $ + ** $Date: 2017/07/03 $ + ** $Revision: 2 $ + ** + */ + filter my\-filter { + interface\-specific; + term my\-term { + from { + source\-address { + 1.2.3.4/32; + } + protocol [ tcp udp ]; + source\-port [ 1234 1235 ]; + } + then { + reject; + } + } + term my\-other\-term { + from { + protocol tcp; + source\-port 5678\-5680; + } + then accept; + } + } + /* + ** $Id: netacl_example $ + ** $Date: 2017/07/03 $ + ** $Revision: 2 $ + ** + */ + filter block\-icmp { + interface\-specific; + term first\-term { + from { + protocol icmp; + } + then { + reject; + } + } + } + } loaded: firewall { family inet { replace: /* ** $Id: netacl_example $ ** $Date: 2017/07/03 $ ** $Revision: 2 $ ** */ filter my\-filter { interface\-specific; term my\-term { from { source\-address { 1.2.3.4/32; } protocol [ tcp udp ]; source\-port [ 1234 1235 ]; } then { reject; } } term my\-other\-term { from { protocol tcp; source\-port 5678\-5680; } then accept; } } } } firewall { family inet { replace: /* ** $Id: netacl_example $ ** $Date: 2017/07/03 $ ** $Revision: 2 $ ** */ filter block\-icmp { interface\-specific; term first\-term { from { protocol icmp; } then { reject; } } } } } Summary for edge01.bjm01 \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 1 (unchanged=1, changed=1) Failed: 0 \-\-\-\-\-\-\-\-\-\-\-\- Total states run: 1 Total run time: 5.569 s .ft P .fi .UNINDENT .UNINDENT .sp The policy configuration has been loaded from the pillar, having the following structure: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C firewall: \- my\-filter: terms: \- my\-term: source_port: [1234, 1235] protocol: \- tcp \- udp source_address: 1.2.3.4 action: reject \- my\-other\-term: source_port: \- [5678, 5680] protocol: tcp action: accept \- block\-icmp: terms: \- first\-term: protocol: \- icmp action: reject .ft P .fi .UNINDENT .UNINDENT .sp Example SLS file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set fw_filters = pillar.get(\(aqfirewall\(aq, {}) \-%} netacl_example: netacl.managed: \- filters: {{ fw_filters | json }} \- revision_no: 2 \- debug: true .ft P .fi .UNINDENT .UNINDENT .sp Or: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C netacl_example: netacl.managed: \- pillar_key: firewall \- merge_pillar: true \- revision_no: 2 \- debug: true .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The first method allows the user to eventually apply complex manipulation and / or retrieve the data from external services before passing the data to the state. The second one is more straightforward, for less complex cases when loading the data directly from the pillar is sufficient. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When passing retrieved pillar data into the state file, it is strongly recommended to use the json serializer explicitly (\(ga\(ga | json\(ga\(ga), instead of relying on the default Python serializer. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.netacl.term(name, filter_name, term_name, filter_options=None, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None, merge_pillar=False, revision_id=None, revision_no=None, revision_date=True, revision_date_format=\(aq%Y/%m/%d\(aq, test=False, commit=True, debug=False, source_service=None, destination_service=None, **term_fields) Manage the configuration of a specific policy term. .INDENT 7.0 .TP .B filter_name The name of the policy filter. .TP .B term_name The name of the term. .TP .B filter_options Additional filter options. These options are platform\-specific. See the complete list of \fI\%options\fP\&. .TP .B pillar_key: \fBacl\fP The key in the pillar containing the default attributes values. Default: \fBacl\fP\&. .TP .B pillarenv Query the master to generate fresh pillar data on the fly, specifically from the requested pillar environment. .TP .B saltenv Included only for compatibility with \fI\%pillarenv_from_saltenv\fP, and is otherwise ignored. .TP .B merge_pillar: \fBFalse\fP Merge the CLI variables with the pillar. Default: \fBFalse\fP\&. .sp The properties specified through the state arguments have higher priority than the pillar. .TP .B revision_id Add a comment in the term config having the description for the changes applied. .TP .B revision_no The revision count. .TP .B revision_date: \fBTrue\fP Boolean flag: display the date when the term configuration was generated. Default: \fBTrue\fP\&. .TP .B revision_date_format: \fB%Y/%m/%d\fP The date format to be used when generating the perforce data. Default: \fB%Y/%m/%d\fP (<year>/<month>/<day>). .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: \fBTrue\fP Commit? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key under the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .TP .B source_service A special service to choose from. This is a helper so the user is able to select a source just using the name, instead of specifying a source_port and protocol. .sp As this module is available on Unix platforms only, it reads the \fI\%IANA\fP port assignment from /etc/services. .sp If the user requires additional shortcuts to be referenced, they can add entries under /etc/services, which can be managed using the \fI\%file state\fP\&. .TP .B destination_service A special service to choose from. This is a helper so the user is able to select a source just using the name, instead of specifying a destination_port and protocol. Allows the same options as \fBsource_service\fP\&. .TP .B term_fields Term attributes. To see what fields are supported, please consult the list of supported \fI\%keywords\fP\&. Some platforms have few other \fI\%optional\fP keywords. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The following fields are accepted: .INDENT 0.0 .IP \(bu 2 action .IP \(bu 2 address .IP \(bu 2 address_exclude .IP \(bu 2 comment .IP \(bu 2 counter .IP \(bu 2 expiration .IP \(bu 2 destination_address .IP \(bu 2 destination_address_exclude .IP \(bu 2 destination_port .IP \(bu 2 destination_prefix .IP \(bu 2 forwarding_class .IP \(bu 2 forwarding_class_except .IP \(bu 2 logging .IP \(bu 2 log_name .IP \(bu 2 loss_priority .IP \(bu 2 option .IP \(bu 2 policer .IP \(bu 2 port .IP \(bu 2 precedence .IP \(bu 2 principals .IP \(bu 2 protocol .IP \(bu 2 protocol_except .IP \(bu 2 qos .IP \(bu 2 pan_application .IP \(bu 2 routing_instance .IP \(bu 2 source_address .IP \(bu 2 source_address_exclude .IP \(bu 2 source_port .IP \(bu 2 source_prefix .IP \(bu 2 verbatim .IP \(bu 2 packet_length .IP \(bu 2 fragment_offset .IP \(bu 2 hop_limit .IP \(bu 2 icmp_type .IP \(bu 2 ether_type .IP \(bu 2 traffic_class_count .IP \(bu 2 traffic_type .IP \(bu 2 translated .IP \(bu 2 dscp_set .IP \(bu 2 dscp_match .IP \(bu 2 dscp_except .IP \(bu 2 next_ip .IP \(bu 2 flexible_match_range .IP \(bu 2 source_prefix_except .IP \(bu 2 destination_prefix_except .IP \(bu 2 vpn .IP \(bu 2 source_tag .IP \(bu 2 destination_tag .IP \(bu 2 source_interface .IP \(bu 2 destination_interface .IP \(bu 2 flattened .IP \(bu 2 flattened_addr .IP \(bu 2 flattened_saddr .IP \(bu 2 flattened_daddr .IP \(bu 2 priority .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The following fields can be also a single value and a list of values: .INDENT 0.0 .IP \(bu 2 action .IP \(bu 2 address .IP \(bu 2 address_exclude .IP \(bu 2 comment .IP \(bu 2 destination_address .IP \(bu 2 destination_address_exclude .IP \(bu 2 destination_port .IP \(bu 2 destination_prefix .IP \(bu 2 forwarding_class .IP \(bu 2 forwarding_class_except .IP \(bu 2 logging .IP \(bu 2 option .IP \(bu 2 port .IP \(bu 2 precedence .IP \(bu 2 principals .IP \(bu 2 protocol .IP \(bu 2 protocol_except .IP \(bu 2 pan_application .IP \(bu 2 source_address .IP \(bu 2 source_address_exclude .IP \(bu 2 source_port .IP \(bu 2 source_prefix .IP \(bu 2 verbatim .IP \(bu 2 icmp_type .IP \(bu 2 ether_type .IP \(bu 2 traffic_type .IP \(bu 2 dscp_match .IP \(bu 2 dscp_except .IP \(bu 2 flexible_match_range .IP \(bu 2 source_prefix_except .IP \(bu 2 destination_prefix_except .IP \(bu 2 source_tag .IP \(bu 2 destination_tag .IP \(bu 2 source_service .IP \(bu 2 destination_service .UNINDENT .sp Example: \fBdestination_address\fP can be either defined as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C destination_address: 172.17.17.1/24 .ft P .fi .UNINDENT .UNINDENT .sp or as a list of destination IP addresses: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C destination_address: \- 172.17.17.1/24 \- 172.17.19.1/24 .ft P .fi .UNINDENT .UNINDENT .sp or a list of services to be matched: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source_service: \- ntp \- snmp \- ldap \- bgpd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The port fields \fBsource_port\fP and \fBdestination_port\fP can be used as above to select either a single value, either a list of values, but also they can select port ranges. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source_port: \- [1000, 2000] \- [3000, 4000] .ft P .fi .UNINDENT .UNINDENT .sp With the configuration above, the user is able to select the 1000\-2000 and 3000\-4000 source port ranges. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqedge01.bjm01\(aq state.sls router.acl .ft P .fi .UNINDENT .UNINDENT .sp Output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C edge01.bjm01: \-\-\-\-\-\-\-\-\-\- ID: update_icmp_first_term Function: netacl.term Result: None Comment: Testing mode: Configuration discarded. Started: 12:49:09.174179 Duration: 5751.882 ms Changes: \-\-\-\-\-\-\-\-\-\- diff: [edit firewall] + family inet { + /* + ** $Id: update_icmp_first_term $ + ** $Date: 2017/02/30 $ + ** + */ + filter block\-icmp { + term first\-term { + from { + protocol icmp; + } + then { + reject; + } + } + } + } Summary for edge01.bjm01 \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 1 (unchanged=1, changed=1) Failed: 0 \-\-\-\-\-\-\-\-\-\-\-\- Total states run: 1 Total run time: 5.752 s .ft P .fi .UNINDENT .UNINDENT .sp Pillar example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C firewall: \- block\-icmp: terms: \- first\-term: protocol: \- icmp action: reject .ft P .fi .UNINDENT .UNINDENT .sp State SLS example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set filter_name = \(aqblock\-icmp\(aq \-%} {%\- set term_name = \(aqfirst\-term\(aq \-%} {%\- set my_term_cfg = salt.netacl.get_term_pillar(filter_name, term_name) \-%} update_icmp_first_term: netacl.term: \- filter_name: {{ filter_name }} \- filter_options: \- not\-interface\-specific \- term_name: {{ term_name }} \- {{ my_term_cfg | json }} .ft P .fi .UNINDENT .UNINDENT .sp Or directly referencing the pillar keys: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C update_icmp_first_term: netacl.term: \- filter_name: block\-icmp \- filter_options: \- not\-interface\-specific \- term_name: first\-term \- merge_pillar: true .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The first method allows the user to eventually apply complex manipulation and / or retrieve the data from external services before passing the data to the state. The second one is more straightforward, for less complex cases when loading the data directly from the pillar is sufficient. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When passing retrieved pillar data into the state file, it is strongly recommended to use the json serializer explicitly (\(ga\(ga | json\(ga\(ga), instead of relying on the default Python serializer. .UNINDENT .UNINDENT .UNINDENT .SS salt.states.netconfig .SS Network Config .sp Manage the configuration on a network device given a specific static config or template. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> & Jerome Fleury <\fI\%jf@cloudflare.com\fP> .TP .B maturity new .TP .B depends napalm .TP .B platform unix .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 \fI\%NAPALM proxy minion\fP .IP \(bu 2 \fI\%Network\-related basic features execution module\fP .UNINDENT .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.states.netconfig.commit_cancelled(name) New in version 2019.2.0. .sp Cancel a commit scheduled to be executed via the \fBcommit_in\fP and \fBcommit_at\fP arguments from the \fI\%net.load_template\fP or \fI\%net.load_config\fP execution functions. The commit ID is displayed when the commit is scheduled via the functions named above. .sp State SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \(aq20180726083540640360\(aq: netconfig.commit_cancelled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.netconfig.commit_confirmed(name) New in version 2019.2.0. .sp Confirm a commit scheduled to be reverted via the \fBrevert_in\fP and \fBrevert_at\fP arguments from the \fI\%net.load_template\fP or \fI\%net.load_config\fP execution functions. The commit ID is displayed when the commit confirmed is scheduled via the functions named above. .sp State SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \(aq20180726083540640360\(aq: netconfig.commit_confirmed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.netconfig.managed(name, template_name=None, template_source=None, template_hash=None, template_hash_name=None, saltenv=\(aqbase\(aq, template_engine=\(aqjinja\(aq, skip_verify=False, context=None, defaults=None, test=False, commit=True, debug=False, replace=False, commit_in=None, commit_at=None, revert_in=None, revert_at=None, **template_vars) Manages the configuration on network devices. .sp By default this state will commit the changes on the device. If there are no changes required, it does not commit and the field \fBalready_configured\fP from the output dictionary will be set as \fBTrue\fP to notify that. .sp To avoid committing the configuration, set the argument \fBtest\fP to \fBTrue\fP (or via the CLI argument \fBtest=True\fP) and will discard (dry run). .sp To preserve the changes, set \fBcommit\fP to \fBFalse\fP (either as CLI argument, either as state parameter). However, this is recommended to be used only in exceptional cases when there are applied few consecutive states and/or configuration changes. Otherwise the user might forget that the config DB is locked and the candidate config buffer is not cleared/merged in the running config. .sp To replace the config, set \fBreplace\fP to \fBTrue\fP\&. This option is recommended to be used with caution! .INDENT 7.0 .TP .B template_name Identifies path to the template source. The template can be either stored on the local machine, either remotely. The recommended location is under the \fBfile_roots\fP as specified in the master config file. For example, let\(aqs suppose the \fBfile_roots\fP is configured as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /etc/salt/states .ft P .fi .UNINDENT .UNINDENT .sp Placing the template under \fB/etc/salt/states/templates/example.jinja\fP, it can be used as \fBsalt://templates/example.jinja\fP\&. Alternatively, for local files, the user can specify the absolute path. If remotely, the source can be retrieved via \fBhttp\fP, \fBhttps\fP or \fBftp\fP\&. .sp Examples: .INDENT 7.0 .IP \(bu 2 \fBsalt://my_template.jinja\fP .IP \(bu 2 \fB/absolute/path/to/my_template.jinja\fP .IP \(bu 2 \fBhttp://example.com/template.cheetah\fP .IP \(bu 2 \fBhttps:/example.com/template.mako\fP .IP \(bu 2 \fBftp://example.com/template.py\fP .UNINDENT .sp Changed in version 2019.2.0: This argument can now support a list of templates to be rendered. The resulting configuration text is loaded at once, as a single configuration chunk. .TP .B template_source: None Inline config template to be rendered and loaded on the device. .TP .B template_hash: None Hash of the template file. Format: \fB{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\fP .TP .B template_hash_name: None When \fBtemplate_hash\fP refers to a remote file, this specifies the filename to look for in that file. .TP .B saltenv: base Specifies the template environment. This will influence the relative imports inside the templates. .TP .B template_engine: jinja The following templates engines are supported: .INDENT 7.0 .IP \(bu 2 \fI\%cheetah\fP .IP \(bu 2 \fI\%genshi\fP .IP \(bu 2 \fI\%jinja\fP .IP \(bu 2 \fI\%mako\fP .IP \(bu 2 \fI\%py\fP .IP \(bu 2 \fI\%wempy\fP .UNINDENT .TP .B skip_verify: False If \fBTrue\fP, hash verification of remote file sources (\fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP) will be skipped, and the \fBsource_hash\fP argument will be ignored. .sp Changed in version 2017.7.1. .TP .B test: False Dry run? If set to \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP (will commit the changes on the device). .TP .B commit: True Commit? Default: \fBTrue\fP\&. .TP .B debug: False Debug mode. Will insert a new key under the output dictionary, as \fBloaded_config\fP containing the raw result after the template was rendered. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument cannot be used directly on the command line. Instead, it can be passed through the \fBpillar\fP variable when executing either of the \fI\%state.sls\fP or \fBstate.apply\fP (see below for an example). .UNINDENT .UNINDENT .TP .B commit_in: \fBNone\fP Commit the changes in a specific number of minutes / hours. Example of accepted formats: \fB5\fP (commit in 5 minutes), \fB2m\fP (commit in 2 minutes), \fB1h\fP (commit the changes in 1 hour)\(ga, \fB5h30m\fP (commit the changes in 5 hours and 30 minutes). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This feature works on any platforms, as it does not rely on the native features of the network operating system. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 After the command is executed and the \fBdiff\fP is not satisfactory, or for any other reasons you have to discard the commit, you are able to do so using the \fI\%net.cancel_commit\fP execution function, using the commit ID returned by this function. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Using this feature, Salt will load the exact configuration you expect, however the diff may change in time (i.e., if an user applies a manual configuration change, or a different process or command changes the configuration in the meanwhile). .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B commit_at: \fBNone\fP Commit the changes at a specific time. Example of accepted formats: \fB1am\fP (will commit the changes at the next 1AM), \fB13:20\fP (will commit at 13:20), \fB1:20am\fP, etc. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This feature works on any platforms, as it does not rely on the native features of the network operating system. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 After the command is executed and the \fBdiff\fP is not satisfactory, or for any other reasons you have to discard the commit, you are able to do so using the \fI\%net.cancel_commit\fP execution function, using the commit ID returned by this function. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Using this feature, Salt will load the exact configuration you expect, however the diff may change in time (i.e., if an user applies a manual configuration change, or a different process or command changes the configuration in the meanwhile). .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B revert_in: \fBNone\fP Commit and revert the changes in a specific number of minutes / hours. Example of accepted formats: \fB5\fP (revert in 5 minutes), \fB2m\fP (revert in 2 minutes), \fB1h\fP (revert the changes in 1 hour)\(ga, \fB5h30m\fP (revert the changes in 5 hours and 30 minutes). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To confirm the commit, and prevent reverting the changes, you will have to execute the \fI\%net.confirm_commit\fP function, using the commit ID returned by this function. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This works on any platform, regardless if they have or don\(aqt have native capabilities to confirming a commit. However, please be \fIvery\fP cautious when using this feature: on Junos (as it is the only NAPALM core platform supporting this natively) it executes a commit confirmed as you would do from the command line. All the other platforms don\(aqt have this capability natively, therefore the revert is done via Salt. That means, your device needs to be reachable at the moment when Salt will attempt to revert your changes. Be cautious when pushing configuration changes that would prevent you reach the device. .sp Similarly, if an user or a different process apply other configuration changes in the meanwhile (between the moment you commit and till the changes are reverted), these changes would be equally reverted, as Salt cannot be aware of them. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B revert_at: \fBNone\fP Commit and revert the changes at a specific time. Example of accepted formats: \fB1am\fP (will commit and revert the changes at the next 1AM), \fB13:20\fP (will commit and revert at 13:20), \fB1:20am\fP, etc. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To confirm the commit, and prevent reverting the changes, you will have to execute the \fI\%net.confirm_commit\fP function, using the commit ID returned by this function. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This works on any platform, regardless if they have or don\(aqt have native capabilities to confirming a commit. However, please be \fIvery\fP cautious when using this feature: on Junos (as it is the only NAPALM core platform supporting this natively) it executes a commit confirmed as you would do from the command line. All the other platforms don\(aqt have this capability natively, therefore the revert is done via Salt. That means, your device needs to be reachable at the moment when Salt will attempt to revert your changes. Be cautious when pushing configuration changes that would prevent you reach the device. .sp Similarly, if an user or a different process apply other configuration changes in the meanwhile (between the moment you commit and till the changes are reverted), these changes would be equally reverted, as Salt cannot be aware of them. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B replace: False Load and replace the configuration. Default: \fBFalse\fP (will apply load merge). .TP .B context: None Overrides default context variables passed to the template. .sp New in version 2019.2.0. .TP .B defaults: None Default variables/context passed to the template. .TP .B template_vars Dictionary with the arguments/context to be used when the template is rendered. Do not explicitly specify this argument. This represents any other variable that will be sent to the template rendering system. Please see an example below! In both \fBntp_peers_example_using_pillar\fP and \fBntp_peers_example\fP, \fBpeers\fP is sent as template variable. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 It is more recommended to use the \fBcontext\fP argument instead, to avoid any conflicts with other arguments. .UNINDENT .UNINDENT .UNINDENT .sp SLS Example (e.g.: under salt://router/config.sls) : .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C whole_config_example: netconfig.managed: \- template_name: salt://path/to/complete_config.jinja \- debug: True \- replace: True bgp_config_example: netconfig.managed: \- template_name: /absolute/path/to/bgp_neighbors.mako \- template_engine: mako prefix_lists_example: netconfig.managed: \- template_name: prefix_lists.cheetah \- debug: True \- template_engine: cheetah ntp_peers_example: netconfig.managed: \- template_name: http://bit.ly/2gKOj20 \- skip_verify: False \- debug: True \- peers: \- 192.168.0.1 \- 192.168.0.1 ntp_peers_example_using_pillar: netconfig.managed: \- template_name: http://bit.ly/2gKOj20 \- peers: {{ pillar.get(\(aqntp.peers\(aq, []) }} .ft P .fi .UNINDENT .UNINDENT .sp Multi template example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C hostname_and_ntp: netconfig.managed: \- template_name: \- https://bit.ly/2OhSgqP \- https://bit.ly/2M6C4Lx \- https://bit.ly/2OIWVTs \- debug: true \- context: hostname: {{ opts.id }} servers: \- 172.17.17.1 \- 172.17.17.2 peers: \- 192.168.0.1 \- 192.168.0.2 .ft P .fi .UNINDENT .UNINDENT .sp Usage examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \(aqjuniper.device\(aq state.sls router.config test=True $ sudo salt \-N all\-routers state.sls router.config pillar=\(dq{\(aqdebug\(aq: True}\(dq .ft P .fi .UNINDENT .UNINDENT .sp \fBrouter.config\fP depends on the location of the SLS file (see above). Running this command, will be executed all five steps from above. These examples above are not meant to be used in a production environment, their sole purpose is to provide usage examples. .sp Output example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \(aqjuniper.device\(aq state.sls router.config test=True juniper.device: \-\-\-\-\-\-\-\-\-\- ID: ntp_peers_example_using_pillar Function: netconfig.managed Result: None Comment: Testing mode: Configuration discarded. Started: 12:01:40.744535 Duration: 8755.788 ms Changes: \-\-\-\-\-\-\-\-\-\- diff: [edit system ntp] peer 192.168.0.1 { ... } + peer 172.17.17.1; + peer 172.17.17.3; Summary for juniper.device \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 1 (unchanged=1, changed=1) Failed: 0 \-\-\-\-\-\-\-\-\-\-\-\- Total states run: 1 Total run time: 8.756 s .ft P .fi .UNINDENT .UNINDENT .sp Raw output example (useful when the output is reused in other states/execution modules): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \-\-out=pprint \(aqjuniper.device\(aq state.sls router.config test=True debug=True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqjuniper.device\(aq: { \(aqnetconfig_|\-ntp_peers_example_using_pillar_|\-ntp_peers_example_using_pillar_|\-managed\(aq: { \(aq__id__\(aq: \(aqntp_peers_example_using_pillar\(aq, \(aq__run_num__\(aq: 0, \(aqalready_configured\(aq: False, \(aqchanges\(aq: { \(aqdiff\(aq: \(aq[edit system ntp] peer 192.168.0.1 { ... }+ peer 172.17.17.1;+ peer 172.17.17.3;\(aq }, \(aqcomment\(aq: \(aqTesting mode: Configuration discarded.\(aq, \(aqduration\(aq: 7400.759, \(aqloaded_config\(aq: \(aqsystem { ntp { peer 172.17.17.1; peer 172.17.17.3; } }\(aq, \(aqname\(aq: \(aqntp_peers_example_using_pillar\(aq, \(aqresult\(aq: None, \(aqstart_time\(aq: \(aq12:09:09.811445\(aq } } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.netconfig.replace_pattern(name, pattern, repl, count=0, flags=8, bufsize=1, append_if_not_found=False, prepend_if_not_found=False, not_found_content=None, search_only=False, show_changes=True, backslash_literal=False, source=\(aqrunning\(aq, path=None, test=False, replace=True, debug=False, commit=True) New in version 2019.2.0. .sp Replace occurrences of a pattern in the configuration source. If \fBshow_changes\fP is \fBTrue\fP, then a diff of what changed will be returned, otherwise a \fBTrue\fP will be returned when changes are made, and \fBFalse\fP when no changes are made. This is a pure Python implementation that wraps Python\(aqs \fI\%sub()\fP\&. .INDENT 7.0 .TP .B pattern A regular expression, to be matched using Python\(aqs \fI\%search()\fP\&. .TP .B repl The replacement text. .TP .B count: \fB0\fP Maximum number of pattern occurrences to be replaced. If count is a positive integer \fBn\fP, only \fBn\fP occurrences will be replaced, otherwise all occurrences will be replaced. .TP .B flags (list or int): \fB8\fP A list of flags defined in the \fBre\fP module documentation from the Python standard library. Each list item should be a string that will correlate to the human\-friendly flag name. E.g., \fB[\(aqIGNORECASE\(aq, \(aqMULTILINE\(aq]\fP\&. Optionally, \fBflags\fP may be an int, with a value corresponding to the XOR (\fB|\fP) of all the desired flags. Defaults to 8 (which supports \(aqMULTILINE\(aq). .TP .B bufsize (int or str): \fB1\fP How much of the configuration to buffer into memory at once. The default value \fB1\fP processes one line at a time. The special value \fBfile\fP may be specified which will read the entire file into memory before processing. .TP .B append_if_not_found: \fBFalse\fP If set to \fBTrue\fP, and pattern is not found, then the content will be appended to the file. .TP .B prepend_if_not_found: \fBFalse\fP If set to \fBTrue\fP and pattern is not found, then the content will be prepended to the file. .TP .B not_found_content Content to use for append/prepend if not found. If None (default), uses \fBrepl\fP\&. Useful when \fBrepl\fP uses references to group in pattern. .TP .B search_only: \fBFalse\fP If set to true, this no changes will be performed on the file, and this function will simply return \fBTrue\fP if the pattern was matched, and \fBFalse\fP if not. .TP .B show_changes: \fBTrue\fP If \fBTrue\fP, return a diff of changes made. Otherwise, return \fBTrue\fP if changes were made, and \fBFalse\fP if not. .TP .B backslash_literal: \fBFalse\fP Interpret backslashes as literal backslashes for the repl and not escape characters. This will help when using append/prepend so that the backslashes are not interpreted for the repl on the second run of the state. .TP .B source: \fBrunning\fP The configuration source. Choose from: \fBrunning\fP, \fBcandidate\fP, or \fBstartup\fP\&. Default: \fBrunning\fP\&. .TP .B path Save the temporary configuration to a specific path, then read from there. .TP .B test: \fBFalse\fP Dry run? If set as \fBTrue\fP, will apply the config, discard and return the changes. Default: \fBFalse\fP and will commit the changes on the device. .TP .B commit: \fBTrue\fP Commit the configuration changes? Default: \fBTrue\fP\&. .TP .B debug: \fBFalse\fP Debug mode. Will insert a new key in the output dictionary, as \fBloaded_config\fP containing the raw configuration loaded on the device. .TP .B replace: \fBTrue\fP Load and replace the configuration. Default: \fBTrue\fP\&. .UNINDENT .sp If an equal sign (\fB=\fP) appears in an argument to a Salt command it is interpreted as a keyword argument in the format \fBkey=val\fP\&. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg: .sp State SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C update_policy_name: netconfig.replace_pattern: \- pattern: OLD\-POLICY\-NAME \- repl: new\-policy\-name \- debug: true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.netconfig.saved(name, source=\(aqrunning\(aq, user=None, group=None, mode=None, attrs=None, makedirs=False, dir_mode=None, replace=True, backup=\(aq\(aq, show_changes=True, create=True, tmp_dir=\(aq\(aq, tmp_ext=\(aq\(aq, encoding=None, encoding_errors=\(aqstrict\(aq, allow_empty=False, follow_symlinks=True, check_cmd=None, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=True, win_perms_reset=False, **kwargs) New in version 2019.2.0. .sp Save the configuration to a file on the local file system. .INDENT 7.0 .TP .B name Absolute path to file where to save the configuration. To push the files to the Master, use \fI\%cp.push\fP Execution function. .TP .B source: \fBrunning\fP The configuration source. Choose from: \fBrunning\fP, \fBcandidate\fP, \fBstartup\fP\&. Default: \fBrunning\fP\&. .TP .B user The user to own the file, this defaults to the user salt is running as on the minion .TP .B group The group ownership set for the file, this defaults to the group salt is running as on the minion. On Windows, this is ignored .TP .B mode The permissions to set on this file, e.g. \fB644\fP, \fB0775\fP, or \fB4664\fP\&. The default mode for new files and directories corresponds to the umask of the salt process. The mode of existing files and directories will only be changed if \fBmode\fP is specified. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is \fBnot\fP supported on Windows. .UNINDENT .UNINDENT .TP .B attrs The attributes to have on this file, e.g. \fBa\fP, \fBi\fP\&. The attributes can be any or a combination of the following characters: \fBaAcCdDeijPsStTu\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option is \fBnot\fP supported on Windows. .UNINDENT .UNINDENT .TP .B makedirs: \fBFalse\fP If set to \fBTrue\fP, then the parent directories will be created to facilitate the creation of the named file. If \fBFalse\fP, and the parent directory of the destination file doesn\(aqt exist, the state will fail. .TP .B dir_mode If directories are to be created, passing this option specifies the permissions for those directories. If this is not set, directories will be assigned permissions by adding the execute bit to the mode of the files. .sp The default mode for new files and directories corresponds umask of salt process. For existing files and directories it\(aqs not enforced. .TP .B replace: \fBTrue\fP If set to \fBFalse\fP and the file already exists, the file will not be modified even if changes would otherwise be made. Permissions and ownership will still be enforced, however. .TP .B backup Overrides the default backup mode for this specific file. See \fI\%backup_mode documentation\fP for more details. .TP .B show_changes: \fBTrue\fP Output a unified diff of the old file and the new file. If \fBFalse\fP return a boolean if any changes were made. .TP .B create: \fBTrue\fP If set to \fBFalse\fP, then the file will only be managed if the file already exists on the system. .TP .B encoding If specified, then the specified encoding will be used. Otherwise, the file will be encoded using the system locale (usually UTF\-8). See \fI\%https://docs.python.org/3/library/codecs.html#standard\-encodings\fP for the list of available encodings. .TP .B encoding_errors: \fB\(aqstrict\(aq\fP Error encoding scheme. Default is \fB\(ga\(aqstrict\(aq\(ga\fP\&. See \fI\%https://docs.python.org/2/library/codecs.html#codec\-base\-classes\fP for the list of available schemes. .TP .B allow_empty: \fBTrue\fP If set to \fBFalse\fP, then the state will fail if the contents specified by \fBcontents_pillar\fP or \fBcontents_grains\fP are empty. .TP .B follow_symlinks: \fBTrue\fP If the desired path is a symlink follow it and make changes to the file to which the symlink points. .TP .B check_cmd The specified command will be run with an appended argument of a \fItemporary\fP file containing the new managed contents. If the command exits with a zero status the new managed contents will be written to the managed destination. If the command exits with a nonzero exit code, the state will fail and no changes will be made to the file. .TP .B tmp_dir Directory for temp file created by \fBcheck_cmd\fP\&. Useful for checkers dependent on config file location (e.g. daemons restricted to their own config directories by an apparmor profile). .TP .B tmp_ext Suffix for temp file created by \fBcheck_cmd\fP\&. Useful for checkers dependent on config file extension (e.g. the init\-checkconf upstart config checker). .TP .B win_owner: \fBNone\fP The owner of the directory. If this is not passed, user will be used. If user is not passed, the account under which Salt is running will be used. .TP .B win_perms: \fBNone\fP A dictionary containing permissions to grant and their propagation. For example: \fB{\(aqAdministrators\(aq: {\(aqperms\(aq: \(aqfull_control\(aq}}\fP Can be a single basic perm or a list of advanced perms. \fBperms\fP must be specified. \fBapplies_to\fP does not apply to file objects. .TP .B win_deny_perms: \fBNone\fP A dictionary containing permissions to deny and their propagation. For example: \fB{\(aqAdministrators\(aq: {\(aqperms\(aq: \(aqfull_control\(aq}}\fP Can be a single basic perm or a list of advanced perms. \fBperms\fP must be specified. \fBapplies_to\fP does not apply to file objects. .TP .B win_inheritance: \fBTrue\fP True to inherit permissions from the parent directory, False not to inherit permission. .TP .B win_perms_reset: \fBFalse\fP If \fBTrue\fP the existing DACL will be cleared and replaced with the settings defined in this function. If \fBFalse\fP, new entries will be appended to the existing DACL. Default is \fBFalse\fP\&. .UNINDENT .sp State SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /var/backups/{{ opts.id }}/{{ salt.status.time(\(aq%s\(aq) }}.cfg: netconfig.saved: \- source: running \- makedirs: true .ft P .fi .UNINDENT .UNINDENT .sp The state SLS above would create a backup config grouping the files by the Minion ID, in chronological files. For example, if the state is executed at on the 3rd of August 2018, at 5:15PM, on the Minion \fBcore1.lon01\fP, the configuration would saved in the file: \fB/var/backups/core01.lon01/1533316558.cfg\fP .UNINDENT .SS salt.states.netntp .SS Network NTP .sp New in version 2016.11.0. .sp Manage the configuration of NTP peers and servers on the network devices through the NAPALM proxy. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> & Jerome Fleury <\fI\%jf@cloudflare.com\fP> .TP .B maturity new .TP .B depends napalm .TP .B platform unix .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 Requires \fI\%netaddr\fP to be installed: \fIpip install netaddr\fP to check if IP Addresses are correctly specified .IP \(bu 2 Requires \fI\%dnspython\fP to be installed: \fIpip install dnspython\fP to resolve the nameserver entities (in case the user does not configure the peers/servers using their IP addresses) .IP \(bu 2 \fI\%NAPALM proxy minion\fP .IP \(bu 2 \fI\%NTP operational and configuration management module\fP .UNINDENT .INDENT 0.0 .TP .B salt.states.netntp.managed(name, peers=None, servers=None) Manages the configuration of NTP peers and servers on the device, as specified in the state SLS file. NTP entities not specified in these lists will be removed whilst entities not configured on the device will be set. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C netntp_example: netntp.managed: \- peers: \- 192.168.0.1 \- 172.17.17.1 \- servers: \- 24.124.0.251 \- 138.236.128.36 .ft P .fi .UNINDENT .UNINDENT .sp Output example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqedge01.nrt04\(aq: { \(aqnetntp_|\-netntp_example_|\-netntp_example_|\-managed\(aq: { \(aqcomment\(aq: \(aqNTP servers already configured as needed.\(aq, \(aqname\(aq: \(aqnetntp_example\(aq, \(aqstart_time\(aq: \(aq12:45:24.056659\(aq, \(aqduration\(aq: 2938.857, \(aqchanges\(aq: { \(aqpeers\(aq: { \(aqremoved\(aq: [ \(aq192.168.0.2\(aq, \(aq192.168.0.3\(aq ], \(aqadded\(aq: [ \(aq192.168.0.1\(aq, \(aq172.17.17.1\(aq ] } }, \(aqresult\(aq: None } } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.netsnmp .SS Network SNMP .sp Manage the SNMP configuration on network devices. .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 \fI\%napalm snmp management module (salt.modules.napalm_snmp)\fP .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.states.netsnmp.managed(name, config=None, defaults=None) Configures the SNMP on the device as specified in the SLS file. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C snmp_example: netsnmp.managed: \- config: location: Honolulu, HI, US \- defaults: contact: noc@cloudflare.com .ft P .fi .UNINDENT .UNINDENT .sp Output example (for the SLS above, e.g. called snmp.sls under /router/): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt edge01.hnl01 state.sls router.snmp test=True edge01.hnl01: \-\-\-\-\-\-\-\-\-\- ID: snmp_example Function: snmp.managed Result: None Comment: Testing mode: configuration was not changed! Started: 13:29:06.872363 Duration: 920.466 ms Changes: \-\-\-\-\-\-\-\-\-\- added: \-\-\-\-\-\-\-\-\-\- chassis_id: None contact: noc@cloudflare.com location: Honolulu, HI, US Summary for edge01.hnl01 \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 1 (unchanged=1, changed=1) Failed: 0 \-\-\-\-\-\-\-\-\-\-\-\- Total states run: 1 Total run time: 920.466 ms .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.netusers .SS Network Users .sp Manage the users configuration on network devices via the NAPALM proxy. .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 \fI\%NAPALM proxy minion\fP .IP \(bu 2 \fI\%Users configuration management module\fP .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.states.netusers.managed(name, users=None, defaults=None) Manages the configuration of the users on the device, as specified in the state SLS file. Users not defined in that file will be removed whilst users not configured on the device, will be added. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C netusers_example: netusers.managed: \- users: admin: level: 15 password: $1$knmhgPPv$g8745biu4rb.Zf.IT.F/U1 sshkeys: [] restricted: level: 1 password: $1$j34j5k4b$4d5SVjTiz1l.Zf.IT.F/K7 martin: level: 15 password: \(aq\(aq sshkeys: \- ssh\-dss AAAAB3NzaC1kc3MAAACBAK9dP3KariMlM/JmFW9rTSm5cXs4nR0+o6fTHP9o+bOLXMBTP8R4vwWHh0w JPjQmJYafAqZTnlgi0srGjyifFwPtODppDWLCgLe2M4LXnu3OMqknr54w344zPHP3iFwWxHrBrZKtCjO8LhbWCa+ X528+i87t6r5e4ersdfxgchvjbknlio87t6r5drcfhgjhbknio8976tycv7t86ftyiu87Oz1nKsKuNzm2csoUQlJ trmRfpjsOPNookmOz5wG0YxhwDmKeo6fWK+ATk1OiP+QT39fn4G77j8o+e4WAwxM570s35Of/vV0zoOccj753sXn pvJenvwpM2H6o3a9ALvehAJKWodAgZT7X8+iu786r5drtycghvjbiu78t+wAAAIBURwSPZVElXe+9a43sF6M4ysT 7Xv+6wTsa8q86E3+RYyu8O2ObI2kwNLC3/HTgFniE/YqRG+WJac81/VHWQNP822gns8RVrWKjqBktmQoEm7z5yy0 bkjui78675dytcghvjkoi9y7t867ftcuvhbuu9t78gy/v+zvMmv8KvQgHg jonathan: level: 15 password: \(aq\(aq sshkeys: \- ssh\-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDcgxE6HZF/xjFtIt0thEDKPjFJxW9BpZtTVstYbDgGR9zPkHG ZJT/j345jk345jk453jk43545j35nl3kln34n5kl4ghv3/JzWt/0Js5KZp/51KRNCs9O4t07qaoqwpLB15GwLfEX Bx9dW26zc4O+hi6754trxcfghvjbo98765drt/LYIEg0KSQPWyJEK1g31gacbxN7Ab006xeHh7rv7HtXF6zH3WId Uhq9rtdUag6kYnv6qvjG7sbCyHGYu5vZB7GytnNuVNbZuI+RdFvmHSnErV9HCu9xZBq6DBb+sESMS4s7nFcsruMo edb+BAc3aww0naeWpogjSt+We7y2N .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqedge01.kix01\(aq state.sls router.users .ft P .fi .UNINDENT .UNINDENT .sp Output example (raw python \- can be reused in other modules): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqnetusers_|\-netusers_example_|\-netusers_example_|\-managed\(aq: { \(aqcomment\(aq: \(aqConfiguration updated!\(aq, \(aqname\(aq: \(aqnetusers_example\(aq, \(aqstart_time\(aq: \(aq10:57:08.678811\(aq, \(aq__id__\(aq: \(aqnetusers_example\(aq, \(aqduration\(aq: 1620.982, \(aq__run_num__\(aq: 0, \(aqchanges\(aq: { \(aqupdated\(aq: { \(aqadmin\(aq: { \(aqlevel\(aq: 15 }, \(aqrestricted\(aq: { \(aqlevel\(aq: 1 }, \(aqmartin\(aq: { \(aqsshkeys\(aq: [ \(aqssh\-dss AAAAB3NzaC1kc3MAAACBAK9dP3KariMlM/JmFW9rTSm5cXs4nR0+o6fTHP9o+bOLXMBTP8R4vwWHh0w JPjQmJYafAqZTnlgi0srGjyifFwPtODppDWLCgLe2M4LXnu3OMqknr54w344zPHP3iFwWxHrBrZKtCjO8LhbWCa+ X528+i87t6r5e4ersdfxgchvjbknlio87t6r5drcfhgjhbknio8976tycv7t86ftyiu87Oz1nKsKuNzm2csoUQlJ trmRfpjsOPNookmOz5wG0YxhwDmKeo6fWK+ATk1OiP+QT39fn4G77j8o+e4WAwxM570s35Of/vV0zoOccj753sXn pvJenvwpM2H6o3a9ALvehAJKWodAgZT7X8+iu786r5drtycghvjbiu78t+wAAAIBURwSPZVElXe+9a43sF6M4ysT 7Xv+6wTsa8q86E3+RYyu8O2ObI2kwNLC3/HTgFniE/YqRG+WJac81/VHWQNP822gns8RVrWKjqBktmQoEm7z5yy0 bkjui78675dytcghvjkoi9y7t867ftcuvhbuu9t78gy/v+zvMmv8KvQgHg\(aq ] } }, \(aqadded\(aq: { \(aqjonathan\(aq: { \(aqpassword\(aq: \(aq\(aq, \(aqsshkeys\(aq: [ \(aqssh\-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDcgxE6HZF/xjFtIt0thEDKPjFJxW9BpZtTVstYbDgGR9zPkHG ZJT/j345jk345jk453jk43545j35nl3kln34n5kl4ghv3/JzWt/0Js5KZp/51KRNCs9O4t07qaoqwpLB15GwLfEX Bx9dW26zc4O+hi6754trxcfghvjbo98765drt/LYIEg0KSQPWyJEK1g31gacbxN7Ab006xeHh7rv7HtXF6zH3WId Uhq9rtdUag6kYnv6qvjG7sbCyHGYu5vZB7GytnNuVNbZuI+RdFvmHSnErV9HCu9xZBq6DBb+sESMS4s7nFcsruMo edb+BAc3aww0naeWpogjSt+We7y2N\(aq ], \(aqlevel\(aq: 15 } }, \(aqremoved\(aq: { } }, \(aqresult\(aq: True } } .ft P .fi .UNINDENT .UNINDENT .sp CLI Output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C edge01.kix01: \-\-\-\-\-\-\-\-\-\- ID: netusers_example Function: netusers.managed Result: True Comment: Configuration updated! Started: 11:03:31.957725 Duration: 1220.435 ms Changes: \-\-\-\-\-\-\-\-\-\- added: \-\-\-\-\-\-\-\-\-\- jonathan: \-\-\-\-\-\-\-\-\-\- level: 15 password: sshkeys: \- ssh\-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDcgxE6HZF/xjFtIt0thEDKPjFJxW9BpZtTVstYbDgG R9zPkHGZJT/j345jk345jk453jk43545j35nl3kln34n5kl4ghv3/JzWt/0Js5KZp/51KRNCs9O4t07qao qwpLB15GwLfEXBx9dW26zc4O+hi6754trxcfghvjbo98765drt/LYIEg0KSQPWyJEK1g31gacbxN7Ab006 xeHh7rv7HtXF6zH3WIdUhq9rtdUag6kYnv6qvjG7sbCyHGYu5vZB7GytnNuVNbZuI+RdFvmHSnErV9HCu9 xZBq6DBb+sESMS4s7nFcsruMoedb+BAc3aww0naeWpogjSt+We7y2N removed: \-\-\-\-\-\-\-\-\-\- updated: \-\-\-\-\-\-\-\-\-\- martin: \-\-\-\-\-\-\-\-\-\- sshkeys: \- ssh\-dss AAAAB3NzaC1kc3MAAACBAK9dP3KariMlM/JmFW9rTSm5cXs4nR0+o6fTHP9o+bOLXMBTP8R4 vwWHh0wJPjQmJYafAqZTnlgi0srGjyifFwPtODppDWLCgLe2M4LXnu3OMqknr54w344zPHP3iFwWxHrBrZ KtCjO8LhbWCa+X528+i87t6r5e4ersdfxgchvjbknlio87t6r5drcfhgjhbknio8976tycv7t86ftyiu87 Oz1nKsKuNzm2csoUQlJtrmRfpjsOPNookmOz5wG0YxhwDmKeo6fWK+ATk1OiP+QT39fn4G77j8o+e4WAwx M570s35Of/vV0zoOccj753sXnpvJenvwpM2H6o3a9ALvehAJKWodAgZT7X8+iu786r5drtycghvjbiu78t +wAAAIBURwSPZVElXe+9a43sF6M4ysT7Xv+6wTsa8q86E3+RYyu8O2ObI2kwNLC3/HTgFniE/YqRG+WJac 81/VHWQNP822gns8RVrWKjqBktmQoEm7z5yy0bkjui78675dytcghvjkoi9y7t867ftcuvhbuu9t78gy/v +zvMmv8KvQgHg admin: \-\-\-\-\-\-\-\-\-\- level: 15 restricted: \-\-\-\-\-\-\-\-\-\- level: 1 Summary for edge01.kix01 \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 1 (changed=1) Failed: 0 \-\-\-\-\-\-\-\-\-\-\-\- Total states run: 1 Total run time: 1.220 s .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.network .SS Configuration of network interfaces .sp The network module is used to create and manage network settings, interfaces can be set as either managed or ignored. By default all interfaces are ignored unless specified. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 RedHat\-based systems (RHEL, CentOS, Scientific, etc.) have been supported since version 2014.1.0. .sp Debian\-based systems (Debian, Ubuntu, etc.) have been supported since version 2017.7.0. The following options are not supported: ipaddr_start, and ipaddr_end. .sp Other platforms are not yet supported. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 On Debian\-based systems, networking configuration can be specified in \fI/etc/network/interfaces\fP or via included files such as (by default) \fI/etc/network/interfaces.d/*\fP\&. This can be problematic for configuration management. It is recommended to use either \fIfile.managed\fP \fIor\fP \fInetwork.managed\fP\&. .sp If using \fBnetwork.managed\fP, it can be useful to ensure \fBinterfaces.d/\fP is empty. This can be done using the following state .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/network/interfaces.d: file.directory: \- clean: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Configuring Global Network Settings .sp Use the \fI\%network.system\fP state to set global network settings: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C system: network.system: \- enabled: True \- hostname: server1.example.com \- gateway: 192.168.0.1 \- gatewaydev: eth0 \- nozeroconf: True \- nisdomain: example.com \- require_reboot: True \- apply_hostname: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The use of \fBapply_hostname\fP above will apply changes to the hostname immediately. .UNINDENT .UNINDENT .sp Changed in version 2015.5.0: \fBapply_hostname\fP added .SS retain_settings .sp New in version 2016.11.0. .sp Use \fIretain_settings\fP to retain current network settings that are not otherwise specified in the state. Particularly useful if only setting the hostname. Default behavior is to delete unspecified network settings. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C system: network.system: \- hostname: server2.example.com \- apply_hostname: True \- retain_settings: True .ft P .fi .UNINDENT .UNINDENT .SS Configuring Network Routes .sp Use the \fI\%network.routes\fP state to set network routes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C routes: network.routes: \- name: eth0 \- routes: \- name: secure_network ipaddr: 10.2.0.0 netmask: 255.255.255.0 gateway: 10.1.0.3 \- name: HQ_network ipaddr: 10.100.0.0 netmask: 255.255.0.0 gateway: 10.1.0.10 .ft P .fi .UNINDENT .UNINDENT .SS Managing Network Interfaces .sp The \fI\%network.managed\fP state is used to configure network interfaces. Here are several examples: .SS Ethernet Interface .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C eth0: network.managed: \- enabled: True \- type: eth \- proto: static \- ipaddr: 10.1.0.7 \- netmask: 255.255.255.0 \- gateway: 10.1.0.1 \- enable_ipv6: true \- ipv6proto: static \- ipv6addrs: \- 2001:db8:dead:beef::3/64 \- 2001:db8:dead:beef::7/64 \- ipv6gateway: 2001:db8:dead:beef::1 \- ipv6netmask: 64 \- dns: \- 8.8.8.8 \- 8.8.4.4 \- channels: rx: 4 tx: 4 other: 4 combined: 4 .ft P .fi .UNINDENT .UNINDENT .SS Ranged Interfaces (RHEL/CentOS Only) .sp New in version 2015.8.0. .sp Ranged interfaces can be created by including the word \fBrange\fP in the interface name. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 The interface type must be \fBeth\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C eth0\-range0: network.managed: \- type: eth \- ipaddr_start: 192.168.1.1 \- ipaddr_end: 192.168.1.10 \- clonenum_start: 10 \- mtu: 9000 bond0\-range0: network.managed: \- type: eth \- ipaddr_start: 192.168.1.1 \- ipaddr_end: 192.168.1.10 \- clonenum_start: 10 \- mtu: 9000 eth1.0\-range0: network.managed: \- type: eth \- ipaddr_start: 192.168.1.1 \- ipaddr_end: 192.168.1.10 \- clonenum_start: 10 \- vlan: True \- mtu: 9000 bond0.1\-range0: network.managed: \- type: eth \- ipaddr_start: 192.168.1.1 \- ipaddr_end: 192.168.1.10 \- clonenum_start: 10 \- vlan: True \- mtu: 9000 .ft P .fi .UNINDENT .UNINDENT .SS Bond Interfaces .sp To configure a bond, you must do the following: .INDENT 0.0 .IP \(bu 2 Configure the bond slaves with a \fBtype\fP of \fBslave\fP, and a \fBmaster\fP option set to the name of the bond interface. .IP \(bu 2 Configure the bond interface with a \fBtype\fP of \fBbond\fP, and a \fBslaves\fP option defining the bond slaves for the bond interface. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C eth2: network.managed: \- enabled: True \- type: slave \- master: bond0 eth3: network.managed: \- enabled: True \- type: slave \- master: bond0 bond0: network.managed: \- type: bond \- ipaddr: 10.1.0.1 \- netmask: 255.255.255.0 \- mode: gre \- proto: static \- dns: \- 8.8.8.8 \- 8.8.4.4 \- enabled: False \- slaves: eth2 eth3 \- require: \- network: eth2 \- network: eth3 \- miimon: 100 \- arp_interval: 250 \- downdelay: 200 \- lacp_rate: fast \- max_bonds: 1 \- updelay: 0 \- use_carrier: on \- hashing\-algorithm: layer2 \- mtu: 9000 \- autoneg: on \- speed: 1000 \- duplex: full \- rx: on \- tx: off \- sg: on \- tso: off \- ufo: off \- gso: off \- gro: off \- lro: off .ft P .fi .UNINDENT .UNINDENT .SS VLANs .sp Set \fBtype\fP to \fBvlan\fP to configure a VLANs. These VLANs are configured on the bond interface defined above. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bond0.2: network.managed: \- type: vlan \- ipaddr: 10.1.0.2 \- use: \- network: bond0 \- require: \- network: bond0 bond0.3: network.managed: \- type: vlan \- ipaddr: 10.1.0.3 \- use: \- network: bond0 \- require: \- network: bond0 bond0.10: network.managed: \- type: vlan \- ipaddr: 10.1.0.4 \- use: \- network: bond0 \- require: \- network: bond0 bond0.12: network.managed: \- type: vlan \- ipaddr: 10.1.0.5 \- use: \- network: bond0 \- require: \- network: bond0 .ft P .fi .UNINDENT .UNINDENT .SS Bridge Interfaces .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C eth4: network.managed: \- enabled: True \- type: eth \- proto: dhcp \- bridge: br0 br0: network.managed: \- enabled: True \- type: bridge \- proto: dhcp \- bridge: br0 \- delay: 0 \- ports: eth4 \- bypassfirewall: True \- use: \- network: eth4 \- require: \- network: eth4 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When managing bridged interfaces on a Debian/Ubuntu based system, the \fBports\fP argument is required. RedHat\-based systems will ignore the argument. .UNINDENT .UNINDENT .SS Network Teaming (RHEL/CentOS 7 and later) .sp New in version 3002. .INDENT 0.0 .IP \(bu 2 Configure the members of the team interface with a \fBtype\fP of \fBteamport\fP, and a \fBteam_master\fP option set to the name of the bond interface. .INDENT 2.0 .IP \(bu 2 \fBmaster\fP also works, but will be ignored if both \fBteam_master\fP and \fBmaster\fP are present. .IP \(bu 2 If applicable, include a \fBteam_port_config\fP option. This should be formatted as a dictionary. Keep in mind that due to a quirk of PyYAML, dictionaries nested under a list item must be double\-indented (see example below for interface \fBeth5\fP). .UNINDENT .IP \(bu 2 Configure the team interface with a \fBtype\fP of \fBteam\fP\&. The team configuration should be passed via the \fBteam_config\fP option. As with \fBteam_port_config\fP, the dictionary should be double\-indented. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C eth5: network.managed: \- type: teamport \- team_master: team0 \- team_port_config: prio: 100 eth6: network.managed: \- type: teamport \- team_master: team0 team0: network.managed: \- type: team \- ipaddr: 172.24.90.42 \- netmask: 255.255.255.128 \- enable_ipv6: True \- ipv6addr: \(aqfee1:dead:beef:af43::\(aq \- team_config: runner: hwaddr_policy: by_active name: activebackup link_watch: name: ethtool .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 While \fBteamd\fP must be installed to manage a team interface, it is not required to configure a separate \fI\%pkg.installed\fP state for it, as it will be silently installed if needed. .UNINDENT .UNINDENT .SS Configuring the Loopback Interface .sp Use \fI\%network.managed\fP with a \fBtype\fP of \fBeth\fP and a \fBproto\fP of \fBloopback\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lo: network.managed: \- name: lo \- type: eth \- proto: loopback \- onboot: yes \- userctl: no \- ipv6_autoconf: no \- enable_ipv6: true .ft P .fi .UNINDENT .UNINDENT .SS Other Useful Options .SS noifupdown .sp The \fBnoifupdown\fP option, if set to \fBTrue\fP, will keep Salt from restart the interface if changes are made, requiring them to be restarted manually. Here are a couple examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C eth7: network.managed: \- enabled: True \- type: eth # Automatic IP/DNS \- proto: dhcp \- noifupdown: True eth8: network.managed: \- type: eth \- noifupdown: True # IPv4 \- proto: static \- ipaddr: 192.168.4.9 \- netmask: 255.255.255.0 \- gateway: 192.168.4.1 \- enable_ipv6: True # IPv6 \- ipv6proto: static \- ipv6addr: 2001:db8:dead:c0::3 \- ipv6netmask: 64 \- ipv6gateway: 2001:db8:dead:c0::1 # override shared; makes those options v4\-only \- ipv6ttl: 15 # Shared \- mtu: 1480 \- ttl: 18 \- dns: \- 8.8.8.8 \- 8.8.4.4 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.network.managed(name, enabled=True, **kwargs) Ensure that the named interface is configured properly. .INDENT 7.0 .TP .B name The name of the interface to manage .TP .B type eth Type of interface and configuration .sp Changed in version 3002. .TP .B enabled Designates the state of this interface. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.network.routes(name, **kwargs) Manage network interface static routes. .INDENT 7.0 .TP .B name Interface name to apply the route to. .TP .B kwargs Named routes .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.network.system(name, **kwargs) Ensure that global network settings are configured properly. .INDENT 7.0 .TP .B name Custom name to represent this configuration change. .TP .B kwargs The global parameters for the system. .UNINDENT .UNINDENT .SS salt.states.neutron_network .SS Management of OpenStack Neutron Networks .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.neutronng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create network: neutron_network.present: \- name: network1 delete network: neutron_network.absent: \- name: network1 create network with optional params: neutron_network.present: \- name: network1 \- vlan: 200 \- shared: False \- external: False \- project: project1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.neutron_network.absent(name, auth=None, **kwargs) Ensure a network does not exists .INDENT 7.0 .TP .B name Name of the network .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.neutron_network.present(name, auth=None, **kwargs) Ensure a network exists and is up\-to\-date .INDENT 7.0 .TP .B name Name of the network .TP .B provider A dict of network provider options. .TP .B shared Set the network as shared. .TP .B external Whether this network is externally accessible. .TP .B admin_state_up Set the network administrative state to up. .TP .B vlan Vlan ID. Alias for provider .INDENT 7.0 .IP \(bu 2 physical_network: provider .IP \(bu 2 network_type: vlan .IP \(bu 2 segmentation_id: (vlan id) .UNINDENT .UNINDENT .UNINDENT .SS salt.states.neutron_secgroup .SS Management of OpenStack Neutron Security Groups .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.neutronng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create security group; neutron_secgroup.present: \- name: security_group1 \- description: \(dqVery Secure Security Group\(dq delete security group: neutron_secgroup.absent: \- name_or_id: security_group1 \- project_name: Project1 create security group with optional params: neutron_secgroup.present: \- name: security_group1 \- description: \(dqVery Secure Security Group\(dq \- project_id: 1dcac318a83b4610b7a7f7ba01465548 create security group with optional params: neutron_secgroup.present: \- name: security_group1 \- description: \(dqVery Secure Security Group\(dq \- project_name: Project1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.neutron_secgroup.absent(name, auth=None, **kwargs) Ensure a security group does not exist .INDENT 7.0 .TP .B name Name of the security group .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.neutron_secgroup.present(name, auth=None, **kwargs) Ensure a security group exists. .sp You can supply either project_name or project_id. .sp Creating a default security group will not show up as a change; it gets created through the lookup process. .INDENT 7.0 .TP .B name Name of the security group .TP .B description Description of the security group .TP .B project_name Name of Project .TP .B project_id ID of Project .UNINDENT .UNINDENT .SS salt.states.neutron_secgroup_rule .SS Management of OpenStack Neutron Security Group Rules .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.neutronng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create security group rule: neutron_secgroup_rule.present: \- name: security_group1 \- project_name: Project1 \- protocol: icmp delete security group: neutron_secgroup_rule.absent: \- name_or_id: security_group1 create security group with optional params: neutron_secgroup_rule.present: \- name: security_group1 \- description: \(dqVery Secure Security Group\(dq \- project_id: 1dcac318a83b4610b7a7f7ba01465548 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.neutron_secgroup_rule.absent(name, auth=None, **kwargs) Ensure a security group rule does not exist .INDENT 7.0 .TP .B name name or id of the security group rule to delete .TP .B rule_id uuid of the rule to delete .TP .B project_id id of project to delete rule from .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.neutron_secgroup_rule.present(name, auth=None, **kwargs) Ensure a security group rule exists .INDENT 7.0 .TP .B defaults: port_range_min=None, port_range_max=None, protocol=None, remote_ip_prefix=None, remote_group_id=None, direction=\(aqingress\(aq, ethertype=\(aqIPv4\(aq, project_id=None .TP .B name Name of the security group to associate with this rule .TP .B project_name Name of the project associated with the security group .TP .B protocol The protocol that is matched by the security group rule. Valid values are None, tcp, udp, and icmp. .UNINDENT .UNINDENT .SS salt.states.neutron_subnet .SS Management of OpenStack Neutron Subnets .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends shade .TP .B configuration see \fI\%salt.modules.neutronng\fP for setup instructions .UNINDENT .sp Example States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create subnet: neutron_subnet.present: \- name: subnet1 \- network_name_or_id: network1 \- cidr: 192.168.199.0/24 delete subnet: neutron_subnet.absent: \- name: subnet2 create subnet with optional params: neutron_subnet.present: \- name: subnet1 \- network_name_or_id: network1 \- enable_dhcp: True \- cidr: 192.168.199.0/24 \- allocation_pools: \- start: 192.168.199.5 end: 192.168.199.250 \- host_routes: \- destination: 192.168..0.0/24 nexthop: 192.168.0.1 \- gateway_ip: 192.168.199.1 \- dns_nameservers: \- 8.8.8.8 \- 8.8.8.7 create ipv6 subnet: neutron_subnet.present: \- name: v6subnet1 \- network_name_or_id: network1 \- ip_version: 6 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.neutron_subnet.absent(name, auth=None) Ensure a subnet does not exists .INDENT 7.0 .TP .B name Name of the subnet .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.neutron_subnet.present(name, auth=None, **kwargs) Ensure a subnet exists and is up\-to\-date .INDENT 7.0 .TP .B name Name of the subnet .TP .B network_name_or_id The unique name or ID of the attached network. If a non\-unique name is supplied, an exception is raised. .TP .B allocation_pools A list of dictionaries of the start and end addresses for the allocation pools .TP .B gateway_ip The gateway IP address. .TP .B dns_nameservers A list of DNS name servers for the subnet. .TP .B host_routes A list of host route dictionaries for the subnet. .TP .B ipv6_ra_mode IPv6 Router Advertisement mode. Valid values are: ‘dhcpv6\-stateful’, ‘dhcpv6\-stateless’, or ‘slaac’. .TP .B ipv6_address_mode IPv6 address mode. Valid values are: ‘dhcpv6\-stateful’, ‘dhcpv6\-stateless’, or ‘slaac’. .UNINDENT .UNINDENT .SS salt.states.nexus .sp This state downloads artifacts from Nexus 3.x. .sp New in version 2018.3.0. .INDENT 0.0 .TP .B salt.states.nexus.downloaded(name, artifact, target_dir=\(aq/tmp\(aq, target_file=None) Ensures that the artifact from nexus exists at given location. If it doesn\(aqt exist, then it will be downloaded. If it already exists then the checksum of existing file is checked against checksum in nexus. If it is different then the step will fail. .INDENT 7.0 .TP .B artifact Details of the artifact to be downloaded from nexus. Various options are: .INDENT 7.0 .IP \(bu 2 nexus_url: URL of the nexus instance .IP \(bu 2 repository: Repository in nexus .IP \(bu 2 artifact_id: Artifact ID .IP \(bu 2 group_id: Group ID .IP \(bu 2 packaging: Packaging .IP \(bu 2 classifier: Classifier .IP \(bu 2 .INDENT 2.0 .TP .B version: Version One of the following: \- Version to download \- \fBlatest\fP \- Download the latest release of this artifact \- \fBlatest_snapshot\fP \- Download the latest snapshot for this artifact .UNINDENT .IP \(bu 2 username: nexus username .IP \(bu 2 password: nexus password .UNINDENT .TP .B target_dir Directory where the artifact should be downloaded. By default it is downloaded to /tmp directory. .TP .B target_file Target file to download artifact to. By default file name is resolved by nexus. .UNINDENT .sp An example to download an artifact to a specific file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C jboss_module_downloaded: nexus.downloaded: \- artifact: nexus_url: http://nexus.intranet.example.com/repository repository: \(aqlibs\-release\-local\(aq artifact_id: \(aqmodule\(aq group_id: \(aqcom.company.module\(aq packaging: \(aqjar\(aq classifier: \(aqsources\(aq version: \(aq1.0\(aq \- target_file: /opt/jboss7/modules/com/company/lib/module.jar .ft P .fi .UNINDENT .UNINDENT .sp Download artifact to the folder (automatically resolves file name): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C maven_artifact_downloaded: nexus.downloaded: \- artifact: nexus_url: http://nexus.intranet.example.com/repository repository: \(aqmaven\-releases\(aq artifact_id: \(aqmodule\(aq group_id: \(aqcom.company.module\(aq packaging: \(aqzip\(aq classifier: \(aqdist\(aq version: \(aq1.0\(aq \- target_dir: /opt/maven/modules/com/company/release .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.nfs_export .SS Management of NFS exports .sp New in version 2018.3.0. .sp To ensure an NFS export exists: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C add_simple_export: nfs_export.present: \- name: \(aq/srv/nfs\(aq \- hosts: \(aq10.0.2.0/24\(aq \- options: \- \(aqrw\(aq .ft P .fi .UNINDENT .UNINDENT .sp This creates the following in /etc/exports: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /srv/nfs 10.0.2.0/24(rw) .ft P .fi .UNINDENT .UNINDENT .sp For more complex exports with multiple groups of hosts, use \(aqclients\(aq: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C add_complex_export: nfs_export.present: \- name: \(aq/srv/nfs\(aq \- clients: # First export, same as simple one above \- hosts: \(aq10.0.2.0/24\(aq options: \- \(aqrw\(aq # Second export \- hosts: \(aq*.example.com\(aq options: \- \(aqro\(aq \- \(aqsubtree_check\(aq .ft P .fi .UNINDENT .UNINDENT .sp This creates the following in /etc/exports: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /srv/nfs 10.0.2.0/24(rw) 192.168.0.0/24,172.19.0.0/16(ro,subtree_check) .ft P .fi .UNINDENT .UNINDENT .sp Any export of the given path will be modified to match the one specified. .sp To ensure an NFS export is absent: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C delete_export: nfs_export.absent: \- name: \(aq/srv/nfs\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.nfs_export.absent(name, exports=\(aq/etc/exports\(aq) Ensure that the named path is not exported .INDENT 7.0 .TP .B name The export path to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.nfs_export.present(name, clients=None, hosts=None, options=None, exports=\(aq/etc/exports\(aq) Ensure that the named export is present with the given options .INDENT 7.0 .TP .B name The export path to configure .TP .B clients A list of hosts and the options applied to them. This option may not be used in combination with the \(aqhosts\(aq or \(aqoptions\(aq shortcuts. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- clients: # First export \- hosts: \(aq10.0.2.0/24\(aq options: \- \(aqrw\(aq # Second export \- hosts: \(aq*.example.com\(aq options: \- \(aqro\(aq \- \(aqsubtree_check\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B hosts A string matching a number of hosts, for example: .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C hosts: \(aq10.0.2.123\(aq hosts: \(aq10.0.2.0/24\(aq hosts: \(aqminion1.example.com\(aq hosts: \(aq*.example.com\(aq hosts: \(aq*\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B options A list of NFS options, for example: .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C options: \- \(aqrw\(aq \- \(aqsubtree_check\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.nftables .SS Management of nftables .sp This is an nftables\-specific module designed to manage Linux firewalls. It is expected that this state module, and other system\-specific firewall states, may at some point be deprecated in favor of a more generic \fIfirewall\fP state. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: nftables.append: \- table: filter \- chain: input \- jump: accept \- match: state \- connstate: new \- dport: 80 \- proto: tcp \- sport: 1025:65535 \- save: True httpd: nftables.append: \- table: filter \- family: ipv6 \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- proto: tcp \- sport: 1025:65535 \- save: True httpd: nftables.insert: \- position: 1 \- table: filter \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- proto: tcp \- sport: 1025:65535 \- save: True httpd: nftables.insert: \- position: 1 \- table: filter \- family: ipv6 \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- proto: tcp \- sport: 1025:65535 \- save: True httpd: nftables.delete: \- table: filter \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- proto: tcp \- sport: 1025:65535 \- save: True httpd: nftables.delete: \- position: 1 \- table: filter \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- proto: tcp \- sport: 1025:65535 \- save: True httpd: nftables.delete: \- table: filter \- family: ipv6 \- chain: INPUT \- jump: ACCEPT \- match: state \- connstate: NEW \- dport: 80 \- proto: tcp \- sport: 1025:65535 \- save: True output: nftables.chain_present: \- family: ip \- table: filter output: nftables.chain_absent: \- family: ip \- table: filter .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.nftables.append(name, family=\(aqipv4\(aq, **kwargs) New in version 0.17.0. .sp Append a rule to a chain .INDENT 7.0 .TP .B name A user\-defined name to call this rule by in another part of a state or formula. This should not be an actual rule. .TP .B family Network family, ipv4 or ipv6. .UNINDENT .sp All other arguments are passed in with the same name as the long option that would normally be used for nftables, with one exception: \fI\-\-state\fP is specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with \fIctstate\fP). .UNINDENT .INDENT 0.0 .TP .B salt.states.nftables.chain_absent(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq) New in version 2014.7.0. .sp Verify the chain is absent. .INDENT 7.0 .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.nftables.chain_present(name, table=\(aqfilter\(aq, table_type=None, hook=None, priority=None, family=\(aqipv4\(aq) New in version 2014.7.0. .sp Changed in version 3002. .sp Verify a chain exists in a table. .INDENT 7.0 .TP .B name A user\-defined chain name. .TP .B table The table to own the chain. .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.nftables.delete(name, family=\(aqipv4\(aq, **kwargs) New in version 2014.7.0. .sp Delete a rule to a chain .INDENT 7.0 .TP .B name A user\-defined name to call this rule by in another part of a state or formula. This should not be an actual rule. .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .sp All other arguments are passed in with the same name as the long option that would normally be used for nftables, with one exception: \fI\-\-state\fP is specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with \fIctstate\fP). .UNINDENT .INDENT 0.0 .TP .B salt.states.nftables.flush(name, family=\(aqipv4\(aq, ignore_absence=False, **kwargs) New in version 2014.7.0. .sp Changed in version 3002. .sp Flush current nftables state .INDENT 7.0 .TP .B family Networking family, either ipv4 or ipv6 .TP .B ignore_absence If set to True, attempts to flush a non\-existent table will not result in a failed state. .sp New in version 3002. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.nftables.insert(name, family=\(aqipv4\(aq, **kwargs) New in version 2014.7.0. .sp Insert a rule into a chain .INDENT 7.0 .TP .B name A user\-defined name to call this rule by in another part of a state or formula. This should not be an actual rule. .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .sp All other arguments are passed in with the same name as the long option that would normally be used for nftables, with one exception: \fI\-\-state\fP is specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with \fIctstate\fP). .UNINDENT .INDENT 0.0 .TP .B salt.states.nftables.set_policy(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq, **kwargs) New in version 3002. .sp Sets the default policy for nftables chains .INDENT 7.0 .TP .B table The table that owns the chain that should be modified .TP .B family Networking family, either ipv4 or ipv6 .TP .B policy The requested table policy (accept or drop) .TP .B save Boolean to save the in\-memory nftables settings to a file. .TP .B save_filename The filename to save the nftables settings (default: /etc/nftables or /etc/nftables/salt\-all\-in\-one.nft if the former is a directory) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.nftables.table_absent(name, family=\(aqipv4\(aq, **kwargs) New in version 3002. .sp Ensure an nftables table is absent .INDENT 7.0 .TP .B name Name of the table to ensure is absent .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.nftables.table_present(name, family=\(aqipv4\(aq, **kwargs) New in version 3002. .sp Ensure an nftables table is present .INDENT 7.0 .TP .B name A user\-defined table name. .TP .B family Networking family, either ipv4 or ipv6 .UNINDENT .UNINDENT .SS salt.states.npm .SS Installation of NPM Packages .sp These states manage the installed packages for node.js using the Node Package Manager (npm). Note that npm must be installed for these states to be available, so npm states should include a requisite to a pkg.installed state for the package which provides npm (simply \fBnpm\fP in most cases). Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C npm: pkg.installed yaml: npm.installed: \- require: \- pkg: npm .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.npm.bootstrap(name, user=None, silent=True) Bootstraps a node.js application. .sp Will execute \(aqnpm install \-\-json\(aq on the specified directory. .INDENT 7.0 .TP .B user The user to run NPM with .sp New in version 0.17.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.npm.cache_cleaned(name=None, user=None, force=False) Ensure that the given package is not cached. .sp If no package is specified, this ensures the entire cache is cleared. .INDENT 7.0 .TP .B name The name of the package to remove from the cache, or None for all packages .TP .B user The user to run NPM with .TP .B force Force cleaning of cache. Required for npm@5 and greater .sp New in version 2016.11.6. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.npm.installed(name, pkgs=None, dir=None, user=None, force_reinstall=False, registry=None, env=None) Verify that the given package is installed and is at the correct version (if specified). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C coffee\-script: npm.installed: \- user: someuser coffee\-script@1.0.1: npm.installed: [] .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The package to install .sp Changed in version 2014.7.2: This parameter is no longer lowercased by salt so that case\-sensitive NPM package names will work. .TP .B pkgs A list of packages to install with a single npm invocation; specifying this argument will ignore the \fBname\fP argument .sp New in version 2014.7.0. .TP .B dir The target directory in which to install the package, or None for global installation .TP .B user The user to run NPM with .sp New in version 0.17.0. .TP .B registry The NPM registry from which to install the package .sp New in version 2014.7.0. .TP .B env A list of environment variables to be set prior to execution. The format is the same as the \fI\%cmd.run\fP\&. state function. .sp New in version 2014.7.0. .TP .B force_reinstall Install the package even if it is already installed .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.npm.removed(name, dir=None, user=None) Verify that the given package is not installed. .INDENT 7.0 .TP .B dir The target directory in which to install the package, or None for global installation .TP .B user The user to run NPM with .sp New in version 0.17.0. .UNINDENT .UNINDENT .SS salt.states.ntp .SS Management of NTP servers .sp New in version 2014.1.0. .sp This state is used to manage NTP servers. Currently only Windows is supported. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C win_ntp: ntp.managed: \- servers: \- pool.ntp.org \- us.pool.ntp.org .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ntp.managed(name, servers=None) Manage NTP servers .INDENT 7.0 .TP .B servers A list of NTP servers .UNINDENT .UNINDENT .SS salt.states.nxos .sp State module for Cisco NX\-OS Switch Proxy and Native minions .sp New in version 2016.11.0. .sp For documentation on setting up the nxos proxy minion look in the documentation for \fI\%salt.proxy.nxos\fP\&. .INDENT 0.0 .TP .B salt.states.nxos.config_absent(name) Ensure a specific configuration line does not exist in the running config .INDENT 7.0 .TP .B name config line to remove .UNINDENT .sp Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C add snmp group: nxos.config_absent: \- names: \- snmp\-server community randoSNMPstringHERE group network\-operator \- snmp\-server community AnotherRandomSNMPSTring group network\-admin .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For certain cases extra lines could be removed based on dependencies. In this example, included after the example for config_present, the ACLs would be removed because they depend on the existence of the group. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.nxos.config_present(name) Ensure a specific configuration line exists in the running config .INDENT 7.0 .TP .B name config line to set .UNINDENT .sp Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C add snmp group: nxos.config_present: \- names: \- snmp\-server community randoSNMPstringHERE group network\-operator \- snmp\-server community AnotherRandomSNMPSTring group network\-admin add snmp acl: nxos.config_present: \- names: \- snmp\-server community randoSNMPstringHERE use\-acl snmp\-acl\-ro \- snmp\-server community AnotherRandomSNMPSTring use\-acl snmp\-acl\-rw .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.nxos.replace(name, repl, full_match=False) Replace all instances of a string or full line in the running config .INDENT 7.0 .TP .B name String to replace .TP .B repl The replacement text .TP .B full_match Whether \fIname\fP will match the full line or only a subset of the line. Defaults to False. When False, .* is added around \fIname\fP for matching in the \fIshow run\fP config. .UNINDENT .sp Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C replace snmp string: nxos.replace: \- name: randoSNMPstringHERE \- repl: NEWrandoSNMPstringHERE replace full snmp string: nxos.replace: \- name: ^snmp\-server community randoSNMPstringHERE group network\-operator$ \- repl: snmp\-server community NEWrandoSNMPstringHERE group network\-operator \- full_match: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The first example will replace the SNMP string on both the group and the ACL, so you will not lose the ACL setting. Because the second is an exact match of the line, when the group is removed, the ACL is removed, but not readded, because it was not matched. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.nxos.user_absent(name) Ensure a user is not present .INDENT 7.0 .TP .B name username to remove if it exists .UNINDENT .sp Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C delete: nxos.user_absent: \- name: daniel .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.nxos.user_present(name, password=None, roles=None, encrypted=False, crypt_salt=None, algorithm=\(aqsha256\(aq) Ensure a user is present with the specified groups .INDENT 7.0 .TP .B name Name of user .TP .B password Encrypted or Plain Text password for user .TP .B roles List of roles the user should be assigned. Any roles not in this list will be removed .TP .B encrypted Whether the password is encrypted already or not. Defaults to False .TP .B crypt_salt Salt to use when encrypting the password. Default is None (salt is randomly generated for unhashed passwords) .TP .B algorithm Algorithm to use for hashing password. Defaults to sha256. Accepts md5, blowfish, sha256, sha512 .UNINDENT .sp Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C create: nxos.user_present: \- name: daniel \- roles: \- vdc\-admin set_password: nxos.user_present: \- name: daniel \- password: admin \- roles: \- network\-admin update: nxos.user_present: \- name: daniel \- password: AiN9jaoP \- roles: \- network\-admin \- vdc\-admin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.nxos_upgrade .sp Manage NX\-OS System Image Upgrades. .sp New in version 3001. .INDENT 0.0 .TP .B maturity new .TP .B platform nxos .TP .B codeauthor Michael G Wiebe .UNINDENT .sp For documentation on setting up the nxos proxy minion look in the documentation for \fI\%salt.proxy.nxos\fP\&. .INDENT 0.0 .TP .B salt.states.nxos_upgrade.image_running(name, system_image, kickstart_image=None, issu=True, **kwargs) Ensure the NX\-OS system image is running on the device. .INDENT 7.0 .TP .B name Name of the salt state task .TP .B system_image Name of the system image file on bootflash: .TP .B kickstart_image Name of the kickstart image file on bootflash: This is not needed if the system_image is a combined system and kickstart image Default: None .TP .B issu Ensure the correct system is running on the device using an in service software upgrade, or force a disruptive upgrade by setting the option to False. Default: False .TP .B timeout Timeout in seconds for long running \(aqinstall all\(aq upgrade command. Default: 900 .UNINDENT .sp Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C upgrade_software_image_n9k: nxos.image_running: \- name: Ensure nxos.7.0.3.I7.5a.bin is running \- system_image: nxos.7.0.3.I7.5a.bin \- issu: True upgrade_software_image_n7k: nxos.image_running: \- name: Ensure n7000\-s2\-kickstart.8.0.1.bin is running \- kickstart_image: n7000\-s2\-kickstart.8.0.1.bin \- system_image: n7000\-s2\-dk9.8.0.1.bin \- issu: False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.openstack_config .sp Manage OpenStack configuration file settings. .INDENT 0.0 .TP .B maintainer Jeffrey C. Ollie <\fI\%jeff@ocjtech.us\fP> .TP .B maturity new .TP .B depends .TP .B platform linux .UNINDENT .INDENT 0.0 .TP .B salt.states.openstack_config.absent(name, filename, section, parameter=None) Ensure a value is not set in an OpenStack configuration file. .INDENT 7.0 .TP .B filename The full path to the configuration file .TP .B section The section in which the parameter will be set .TP .B parameter (optional) The parameter to change. If the parameter is not supplied, the name will be used as the parameter. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.openstack_config.present(name, filename, section, value, parameter=None) Ensure a value is set in an OpenStack configuration file. .INDENT 7.0 .TP .B filename The full path to the configuration file .TP .B section The section in which the parameter will be set .TP .B parameter (optional) The parameter to change. If the parameter is not supplied, the name will be used as the parameter. .TP .B value The value to set .UNINDENT .UNINDENT .SS salt.states.openvswitch_bridge .sp Management of Open vSwitch bridges. .INDENT 0.0 .TP .B salt.states.openvswitch_bridge.absent(name) Ensures that the named bridge does not exist, eventually deletes it. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the bridge. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.openvswitch_bridge.present(name, parent=None, vlan=None) Ensures that the named bridge exists, eventually creates it. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- string name of the bridge .IP \(bu 2 \fBparent\fP \-\- string name of the parent bridge (if the bridge shall be created as a fake bridge). If specified, vlan must also be specified. .IP \(bu 2 \fBversionadded:\fP (\fI\&..\fP) \-\- 3006.0: .IP \(bu 2 \fBvlan\fP \-\- int VLAN ID of the bridge (if the bridge shall be created as a fake bridge). If specified, parent must also be specified. .IP \(bu 2 \fBversionadded:\fP \-\- 3006.0: .UNINDENT .UNINDENT .UNINDENT .SS salt.states.openvswitch_db module .sp Management of Open vSwitch database records. .sp New in version 3006.0. .INDENT 0.0 .TP .B salt.states.openvswitch_db.managed(name, table, data, record=None) Ensures that the specified columns of the named record have the specified values. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- string name of the record .IP \(bu 2 \fBtable\fP \-\- string name of the table to which the record belongs. .IP \(bu 2 \fBdata\fP \-\- dict dictionary containing a mapping from column names to the desired values. Columns that exist, but are not specified in this dictionary are not touched. .IP \(bu 2 \fBrecord\fP \-\- string name of the record (optional). Replaces name if specified. .UNINDENT .UNINDENT .UNINDENT .SS salt.states.openvswitch_port .sp Management of Open vSwitch ports. .INDENT 0.0 .TP .B salt.states.openvswitch_port.absent(name, bridge=None) Ensures that the named port exists on bridge, eventually deletes it. If bridge is not set, port is removed from whatever bridge contains it. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the port. .IP \(bu 2 \fBbridge\fP \-\- The name of the bridge. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.openvswitch_port.present(name, bridge, tunnel_type=None, id=None, remote=None, dst_port=None, internal=False) Ensures that the named port exists on bridge, eventually creates it. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the port. .IP \(bu 2 \fBbridge\fP \-\- The name of the bridge. .IP \(bu 2 \fBtunnel_type\fP \-\- Optional type of interface to create, currently supports: vlan, vxlan and gre. .IP \(bu 2 \fBid\fP \-\- Optional tunnel\(aqs key. .IP \(bu 2 \fBremote\fP \-\- Remote endpoint\(aqs IP address. .IP \(bu 2 \fBdst_port\fP \-\- Port to use when creating tunnelport in the switch. .IP \(bu 2 \fBinternal\fP \-\- Create an internal port if one does not exist .UNINDENT .UNINDENT .UNINDENT .SS salt.states.opsgenie .SS Create/Close an alert in OpsGenie .sp New in version 2018.3.0. .sp This state is useful for creating or closing alerts in OpsGenie during state runs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C used_space: disk.status: \- name: / \- maximum: 79% \- minimum: 20% opsgenie_create_action_sender: opsgenie.create_alert: \- api_key: XXXXXXXX\-XXXX\-XXXX\-XXXX\-XXXXXXXXXXXX \- reason: \(aqDisk capacity is out of designated range.\(aq \- name: disk.status \- onfail: \- disk: used_space opsgenie_close_action_sender: opsgenie.close_alert: \- api_key: XXXXXXXX\-XXXX\-XXXX\-XXXX\-XXXXXXXXXXXX \- name: disk.status \- require: \- disk: used_space .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.opsgenie.close_alert(name=None, api_key=None, reason=\(aqConditions are met.\(aq, action_type=\(aqClose\(aq) Close an alert in OpsGenie. It\(aqs a wrapper function for create_alert. Example usage with Salt\(aqs requisites and other global state arguments could be found above. .sp Required Parameters: .INDENT 7.0 .TP .B name It will be used as alert\(aqs alias. If you want to use the close functionality you must provide name field for both states like in above case. .UNINDENT .sp Optional Parameters: .INDENT 7.0 .TP .B api_key It\(aqs the API Key you\(aqve copied while adding integration in OpsGenie. .TP .B reason It will be used as alert\(aqs default message in OpsGenie. .TP .B action_type OpsGenie supports the default values Create/Close for action_type. You can customize this field with OpsGenie\(aqs custom actions for other purposes like adding notes or acknowledging alerts. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.opsgenie.create_alert(name=None, api_key=None, reason=None, action_type=\(aqCreate\(aq) Create an alert in OpsGenie. Example usage with Salt\(aqs requisites and other global state arguments could be found above. .sp Required Parameters: .INDENT 7.0 .TP .B api_key It\(aqs the API Key you\(aqve copied while adding integration in OpsGenie. .TP .B reason It will be used as alert\(aqs default message in OpsGenie. .UNINDENT .sp Optional Parameters: .INDENT 7.0 .TP .B name It will be used as alert\(aqs alias. If you want to use the close functionality you must provide name field for both states like in above case. .TP .B action_type OpsGenie supports the default values Create/Close for action_type. You can customize this field with OpsGenie\(aqs custom actions for other purposes like adding notes or acknowledging alerts. .UNINDENT .UNINDENT .SS salt.states.pagerduty .SS Create an Event in PagerDuty .sp New in version 2014.1.0. .sp This state is useful for creating events on the PagerDuty service during state runs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C server\-warning\-message: pagerduty.create_event: \- name: \(aqThis is a server warning message\(aq \- details: \(aqThis is a much more detailed message\(aq \- service_key: 9abcd123456789efabcde362783cdbaf \- profile: my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pagerduty.create_event(name, details, service_key, profile) Create an event on the PagerDuty service .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C server\-warning\-message: pagerduty.create_event: \- name: \(aqThis is a server warning message\(aq \- details: \(aqThis is a much more detailed message\(aq \- service_key: 9abcd123456789efabcde362783cdbaf \- profile: my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B name This is a short description of the event. .TP .B details This can be a more detailed description of the event. .TP .B service_key This key can be found by using pagerduty.list_services. .TP .B profile This refers to the configuration profile to use to connect to the PagerDuty service. .UNINDENT .UNINDENT .SS salt.states.pagerduty_escalation_policy .sp Manage PagerDuty escalation policies. .sp Schedules and users can be referenced by pagerduty ID, or by name, or by email address. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ensure test escalation policy: pagerduty_escalation_policy.present: \- name: bruce test escalation policy \- escalation_rules: \- targets: \- type: schedule id: \(aqbruce test schedule level1\(aq \- type: user id: \(aqBruce Sherrod\(aq escalation_delay_in_minutes: 15 \- targets: \- type: schedule id: \(aqbruce test schedule level2\(aq escalation_delay_in_minutes: 15 \- targets: \- type: user id: \(aqBruce TestUser1\(aq \- type: user id: \(aqBruce TestUser2\(aq \- type: user id: \(aqBruce TestUser3\(aq \- type: user id: \(aqbruce+test4@lyft.com\(aq escalation_delay_in_minutes: 15 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pagerduty_escalation_policy.absent(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None, **kwargs) Ensure that a PagerDuty escalation policy does not exist. Accepts all the arguments that pagerduty_escalation_policy.present accepts; but ignores all arguments except the name. .sp Name can be the escalation policy id or the escalation policy name. .UNINDENT .INDENT 0.0 .TP .B salt.states.pagerduty_escalation_policy.present(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None, **kwargs) Ensure that a pagerduty escalation policy exists. Will create or update as needed. .sp This method accepts as args everything defined in \fI\%https://developer.pagerduty.com/documentation/rest/escalation_policies/create\fP\&. In addition, user and schedule id\(aqs will be translated from name (or email address) into PagerDuty unique ids. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B pagerduty_escalation_policy.present: .INDENT 7.0 .IP \(bu 2 name: bruce test escalation policy .IP \(bu 2 .INDENT 2.0 .TP .B escalation_rules: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B targets: .INDENT 7.0 .IP \(bu 2 type: schedule id: \(aqbruce test schedule level1\(aq .IP \(bu 2 type: user id: \(aqBruce Sherrod\(aq .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp In this example, \(aqBruce Sherrod\(aq will be looked up and replaced with the PagerDuty id (usually a 7 digit all\-caps string, e.g. PX6GQL7) .UNINDENT .SS salt.states.pagerduty_schedule .sp Manage PagerDuty schedules. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ensure test schedule: pagerduty_schedule.present: \- name: \(aqbruce test schedule level1\(aq \- schedule: name: \(aqbruce test schedule level1\(aq time_zone: \(aqPacific Time (US & Canada)\(aq schedule_layers: \- name: \(aqSchedule Layer 1\(aq start: \(aq2015\-01\-01T00:00:00\(aq users: \- user: \(aqid\(aq: \(aqBruce TestUser1\(aq member_order: 1 \- user: \(aqid\(aq: \(aqBruce TestUser2\(aq member_order: 2 \- user: \(aqid\(aq: \(aqbruce+test3@lyft.com\(aq member_order: 3 \- user: \(aqid\(aq: \(aqbruce+test4@lyft.com\(aq member_order: 4 rotation_virtual_start: \(aq2015\-01\-01T00:00:00\(aq priority: 1 rotation_turn_length_seconds: 604800 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pagerduty_schedule.absent(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None, **kwargs) Ensure that a pagerduty schedule does not exist. Name can be pagerduty schedule id or pagerduty schedule name. .UNINDENT .INDENT 0.0 .TP .B salt.states.pagerduty_schedule.present(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None, **kwargs) Ensure that a pagerduty schedule exists. This method accepts as args everything defined in \fI\%https://developer.pagerduty.com/documentation/rest/schedules/create\fP\&. This means that most arguments are in a dict called \(dqschedule.\(dq .sp User id\(aqs can be pagerduty id, or name, or email address. .UNINDENT .SS salt.states.pagerduty_service .sp Manage PagerDuty services .sp Escalation policies can be referenced by pagerduty ID or by namea. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ensure test service pagerduty_service.present: \- name: \(aqmy service\(aq \- escalation_policy_id: \(aqmy escalation policy\(aq \- type: nagios .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pagerduty_service.absent(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None, **kwargs) Ensure a pagerduty service does not exist. Name can be the service name or pagerduty service id. .UNINDENT .INDENT 0.0 .TP .B salt.states.pagerduty_service.present(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None, **kwargs) Ensure pagerduty service exists. This method accepts as arguments everything defined in \fI\%https://developer.pagerduty.com/documentation/rest/services/create\fP .sp Note that many arguments are mutually exclusive, depending on the \(dqtype\(dq argument. .sp Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # create a PagerDuty email service at test\-email@DOMAIN.pagerduty.com ensure generic email service exists: pagerduty_service.present: \- name: my email service \- service: description: \(dqemail service controlled by salt\(dq escalation_policy_id: \(dqmy escalation policy\(dq type: \(dqgeneric_email\(dq service_key: \(dqtest\-email\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # create a pagerduty service using cloudwatch integration ensure my cloudwatch service exists: pagerduty_service.present: \- name: my cloudwatch service \- service: escalation_policy_id: \(dqmy escalation policy\(dq type: aws_cloudwatch description: \(dqmy cloudwatch service controlled by salt\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.pagerduty_user .sp Manage PagerDuty users. .sp Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B ensure bruce test user 1: .INDENT 7.0 .TP .B pagerduty.user_present: .INDENT 7.0 .IP \(bu 2 name: \(aqBruce TestUser1\(aq .IP \(bu 2 email: \fI\%bruce+test1@lyft.com\fP .IP \(bu 2 requester_id: P1GV5NT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pagerduty_user.absent(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None, **kwargs) Ensure pagerduty user does not exist. Name can be pagerduty id, email address, or user name. .UNINDENT .INDENT 0.0 .TP .B salt.states.pagerduty_user.present(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None, **kwargs) Ensure pagerduty user exists. Arguments match those supported by \fI\%https://developer.pagerduty.com/documentation/rest/users/create\fP\&. .UNINDENT .SS salt.states.panos .sp A state module to manage Palo Alto network devices. .INDENT 0.0 .TP .B codeauthor \fBSpencer Ervin <spencer_ervin@hotmail.com>\fP .TP .B maturity new .TP .B depends none .TP .B platform unix .UNINDENT .SS About .sp This state module was designed to handle connections to a Palo Alto based firewall. This module relies on the Palo Alto proxy module to interface with the devices. .sp This state module is designed to give extreme flexibility in the control over XPATH values on the PANOS device. It exposes the core XML API commands and allows state modules to chain complex XPATH commands. .sp Below is an example of how to construct a security rule and move to the top of the policy. This will take a config lock to prevent execution during the operation, then remove the lock. After the XPATH has been deployed, it will commit to the device. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C panos/takelock: panos.add_config_lock panos/service_tcp_22: panos.set_config: \- xpath: /config/devices/entry[@name=\(aqlocalhost.localdomain\(aq]/vsys/entry[@name=\(aqvsys1\(aq]/service \- value: <entry name=\(aqtcp\-22\(aq><protocol><tcp><port>22</port></tcp></protocol></entry> \- commit: False panos/create_rule1: panos.set_config: \- xpath: /config/devices/entry[@name=\(aqlocalhost.localdomain\(aq]/vsys/entry[@name=\(aqvsys1\(aq]/rulebase/security/rules \- value: \(aq <entry name=\(dqrule1\(dq> <from><member>trust</member></from> <to><member>untrust</member></to> <source><member>10.0.0.1</member></source> <destination><member>10.0.1.1</member></destination> <service><member>tcp\-22</member></service> <application><member>any</member></application> <action>allow</action> <disabled>no</disabled> </entry>\(aq \- commit: False panos/moveruletop: panos.move_config: \- xpath: /config/devices/entry[@name=\(aqlocalhost.localdomain\(aq]/vsys/entry[@name=\(aqvsys1\(aq]/rulebase/security/rules/entry[@name=\(aqrule1\(aq] \- where: top \- commit: False panos/removelock: panos.remove_config_lock panos/commit: panos.commit_config .ft P .fi .UNINDENT .UNINDENT .SS Version Specific Configurations .sp Palo Alto devices running different versions will have different supported features and different command structures. In order to account for this, the proxy module can be leveraged to check if the panos device is at a specific revision level. .sp The proxy[\(aqpanos.is_required_version\(aq] method will check if a panos device is currently running a version equal or greater than the passed version. For example, proxy[\(aqpanos.is_required_version\(aq](\(aq7.0.0\(aq) would match both 7.1.0 and 8.0.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if proxy[\(aqpanos.is_required_version\(aq](\(aq8.0.0\(aq) %} panos/deviceconfig/system/motd\-and\-banner: panos.set_config: \- xpath: /config/devices/entry[@name=\(aqlocalhost.localdomain\(aq]/deviceconfig/system/motd\-and\-banner \- value: | <banner\-header>BANNER TEXT</banner\-header> <banner\-header\-color>color2</banner\-header\-color> <banner\-header\-text\-color>color18</banner\-header\-text\-color> <banner\-header\-footer\-match>yes</banner\-header\-footer\-match> \- commit: False {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Palo Alto Proxy Module\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.add_config_lock(name) Prevent other users from changing configuration until the lock is released. .sp name: The name of the module function to execute. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/takelock: panos.add_config_lock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.address_exists(name, addressname=None, vsys=1, ipnetmask=None, iprange=None, fqdn=None, description=None, commit=False) Ensures that an address object exists in the configured state. If it does not exist or is not configured with the specified attributes, it will be adjusted to match the specified values. .sp This module will only process a single address type (ip\-netmask, ip\-range, or fqdn). It will process the specified value if the following order: ip\-netmask, ip\-range, fqdn. For proper execution, only specify a single address type. .sp name: The name of the module function to execute. .sp addressname(str): The name of the address object. The name is case\-sensitive and can have up to 31 characters, which an be letters, numbers, spaces, hyphens, and underscores. The name must be unique on a firewall and, on Panorama, unique within its device group and any ancestor or descendant device groups. .sp vsys(str): The string representation of the VSYS ID. Defaults to VSYS 1. .sp ipnetmask(str): The IPv4 or IPv6 address or IP address range using the format ip_address/mask or ip_address where the mask is the number of significant binary digits used for the network portion of the address. Ideally, for IPv6, you specify only the network portion, not the host portion. .sp iprange(str): A range of addresses using the format ip_address–ip_address where both addresses can be IPv4 or both can be IPv6. .sp fqdn(str): A fully qualified domain name format. The FQDN initially resolves at commit time. Entries are subsequently refreshed when the firewall performs a check every 30 minutes; all changes in the IP address for the entries are picked up at the refresh cycle. .sp description(str): A description for the policy (up to 255 characters). .sp commit(bool): If true the firewall will commit the changes, if false do not commit changes. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/address/h\-10.10.10.10: panos.address_exists: \- addressname: h\-10.10.10.10 \- vsys: 1 \- ipnetmask: 10.10.10.10 \- commit: False panos/address/10.0.0.1\-10.0.0.50: panos.address_exists: \- addressname: r\-10.0.0.1\-10.0.0.50 \- vsys: 1 \- iprange: 10.0.0.1\-10.0.0.50 \- commit: False panos/address/foo.bar.com: panos.address_exists: \- addressname: foo.bar.com \- vsys: 1 \- fqdn: foo.bar.com \- description: My fqdn object \- commit: False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.address_group_exists(name, groupname=None, vsys=1, members=None, description=None, commit=False) Ensures that an address group object exists in the configured state. If it does not exist or is not configured with the specified attributes, it will be adjusted to match the specified values. .sp This module will enforce group membership. If a group exists and contains members this state does not include, those members will be removed and replaced with the specified members in the state. .sp name: The name of the module function to execute. .sp groupname(str): The name of the address group object. The name is case\-sensitive and can have up to 31 characters, which an be letters, numbers, spaces, hyphens, and underscores. The name must be unique on a firewall and, on Panorama, unique within its device group and any ancestor or descendant device groups. .sp vsys(str): The string representation of the VSYS ID. Defaults to VSYS 1. .sp members(str, list): The members of the address group. These must be valid address objects or address groups on the system that already exist prior to the execution of this state. .sp description(str): A description for the policy (up to 255 characters). .sp commit(bool): If true the firewall will commit the changes, if false do not commit changes. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/address\-group/my\-group: panos.address_group_exists: \- groupname: my\-group \- vsys: 1 \- members: \- my\-address\-object \- my\-other\-address\-group \- description: A group that needs to exist \- commit: False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.clone_config(name, xpath=None, newname=None, commit=False) Clone a specific XPATH and set it to a new name. .sp name: The name of the module function to execute. .sp xpath(str): The XPATH of the configuration API tree to clone. .sp newname(str): The new name of the XPATH clone. .sp commit(bool): If true the firewall will commit the changes, if false do not commit changes. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/clonerule: panos.clone_config: \- xpath: /config/devices/entry/vsys/entry[@name=\(aqvsys1\(aq]/rulebase/security/rules&from=/config/devices/ entry/vsys/entry[@name=\(aqvsys1\(aq]/rulebase/security/rules/entry[@name=\(aqrule1\(aq] \- value: rule2 \- commit: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.commit_config(name) Commits the candidate configuration to the running configuration. .sp name: The name of the module function to execute. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/commit: panos.commit_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.delete_config(name, xpath=None, commit=False) Deletes a Palo Alto XPATH to a specific value. .sp Use the xpath parameter to specify the location of the object to be deleted. .sp name: The name of the module function to execute. .sp xpath(str): The XPATH of the configuration API tree to control. .sp commit(bool): If true the firewall will commit the changes, if false do not commit changes. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/deletegroup: panos.delete_config: \- xpath: /config/devices/entry/vsys/entry[@name=\(aqvsys1\(aq]/address\-group/entry[@name=\(aqtest\(aq] \- commit: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.download_software(name, version=None, synch=False, check=False) Ensures that a software version is downloaded. .sp name: The name of the module function to execute. .sp version(str): The software version to check. If this version is not already downloaded, it will attempt to download the file from Palo Alto. .sp synch(bool): If true, after downloading the file it will be synched to its peer. .sp check(bool): If true, the PANOS device will first attempt to pull the most recent software inventory list from Palo Alto. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/version8.0.0: panos.download_software: \- version: 8.0.0 \- synch: False \- check: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.edit_config(name, xpath=None, value=None, commit=False) Edits a Palo Alto XPATH to a specific value. This will always overwrite the existing value, even if it is not changed. .sp You can replace an existing object hierarchy at a specified location in the configuration with a new value. Use the xpath parameter to specify the location of the object, including the node to be replaced. .sp This is the recommended state to enforce configurations on a xpath. .sp name: The name of the module function to execute. .sp xpath(str): The XPATH of the configuration API tree to control. .sp value(str): The XML value to edit. This must be a child to the XPATH. .sp commit(bool): If true the firewall will commit the changes, if false do not commit changes. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/addressgroup: panos.edit_config: \- xpath: /config/devices/entry/vsys/entry[@name=\(aqvsys1\(aq]/address\-group/entry[@name=\(aqtest\(aq] \- value: <static><entry name=\(aqtest\(aq><member>abc</member><member>xyz</member></entry></static> \- commit: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.move_config(name, xpath=None, where=None, dst=None, commit=False) Moves a XPATH value to a new location. .sp Use the xpath parameter to specify the location of the object to be moved, the where parameter to specify type of move, and dst parameter to specify the destination path. .sp name: The name of the module function to execute. .sp xpath(str): The XPATH of the configuration API tree to move. .sp where(str): The type of move to execute. Valid options are after, before, top, bottom. The after and before options will require the dst option to specify the destination of the action. The top action will move the XPATH to the top of its structure. The botoom action will move the XPATH to the bottom of its structure. .sp dst(str): Optional. Specifies the destination to utilize for a move action. This is ignored for the top or bottom action. .sp commit(bool): If true the firewall will commit the changes, if false do not commit changes. If the operation is not successful, it will not commit. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/moveruletop: panos.move_config: \- xpath: /config/devices/entry/vsys/entry[@name=\(aqvsys1\(aq]/rulebase/security/rules/entry[@name=\(aqrule1\(aq] \- where: top \- commit: True panos/moveruleafter: panos.move_config: \- xpath: /config/devices/entry/vsys/entry[@name=\(aqvsys1\(aq]/rulebase/security/rules/entry[@name=\(aqrule1\(aq] \- where: after \- dst: rule2 \- commit: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.remove_config_lock(name) Release config lock previously held. .sp name: The name of the module function to execute. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/takelock: panos.remove_config_lock .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.rename_config(name, xpath=None, newname=None, commit=False) Rename a Palo Alto XPATH to a specific value. This will always rename the value even if a change is not needed. .sp name: The name of the module function to execute. .sp xpath(str): The XPATH of the configuration API tree to control. .sp newname(str): The new name of the XPATH value. .sp commit(bool): If true the firewall will commit the changes, if false do not commit changes. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/renamegroup: panos.rename_config: \- xpath: /config/devices/entry/vsys/entry[@name=\(aqvsys1\(aq]/address/entry[@name=\(aqold_address\(aq] \- value: new_address \- commit: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.security_rule_exists(name, rulename=None, vsys=\(aq1\(aq, action=None, disabled=None, sourcezone=None, destinationzone=None, source=None, destination=None, application=None, service=None, description=None, logsetting=None, logstart=None, logend=None, negatesource=None, negatedestination=None, profilegroup=None, datafilter=None, fileblock=None, spyware=None, urlfilter=None, virus=None, vulnerability=None, wildfire=None, move=None, movetarget=None, commit=False) Ensures that a security rule exists on the device. Also, ensure that all configurations are set appropriately. .sp This method will create the rule if it does not exist. If the rule does exist, it will ensure that the configurations are set appropriately. .sp If the rule does not exist and is created, any value that is not provided will be provided as the default. The action, to, from, source, destination, application, and service fields are mandatory and must be provided. .sp This will enforce the exact match of the rule. For example, if the rule is currently configured with the log\-end option, but this option is not specified in the state method, it will be removed and reset to the system default. .sp It is strongly recommended to specify all options to ensure proper operation. .sp When defining the profile group settings, the device can only support either a profile group or individual settings. If both are specified, the profile group will be preferred and the individual settings are ignored. If neither are specified, the value will be set to system default of none. .sp name: The name of the module function to execute. .sp rulename(str): The name of the security rule. The name is case\-sensitive and can have up to 31 characters, which can be letters, numbers, spaces, hyphens, and underscores. The name must be unique on a firewall and, on Panorama, unique within its device group and any ancestor or descendant device groups. .sp vsys(str): The string representation of the VSYS ID. Defaults to VSYS 1. .sp action(str): The action that the security rule will enforce. Valid options are: allow, deny, drop, reset\-client, reset\-server, reset\-both. .sp disabled(bool): Controls if the rule is disabled. Set \(aqTrue\(aq to disable and \(aqFalse\(aq to enable. .sp sourcezone(str, list): The source zone(s). The value \(aqany\(aq will match all zones. .sp destinationzone(str, list): The destination zone(s). The value \(aqany\(aq will match all zones. .sp source(str, list): The source address(es). The value \(aqany\(aq will match all addresses. .sp destination(str, list): The destination address(es). The value \(aqany\(aq will match all addresses. .sp application(str, list): The application(s) matched. The value \(aqany\(aq will match all applications. .sp service(str, list): The service(s) matched. The value \(aqany\(aq will match all services. The value \(aqapplication\-default\(aq will match based upon the application defined ports. .sp description(str): A description for the policy (up to 255 characters). .sp logsetting(str): The name of a valid log forwarding profile. .sp logstart(bool): Generates a traffic log entry for the start of a session (disabled by default). .sp logend(bool): Generates a traffic log entry for the end of a session (enabled by default). .sp negatesource(bool): Match all but the specified source addresses. .sp negatedestination(bool): Match all but the specified destination addresses. .sp profilegroup(str): A valid profile group name. .sp datafilter(str): A valid data filter profile name. Ignored with the profilegroup option set. .sp fileblock(str): A valid file blocking profile name. Ignored with the profilegroup option set. .sp spyware(str): A valid spyware profile name. Ignored with the profilegroup option set. .sp urlfilter(str): A valid URL filtering profile name. Ignored with the profilegroup option set. .sp virus(str): A valid virus profile name. Ignored with the profilegroup option set. .sp vulnerability(str): A valid vulnerability profile name. Ignored with the profilegroup option set. .sp wildfire(str): A valid vulnerability profile name. Ignored with the profilegroup option set. .sp move(str): An optional argument that ensure the rule is moved to a specific location. Valid options are \(aqtop\(aq, \(aqbottom\(aq, \(aqbefore\(aq, or \(aqafter\(aq. The \(aqbefore\(aq and \(aqafter\(aq options require the use of the \(aqmovetarget\(aq argument to define the location of the move request. .sp movetarget(str): An optional argument that defines the target of the move operation if the move argument is set to \(aqbefore\(aq or \(aqafter\(aq. .sp commit(bool): If true the firewall will commit the changes, if false do not commit changes. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/rulebase/security/rule01: panos.security_rule_exists: \- rulename: rule01 \- vsys: 1 \- action: allow \- disabled: False \- sourcezone: untrust \- destinationzone: trust \- source: \- 10.10.10.0/24 \- 1.1.1.1 \- destination: \- 2.2.2.2\-2.2.2.4 \- application: \- any \- service: \- tcp\-25 \- description: My test security rule \- logsetting: logprofile \- logstart: False \- logend: True \- negatesource: False \- negatedestination: False \- profilegroup: myprofilegroup \- move: top \- commit: False panos/rulebase/security/rule01: panos.security_rule_exists: \- rulename: rule01 \- vsys: 1 \- action: allow \- disabled: False \- sourcezone: untrust \- destinationzone: trust \- source: \- 10.10.10.0/24 \- 1.1.1.1 \- destination: \- 2.2.2.2\-2.2.2.4 \- application: \- any \- service: \- tcp\-25 \- description: My test security rule \- logsetting: logprofile \- logstart: False \- logend: False \- datafilter: foobar \- fileblock: foobar \- spyware: foobar \- urlfilter: foobar \- virus: foobar \- vulnerability: foobar \- wildfire: foobar \- move: after \- movetarget: rule02 \- commit: False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.service_exists(name, servicename=None, vsys=1, protocol=None, port=None, description=None, commit=False) Ensures that a service object exists in the configured state. If it does not exist or is not configured with the specified attributes, it will be adjusted to match the specified values. .sp name: The name of the module function to execute. .sp servicename(str): The name of the security object. The name is case\-sensitive and can have up to 31 characters, which an be letters, numbers, spaces, hyphens, and underscores. The name must be unique on a firewall and, on Panorama, unique within its device group and any ancestor or descendant device groups. .sp vsys(str): The string representation of the VSYS ID. Defaults to VSYS 1. .sp protocol(str): The protocol that is used by the service object. The only valid options are tcp and udp. .sp port(str): The port number that is used by the service object. This can be specified as a single integer or a valid range of ports. .sp description(str): A description for the policy (up to 255 characters). .sp commit(bool): If true the firewall will commit the changes, if false do not commit changes. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/service/tcp\-80: panos.service_exists: \- servicename: tcp\-80 \- vsys: 1 \- protocol: tcp \- port: 80 \- description: Hypertext Transfer Protocol \- commit: False panos/service/udp\-500\-550: panos.service_exists: \- servicename: udp\-500\-550 \- vsys: 3 \- protocol: udp \- port: 500\-550 \- commit: False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.service_group_exists(name, groupname=None, vsys=1, members=None, description=None, commit=False) Ensures that a service group object exists in the configured state. If it does not exist or is not configured with the specified attributes, it will be adjusted to match the specified values. .sp This module will enforce group membership. If a group exists and contains members this state does not include, those members will be removed and replaced with the specified members in the state. .sp name: The name of the module function to execute. .sp groupname(str): The name of the service group object. The name is case\-sensitive and can have up to 31 characters, which an be letters, numbers, spaces, hyphens, and underscores. The name must be unique on a firewall and, on Panorama, unique within its device group and any ancestor or descendant device groups. .sp vsys(str): The string representation of the VSYS ID. Defaults to VSYS 1. .sp members(str, list): The members of the service group. These must be valid service objects or service groups on the system that already exist prior to the execution of this state. .sp description(str): A description for the policy (up to 255 characters). .sp commit(bool): If true the firewall will commit the changes, if false do not commit changes. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/service\-group/my\-group: panos.service_group_exists: \- groupname: my\-group \- vsys: 1 \- members: \- tcp\-80 \- custom\-port\-group \- description: A group that needs to exist \- commit: False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.panos.set_config(name, xpath=None, value=None, commit=False) Sets a Palo Alto XPATH to a specific value. This will always overwrite the existing value, even if it is not changed. .sp You can add or create a new object at a specified location in the configuration hierarchy. Use the xpath parameter to specify the location of the object in the configuration .sp name: The name of the module function to execute. .sp xpath(str): The XPATH of the configuration API tree to control. .sp value(str): The XML value to set. This must be a child to the XPATH. .sp commit(bool): If true the firewall will commit the changes, if false do not commit changes. .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C panos/hostname: panos.set_config: \- xpath: /config/devices/entry[@name=\(aqlocalhost.localdomain\(aq]/deviceconfig/system \- value: <hostname>foobar</hostname> \- commit: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.pbm .sp Manages VMware storage policies (called pbm because the vCenter endpoint is /pbm) .sp Examples .SS Storage policy .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { \(dqname\(dq: \(dqsalt_storage_policy\(dq \(dqdescription\(dq: \(dqManaged by Salt. Random capability values.\(dq, \(dqresource_type\(dq: \(dqSTORAGE\(dq, \(dqsubprofiles\(dq: [ { \(dqcapabilities\(dq: [ { \(dqsetting\(dq: { \(dqtype\(dq: \(dqscalar\(dq, \(dqvalue\(dq: 2 }, \(dqnamespace\(dq: \(dqVSAN\(dq, \(dqid\(dq: \(dqhostFailuresToTolerate\(dq }, { \(dqsetting\(dq: { \(dqtype\(dq: \(dqscalar\(dq, \(dqvalue\(dq: 2 }, \(dqnamespace\(dq: \(dqVSAN\(dq, \(dqid\(dq: \(dqstripeWidth\(dq }, { \(dqsetting\(dq: { \(dqtype\(dq: \(dqscalar\(dq, \(dqvalue\(dq: true }, \(dqnamespace\(dq: \(dqVSAN\(dq, \(dqid\(dq: \(dqforceProvisioning\(dq }, { \(dqsetting\(dq: { \(dqtype\(dq: \(dqscalar\(dq, \(dqvalue\(dq: 50 }, \(dqnamespace\(dq: \(dqVSAN\(dq, \(dqid\(dq: \(dqproportionalCapacity\(dq }, { \(dqsetting\(dq: { \(dqtype\(dq: \(dqscalar\(dq, \(dqvalue\(dq: 0 }, \(dqnamespace\(dq: \(dqVSAN\(dq, \(dqid\(dq: \(dqcacheReservation\(dq } ], \(dqname\(dq: \(dqRule\-Set 1: VSAN\(dq, \(dqforce_provision\(dq: null } ], } .ft P .fi .UNINDENT .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 \fIIssue #29537 <https://github.com/saltstack/salt/issues/29537>\fP for more information. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pbm.default_storage_policy_assigned(name, policy, datastore) Assigns a default storage policy to a datastore .INDENT 7.0 .TP .B policy Name of storage policy .TP .B datastore Name of datastore .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pbm.default_vsan_policy_configured(name, policy) Configures the default VSAN policy on a vCenter. The state assumes there is only one default VSAN policy on a vCenter. .INDENT 7.0 .TP .B policy Dict representation of a policy .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pbm.storage_policies_configured(name, policies) Configures storage policies on a vCenter. .INDENT 7.0 .TP .B policies List of dict representation of the required storage policies .UNINDENT .UNINDENT .SS salt.states.pcs .SS Management of Pacemaker/Corosync clusters with PCS .sp A state module to manage Pacemaker/Corosync clusters with the Pacemaker/Corosync configuration system (PCS) .sp New in version 2016.11.0. .INDENT 0.0 .TP .B depends pcs .UNINDENT .sp Walkthrough of a complete PCS cluster setup: \fI\%http://clusterlabs.org/doc/en\-US/Pacemaker/1.1/html/Clusters_from_Scratch/\fP .INDENT 0.0 .TP .B Requirements: PCS is installed, pcs service is started and the password for the hacluster user is set and known. .TP .B Remark on the cibname variable used in the examples: The use of the cibname variable is optional. Use it only if you want to deploy your changes into a cibfile first and then push it. This makes only sense if you want to deploy multiple changes (which require each other) at once to the cluster. .UNINDENT .sp At first the cibfile must be created: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql_pcs__cib_present_cib_for_galera: pcs.cib_present: \- cibname: cib_for_galera \- scope: None \- extra_args: None .ft P .fi .UNINDENT .UNINDENT .sp Then the cibfile can be modified by creating resources (creating only 1 resource for demonstration, see also 7.): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql_pcs__resource_present_galera: pcs.resource_present: \- resource_id: galera \- resource_type: \(dqocf:heartbeat:galera\(dq \- resource_options: \- \(aqwsrep_cluster_address=gcomm://node1.example.org,node2.example.org,node3.example.org\(aq \- \(aq\-\-master\(aq \- cibname: cib_for_galera .ft P .fi .UNINDENT .UNINDENT .sp After modifying the cibfile, it can be pushed to the live CIB in the cluster: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql_pcs__cib_pushed_cib_for_galera: pcs.cib_pushed: \- cibname: cib_for_galera \- scope: None \- extra_args: None .ft P .fi .UNINDENT .UNINDENT .sp Create a cluster from scratch: .INDENT 0.0 .IP 1. 3 .INDENT 3.0 .TP .B This authorizes nodes to each other. It probably won\(aqt work with Ubuntu as it rolls out a default cluster that needs to be destroyed before the new cluster can be created. This is a little complicated so it\(aqs best to just run the cluster_setup below in most cases.: .UNINDENT .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C pcs_auth__auth: pcs.auth: \- nodes: \- node1.example.com \- node2.example.com \- pcsuser: hacluster \- pcspasswd: hoonetorg .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 Do the initial cluster setup: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C pcs_setup__setup: pcs.cluster_setup: \- nodes: \- node1.example.com \- node2.example.com \- pcsclustername: pcscluster \- extra_args: \- \(aq\-\-start\(aq \- \(aq\-\-enable\(aq \- pcsuser: hacluster \- pcspasswd: hoonetorg .ft P .fi .UNINDENT .UNINDENT .IP 3. 3 Optional: Set cluster properties: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C pcs_properties__prop_has_value_no\-quorum\-policy: pcs.prop_has_value: \- prop: no\-quorum\-policy \- value: ignore \- cibname: cib_for_cluster_settings .ft P .fi .UNINDENT .UNINDENT .IP 4. 3 Optional: Set resource defaults: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C pcs_properties__resource_defaults_to_resource\-stickiness: pcs.resource_defaults_to: \- default: resource\-stickiness \- value: 100 \- cibname: cib_for_cluster_settings .ft P .fi .UNINDENT .UNINDENT .IP 5. 3 Optional: Set resource op defaults: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C pcs_properties__resource_op_defaults_to_monitor\-interval: pcs.resource_op_defaults_to: \- op_default: monitor\-interval \- value: 60s \- cibname: cib_for_cluster_settings .ft P .fi .UNINDENT .UNINDENT .IP 6. 3 Configure Fencing (!is often not optional on production ready cluster!): .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C pcs_stonith__created_eps_fence: pcs.stonith_present: \- stonith_id: eps_fence \- stonith_device_type: fence_eps \- stonith_device_options: \- \(aqpcmk_host_map=node1.example.org:01;node2.example.org:02\(aq \- \(aqipaddr=myepsdevice.example.org\(aq \- \(aqpower_wait=5\(aq \- \(aqverbose=1\(aq \- \(aqdebug=/var/log/pcsd/eps_fence.log\(aq \- \(aqlogin=hidden\(aq \- \(aqpasswd=hoonetorg\(aq \- cibname: cib_for_stonith .ft P .fi .UNINDENT .UNINDENT .IP 7. 3 Add resources to your cluster: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C mysql_pcs__resource_present_galera: pcs.resource_present: \- resource_id: galera \- resource_type: \(dqocf:heartbeat:galera\(dq \- resource_options: \- \(aqwsrep_cluster_address=gcomm://node1.example.org,node2.example.org,node3.example.org\(aq \- \(aq\-\-master\(aq \- cibname: cib_for_galera .ft P .fi .UNINDENT .UNINDENT .IP 8. 3 Optional: Add constraints (locations, colocations, orders): .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C haproxy_pcs__constraint_present_colocation\-vip_galera\-haproxy\-clone\-INFINITY: pcs.constraint_present: \- constraint_id: colocation\-vip_galera\-haproxy\-clone\-INFINITY \- constraint_type: colocation \- constraint_options: \- \(aqadd\(aq \- \(aqvip_galera\(aq \- \(aqwith\(aq \- \(aqhaproxy\-clone\(aq \- cibname: cib_for_haproxy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.states.pcs.auth(name, nodes, pcsuser=\(aqhacluster\(aq, pcspasswd=\(aqhacluster\(aq, extra_args=None) Ensure all nodes are authorized to the cluster .INDENT 7.0 .TP .B name Irrelevant, not used (recommended: pcs_auth__auth) .TP .B nodes a list of nodes which should be authorized to the cluster .TP .B pcsuser user for communication with pcs (default: hacluster) .TP .B pcspasswd password for pcsuser (default: hacluster) .TP .B extra_args list of extra args for the \(aqpcs cluster auth\(aq command, there are none so it\(aqs here for compatibility. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pcs_auth__auth: pcs.auth: \- nodes: \- node1.example.com \- node2.example.com \- pcsuser: hacluster \- pcspasswd: hoonetorg \- extra_args: [] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pcs.cib_present(name, cibname, scope=None, extra_args=None) Ensure that a CIB\-file with the content of the current live CIB is created .sp Should be run on one cluster node only (there may be races) .INDENT 7.0 .TP .B name Irrelevant, not used (recommended: {{formulaname}}__cib_present_{{cibname}}) .TP .B cibname name/path of the file containing the CIB .TP .B scope specific section of the CIB (default: None) .TP .B extra_args additional options for creating the CIB\-file .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mysql_pcs__cib_present_cib_for_galera: pcs.cib_present: \- cibname: cib_for_galera \- scope: None \- extra_args: None .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pcs.cib_pushed(name, cibname, scope=None, extra_args=None) Ensure that a CIB\-file is pushed if it is changed since the creation of it with pcs.cib_present .sp Should be run on one cluster node only (there may be races) .INDENT 7.0 .TP .B name Irrelevant, not used (recommended: {{formulaname}}__cib_pushed_{{cibname}}) .TP .B cibname name/path of the file containing the CIB .TP .B scope specific section of the CIB .TP .B extra_args additional options for creating the CIB\-file .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mysql_pcs__cib_pushed_cib_for_galera: pcs.cib_pushed: \- cibname: cib_for_galera \- scope: None \- extra_args: None .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pcs.cluster_node_present(name, node, extra_args=None) Add a node to the Pacemaker cluster via PCS Should be run on one cluster node only (there may be races) Can only be run on a already setup/added node .INDENT 7.0 .TP .B name Irrelevant, not used (recommended: pcs_setup__node_add_{{node}}) .TP .B node node that should be added .TP .B extra_args list of extra args for the \(aqpcs cluster node add\(aq command .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pcs_setup__node_add_node1.example.com: pcs.cluster_node_present: \- node: node1.example.com \- extra_args: \- \(aq\-\-start\(aq \- \(aq\-\-enable\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pcs.cluster_setup(name, nodes, pcsclustername=\(aqpcscluster\(aq, extra_args=None, pcsuser=\(aqhacluster\(aq, pcspasswd=\(aqhacluster\(aq, pcs_auth_extra_args=None, wipe_default=False) Setup Pacemaker cluster on nodes. Should be run on one cluster node only to avoid race conditions. This performs auth as well as setup so can be run in place of the auth state. It is recommended not to run auth on Debian/Ubuntu for a new cluster and just to run this because of the initial cluster config that is installed on Ubuntu/Debian by default. .INDENT 7.0 .TP .B name Irrelevant, not used (recommended: pcs_setup__setup) .TP .B nodes a list of nodes which should be set up .TP .B pcsclustername Name of the Pacemaker cluster .TP .B extra_args list of extra args for the \(aqpcs cluster setup\(aq command .TP .B pcsuser The username for authenticating the cluster (default: hacluster) .TP .B pcspasswd The password for authenticating the cluster (default: hacluster) .TP .B pcs_auth_extra_args Extra args to be passed to the auth function in case of reauth. .TP .B wipe_default This removes the files that are installed with Debian based operating systems. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pcs_setup__setup: pcs.cluster_setup: \- nodes: \- node1.example.com \- node2.example.com \- pcsclustername: pcscluster \- extra_args: \- \(aq\-\-start\(aq \- \(aq\-\-enable\(aq \- pcsuser: hacluster \- pcspasswd: hoonetorg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pcs.constraint_present(name, constraint_id, constraint_type, constraint_options=None, cibname=None) Ensure that a constraint is created .sp Should be run on one cluster node only (there may be races) Can only be run on a node with a functional pacemaker/corosync .INDENT 7.0 .TP .B name Irrelevant, not used (recommended: {{formulaname}}__constraint_present_{{constraint_id}}) .TP .B constraint_id name for the constraint (try first to create manually to find out the autocreated name) .TP .B constraint_type constraint type (location, colocation, order) .TP .B constraint_options options for creating the constraint .TP .B cibname use a cached CIB\-file named like cibname instead of the live CIB .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C haproxy_pcs__constraint_present_colocation\-vip_galera\-haproxy\-clone\-INFINITY: pcs.constraint_present: \- constraint_id: colocation\-vip_galera\-haproxy\-clone\-INFINITY \- constraint_type: colocation \- constraint_options: \- \(aqadd\(aq \- \(aqvip_galera\(aq \- \(aqwith\(aq \- \(aqhaproxy\-clone\(aq \- cibname: cib_for_haproxy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pcs.prop_has_value(name, prop, value, extra_args=None, cibname=None) Ensure that a property in the cluster is set to a given value .sp Should be run on one cluster node only (there may be races) .INDENT 7.0 .TP .B name Irrelevant, not used (recommended: pcs_properties__prop_has_value_{{prop}}) .TP .B prop name of the property .TP .B value value of the property .TP .B extra_args additional options for the pcs property command .TP .B cibname use a cached CIB\-file named like cibname instead of the live CIB .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pcs_properties__prop_has_value_no\-quorum\-policy: pcs.prop_has_value: \- prop: no\-quorum\-policy \- value: ignore \- cibname: cib_for_cluster_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pcs.resource_defaults_to(name, default, value, extra_args=None, cibname=None) Ensure a resource default in the cluster is set to a given value .sp Should be run on one cluster node only (there may be races) Can only be run on a node with a functional pacemaker/corosync .INDENT 7.0 .TP .B name Irrelevant, not used (recommended: pcs_properties__resource_defaults_to_{{default}}) .TP .B default name of the default resource property .TP .B value value of the default resource property .TP .B extra_args additional options for the pcs command .TP .B cibname use a cached CIB\-file named like cibname instead of the live CIB .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pcs_properties__resource_defaults_to_resource\-stickiness: pcs.resource_defaults_to: \- default: resource\-stickiness \- value: 100 \- cibname: cib_for_cluster_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pcs.resource_op_defaults_to(name, op_default, value, extra_args=None, cibname=None) Ensure a resource operation default in the cluster is set to a given value .sp Should be run on one cluster node only (there may be races) Can only be run on a node with a functional pacemaker/corosync .INDENT 7.0 .TP .B name Irrelevant, not used (recommended: pcs_properties__resource_op_defaults_to_{{op_default}}) .TP .B op_default name of the operation default resource property .TP .B value value of the operation default resource property .TP .B extra_args additional options for the pcs command .TP .B cibname use a cached CIB\-file named like cibname instead of the live CIB .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pcs_properties__resource_op_defaults_to_monitor\-interval: pcs.resource_op_defaults_to: \- op_default: monitor\-interval \- value: 60s \- cibname: cib_for_cluster_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pcs.resource_present(name, resource_id, resource_type, resource_options=None, cibname=None) Ensure that a resource is created .sp Should be run on one cluster node only (there may be races) Can only be run on a node with a functional pacemaker/corosync .INDENT 7.0 .TP .B name Irrelevant, not used (recommended: {{formulaname}}__resource_present_{{resource_id}}) .TP .B resource_id name for the resource .TP .B resource_type resource type (f.e. ocf:heartbeat:IPaddr2 or VirtualIP) .TP .B resource_options additional options for creating the resource .TP .B cibname use a cached CIB\-file named like cibname instead of the live CIB .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mysql_pcs__resource_present_galera: pcs.resource_present: \- resource_id: galera \- resource_type: \(dqocf:heartbeat:galera\(dq \- resource_options: \- \(aqwsrep_cluster_address=gcomm://node1.example.org,node2.example.org,node3.example.org\(aq \- \(aq\-\-master\(aq \- cibname: cib_for_galera .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pcs.stonith_present(name, stonith_id, stonith_device_type, stonith_device_options=None, cibname=None) Ensure that a fencing resource is created .sp Should be run on one cluster node only (there may be races) Can only be run on a node with a functional pacemaker/corosync .INDENT 7.0 .TP .B name Irrelevant, not used (recommended: pcs_stonith__created_{{stonith_id}}) .TP .B stonith_id name for the stonith resource .TP .B stonith_device_type name of the stonith agent fence_eps, fence_xvm f.e. .TP .B stonith_device_options additional options for creating the stonith resource .TP .B cibname use a cached CIB\-file named like cibname instead of the live CIB .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pcs_stonith__created_eps_fence: pcs.stonith_present: \- stonith_id: eps_fence \- stonith_device_type: fence_eps \- stonith_device_options: \- \(aqpcmk_host_map=node1.example.org:01;node2.example.org:02\(aq \- \(aqipaddr=myepsdevice.example.org\(aq \- \(aqpower_wait=5\(aq \- \(aqverbose=1\(aq \- \(aqdebug=/var/log/pcsd/eps_fence.log\(aq \- \(aqlogin=hidden\(aq \- \(aqpasswd=hoonetorg\(aq \- cibname: cib_for_stonith .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.pdbedit .sp Manage accounts in Samba\(aqs passdb using pdbedit .INDENT 0.0 .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B depends pdbedit .TP .B platform posix .UNINDENT .sp New in version 2017.7.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wash: pdbedit.absent kaylee: pdbedit.managed: \- password: A70C708517B5DD0EDB67714FE25336EB \- password_hashed: True \- drive: \(aqX:\(aq \- homedir: \(aq\e\eserenity\emechanic\eprofile\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pdbedit.absent(name) Ensure user account is absent .INDENT 7.0 .TP .B name string username .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pdbedit.managed(name, **kwargs) Manage user account .INDENT 7.0 .TP .B login string login name .TP .B password string password .TP .B password_hashed boolean set if password is a nt hash instead of plain text .TP .B domain string users domain .TP .B profile string profile path .TP .B script string logon script .TP .B drive string home drive .TP .B homedir string home directory .TP .B fullname string full name .TP .B account_desc string account description .TP .B machine_sid string specify the machines new primary group SID or rid .TP .B user_sid string specify the users new primary group SID or rid .TP .B account_control string specify user account control properties .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Only the following can be set: \- N: No password required \- D: Account disabled \- H: Home directory required \- L: Automatic Locking \- X: Password does not expire .UNINDENT .UNINDENT .TP .B reset_login_hours boolean reset the users allowed logon hours .TP .B reset_bad_password_count boolean reset the stored bad login counter .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pdbedit.present(name, **kwargs) Alias for pdbedit.managed .UNINDENT .SS salt.states.pecl .SS Installation of PHP Extensions Using pecl .sp These states manage the installed pecl extensions. Note that php\-pear must be installed for these states to be available, so pecl states should include a requisite to a pkg.installed state for the package which provides pecl (\fBphp\-pear\fP in most cases). Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C php\-pear: pkg.installed mongo: pecl.installed: \- require: \- pkg: php\-pear .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pecl.installed(name, version=None, defaults=False, force=False, preferred_state=\(aqstable\(aq) New in version 0.17.0. .sp Make sure that a pecl extension is installed. .INDENT 7.0 .TP .B name The pecl extension name to install .TP .B version The pecl extension version to install. This option may be ignored to install the latest stable version. .TP .B defaults Use default answers for extensions such as pecl_http which ask questions before installation. Without this option, the pecl.installed state will hang indefinitely when trying to install these extensions. .TP .B force Whether to force the installed version or not .TP .B preferred_state The pecl extension state to install .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pecl.removed(name) Make sure that a pecl extension is not installed. .INDENT 7.0 .TP .B name The pecl extension name to uninstall .UNINDENT .UNINDENT .SS salt.states.pip_state .SS Installation of Python Packages Using pip .sp These states manage system installed python packages. Note that pip must be installed for these states to be available, so pip states should include a requisite to a pkg.installed state for the package which provides pip (\fBpython\-pip\fP in most cases). Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-pip: pkg.installed virtualenvwrapper: pip.installed: \- require: \- pkg: python\-pip .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pip_state.installed(name, pkgs=None, pip_bin=None, requirements=None, bin_env=None, use_wheel=False, no_use_wheel=False, log=None, proxy=None, timeout=None, repo=None, editable=None, find_links=None, index_url=None, extra_index_url=None, no_index=False, mirrors=None, build=None, target=None, download=None, download_cache=None, source=None, upgrade=False, force_reinstall=False, ignore_installed=False, exists_action=None, no_deps=False, no_install=False, no_download=False, install_options=None, global_options=None, user=None, cwd=None, pre_releases=False, cert=None, allow_all_external=False, allow_external=None, allow_unverified=None, process_dependency_links=False, env_vars=None, use_vt=False, trusted_host=None, no_cache_dir=False, cache_dir=None, no_binary=None, extra_args=None, **kwargs) Make sure the package is installed .INDENT 7.0 .TP .B name The name of the python package to install. You can also specify version numbers here using the standard operators \fB==, >=, <=\fP\&. If \fBrequirements\fP or \fBpkgs\fP is given, this parameter will be ignored. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C django: pip.installed: \- name: django >= 1.6, <= 1.7 \- require: \- pkg: python\-pip .ft P .fi .UNINDENT .UNINDENT .sp Installs the latest Django version greater than 1.6 but less than 1.7. .TP .B pkgs A list of python packages to install. This let you install multiple packages at the same time. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C django\-and\-psycopg2: pip.installed: \- pkgs: \- django >= 1.6, <= 1.7 \- psycopg2 >= 2.8.4 \- require: \- pkg: python\-pip .ft P .fi .UNINDENT .UNINDENT .sp Installs the latest Django version greater than 1.6 but less than 1.7 and the latest psycopg2 greater than 2.8.4 at the same time. .TP .B requirements Path to a pip requirements file. If the path begins with salt:// the file will be transferred from the master file server. .TP .B user The user under which to run pip .TP .B use_wheel False Prefer wheel archives (requires pip>=1.4) .TP .B no_use_wheel False Force to not use wheel archives (requires pip>=1.4) .TP .B no_binary Force to not use binary packages (requires pip >= 7.0.0) Accepts either :all: to disable all binary packages, :none: to empty the set, or a list of one or more packages .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C django: pip.installed: \- no_binary: \(aq:all:\(aq flask: pip.installed: \- no_binary: \- itsdangerous \- click .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B log Log file where a complete (maximum verbosity) record will be kept .TP .B proxy Specify a proxy in the form user:passwd@proxy.server:port. Note that the user:password@ is optional and required only if you are behind an authenticated proxy. If you provide user@proxy.server:port then you will be prompted for a password. .TP .B timeout Set the socket timeout (default 15 seconds) .TP .B editable install something editable (i.e. git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed) .TP .B find_links URL to look for packages at .TP .B index_url Base URL of Python Package Index .TP .B extra_index_url Extra URLs of package indexes to use in addition to \fBindex_url\fP .TP .B no_index Ignore package index .TP .B mirrors Specific mirror URL(s) to query (automatically adds \-\-use\-mirrors) .TP .B build Unpack packages into \fBbuild\fP dir .TP .B target Install packages into \fBtarget\fP dir .TP .B download Download packages into \fBdownload\fP instead of installing them .TP .B download_cache Cache downloaded packages in \fBdownload_cache\fP dir .TP .B source Check out \fBeditable\fP packages into \fBsource\fP dir .TP .B upgrade Upgrade all packages to the newest available version .TP .B force_reinstall When upgrading, reinstall all packages even if they are already up\-to\-date. .TP .B ignore_installed Ignore the installed packages (reinstalling instead) .TP .B exists_action Default action when a path already exists: (s)witch, (i)gnore, (w)ipe, (b)ackup .TP .B no_deps Ignore package dependencies .TP .B no_install Download and unpack all packages, but don\(aqt actually install them .TP .B no_cache_dir: Disable the cache. .TP .B cwd Current working directory to run pip from .TP .B pre_releases Include pre\-releases in the available versions .TP .B cert Provide a path to an alternate CA bundle .TP .B allow_all_external Allow the installation of all externally hosted files .TP .B allow_external Allow the installation of externally hosted files (comma separated list) .TP .B allow_unverified Allow the installation of insecure and unverifiable files (comma separated list) .TP .B process_dependency_links Enable the processing of dependency links .TP .B env_vars Add or modify environment variables. Useful for tweaking build steps, such as specifying INCLUDE or LIBRARY paths in Makefiles, build scripts or compiler calls. This must be in the form of a dictionary or a mapping. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C django: pip.installed: \- name: django_app \- env_vars: CUSTOM_PATH: /opt/django_app VERBOSE: True .ft P .fi .UNINDENT .UNINDENT .TP .B use_vt Use VT terminal emulation (see output while installing) .TP .B trusted_host Mark this host as trusted, even though it does not have valid or any HTTPS. .TP .B bin_env None Absolute path to a virtual environment directory or absolute path to a pip executable. The example below assumes a virtual environment has been created at \fB/foo/.virtualenvs/bar\fP\&. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C django: pip.installed: \- name: django >= 1.6, <= 1.7 \- bin_env: /foo/.virtualenvs/bar \- require: \- pkg: python\-pip .ft P .fi .UNINDENT .UNINDENT .sp Or .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C django: pip.installed: \- name: django >= 1.6, <= 1.7 \- bin_env: /foo/.virtualenvs/bar/bin/pip \- require: \- pkg: python\-pip .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .IP "Attention" .sp The following arguments are deprecated, do not use. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B pip_bin None Deprecated, use \fBbin_env\fP .UNINDENT .sp Changed in version 0.17.0: \fBuse_wheel\fP option added. .sp install_options .INDENT 7.0 .INDENT 3.5 Extra arguments to be supplied to the setup.py install command. If you are using an option with a directory path, be sure to use absolute path. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C django: pip.installed: \- name: django \- install_options: \- \-\-prefix=/blah \- require: \- pkg: python\-pip .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B global_options Extra global options to be supplied to the setup.py call before the install command. .sp New in version 2014.1.3. .UNINDENT .INDENT 7.0 .INDENT 3.5 .IP "Attention" .sp As of Salt 0.17.0 the pip state \fBneeds\fP an importable pip module. This usually means having the system\(aqs pip package installed or running Salt from an active \fI\%virtualenv\fP\&. .sp The reason for this requirement is because \fBpip\fP already does a pretty good job parsing its own requirements. It makes no sense for Salt to do \fBpip\fP requirements parsing and validation before passing them to the \fBpip\fP library. It\(aqs functionality duplication and it\(aqs more error prone. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .IP "Attention" .sp Please set \fBreload_modules: True\fP to have the salt minion import this module after installation. .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pyopenssl: pip.installed: \- name: pyOpenSSL \- reload_modules: True \- exists_action: i .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B extra_args pip keyword and positional arguments not yet implemented in salt .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pandas: pip.installed: \- name: pandas \- extra_args: \- \-\-latest\-pip\-kwarg: param \- \-\-latest\-pip\-arg .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 If unsupported options are passed here that are not supported in a minion\(aqs version of pip, a \fINo such option error\fP will be thrown. .UNINDENT .UNINDENT .UNINDENT .sp If you are using onedir packages and you need to install python packages into the system python environment, you must provide the pip_bin or bin_env to the pip state module. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C lib\-foo: pip.installed: \- pip_bin: /usr/bin/pip3 lib\-bar: pip.installed: \- bin_env: /usr/bin/python3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pip_state.pip_has_exceptions_mod(ver) True when the pip version has the \fIpip.exceptions\fP module .UNINDENT .INDENT 0.0 .TP .B salt.states.pip_state.pip_has_internal_exceptions_mod(ver) True when the pip version has the \fIpip._internal.exceptions\fP module .UNINDENT .INDENT 0.0 .TP .B salt.states.pip_state.purge_pip() Purge pip and its sub\-modules .UNINDENT .INDENT 0.0 .TP .B salt.states.pip_state.removed(name, requirements=None, bin_env=None, log=None, proxy=None, timeout=None, user=None, cwd=None, use_vt=False) Make sure that a package is not installed. .INDENT 7.0 .TP .B name The name of the package to uninstall .TP .B user The user under which to run pip .TP .B bin_env None the pip executable or virtualenenv to use .TP .B use_vt Use VT terminal emulation (see output while installing) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pip_state.uptodate(name, bin_env=None, user=None, cwd=None, use_vt=False) New in version 2015.5.0. .sp Verify that the system is completely up to date. .INDENT 7.0 .TP .B name The name has no functional value and is only used as a tracking reference .TP .B user The user under which to run pip .TP .B bin_env the pip executable or virtualenenv to use .TP .B use_vt Use VT terminal emulation (see output while installing) .UNINDENT .UNINDENT .SS salt.states.pkg .SS Installation of packages using OS package managers such as yum or apt\-get .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 On minions running systemd>=205, as of version 2015.8.12, 2016.3.3, and 2016.11.0, \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 the package manager commands spawned by Salt, when Salt updates itself (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 \fI\%config option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .UNINDENT .UNINDENT .sp Salt can manage software packages via the pkg state module, packages can be set up to be installed, latest, removed and purged. Package management declarations are typically rather simple: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed .ft P .fi .UNINDENT .UNINDENT .sp A more involved example involves pulling from a custom repository. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: pkgrepo.managed: \- name: ppa:wolfnet/logstash \- dist: precise \- file: /etc/apt/sources.list.d/logstash.list \- keyid: 28B04E4A \- keyserver: keyserver.ubuntu.com logstash: pkg.installed: \- fromrepo: ppa:wolfnet/logstash .ft P .fi .UNINDENT .UNINDENT .sp Multiple packages can also be installed with the use of the pkgs state module .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C dotdeb.repo: pkgrepo.managed: \- name: deb http://packages.dotdeb.org wheezy\-php55 all \- dist: wheezy\-php55 \- file: /etc/apt/sources.list.d/dotbeb.list \- keyid: 89DF5277 \- keyserver: keys.gnupg.net \- refresh_db: true php.packages: pkg.installed: \- fromrepo: wheezy\-php55 \- pkgs: \- php5\-fpm \- php5\-cli \- php5\-curl .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Make sure the package name has the correct case for package managers which are case\-sensitive (such as \fI\%pkgng\fP). .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.downloaded(name, version=None, pkgs=None, fromrepo=None, ignore_epoch=None, **kwargs) New in version 2017.7.0. .sp Ensure that the package is downloaded, and that it is the correct version (if specified). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Any argument which is either a) not explicitly defined for this state, or b) not a global state argument like \fBsaltenv\fP, or \fBreload_modules\fP, will be passed through to the call to \fBpkg.install\fP to download the package(s). For example, you can include a \fBdisablerepo\fP argument on platforms that use yum/dnf to disable that repo: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mypkg: pkg.downloaded: \- disablerepo: base,updates .ft P .fi .UNINDENT .UNINDENT .sp To see what is supported, check \fI\%this page\fP to find the documentation for your platform\(aqs \fBpkg\fP module, then look at the documentation for the \fBinstall\fP function. .sp Any argument that is passed through to the \fBinstall\fP function, which is not defined for that function, will be silently ignored. .UNINDENT .UNINDENT .sp Currently supported for the following pkg providers: \fI\%yum\fP, \fI\%zypper\fP and \fI\%apt\fP .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be downloaded. This parameter is ignored if either \(dqpkgs\(dq is used. Additionally, please note that this option can only be used to download packages from a software repository. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- .sp Download a specific version of a package. .sp \fBIMPORTANT:\fP .INDENT 2.0 .INDENT 3.5 As of version 2015.8.7, for distros which use yum/dnf, packages which have a version with a nonzero epoch (that is, versions which start with a number followed by a colon must have the epoch included when specifying the version number. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim\-enhanced: pkg.downloaded: \- version: 2:7.4.160\-1.el7 .ft P .fi .UNINDENT .UNINDENT .sp An \fBignore_epoch\fP argument has been added to which causes the epoch to be disregarded when the state checks to see if the desired version was installed. .sp You can install a specific version when using the \fBpkgs\fP argument by including the version after the package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C common_packages: pkg.downloaded: \- pkgs: \- unzip \- dos2unix \- salt\-minion: 2015.8.5\-1.el6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBresolve_capabilities\fP (\fI\%bool\fP) \-\- .sp Turn on resolving capabilities. This allow one to name \(dqprovides\(dq or alias names for packages. .sp New in version 2018.3.0. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C zsh: pkg.downloaded: \- version: 5.0.5\-4.63 \- fromrepo: \(dqmyrepository\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.group_installed(name, skip=None, include=None, **kwargs) New in version 2015.8.0. .sp Changed in version 2016.11.0: Added support in \fBpacman\fP .sp Changed in version 3006.2: For RPM\-based systems, support for \fBfromrepo\fP, \fBenablerepo\fP, and \fBdisablerepo\fP (as used in \fI\%pkg.install\fP) has been added. This allows one to, for example, use \fBenablerepo\fP to perform a group install from a repo that is otherwise disabled. .sp Ensure that an entire package group is installed. This state is currently only supported for the \fI\%yum\fP and \fBpacman\fP package managers. .INDENT 7.0 .TP .B skip Packages that would normally be installed by the package group (\(dqdefault\(dq packages), which should not be installed. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Load Balancer: pkg.group_installed: \- skip: \- piranha .ft P .fi .UNINDENT .UNINDENT .TP .B include Packages which are included in a group, which would not normally be installed by a \fByum groupinstall\fP (\(dqoptional\(dq packages). Note that this will not enforce group membership; if you include packages which are not members of the specified groups, they will still be installed. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Load Balancer: pkg.group_installed: \- include: \- haproxy .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2016.3.0: This option can no longer be passed as a comma\-separated list, it must now be passed as a list (as shown in the above example). .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The below options are only supported on RPM\-based systems .UNINDENT .UNINDENT .INDENT 7.0 .TP .B fromrepo Restrict \fByum groupinfo\fP to the specified repo(s). (e.g., \fByum \-\-disablerepo=\(aq*\(aq \-\-enablerepo=\(aqsomerepo\(aq\fP) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C MyGroup: pkg.group_installed: \- fromrepo: base,updates .ft P .fi .UNINDENT .UNINDENT .sp New in version 3006.2. .TP .B enablerepo (ignored if \fBfromrepo\fP is specified) Specify a disabled package repository (or repositories) to enable. (e.g., \fByum \-\-enablerepo=\(aqsomerepo\(aq\fP) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C MyGroup: pkg.group_installed: \- enablerepo: myrepo .ft P .fi .UNINDENT .UNINDENT .sp New in version 3006.2. .TP .B disablerepo (ignored if \fBfromrepo\fP is specified) Specify an enabled package repository (or repositories) to disable. (e.g., \fByum \-\-disablerepo=\(aqsomerepo\(aq\fP) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C MyGroup: pkg.group_installed: \- disablerepo: epel .ft P .fi .UNINDENT .UNINDENT .sp New in version 3006.2. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Because this is essentially a wrapper around \fI\%pkg.install\fP, any argument which can be passed to pkg.install may also be included here, and it will be passed on to the call to \fI\%pkg.install\fP\&. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.held(name, version=None, pkgs=None, replace=False, **kwargs) New in version 3005. .sp Set package in \(aqhold\(aq state, meaning it will not be changed. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be held. This parameter is ignored if \fBpkgs\fP is used. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- .sp Hold a specific version of a package. Full description of this parameter is in \fIinstalled\fP function. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This parameter make sense for Zypper\-based systems. Ignored for YUM/DNF and APT .UNINDENT .UNINDENT .IP \(bu 2 \fBpkgs\fP (\fI\%list\fP) \-\- .sp A list of packages to be held. All packages listed under \fBpkgs\fP will be held. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mypkgs: pkg.held: \- pkgs: \- foo \- bar: 1.2.3\-4 \- baz .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 For Zypper\-based systems the package could be held for the version specified. YUM/DNF and APT ingore it. .UNINDENT .UNINDENT .IP \(bu 2 \fBreplace\fP (\fI\%bool\fP) \-\- Force replacement of existings holds with specified. By default, this parameter is set to \fBFalse\fP\&. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.installed(name, version=None, refresh=None, fromrepo=None, skip_verify=False, skip_suggestions=False, pkgs=None, sources=None, allow_updates=False, pkg_verify=False, normalize=True, ignore_epoch=None, reinstall=False, update_holds=False, **kwargs) Changed in version 3007.0. .sp Ensure that the package is installed, and that it is the correct version (if specified). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Any argument which is either a) not explicitly defined for this state, or b) not a global state argument like \fBsaltenv\fP, or \fBreload_modules\fP, will be passed through to the call to \fBpkg.install\fP to install the package(s). For example, you can include a \fBdisablerepo\fP argument on platforms that use yum/dnf to disable that repo: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mypkg: pkg.installed: \- disablerepo: base,updates .ft P .fi .UNINDENT .UNINDENT .sp To see what is supported, check \fI\%this page\fP to find the documentation for your platform\(aqs \fBpkg\fP module, then look at the documentation for the \fBinstall\fP function. .sp Any argument that is passed through to the \fBinstall\fP function, which is not defined for that function, will be silently ignored. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 In Windows, some packages are installed using the task manager. The Salt minion installer does this. In that case, there is no way to know if the package installs correctly. All that can be reported is that the task that launches the installer started successfully. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be installed. This parameter is ignored if either \(dqpkgs\(dq or \(dqsources\(dq is used. 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 \(dqsources\(dq option detailed below. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- .sp Install a specific version of a package. This option is ignored if \(dqsources\(dq is used. Currently, this option is supported for the following pkg providers: \fI\%apt\fP, \fBebuild\fP, \fBpacman\fP, \fI\%pkgin\fP, \fI\%win_pkg\fP, \fI\%yum\fP, and \fI\%zypper\fP\&. The version number includes the release designation where applicable, to allow Salt to target a specific release of a given version. When in doubt, using the \fBpkg.latest_version\fP function for an uninstalled package will tell you the version available. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C # salt myminion pkg.latest_version vim\-enhanced myminion: 2:7.4.160\-1.el7 .ft P .fi .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 2.0 .INDENT 3.5 As of version 2015.8.7, for distros which use yum/dnf, packages which have a version with a nonzero epoch (that is, versions which start with a number followed by a colon like in the \fBpkg.latest_version\fP output above) must have the epoch included when specifying the version number. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim\-enhanced: pkg.installed: \- version: 2:7.4.160\-1.el7 .ft P .fi .UNINDENT .UNINDENT .sp In version 2015.8.9, an \fBignore_epoch\fP argument has been added to \fI\%pkg.installed\fP, \fI\%pkg.removed\fP, and \fI\%pkg.purged\fP states, which causes the epoch to be disregarded when the state checks to see if the desired version was installed. .UNINDENT .UNINDENT .sp Also, while this function is not yet implemented for all pkg frontends, \fI\%pkg.list_repo_pkgs\fP will show all versions available in the various repositories for a given package, irrespective of whether or not it is installed. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C # salt myminion pkg.list_repo_pkgs bash myminion: \-\-\-\-\-\-\-\-\-\- bash: \- 4.2.46\-21.el7_3 \- 4.2.46\-20.el7_2 .ft P .fi .UNINDENT .UNINDENT .sp This function was first added for \fI\%pkg.list_repo_pkgs\fP in 2014.1.0, and was expanded to \fI\%Debian/Ubuntu\fP and \fBArch Linux\fP\-based distros in the 2017.7.0 release. .sp The version strings returned by either of these functions can be used as version specifiers in pkg states. .sp You can install a specific version when using the \fBpkgs\fP argument by including the version after the package: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C common_packages: pkg.installed: \- pkgs: \- unzip \- dos2unix \- salt\-minion: 2015.8.5\-1.el6 .ft P .fi .UNINDENT .UNINDENT .sp If the version given is the string \fBlatest\fP, the latest available package version will be installed à la \fBpkg.latest\fP\&. .sp \fBWILDCARD VERSIONS\fP .sp As of the 2017.7.0 release, this state now supports wildcards in package versions for SUSE SLES/Leap/Tumbleweed, Debian/Ubuntu, RHEL/CentOS, Arch Linux, and their derivatives. Using wildcards can be useful for packages where the release name is built into the version in some way, such as for RHEL/CentOS which typically has version numbers like \fB1.2.34\-5.el7\fP\&. An example of the usage for this would be: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mypkg: pkg.installed: \- version: \(aq1.2.34*\(aq .ft P .fi .UNINDENT .UNINDENT .sp Keep in mind that using wildcard versions will result in a slower state run since Salt must gather the available versions of the specified packages and figure out which of them match the specified wildcard expression. .IP \(bu 2 \fBrefresh\fP (\fI\%bool\fP) \-\- .sp This parameter controls whether or not the package repo database is updated prior to installing the requested package(s). .sp If \fBTrue\fP, the package database will be refreshed (\fBapt\-get update\fP or equivalent, depending on platform) before installing. .sp If \fBFalse\fP, the package database will \fInot\fP be refreshed before installing. .sp If unset, then Salt treats package database refreshes differently depending on whether or not a \fBpkg\fP state has been executed already during the current Salt run. Once a refresh has been performed in a \fBpkg\fP state, for the remainder of that Salt run no other refreshes will be performed for \fBpkg\fP states which do not explicitly set \fBrefresh\fP to \fBTrue\fP\&. This prevents needless additional refreshes from slowing down the Salt run. .IP \(bu 2 \fBcache_valid_time\fP (\fI\%str\fP) \-\- .sp New in version 2016.11.0. .sp This parameter sets the value in seconds after which the cache is marked as invalid, and a cache update is necessary. This overwrites the \fBrefresh\fP parameter\(aqs default behavior. .sp Example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: \- fromrepo: mycustomrepo \- skip_verify: True \- skip_suggestions: True \- version: 2.0.6~ubuntu3 \- refresh: True \- cache_valid_time: 300 \- allow_updates: True \- hold: False .ft P .fi .UNINDENT .UNINDENT .sp In this case, a refresh will not take place for 5 minutes since the last \fBapt\-get update\fP was executed on the system. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This parameter is available only on Debian based distributions and has no effect on the rest. .UNINDENT .UNINDENT .IP \(bu 2 \fBfromrepo\fP (\fI\%str\fP) \-\- .sp Specify a repository from which to install .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 Distros which use APT (Debian, Ubuntu, etc.) do not have a concept of repositories, in the same way as YUM\-based distros do. When a source is added, it is assigned to a given release. Consider the following source configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C deb http://ppa.launchpad.net/saltstack/salt/ubuntu precise main .ft P .fi .UNINDENT .UNINDENT .sp The packages provided by this source would be made available via the \fBprecise\fP release, therefore \fBfromrepo\fP would need to be set to \fBprecise\fP for Salt to install the package from this source. .sp Having multiple sources in the same release may result in the default install candidate being newer than what is desired. If this is the case, the desired version must be specified using the \fBversion\fP parameter. .sp If the \fBpkgs\fP parameter is being used to install multiple packages in the same state, then instead of using \fBversion\fP, use the method of version specification described in the \fBMultiple Package Installation Options\fP section below. .sp Running the shell command \fBapt\-cache policy pkgname\fP on a minion can help elucidate the APT configuration and aid in properly configuring states: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root@saltmaster:~# salt ubuntu01 cmd.run \(aqapt\-cache policy ffmpeg\(aq ubuntu01: ffmpeg: Installed: (none) Candidate: 7:0.10.11\-1~precise1 Version table: 7:0.10.11\-1~precise1 0 500 http://ppa.launchpad.net/jon\-severinsson/ffmpeg/ubuntu/ precise/main amd64 Packages 4:0.8.10\-0ubuntu0.12.04.1 0 500 http://us.archive.ubuntu.com/ubuntu/ precise\-updates/main amd64 Packages 500 http://security.ubuntu.com/ubuntu/ precise\-security/main amd64 Packages 4:0.8.1\-0ubuntu1 0 500 http://us.archive.ubuntu.com/ubuntu/ precise/main amd64 Packages .ft P .fi .UNINDENT .UNINDENT .sp The release is located directly after the source\(aqs URL. The actual release name is the part before the slash, so to install version \fB4:0.8.10\-0ubuntu0.12.04.1\fP either \fBprecise\-updates\fP or \fBprecise\-security\fP could be used for the \fBfromrepo\fP value. .UNINDENT .UNINDENT .IP \(bu 2 \fBskip_verify\fP (\fI\%bool\fP) \-\- Skip the GPG verification check for the package to be installed .IP \(bu 2 \fBskip_suggestions\fP (\fI\%bool\fP) \-\- .sp Force strict package naming. Disables lookup of package alternatives. .sp New in version 2014.1.1. .IP \(bu 2 \fBresolve_capabilities\fP (\fI\%bool\fP) \-\- .sp Turn on resolving capabilities. This allow one to name \(dqprovides\(dq or alias names for packages. .sp New in version 2018.3.0. .IP \(bu 2 \fBallow_updates\fP (\fI\%bool\fP) \-\- .sp Allow the package to be updated outside Salt\(aqs control (e.g. auto updates on Windows). This means a package on the Minion can have a newer version than the latest available in the repository without enforcing a re\-installation of the package. .sp New in version 2014.7.0. .sp Example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: \- fromrepo: mycustomrepo \- skip_verify: True \- skip_suggestions: True \- version: 2.0.6~ubuntu3 \- refresh: True \- allow_updates: True \- hold: False .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBpkg_verify\fP (\fI\%bool\fP) \-\- .sp New in version 2014.7.0. .sp Use pkg.verify to check if already installed packages require reinstallion. Requested packages that are already installed and not targeted for up\- or downgrade are verified with pkg.verify to determine if any file installed by the package have been modified or if package dependencies are not fulfilled. \fBignore_types\fP and \fBverify_options\fP can be passed to pkg.verify. See examples below. Currently, this option is supported for the following pkg providers: \fI\%yum\fP, \fI\%zypperpkg\fP\&. .sp Examples: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: \- version: 2.2.15\-30.el6.centos \- pkg_verify: True .ft P .fi .UNINDENT .UNINDENT .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mypkgs: pkg.installed: \- pkgs: \- foo \- bar: 1.2.3\-4 \- baz \- pkg_verify: \- ignore_types: \- config \- doc .ft P .fi .UNINDENT .UNINDENT .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mypkgs: pkg.installed: \- pkgs: \- foo \- bar: 1.2.3\-4 \- baz \- pkg_verify: \- ignore_types: \- config \- doc \- verify_options: \- nodeps \- nofiledigest .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_types\fP (\fI\%list\fP) \-\- .sp List of types to ignore when verifying the package .sp New in version 2014.7.0. .IP \(bu 2 \fBverify_options\fP (\fI\%list\fP) \-\- .sp List of additional options to pass when verifying the package. These options will be added to the \fBrpm \-V\fP command, prepended with \fB\-\-\fP (for example, when \fBnodeps\fP is passed in this option, \fBrpm \-V\fP will be run with \fB\-\-nodeps\fP). .sp New in version 2016.11.0. .IP \(bu 2 \fBnormalize\fP (\fI\%bool\fP) \-\- .sp Normalize the package name by removing the architecture, if the architecture of the package is different from the architecture of the operating system. The ability to disable this behavior is useful for poorly\-created packages which include the architecture as an actual part of the name, such as kernel modules which match a specific kernel version. .sp New in version 2014.7.0. .sp Example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C gpfs.gplbin\-2.6.32\-279.31.1.el6.x86_64: pkg.installed: \- normalize: False .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBignore_epoch\fP (\fI\%bool\fP) \-\- .sp If this option is not explicitly set, and there is no epoch in the desired package version, the epoch will be implicitly ignored. Set this argument to \fBTrue\fP to explicitly ignore the epoch, and \fBFalse\fP to strictly enforce it. .sp New in version 2015.8.9. .sp Changed in version 3001: In prior releases, the default behavior was to strictly enforce epochs unless this argument was set to \fBTrue\fP\&. .UNINDENT .UNINDENT .nf .fi .sp .sp \fBMULTIPLE PACKAGE INSTALLATION OPTIONS:\fP .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpkgs\fP (\fI\%list\fP) \-\- .sp A list of packages to install from a software repository. All packages listed under \fBpkgs\fP will be installed via a single command. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mypkgs: pkg.installed: \- pkgs: \- foo \- bar \- baz \- hold: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP For \fI\%apt\fP, \fBebuild\fP, \fBpacman\fP, \fI\%winrepo\fP, \fI\%yum\fP, and \fI\%zypper\fP, version numbers can be specified in the \fBpkgs\fP argument. For example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mypkgs: pkg.installed: \- pkgs: \- foo \- bar: 1.2.3\-4 \- baz .ft P .fi .UNINDENT .UNINDENT .sp Additionally, \fBebuild\fP, \fBpacman\fP, \fI\%zypper\fP, \fI\%yum/dnf\fP, and \fI\%apt\fP support the \fB<\fP, \fB<=\fP, \fB>=\fP, and \fB>\fP operators for more control over what versions will be installed. For example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mypkgs: pkg.installed: \- pkgs: \- foo \- bar: \(aq>=1.2.3\-4\(aq \- baz .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP When using comparison operators, the expression must be enclosed in quotes to avoid a YAML render error. .sp With \fBebuild\fP is also possible to specify a use flag list and/or if the given packages should be in package.accept_keywords file and/or the overlay from which you want the package to be installed. For example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mypkgs: pkg.installed: \- pkgs: \- foo: \(aq~\(aq \- bar: \(aq~>=1.2:slot::overlay[use,\-otheruse]\(aq \- baz .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBsources\fP (\fI\%list\fP) \-\- .sp A list of packages to install, along with the source URI or local path from which to install each package. In the example below, \fBfoo\fP, \fBbar\fP, \fBbaz\fP, etc. refer to the name of the package, as it would appear in the output of the \fBpkg.version\fP or \fBpkg.list_pkgs\fP salt CLI commands. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mypkgs: pkg.installed: \- sources: \- foo: salt://rpms/foo.rpm \- bar: http://somesite.org/bar.rpm \- baz: ftp://someothersite.org/baz.rpm \- qux: /minion/path/to/qux.rpm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBPLATFORM\-SPECIFIC ARGUMENTS\fP .sp These are specific to each OS. If it does not apply to the execution module for your OS, it is ignored. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhold\fP (\fI\%bool\fP) \-\- .sp Force the package to be held at the current installed version. .sp Supported on YUM/DNF & APT based systems. .sp New in version 2014.7.0. .sp Supported on Zypper\-based systems. .sp New in version 3003. .IP \(bu 2 \fBupdate_holds\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP, and this function would update the package version, any packages which are being held will be temporarily unheld so that they can be updated. Otherwise, if this function attempts to update a held package, the held package(s) will be skipped and the state will fail. By default, this parameter is set to \fBFalse\fP\&. .sp Supported on YUM/DNF & APT based systems. .sp New in version 2016.11.0. .sp Supported on Zypper\-based systems. .sp New in version 3003. .IP \(bu 2 \fBnames\fP (\fI\%list\fP) \-\- .sp A list of packages to install from a software repository. Each package will be installed individually by the package manager. .sp \fBWARNING:\fP .INDENT 2.0 .INDENT 3.5 Unlike \fBpkgs\fP, the \fBnames\fP parameter cannot specify a version. In addition, it makes a separate call to the package management frontend to install each package, whereas \fBpkgs\fP makes just a single call. It is therefore recommended to use \fBpkgs\fP instead of \fBnames\fP to install multiple packages, both for the additional features and the performance improvement that it brings. .UNINDENT .UNINDENT .IP \(bu 2 \fBinstall_recommends\fP (\fI\%bool\fP) \-\- .sp Whether to install the packages marked as recommended. Default is \fBTrue\fP\&. Currently only works with APT\-based systems. .sp New in version 2015.5.0. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: \- install_recommends: False .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBonly_upgrade\fP (\fI\%bool\fP) \-\- .sp Only upgrade the packages, if they are already installed. Default is \fBFalse\fP\&. Currently only works with APT\-based systems. .sp New in version 2015.5.0. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: \- only_upgrade: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 If this parameter is set to True and the package is not already installed, the state will fail. .UNINDENT .UNINDENT .IP \(bu 2 \fBreport_reboot_exit_codes\fP (\fI\%bool\fP) \-\- .sp If the installer exits with a recognized exit code indicating that a reboot is required, the module function .INDENT 2.0 .INDENT 3.5 \fIwin_system.set_reboot_required_witnessed\fP .UNINDENT .UNINDENT .sp will be called, preserving the knowledge of this event for the remainder of the current boot session. For the time being, \fB3010\fP is the only recognized exit code, but this is subject to future refinement. The value of this param defaults to \fBTrue\fP\&. This parameter has no effect on non\-Windows systems. .sp New in version 2016.11.0. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C ms vcpp installed: pkg.installed: \- name: ms\-vcpp \- version: 10.0.40219 \- report_reboot_exit_codes: False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .TP .B Returns A dictionary containing the state of the software installation .TP .B Rtype dict .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fBpkg.installed\fP state supports the usage of \fBreload_modules\fP\&. This functionality allows you to force Salt to reload all modules. In many 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 the package which was installed. However, there are some edge cases where this may not be the case, which is what \fBreload_modules\fP is meant to resolve. .sp You should only use \fBreload_modules\fP if your \fBpkg.installed\fP does some sort of installation where if you do not reload the modules future items in your state which rely on the software being installed will fail. Please see the \fI\%Reloading Modules\fP documentation for more information. .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 unless and onlyif .sp If running pkg commands together with \fI\%aggregate\fP isn\(aqt an option, you can use the \fI\%creates\fP, \fI\%unless\fP, or \fI\%onlyif\fP syntax to skip a full package run. This can be helpful in large environments with multiple states that include requisites for packages to be installed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Using creates for a simple single\-factor check install_nginx: pkg.installed: \- name: nginx \- creates: \- /etc/nginx/nginx.conf .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Using file.file_exists for a single\-factor check install_nginx: pkg.installed: \- name: nginx \- unless: \- fun: file.file_exists args: \- /etc/nginx/nginx.conf # Using unless with a shell test install_nginx: pkg.installed: \- name: nginx \- unless: test \-f /etc/nginx/nginx.conf .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Using file.search for a two\-factor check install_nginx: pkg.installed: \- name: nginx \- unless: \- fun: file.search args: \- /etc/nginx/nginx.conf \- \(aquser www\-data;\(aq .ft P .fi .UNINDENT .UNINDENT .sp The above examples use different methods to reasonably ensure that a package has already been installed. First, with checking for a file that would be created with the package. Second, by checking for specific text within a file that would be created or managed by salt. With these requisists satisfied, creates/unless will return \fBTrue\fP and the \fBpkg.installed\fP state will be skipped. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Example of state run without unless used salt \(aqsaltdev\(aq state.apply nginx saltdev: \-\-\-\-\-\-\-\-\-\- ID: install_nginx Function: pkg.installed Name: nginx Result: True Comment: All specified packages are already installed Started: 20:11:56.388331 Duration: 4290.0 ms Changes: # Example of state run using unless requisite salt \(aqsaltdev\(aq state.apply nginx saltdev: \-\-\-\-\-\-\-\-\-\- ID: install_nginx Function: pkg.installed Name: nginx Result: True Comment: unless condition is true Started: 20:10:50.659215 Duration: 1530.0 ms Changes: .ft P .fi .UNINDENT .UNINDENT .sp The result is a reduction of almost 3 seconds. In larger environments, small reductions in waiting time can add up. .sp \fI\%Unless Requisite\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.latest(name, refresh=None, fromrepo=None, skip_verify=False, pkgs=None, watch_flags=True, **kwargs) Changed in version 3007.0. .sp Ensure that the named package is installed and the latest available package. If the package can be updated, this state function will update the package. Generally it is better for the \fI\%installed\fP function to be used, as \fI\%latest\fP will update the package whenever a new package is available. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Any argument which is either a) not explicitly defined for this state, or b) not a global state argument like \fBsaltenv\fP, or \fBreload_modules\fP, will be passed through to the call to \fBpkg.install\fP to install the package(s). For example, you can include a \fBdisablerepo\fP argument on platforms that use yum/dnf to disable that repo: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mypkg: pkg.latest: \- disablerepo: base,updates .ft P .fi .UNINDENT .UNINDENT .sp To see what is supported, check \fI\%this page\fP to find the documentation for your platform\(aqs \fBpkg\fP module, then look at the documentation for the \fBinstall\fP function. .sp Any argument that is passed through to the \fBinstall\fP function, which is not defined for that function, will be silently ignored. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the package to maintain at the latest available version. This parameter is ignored if \(dqpkgs\(dq is used. .TP .B fromrepo Specify a repository from which to install .TP .B skip_verify Skip the GPG verification check for the package to be installed .TP .B refresh This parameter controls whether or not the package repo database is updated prior to checking for the latest available version of the requested packages. .sp If \fBTrue\fP, the package database will be refreshed (\fBapt\-get update\fP or equivalent, depending on platform) before checking for the latest available version of the requested packages. .sp If \fBFalse\fP, the package database will \fInot\fP be refreshed before checking. .sp If unset, then Salt treats package database refreshes differently depending on whether or not a \fBpkg\fP state has been executed already during the current Salt run. Once a refresh has been performed in a \fBpkg\fP state, for the remainder of that Salt run no other refreshes will be performed for \fBpkg\fP states which do not explicitly set \fBrefresh\fP to \fBTrue\fP\&. This prevents needless additional refreshes from slowing down the Salt run. .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcache_valid_time\fP (\fI\%str\fP) \-\- .sp New in version 2016.11.0. .sp This parameter sets the value in seconds after which the cache is marked as invalid, and a cache update is necessary. This overwrites the \fBrefresh\fP parameter\(aqs default behavior. .sp Example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.latest: \- refresh: True \- cache_valid_time: 300 .ft P .fi .UNINDENT .UNINDENT .sp In this case, a refresh will not take place for 5 minutes since the last \fBapt\-get update\fP was executed on the system. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This parameter is available only on Debian based distributions and has no effect on the rest. .UNINDENT .UNINDENT .IP \(bu 2 \fBresolve_capabilities\fP (\fI\%bool\fP) \-\- .sp Turn on resolving capabilities. This allow one to name \(dqprovides\(dq or alias names for packages. .sp New in version 2018.3.0. .UNINDENT .UNINDENT .sp Multiple Package Installation Options: .sp (Not yet supported for: FreeBSD, OpenBSD, MacOS, and Solaris pkgutil) .INDENT 7.0 .TP .B pkgs A list of packages to maintain at the latest available version. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mypkgs: pkg.latest: \- pkgs: \- foo \- bar \- baz .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B install_recommends Whether to install the packages marked as recommended. Default is \fBTrue\fP\&. Currently only works with APT\-based systems. .sp New in version 2015.5.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.latest: \- install_recommends: False .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B only_upgrade Only upgrade the packages, if they are already installed. Default is \fBFalse\fP\&. Currently only works with APT\-based systems. .sp New in version 2015.5.0. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.latest: \- only_upgrade: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If this parameter is set to True and the package is not already installed, the state will fail. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B report_reboot_exit_codes If the installer exits with a recognized exit code indicating that a reboot is required, the module function .INDENT 7.0 .INDENT 3.5 \fIwin_system.set_reboot_required_witnessed\fP .UNINDENT .UNINDENT .sp will be called, preserving the knowledge of this event for the remainder of the current boot session. For the time being, \fB3010\fP is the only recognized exit code, but this is subject to future refinement. The value of this param defaults to \fBTrue\fP\&. This parameter has no effect on non\-Windows systems. .sp New in version 2016.11.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ms vcpp installed: pkg.latest: \- name: ms\-vcpp \- report_reboot_exit_codes: False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.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 .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.mod_beacon(name, **kwargs) Create a beacon to monitor a package or packages based on a beacon state argument. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBbeacon\fP state argument for supported state functions. It should not be called directly. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.mod_watch(name, **kwargs) Install/reinstall a package based on a watch requisite .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBwatch\fP \fI\%requisite\fP\&. It should not be called directly. .sp Parameters for this function should be set by the state being triggered. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.patch_downloaded(name, advisory_ids=None, **kwargs) New in version 2017.7.0. .sp Ensure that packages related to certain advisory ids are downloaded. .sp Currently supported for the following pkg providers: \fI\%yum\fP and \fI\%zypper\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C preparing\-to\-fix\-issues: pkg.patch_downloaded: \- advisory_ids: \- SUSE\-SLE\-SERVER\-12\-SP2\-2017\-185 \- SUSE\-SLE\-SERVER\-12\-SP2\-2017\-150 \- SUSE\-SLE\-SERVER\-12\-SP2\-2017\-120 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.patch_installed(name, advisory_ids=None, downloadonly=None, **kwargs) New in version 2017.7.0. .sp Ensure that packages related to certain advisory ids are installed. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Any argument which is either a) not explicitly defined for this state, or b) not a global state argument like \fBsaltenv\fP, or \fBreload_modules\fP, will be passed through to the call to \fBpkg.install\fP to install the patch(es). .sp To see what is supported, check \fI\%this page\fP to find the documentation for your platform\(aqs \fBpkg\fP module, then look at the documentation for the \fBinstall\fP function. .sp Any argument that is passed through to the \fBinstall\fP function, which is not defined for that function, will be silently ignored. .UNINDENT .UNINDENT .sp Currently supported for the following pkg providers: \fI\%yum\fP and \fI\%zypper\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C issue\-foo\-fixed: pkg.patch_installed: \- advisory_ids: \- SUSE\-SLE\-SERVER\-12\-SP2\-2017\-185 \- SUSE\-SLE\-SERVER\-12\-SP2\-2017\-150 \- SUSE\-SLE\-SERVER\-12\-SP2\-2017\-120 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.purged(name, version=None, pkgs=None, normalize=True, ignore_epoch=None, **kwargs) Verify that a package is not installed, calling \fBpkg.purge\fP if necessary to purge the package. All configuration files are also removed. .INDENT 7.0 .TP .B name The name of the package to be purged. .TP .B version The version of the package that should be removed. Don\(aqt do anything if the package is installed with an unmatching version. .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 As of version 2015.8.7, for distros which use yum/dnf, packages which have a version with a nonzero epoch (that is, versions which start with a number followed by a colon like in the example above) must have the epoch included when specifying the version number. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim\-enhanced: pkg.purged: \- version: 2:7.4.160\-1.el7 .ft P .fi .UNINDENT .UNINDENT .sp In version 2015.8.9, an \fBignore_epoch\fP argument has been added to \fI\%pkg.installed\fP, \fI\%pkg.removed\fP, and \fI\%pkg.purged\fP states, which causes the epoch to be disregarded when the state checks to see if the desired version was installed. If \fBignore_epoch\fP was not set to \fBTrue\fP, and instead of \fB2:7.4.160\-1.el7\fP a version of \fB7.4.160\-1.el7\fP were used, this state would report success since the actual installed version includes the epoch, and the specified version would not match. .UNINDENT .UNINDENT .TP .B normalize True Normalize the package name by removing the architecture, if the architecture of the package is different from the architecture of the operating system. The ability to disable this behavior is useful for poorly\-created packages which include the architecture as an actual part of the name, such as kernel modules which match a specific kernel version. .sp New in version 2015.8.0. .TP .B ignore_epoch None If this option is not explicitly set, and there is no epoch in the desired package version, the epoch will be implicitly ignored. Set this argument to \fBTrue\fP to explicitly ignore the epoch, and \fBFalse\fP to strictly enforce it. .sp New in version 2015.8.9. .sp Changed in version 3001: In prior releases, the default behavior was to strictly enforce epochs unless this argument was set to \fBTrue\fP\&. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to purge. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. It accepts version numbers as well. .sp New in version 0.16.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.removed(name, version=None, pkgs=None, normalize=True, ignore_epoch=None, **kwargs) Verify that a package is not installed, calling \fBpkg.remove\fP if necessary to remove the package. .INDENT 7.0 .TP .B name The name of the package to be removed. .TP .B version The version of the package that should be removed. Don\(aqt do anything if the package is installed with an unmatching version. .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 As of version 2015.8.7, for distros which use yum/dnf, packages which have a version with a nonzero epoch (that is, versions which start with a number followed by a colon like in the example above) must have the epoch included when specifying the version number. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim\-enhanced: pkg.removed: \- version: 2:7.4.160\-1.el7 .ft P .fi .UNINDENT .UNINDENT .sp In version 2015.8.9, an \fBignore_epoch\fP argument has been added to \fI\%pkg.installed\fP, \fI\%pkg.removed\fP, and \fI\%pkg.purged\fP states, which causes the epoch to be disregarded when the state checks to see if the desired version was installed. If \fBignore_epoch\fP was not set to \fBTrue\fP, and instead of \fB2:7.4.160\-1.el7\fP a version of \fB7.4.160\-1.el7\fP were used, this state would report success since the actual installed version includes the epoch, and the specified version would not match. .UNINDENT .UNINDENT .TP .B normalize True Normalize the package name by removing the architecture, if the architecture of the package is different from the architecture of the operating system. The ability to disable this behavior is useful for poorly\-created packages which include the architecture as an actual part of the name, such as kernel modules which match a specific kernel version. .sp New in version 2015.8.0. .TP .B ignore_epoch None If this option is not explicitly set, and there is no epoch in the desired package version, the epoch will be implicitly ignored. Set this argument to \fBTrue\fP to explicitly ignore the epoch, and \fBFalse\fP to strictly enforce it. .sp New in version 2015.8.9. .sp Changed in version 3001: In prior releases, the default behavior was to strictly enforce epochs unless this argument was set to \fBTrue\fP\&. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to remove. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. It accepts version numbers as well. .sp New in version 0.16.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.unheld(name, version=None, pkgs=None, all=False, **kwargs) New in version 3005. .sp Unset package from \(aqhold\(aq state, to allow operations with the package. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the package to be unheld. This parameter is ignored if \fBpkgs\fP is used. .IP \(bu 2 \fBversion\fP (\fI\%str\fP) \-\- .sp Unhold a specific version of a package. Full description of this parameter is in \fIinstalled\fP function. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 This parameter make sense for Zypper\-based systems. Ignored for YUM/DNF and APT .UNINDENT .UNINDENT .IP \(bu 2 \fBpkgs\fP (\fI\%list\fP) \-\- .sp A list of packages to be unheld. All packages listed under \fBpkgs\fP will be unheld. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mypkgs: pkg.unheld: \- pkgs: \- foo \- bar: 1.2.3\-4 \- baz .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 For Zypper\-based systems the package could be held for the version specified. YUM/DNF and APT ingore it. For \fBunheld\fP there is no need to specify the exact version to be unheld. .UNINDENT .UNINDENT .IP \(bu 2 \fBall\fP (\fI\%bool\fP) \-\- Force removing of all existings locks. By default, this parameter is set to \fBFalse\fP\&. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.uptodate(name, refresh=False, pkgs=None, **kwargs) New in version 2014.7.0. .sp Changed in version 2018.3.0: Added support for the \fBpkgin\fP provider. .sp Verify that the system is completely up to date. .INDENT 7.0 .TP .B :param str name The name has no functional value and is only used as a tracking reference .TP .B :param bool refresh refresh the package database before checking for new upgrades .TP .B :param list pkgs list of packages to upgrade .UNINDENT .INDENT 7.0 .TP .B Parameters \fBresolve_capabilities\fP (\fI\%bool\fP) \-\- .sp Turn on resolving capabilities. This allow one to name \(dqprovides\(dq or alias names for packages. .sp New in version 2018.3.0. .UNINDENT .INDENT 7.0 .TP .B :param kwargs Any keyword arguments to pass through to the \fBpkg\fP module. .sp For example, for apt systems: \fIdist_upgrade\fP, \fIcache_valid_time\fP, \fIforce_conf_new\fP .sp New in version 2015.5.0. .UNINDENT .UNINDENT .SS salt.states.pkgbuild .sp The pkgbuild state is the front of Salt package building backend. It automatically builds DEB and RPM packages from specified sources .sp New in version 2015.8.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt_2015.5.2: pkgbuild.built: \- runas: thatch \- results: \- salt\-2015.5.2\-2.el7.centos.noarch.rpm \- salt\-api\-2015.5.2\-2.el7.centos.noarch.rpm \- salt\-cloud\-2015.5.2\-2.el7.centos.noarch.rpm \- salt\-master\-2015.5.2\-2.el7.centos.noarch.rpm \- salt\-minion\-2015.5.2\-2.el7.centos.noarch.rpm \- salt\-ssh\-2015.5.2\-2.el7.centos.noarch.rpm \- salt\-syndic\-2015.5.2\-2.el7.centos.noarch.rpm \- dest_dir: /tmp/pkg \- spec: salt://pkg/salt/spec/salt.spec \- template: jinja \- deps: \- salt://pkg/salt/sources/required_dependency.rpm \- tgt: epel\-7\-x86_64 \- sources: \- salt://pkg/salt/sources/logrotate.salt \- salt://pkg/salt/sources/README.fedora \- salt://pkg/salt/sources/salt\-2015.5.2.tar.gz \- salt://pkg/salt/sources/salt\-2015.5.2\-tests.patch \- salt://pkg/salt/sources/salt\-api \- salt://pkg/salt/sources/salt\-api.service \- salt://pkg/salt/sources/salt\-master \- salt://pkg/salt/sources/salt\-master.service \- salt://pkg/salt/sources/salt\-minion \- salt://pkg/salt/sources/salt\-minion.service \- salt://pkg/salt/sources/saltpkg.sls \- salt://pkg/salt/sources/salt\-syndic \- salt://pkg/salt/sources/salt\-syndic.service \- salt://pkg/salt/sources/SaltTesting\-2015.5.8.tar.gz /tmp/pkg: pkgbuild.repo .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkgbuild.built(name, runas, dest_dir, spec, sources, tgt, template=None, deps=None, env=None, results=None, force=False, saltenv=\(aqbase\(aq, log_dir=\(aq/var/log/salt/pkgbuild\(aq) Ensure that the named package is built and exists in the named directory .INDENT 7.0 .TP .B name The name to track the build, the name value is otherwise unused .TP .B runas The user to run the build process as .TP .B dest_dir The directory on the minion to place the built package(s) .TP .B spec The location of the spec file (used for rpms) .TP .B sources The list of package sources .TP .B tgt The target platform to run the build on .TP .B template Run the spec file through a templating engine .sp Changed in version 2015.8.2: This argument is now optional, allowing for no templating engine to be used if none is desired. .TP .B deps Packages required to ensure that the named package is built can be hosted on either the salt master server or on an HTTP or FTP server. Both HTTPS and HTTP are supported as well as downloading directly from Amazon S3 compatible URLs with both pre\-configured and automatic IAM credentials .TP .B env A dictionary of environment variables to be set prior to execution. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- env: DEB_BUILD_OPTIONS: \(aqnocheck\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The above illustrates a common PyYAML pitfall, that \fByes\fP, \fBno\fP, \fBon\fP, \fBoff\fP, \fBtrue\fP, and \fBfalse\fP are all loaded as boolean \fBTrue\fP and \fBFalse\fP values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found \fI\%here\fP\&. .UNINDENT .UNINDENT .TP .B results The names of the expected rpms that will be built .TP .B force False If \fBTrue\fP, packages will be built even if they already exist in the \fBdest_dir\fP\&. This is useful when building a package for continuous or nightly package builds. .sp New in version 2015.8.2. .TP .B saltenv The saltenv to use for files downloaded from the salt filesever .TP .B log_dir /var/log/salt/rpmbuild Root directory for log files created from the build. Logs will be organized by package name, version, OS release, and CPU architecture under this directory. .sp New in version 2015.8.2. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkgbuild.repo(name, keyid=None, env=None, use_passphrase=False, gnupghome=\(aq/etc/salt/gpgkeys\(aq, runas=\(aqbuilder\(aq, timeout=15.0) Make a package repository and optionally sign it and packages present .sp The name is directory to turn into a repo. This state is best used with onchanges linked to your package building states. .INDENT 7.0 .TP .B name The directory to find packages that will be in the repository .TP .B keyid Changed in version 2016.3.0. .sp Optional Key ID to use in signing packages and repository. Utilizes Public and Private keys associated with keyid which have been loaded into the minion\(aqs Pillar data. .sp For example, contents from a Pillar data file with named Public and Private keys as follows: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C gpg_pkg_priv_key: | \-\-\-\-\-BEGIN PGP PRIVATE KEY BLOCK\-\-\-\-\- Version: GnuPG v1 lQO+BFciIfQBCADAPCtzx7I5Rl32escCMZsPzaEKWe7bIX1em4KCKkBoX47IG54b w82PCE8Y1jF/9Uk2m3RKVWp3YcLlc7Ap3gj6VO4ysvVz28UbnhPxsIkOlf2cq8qc . . Ebe+8JCQTwqSXPRTzXmy/b5WXDeM79CkLWvuGpXFor76D+ECMRPv/rawukEcNptn R5OmgHqvydEnO4pWbn8JzQO9YX/Us0SMHBVzLC8eIi5ZIopzalvX =JvW8 \-\-\-\-\-END PGP PRIVATE KEY BLOCK\-\-\-\-\- gpg_pkg_priv_keyname: gpg_pkg_key.pem gpg_pkg_pub_key: | \-\-\-\-\-BEGIN PGP PUBLIC KEY BLOCK\-\-\-\-\- Version: GnuPG v1 mQENBFciIfQBCADAPCtzx7I5Rl32escCMZsPzaEKWe7bIX1em4KCKkBoX47IG54b w82PCE8Y1jF/9Uk2m3RKVWp3YcLlc7Ap3gj6VO4ysvVz28UbnhPxsIkOlf2cq8qc . . bYP7t5iwJmQzRMyFInYRt77wkJBPCpJc9FPNebL9vlZcN4zv0KQta+4alcWivvoP 4QIxE+/+trC6QRw2m2dHk6aAeq/J0Sc7ilZufwnNA71hf9SzRIwcFXMsLx4iLlki inNqW9c= =s1CX \-\-\-\-\-END PGP PUBLIC KEY BLOCK\-\-\-\-\- gpg_pkg_pub_keyname: gpg_pkg_key.pub .ft P .fi .UNINDENT .UNINDENT .TP .B env Changed in version 2016.3.0. .sp A dictionary of environment variables to be utilized in creating the repository. Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- env: OPTIONS: \(aqask\-passphrase\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 The above illustrates a common \fBPyYAML\fP pitfall, that \fByes\fP, \fBno\fP, \fBon\fP, \fBoff\fP, \fBtrue\fP, and \fBfalse\fP are all loaded as boolean \fBTrue\fP and \fBFalse\fP values, and must be enclosed in quotes to be used as strings. More info on this (and other) \fBPyYAML\fP idiosyncrasies can be found \fI\%here\fP\&. .sp Use of \fBOPTIONS\fP on some platforms, for example: \fBask\-passphrase\fP, will require \fBgpg\-agent\fP or similar to cache passphrases. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This parameter is not used for making \fByum\fP repositories. .UNINDENT .UNINDENT .TP .B use_passphrase False New in version 2016.3.0. .sp Use a passphrase with the signing key presented in \fBkeyid\fP\&. Passphrase is received from Pillar data which could be passed on the command line with \fBpillar\fP parameter. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pillar=\(aq{ \(dqgpg_passphrase\(dq : \(dqmy_passphrase\(dq }\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B gnupghome /etc/salt/gpgkeys New in version 2016.3.0. .sp Location where GPG related files are stored, used with \(aqkeyid\(aq .TP .B runas builder New in version 2016.3.0. .sp User to create the repository as, and optionally sign packages. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Ensure the user has correct permissions to any files and directories which are to be utilized. .UNINDENT .UNINDENT .TP .B timeout 15.0 New in version 2016.3.4. .sp Timeout in seconds to wait for the prompt for inputting the passphrase. .UNINDENT .UNINDENT .SS salt.states.pkgng .SS Manage package remote repo using FreeBSD pkgng .sp Salt can manage the URL pkgng pulls packages from. ATM the state and module are small so use cases are typically rather simple: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pkgng_clients: pkgng.update_packaging_site: \- name: \(dqhttp://192.168.0.2\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkgng.update_packaging_site(name) .UNINDENT .SS salt.states.pkgrepo .SS Management of APT/DNF/YUM/Zypper package repos .sp States for managing software package repositories on Linux distros. Supported package managers are APT, DNF, YUM and Zypper. Here is some example SLS: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: pkgrepo.managed: \- humanname: CentOS\-$releasever \- Base \- mirrorlist: http://mirrorlist.centos.org/?release=$releasever&arch=$basearch&repo=os \- comments: \- \(aqhttp://mirror.centos.org/centos/$releasever/os/$basearch/\(aq \- gpgcheck: 1 \- gpgkey: file:///etc/pki/rpm\-gpg/RPM\-GPG\-KEY\-CentOS\-6 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: pkgrepo.managed: \- humanname: Logstash PPA \- name: deb http://ppa.launchpad.net/wolfnet/logstash/ubuntu precise main \- dist: precise \- file: /etc/apt/sources.list.d/logstash.list \- keyid: 28B04E4A \- keyserver: keyserver.ubuntu.com \- require_in: \- pkg: logstash pkg.latest: \- name: logstash \- refresh: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: pkgrepo.managed: \- humanname: deb\-multimedia \- name: deb http://www.deb\-multimedia.org stable main \- file: /etc/apt/sources.list.d/deb\-multimedia.list \- key_url: salt://deb\-multimedia/files/marillat.pub .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: pkgrepo.managed: \- humanname: Google Chrome \- name: deb http://dl.google.com/linux/chrome/deb/ stable main \- dist: stable \- file: /etc/apt/sources.list.d/chrome\-browser.list \- require_in: \- pkg: google\-chrome\-stable \- gpgcheck: 1 \- key_url: https://dl\-ssl.google.com/linux/linux_signing_key.pub .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: pkgrepo.managed: \- ppa: wolfnet/logstash pkg.latest: \- name: logstash \- refresh: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 On Ubuntu systems, the \fBpython\-software\-properties\fP package should be installed for better support of PPA repositories. To check if this package is installed, run \fBdpkg \-l python\-software\-properties\fP\&. .sp On Ubuntu & Debian systems, the \fBpython\-apt\fP package is required to be installed. To check if this package is installed, run \fBdpkg \-l python\-apt\fP\&. \fBpython\-apt\fP will need to be manually installed if it is not present. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hello\-copr: pkgrepo.managed: \- copr: mymindstorm/hello pkg.installed: \- name: hello .ft P .fi .UNINDENT .UNINDENT .SS apt\-key deprecated .sp \fBapt\-key\fP is deprecated and will be last available in Debian 11 and Ubuntu 22.04. The recommended way to manage repo keys going forward is to download the keys into /etc/apt/keyrings and use \fBsigned\-by\fP in your repo file pointing to the key. This module was updated in version 3005 to implement the recommended approach. You need to add \fB\- aptkey: False\fP to your state and set \fBsigned\-by\fP in your repo name, to use this recommended approach. If the cli command \fBapt\-key\fP is not available it will automatically set \fBaptkey\fP to False. .sp Using \fBaptkey: False\fP with \fBkey_url\fP example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C deb [signed\-by=/etc/apt/keyrings/salt\-archive\-keyring.gpg arch=amd64] https://repo.saltproject.io/py3/ubuntu/18.04/amd64/latest bionic main: pkgrepo.managed: \- file: /etc/apt/sources.list.d/salt.list \- key_url: https://repo.saltproject.io/py3/ubuntu/18.04/amd64/latest/salt\-archive\-keyring.gpg \- aptkey: False .ft P .fi .UNINDENT .UNINDENT .sp Using \fBaptkey: False\fP with \fBkeyserver\fP and \fBkeyid\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C deb [signed\-by=/etc/apt/keyrings/salt\-archive\-keyring.gpg arch=amd64] https://repo.saltproject.io/py3/ubuntu/18.04/amd64/latest bionic main: pkgrepo.managed: \- file: /etc/apt/sources.list.d/salt.list \- keyserver: keyserver.ubuntu.com \- keyid: 0E08A149DE57BFBE \- aptkey: False .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkgrepo.absent(name, **kwargs) This function deletes the specified repo on the system, if it exists. It is essentially a wrapper around \fBpkg.del_repo\fP\&. .INDENT 7.0 .TP .B name The name of the package repo, as it would be referred to when running the regular package manager commands. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On apt\-based systems this must be the complete source entry. For example, if you include \fB[arch=amd64]\fP, and a repo matching the specified URI, dist, etc. exists _without_ an architecture, then no changes will be made and the state will report a \fBTrue\fP result. .UNINDENT .UNINDENT .sp \fBFEDORA/REDHAT\-SPECIFIC OPTIONS\fP .INDENT 7.0 .TP .B copr Use community packages outside of the main package repository. .sp New in version 3002. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C hello\-copr: pkgrepo.absent: \- copr: mymindstorm/hello .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp \fBUBUNTU\-SPECIFIC OPTIONS\fP .INDENT 7.0 .TP .B ppa On Ubuntu, you can take advantage of Personal Package Archives on Launchpad simply by specifying the user and archive name. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C logstash\-ppa: pkgrepo.absent: \- ppa: wolfnet/logstash .ft P .fi .UNINDENT .UNINDENT .TP .B ppa_auth For Ubuntu PPAs there can be private PPAs that require authentication to access. For these PPAs the username/password can be specified. This is required for matching if the name format uses the \fBppa:\fP specifier and is private (requires username/password to access, which is encoded in the URI). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C logstash\-ppa: pkgrepo.absent: \- ppa: wolfnet/logstash \- ppa_auth: username:password .ft P .fi .UNINDENT .UNINDENT .TP .B keyid If passed, then the GPG key corresponding to the passed KeyID will also be removed. .TP .B keyid_ppa False If set to \fBTrue\fP, the GPG key\(aqs ID will be looked up from ppa.launchpad.net and removed, and the \fBkeyid\fP argument will be ignored. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option will be disregarded unless the \fBppa\fP argument is present. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkgrepo.managed(name, ppa=None, copr=None, aptkey=True, **kwargs) This state manages software package repositories. Currently, \fI\%yum\fP, \fI\%apt\fP, and \fI\%zypper\fP repositories are supported. .sp \fBYUM/DNF/ZYPPER\-BASED SYSTEMS\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 One of \fBbaseurl\fP or \fBmirrorlist\fP below is required. Additionally, note that this state is not presently capable of managing more than one repo in a single repo file, so each instance of this state will manage a single repo file containing the configuration for a single repo. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name This value will be used in two ways: Firstly, it will be the repo ID, as seen in the entry in square brackets (e.g. \fB[foo]\fP) for a given repo. Secondly, it will be the name of the file as stored in /etc/yum.repos.d (e.g. \fB/etc/yum.repos.d/foo.conf\fP). .TP .B enabled True Whether the repo is enabled or not. Can be specified as \fBTrue\fP/\fBFalse\fP or \fB1\fP/\fB0\fP\&. .TP .B disabled False Included to reduce confusion due to APT\(aqs use of the \fBdisabled\fP argument. If this is passed for a YUM/DNF/Zypper\-based distro, then the reverse will be passed as \fBenabled\fP\&. For example passing \fBdisabled=True\fP will assume \fBenabled=False\fP\&. .TP .B copr Fedora and RedHat based distributions only. Use community packages outside of the main package repository. .sp New in version 3002. .TP .B humanname This is used as the \fBname\fP value in the repo file in \fB/etc/yum.repos.d/\fP (or \fB/etc/zypp/repos.d\fP for SUSE distros). .TP .B baseurl The URL to a yum repository .TP .B mirrorlist A URL which points to a file containing a collection of baseurls .TP .B comments Sometimes you want to supply additional information, but not as enabled configuration. Anything supplied for this list will be saved in the repo configuration with a comment marker (#) in front. .TP .B gpgautoimport Only valid for Zypper package manager. If set to \fBTrue\fP, automatically trust and import the new repository signing key. The key should be specified with \fBgpgkey\fP parameter. See details below. .UNINDENT .sp Additional configuration values seen in YUM/DNF/Zypper repo files, such as \fBgpgkey\fP or \fBgpgcheck\fP, will be used directly as key\-value pairs. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C foo: pkgrepo.managed: \- humanname: Personal repo for foo \- baseurl: https://mydomain.tld/repo/foo/$releasever/$basearch \- gpgkey: file:///etc/pki/rpm\-gpg/foo\-signing\-key \- gpgcheck: 1 .ft P .fi .UNINDENT .UNINDENT .sp \fBAPT\-BASED SYSTEMS\fP .INDENT 7.0 .TP .B ppa On Ubuntu, you can take advantage of Personal Package Archives on Launchpad simply by specifying the user and archive name. The keyid will be queried from launchpad and everything else is set automatically. You can override any of the below settings by simply setting them as you would normally. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C logstash\-ppa: pkgrepo.managed: \- ppa: wolfnet/logstash .ft P .fi .UNINDENT .UNINDENT .TP .B ppa_auth For Ubuntu PPAs there can be private PPAs that require authentication to access. For these PPAs the username/password can be passed as an HTTP Basic style username/password combination. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C logstash\-ppa: pkgrepo.managed: \- ppa: wolfnet/logstash \- ppa_auth: username:password .ft P .fi .UNINDENT .UNINDENT .TP .B name On apt\-based systems this must be the complete entry as it would be seen in the \fBsources.list\fP file. This can have a limited subset of components (e.g. \fBmain\fP) which can be added/modified with the \fBcomps\fP option. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C precise\-repo: pkgrepo.managed: \- name: deb http://us.archive.ubuntu.com/ubuntu precise main .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The above example is intended as a more readable way of configuring the SLS, it is equivalent to the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aqdeb http://us.archive.ubuntu.com/ubuntu precise main\(aq: pkgrepo.managed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B disabled False Toggles whether or not the repo is used for resolving dependencies and/or installing packages. .TP .B enabled True Included to reduce confusion due to YUM/DNF/Zypper\(aqs use of the \fBenabled\fP argument. If this is passed for an APT\-based distro, then the reverse will be passed as \fBdisabled\fP\&. For example, passing \fBenabled=False\fP will assume \fBdisabled=False\fP\&. .TP .B architectures On apt\-based systems, \fBarchitectures\fP can restrict the available architectures that the repository provides (e.g. only \fBamd64\fP). \fBarchitectures\fP should be a comma\-separated list. .TP .B comps On apt\-based systems, comps dictate the types of packages to be installed from the repository (e.g. \fBmain\fP, \fBnonfree\fP, ...). For purposes of this, \fBcomps\fP should be a comma\-separated list. .TP .B file The filename for the \fB*.list\fP that the repository is configured in. It is important to include the full\-path AND make sure it is in a directory that APT will look in when handling packages .TP .B dist This dictates the release of the distro the packages should be built for. (e.g. \fBunstable\fP). This option is rarely needed. .TP .B keyid The KeyID or a list of KeyIDs of the GPG key to install. This option also requires the \fBkeyserver\fP option to be set. .TP .B keyserver This is the name of the keyserver to retrieve GPG keys from. The \fBkeyid\fP option must also be set for this option to work. .TP .B key_url URL to retrieve a GPG key from. Allows the usage of \fBhttps://\fP as well as \fBsalt://\fP\&. If \fBallow_insecure_key\fP is True, this also allows \fBhttp://\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Use either \fBkeyid\fP/\fBkeyserver\fP or \fBkey_url\fP, but not both. .UNINDENT .UNINDENT .TP .B key_text The string representation of the GPG key to install. .sp New in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Use either \fBkeyid\fP/\fBkeyserver\fP, \fBkey_url\fP, or \fBkey_text\fP but not more than one method. .UNINDENT .UNINDENT .TP .B consolidate False If set to \fBTrue\fP, this will consolidate all sources definitions to the \fBsources.list\fP file, cleanup the now unused files, consolidate components (e.g. \fBmain\fP) for the same URI, type, and architecture to a single line, and finally remove comments from the \fBsources.list\fP file. The consolidation will run every time the state is processed. The option only needs to be set on one repo managed by Salt to take effect. .TP .B clean_file False If set to \fBTrue\fP, empty the file before configuring the defined repository .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Use with care. This can be dangerous if multiple sources are configured in the same file. .UNINDENT .UNINDENT .sp New in version 2015.8.0. .TP .B refresh True If set to \fBFalse\fP this will skip refreshing the apt package database on Debian based systems. .TP .B refresh_db True Deprecated since version 2018.3.0: Use \fBrefresh\fP instead. .TP .B require_in Set this to a list of \fI\%pkg.installed\fP or \fI\%pkg.latest\fP to trigger the running of \fBapt\-get update\fP prior to attempting to install these packages. Setting a require in the pkg state will not work for this. .TP .B aptkey: Use the binary apt\-key. If the command \fBapt\-key\fP is not found in the path, aptkey will be False, regardless of what is passed into this argument. .TP .B allow_insecure_key True Whether to allow an insecure (e.g. http vs. https) key_url. .sp New in version 3006.0. .UNINDENT .UNINDENT .SS salt.states.portage_config .SS Management of Portage package configuration on Gentoo .sp A state module to manage Portage configuration on Gentoo .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt: portage_config.flags: \- use: \- openssl .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.portage_config.flags(name, use=None, accept_keywords=None, env=None, license=None, properties=None, unmask=False, mask=False) Enforce the given flags on the given package or \fBDEPEND\fP atom. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 In most cases, the affected package(s) need to be rebuilt in order to apply the changes. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the package or its DEPEND atom .TP .B use A list of \fBUSE\fP flags .TP .B accept_keywords A list of keywords to accept. \fB~ARCH\fP means current host arch, and will be translated into a line without keywords .TP .B env A list of environment files .TP .B license A list of accepted licenses .TP .B properties A list of additional properties .TP .B unmask A boolean to unmask the package .TP .B mask A boolean to mask the package .UNINDENT .UNINDENT .SS salt.states.ports .sp Manage software from FreeBSD ports .sp New in version 2014.1.0. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 It may be helpful to use a higher timeout when running a \fI\%ports.installed\fP state, since compiling the port may exceed Salt\(aqs timeout. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-t 1200 \(aq*\(aq state.highstate .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ports.installed(name, options=None) Verify that the desired port is installed, and that it was compiled with the desired options. .INDENT 7.0 .TP .B options Make sure that the desired non\-default options are set .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Any build options not passed here assume the default values for the port, and are not just differences from the existing cached options from a previous \fBmake config\fP\&. .UNINDENT .UNINDENT .UNINDENT .sp Example usage: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C security/nmap: ports.installed: \- options: \- IPV6: off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.postgres_cluster .SS Management of PostgreSQL clusters .sp The postgres_cluster state module is used to manage PostgreSQL clusters. Clusters can be set as either absent or present .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create cluster 9.3 main: postgres_cluster.present: \- name: \(aqmain\(aq \- version: \(aq9.3\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_cluster.absent(version, name) Ensure that the named cluster is absent .INDENT 7.0 .TP .B version Version of the postgresql server of the cluster to remove .TP .B name The name of the cluster to remove .sp New in version 2016.3.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_cluster.present(version, name, port=None, encoding=None, locale=None, datadir=None, allow_group_access=None, data_checksums=None, wal_segsize=None) Ensure that the named cluster is present with the specified properties. For more information about all of these options see man pg_createcluster(1) .INDENT 7.0 .TP .B version Version of the postgresql cluster .TP .B name The name of the cluster .TP .B port Cluster port .TP .B encoding The character encoding scheme to be used in this database .TP .B locale Locale with which to create cluster .TP .B datadir Where the cluster is stored .TP .B allow_group_access Allows users in the same group as the cluster owner to read all cluster files created by initdb .TP .B data_checksums Use checksums on data pages .TP .B wal_segsize Set the WAL segment size, in megabytes .sp New in version 2016.3.0. .UNINDENT .UNINDENT .SS salt.states.postgres_database .SS Management of PostgreSQL databases .sp The postgres_database module is used to create and manage Postgres databases. Databases can be set as either absent or present .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C frank: postgres_database.present .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_database.absent(name, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None) Ensure that the named database is absent .INDENT 7.0 .TP .B name The name of the database to remove .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .TP .B user System user all operations should be performed on behalf of .sp New in version 0.17.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_database.present(name, tablespace=None, encoding=None, lc_collate=None, lc_ctype=None, owner=None, owner_recurse=False, template=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None) Ensure that the named database is present with the specified properties. For more information about all of these options see man createdb(1) .INDENT 7.0 .TP .B name The name of the database to manage .TP .B tablespace Default tablespace for the database .TP .B encoding The character encoding scheme to be used in this database. The encoding has to be defined in the following format (without hyphen). .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- encoding: UTF8 .ft P .fi .UNINDENT .UNINDENT .TP .B lc_collate The LC_COLLATE setting to be used in this database .TP .B lc_ctype The LC_CTYPE setting to be used in this database .TP .B owner The username of the database owner .TP .B owner_recurse Recurse owner change to all relations in the database .TP .B template The template database from which to build this database .TP .B user System user all operations should be performed on behalf of .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .sp New in version 0.17.0. .UNINDENT .UNINDENT .SS salt.states.postgres_extension .SS Management of PostgreSQL extensions .sp A module used to install and manage PostgreSQL extensions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C adminpack: postgres_extension.present .ft P .fi .UNINDENT .UNINDENT .sp New in version 2014.7.0. .INDENT 0.0 .TP .B salt.states.postgres_extension.absent(name, if_exists=None, restrict=None, cascade=None, user=None, maintenance_db=None, db_user=None, db_password=None, db_host=None, db_port=None) Ensure that the named extension is absent. .INDENT 7.0 .TP .B name Extension name of the extension to remove .TP .B if_exists Add if exist slug .TP .B restrict Add restrict slug .TP .B cascade Drop on cascade .TP .B user System user all operations should be performed on behalf of .TP .B maintenance_db Database to act on .TP .B db_user Database username if different from config or default .TP .B db_password User password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_extension.present(name, if_not_exists=None, schema=None, ext_version=None, from_version=None, user=None, maintenance_db=None, db_user=None, db_password=None, db_host=None, db_port=None) Ensure that the named extension is present. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Before you can use the state to load an extension into a database, the extension\(aqs supporting files must be already installed. .UNINDENT .UNINDENT .sp For more information about all of these options see \fBCREATE EXTENSION\fP SQL command reference in the PostgreSQL documentation. .INDENT 7.0 .TP .B name The name of the extension to be installed .TP .B if_not_exists Add an \fBIF NOT EXISTS\fP parameter to the DDL statement .TP .B schema Schema to install the extension into .TP .B ext_version Version to install .TP .B from_version Old extension version if already installed .TP .B user System user all operations should be performed on behalf of .TP .B maintenance_db Database to act on .TP .B db_user Database username if different from config or default .TP .B db_password User password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .SS salt.states.postgres_group .SS Management of PostgreSQL groups (roles) .sp The postgres_group module is used to create and manage Postgres groups. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C frank: postgres_group.present .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_group.absent(name, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None) Ensure that the named group is absent .INDENT 7.0 .TP .B name The groupname of the group to remove .TP .B user System user all operations should be performed on behalf of .sp New in version 0.17.0. .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_group.present(name, createdb=None, createroles=None, encrypted=None, superuser=None, inherit=None, login=None, replication=None, password=None, refresh_password=None, groups=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None) Ensure that the named group is present with the specified privileges Please note that the user/group notion in postgresql is just abstract, we have roles, where users can be seen as roles with the \fBLOGIN\fP privilege and groups the others. .INDENT 7.0 .TP .B name The name of the group to manage .TP .B createdb Is the group allowed to create databases? .TP .B createroles Is the group allowed to create other roles/users .TP .B encrypted How the password should be stored. .sp If encrypted is \fBNone\fP, \fBTrue\fP, or \fBmd5\fP, it will use PostgreSQL\(aqs MD5 algorithm. .sp If encrypted is \fBFalse\fP, it will be stored in plaintext. .sp If encrypted is \fBscram\-sha\-256\fP, it will use the algorithm described in RFC 7677. .sp Changed in version 3003: Prior versions only supported \fBTrue\fP and \fBFalse\fP .TP .B login Should the group have login perm .TP .B inherit Should the group inherit permissions .TP .B superuser Should the new group be a \(dqsuperuser\(dq .TP .B replication Should the new group be allowed to initiate streaming replication .TP .B password The group\(aqs password. It can be either a plain string or a pre\-hashed password: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \(aqmd5{MD5OF({password}{role}}\(aq \(aqSCRAM\-SHA\-256${iterations}:{salt}${stored_key}:{server_key}\(aq .ft P .fi .UNINDENT .UNINDENT .sp If encrypted is not \fBFalse\fP, then the password will be converted to the appropriate format above, if not already. As a consequence, passwords that start with \(dqmd5\(dq or \(dqSCRAM\-SHA\-256\(dq cannot be used. .TP .B refresh_password Password refresh flag .sp Boolean attribute to specify whether to password comparison check should be performed. .sp If refresh_password is \fBTrue\fP, the password will be automatically updated without extra password change check. .sp This behaviour makes it possible to execute in environments without superuser access available, e.g. Amazon RDS for PostgreSQL .TP .B groups A string of comma separated groups the group should be in .TP .B user System user all operations should be performed on behalf of .sp New in version 0.17.0. .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .SS salt.states.postgres_initdb .SS Initialization of PostgreSQL data directory .sp The postgres_initdb module is used to initialize the postgresql data directory. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pgsql\-data\-dir: postgres_initdb.present: \- name: /var/lib/pgsql/data \- auth: password \- user: postgres \- password: strong_password \- encoding: UTF8 \- locale: C \- runas: postgres \- checksums: True \- waldir: /var/postgresql/wal .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_initdb.present(name, user=None, password=None, auth=\(aqpassword\(aq, encoding=\(aqUTF8\(aq, locale=None, runas=None, waldir=None, checksums=False) Initialize the PostgreSQL data directory .INDENT 7.0 .TP .B name The name of the directory to initialize .TP .B user The database superuser name .TP .B password The password to set for the postgres user .TP .B auth The default authentication method for local connections .TP .B encoding The default encoding for new databases .TP .B locale The default locale for new databases .TP .B waldir The transaction log (WAL) directory (default is to keep WAL inside the data directory) .sp New in version 2019.2.0. .TP .B checksums If True, the cluster will be created with data page checksums. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Data page checksums are supported since PostgreSQL 9.3. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .TP .B runas The system user the operation should be performed on behalf of .UNINDENT .UNINDENT .SS salt.states.postgres_language .SS Management of PostgreSQL languages .sp The postgres_language module is used to create and manage Postgres languages. Languages can be set as either absent or present .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plpgsql: postgres_language.present: \- maintenance_db: testdb .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plpgsql: postgres_language.absent: \- maintenance_db: testdb .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_language.absent(name, maintenance_db, user=None, db_password=None, db_host=None, db_port=None, db_user=None) Ensure that a named language is absent in the specified database. .INDENT 7.0 .TP .B name The name of the language to remove .TP .B maintenance_db The name of the database in which the language is to be installed .TP .B user System user all operations should be performed on behalf of .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_language.present(name, maintenance_db, user=None, db_password=None, db_host=None, db_port=None, db_user=None) Ensure that a named language is present in the specified database. .INDENT 7.0 .TP .B name The name of the language to install .TP .B maintenance_db The name of the database in which the language is to be installed .TP .B user System user all operations should be performed on behalf of .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .SS salt.states.postgres_privileges .SS Management of PostgreSQL Privileges .sp The postgres_privileges module is used to manage Postgres privileges. Privileges can be set as either absent or present. .sp Privileges can be set on the following database object types: .INDENT 0.0 .IP \(bu 2 database .IP \(bu 2 schema .IP \(bu 2 tablespace .IP \(bu 2 table .IP \(bu 2 sequence .IP \(bu 2 language .IP \(bu 2 group .UNINDENT .sp Setting the grant option is supported as well. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C baruwa: postgres_privileges.present: \- object_name: awl \- object_type: table \- privileges: \- SELECT \- INSERT \- DELETE \- grant_option: False \- prepend: public \- maintenance_db: testdb .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C andrew: postgres_privileges.present: \- object_name: admins \- object_type: group \- grant_option: False \- maintenance_db: testdb .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C baruwa: postgres_privileges.absent: \- object_name: awl \- object_type: table \- privileges: \- SELECT \- INSERT \- DELETE \- prepend: public \- maintenance_db: testdb .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C andrew: postgres_privileges.absent: \- object_name: admins \- object_type: group \- maintenance_db: testdb .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_privileges.absent(name, object_name, object_type, privileges=None, prepend=\(aqpublic\(aq, maintenance_db=None, user=None, db_password=None, db_host=None, db_port=None, db_user=None) Revoke the requested privilege(s) on the specificed object(s) .INDENT 7.0 .TP .B name Name of the role whose privileges should be revoked .TP .B object_name Name of the object on which the revoke is to be performed .TP .B object_type The object type, which can be one of the following: .INDENT 7.0 .IP \(bu 2 table .IP \(bu 2 sequence .IP \(bu 2 schema .IP \(bu 2 tablespace .IP \(bu 2 language .IP \(bu 2 database .IP \(bu 2 group .IP \(bu 2 function .UNINDENT .sp View permissions should specify \fIobject_type: table\fP\&. .TP .B privileges Comma separated list of privileges to revoke, from the list below: .INDENT 7.0 .IP \(bu 2 INSERT .IP \(bu 2 CREATE .IP \(bu 2 TRUNCATE .IP \(bu 2 CONNECT .IP \(bu 2 TRIGGER .IP \(bu 2 SELECT .IP \(bu 2 USAGE .IP \(bu 2 TEMPORARY .IP \(bu 2 UPDATE .IP \(bu 2 EXECUTE .IP \(bu 2 REFERENCES .IP \(bu 2 DELETE .IP \(bu 2 ALL .UNINDENT .INDENT 7.0 .TP .B note privileges should not be set when revoking group membership .UNINDENT .TP .B prepend Table and Sequence object types live under a schema so this should be provided if the object is not under the default \fIpublic\fP schema .TP .B maintenance_db The name of the database in which the language is to be installed .TP .B user System user all operations should be performed on behalf of .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_privileges.present(name, object_name, object_type, privileges=None, grant_option=None, prepend=\(aqpublic\(aq, maintenance_db=None, user=None, db_password=None, db_host=None, db_port=None, db_user=None) Grant the requested privilege(s) on the specified object to a role .INDENT 7.0 .TP .B name Name of the role to which privileges should be granted .TP .B object_name Name of the object on which the grant is to be performed. \(aqALL\(aq may be used for objects of type \(aqtable\(aq or \(aqsequence\(aq. .TP .B object_type The object type, which can be one of the following: .INDENT 7.0 .IP \(bu 2 table .IP \(bu 2 sequence .IP \(bu 2 schema .IP \(bu 2 tablespace .IP \(bu 2 language .IP \(bu 2 database .IP \(bu 2 group .IP \(bu 2 function .UNINDENT .sp View permissions should specify \fIobject_type: table\fP\&. .TP .B privileges List of privileges to grant, from the list below: .INDENT 7.0 .IP \(bu 2 INSERT .IP \(bu 2 CREATE .IP \(bu 2 TRUNCATE .IP \(bu 2 CONNECT .IP \(bu 2 TRIGGER .IP \(bu 2 SELECT .IP \(bu 2 USAGE .IP \(bu 2 TEMPORARY .IP \(bu 2 UPDATE .IP \(bu 2 EXECUTE .IP \(bu 2 REFERENCES .IP \(bu 2 DELETE .IP \(bu 2 ALL .UNINDENT .INDENT 7.0 .TP .B note privileges should not be set when granting group membership .UNINDENT .TP .B grant_option If grant_option is set to True, the recipient of the privilege can in turn grant it to others .TP .B prepend Table and Sequence object types live under a schema so this should be provided if the object is not under the default \fIpublic\fP schema .TP .B maintenance_db The name of the database in which the language is to be installed .TP .B user System user all operations should be performed on behalf of .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .SS salt.states.postgres_schema .SS Management of PostgreSQL schemas .sp The postgres_schemas module is used to create and manage Postgres schemas. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C public: postgres_schema.present \(aqdbname\(aq \(aqname\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_schema.absent(dbname, name, user=None, db_user=None, db_password=None, db_host=None, db_port=None) Ensure that the named schema is absent. .INDENT 7.0 .TP .B dbname The database\(aqs name will work on .TP .B name The name of the schema to remove .TP .B user system user all operations should be performed on behalf of .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_schema.present(dbname, name, owner=None, user=None, db_user=None, db_password=None, db_host=None, db_port=None) Ensure that the named schema is present in the database. .INDENT 7.0 .TP .B dbname The database\(aqs name will work on .TP .B name The name of the schema to manage .TP .B user system user all operations should be performed on behalf of .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .SS salt.states.postgres_tablespace .SS Management of PostgreSQL tablespace .sp A module used to create and manage PostgreSQL tablespaces. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssd\-tablespace: postgres_tablespace.present: \- name: indexes \- directory: /mnt/ssd\-data .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .INDENT 0.0 .TP .B salt.states.postgres_tablespace.absent(name, user=None, maintenance_db=None, db_user=None, db_password=None, db_host=None, db_port=None) Ensure that the named tablespace is absent. .INDENT 7.0 .TP .B name The name of the tablespace to remove .TP .B user System user all operations should be performed on behalf of .TP .B maintenance_db Database to act on .TP .B db_user Database username if different from config or default .TP .B db_password User password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_tablespace.present(name, directory, options=None, owner=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None) Ensure that the named tablespace is present with the specified properties. For more information about all of these options run \fBman 7 create_tablespace\fP\&. .INDENT 7.0 .TP .B name The name of the tablespace to create/manage. .TP .B directory The directory where the tablespace will be located, must already exist .TP .B options A dictionary of options to specify for the tablespace. Currently, the only tablespace options supported are \fBseq_page_cost\fP and \fBrandom_page_cost\fP\&. Default values are shown in the example below: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my_space: postgres_tablespace.present: \- directory: /srv/my_tablespace \- options: seq_page_cost: 1.0 random_page_cost: 4.0 .ft P .fi .UNINDENT .UNINDENT .TP .B owner The database user that will be the owner of the tablespace. Defaults to the user executing the command (i.e. the \fIuser\fP option) .TP .B user System user all operations should be performed on behalf of .TP .B maintenance_db Database to act on .TP .B db_user Database username if different from config or default .TP .B db_password User password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .SS salt.states.postgres_user .SS Management of PostgreSQL users (roles) .sp The postgres_users module is used to create and manage Postgres users. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C frank: postgres_user.present .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_user.absent(name, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None) Ensure that the named user is absent .INDENT 7.0 .TP .B name The username of the user to remove .TP .B user System user all operations should be performed on behalf of .sp New in version 0.17.0. .TP .B db_user database username if different from config or default .TP .B db_password user password if any password for a specified user .TP .B db_host Database host if different from config or default .TP .B db_port Database port if different from config or default .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.postgres_user.present(name, createdb=None, createroles=None, encrypted=None, superuser=None, replication=None, inherit=None, login=None, password=None, default_password=None, refresh_password=None, valid_until=None, groups=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None) Ensure that the named user is present with the specified privileges Please note that the user/group notion in postgresql is just abstract, we have roles, where users can be seen as roles with the LOGIN privilege and groups the others. .INDENT 7.0 .TP .B name The name of the system user to manage. .TP .B createdb Is the user allowed to create databases? .TP .B createroles Is the user allowed to create other users? .TP .B encrypted How the password should be stored. .sp If encrypted is \fBNone\fP, \fBTrue\fP, or \fBmd5\fP, it will use PostgreSQL\(aqs MD5 algorithm. .sp If encrypted is \fBFalse\fP, it will be stored in plaintext. .sp If encrypted is \fBscram\-sha\-256\fP, it will use the algorithm described in RFC 7677. .sp Changed in version 3003: Prior versions only supported \fBTrue\fP and \fBFalse\fP .TP .B login Should the group have login perm .TP .B inherit Should the group inherit permissions .TP .B superuser Should the new user be a \(dqsuperuser\(dq .TP .B replication Should the new user be allowed to initiate streaming replication .TP .B password The user\(aqs password. It can be either a plain string or a pre\-hashed password: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \(aqmd5{MD5OF({password}{role}}\(aq \(aqSCRAM\-SHA\-256${iterations}:{salt}${stored_key}:{server_key}\(aq .ft P .fi .UNINDENT .UNINDENT .sp If encrypted is not \fBFalse\fP, then the password will be converted to the appropriate format above, if not already. As a consequence, passwords that start with \(dqmd5\(dq or \(dqSCRAM\-SHA\-256\(dq cannot be used. .TP .B default_password The password used only when creating the user, unless password is set. .sp New in version 2016.3.0. .TP .B refresh_password Password refresh flag .sp Boolean attribute to specify whether to password comparison check should be performed. .sp If refresh_password is \fBTrue\fP, the password will be automatically updated without extra password change check. .sp This behaviour makes it possible to execute in environments without superuser access available, e.g. Amazon RDS for PostgreSQL .TP .B valid_until A date and time after which the role\(aqs password is no longer valid. .TP .B groups A string of comma separated groups the user should be in .TP .B user System user all operations should be performed on behalf of .sp New in version 0.17.0. .TP .B db_user Postgres database username, if different from config or default. .TP .B db_password Postgres user\(aqs password, if any password, for a specified db_user. .TP .B db_host Postgres database host, if different from config or default. .TP .B db_port Postgres database port, if different from config or default. .UNINDENT .UNINDENT .SS salt.states.powerpath .SS Powerpath configuration support .sp Allows configuration of EMC Powerpath. Currently only addition/deletion of licenses is supported. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C key: powerpath.license_present: [] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.powerpath.license_absent(name) Ensures that the specified PowerPath license key is absent on the host. .INDENT 7.0 .TP .B name The license key to ensure is absent .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.powerpath.license_present(name) Ensures that the specified PowerPath license key is present on the host. .INDENT 7.0 .TP .B name The license key to ensure is present .UNINDENT .UNINDENT .SS salt.states.probes .SS Network Probes .sp Configure RPM (JunOS)/SLA (Cisco) probes on the device via NAPALM proxy. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> & Jerome Fleury <\fI\%jf@cloudflare.com\fP> .TP .B maturity new .TP .B depends napalm .TP .B platform unix .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 \fI\%napalm probes management module\fP .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.states.probes.managed(name, probes, defaults=None) Ensure the networks device is configured as specified in the state SLS file. Probes not specified will be removed, while probes not confiured as expected will trigger config updates. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprobes\fP \-\- Defines the probes as expected to be configured on the device. In order to ease the configuration and avoid repeating the same parameters for each probe, the next parameter (defaults) can be used, providing common characteristics. .IP \(bu 2 \fBdefaults\fP \-\- Specifies common parameters for the probes. .UNINDENT .UNINDENT .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C rpmprobes: probes.managed: \- probes: probe_name1: probe1_test1: source: 192.168.0.2 target: 192.168.0.1 probe1_test2: target: 172.17.17.1 probe1_test3: target: 8.8.8.8 probe_type: http\-ping probe_name2: probe2_test1: test_interval: 100 \- defaults: target: 10.10.10.10 probe_count: 15 test_interval: 3 probe_type: icmp\-ping .ft P .fi .UNINDENT .UNINDENT .sp In the probes configuration, the only mandatory attribute is \fItarget\fP (specified either in probes configuration, either in the defaults dictionary). All the other parameters will use the operating system defaults, if not provided: .INDENT 7.0 .IP \(bu 2 \fBsource\fP \- Specifies the source IP Address to be used during the tests. If not specified will use the IP Address of the logical interface loopback0. .IP \(bu 2 \fBtarget\fP \- Destination IP Address. .IP \(bu 2 \fBprobe_count\fP \- Total number of probes per test (1..15). System defaults: 1 on both JunOS & Cisco. .IP \(bu 2 \fBprobe_interval\fP \- Delay between tests (0..86400 seconds). System defaults: 3 on JunOS, 5 on Cisco. .IP \(bu 2 \fBprobe_type\fP \- Probe request type. Available options: .INDENT 2.0 .IP \(bu 2 icmp\-ping .IP \(bu 2 tcp\-ping .IP \(bu 2 udp\-ping .UNINDENT .UNINDENT .sp Using the example configuration above, after running the state, on the device will be configured 4 probes, with the following properties: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C probe_name1: probe1_test1: source: 192.168.0.2 target: 192.168.0.1 probe_count: 15 test_interval: 3 probe_type: icmp\-ping probe1_test2: target: 172.17.17.1 probe_count: 15 test_interval: 3 probe_type: icmp\-ping probe1_test3: target: 8.8.8.8 probe_count: 15 test_interval: 3 probe_type: http\-ping probe_name2: probe2_test1: target: 10.10.10.10 probe_count: 15 test_interval: 3 probe_type: icmp\-ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.process .SS Process Management .sp Ensure a process matching a given pattern is absent. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd\-absent: process.absent: \- name: apache2 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.process.absent(name, user=None, signal=None) Ensures that the named command is not running. .INDENT 7.0 .TP .B name The pattern to match. .TP .B user The user to which the process belongs .TP .B signal Signal to send to the process(es). .UNINDENT .UNINDENT .SS salt.states.proxy .SS Allows you to manage proxy settings on minions .sp Setup proxy settings on minions .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 192.168.1.4: proxy.managed: \- port: 3128 \- bypass_domains: \- localhost \- 127.0.0.1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.proxy.managed(name, port, services=None, user=None, password=None, bypass_domains=None, network_service=\(aqEthernet\(aq) Manages proxy settings for this mininon .INDENT 7.0 .TP .B name The proxy server to use .TP .B port The port used by the proxy server .TP .B services A list of the services that should use the given proxy settings, valid services include http, https and ftp. If no service is given all of the valid services will be used. .TP .B user The username to use for the proxy server if required .TP .B password The password to use for the proxy server if required .TP .B bypass_domains An array of the domains that should bypass the proxy .TP .B network_service The network service to apply the changes to, this only necessary on macOS .UNINDENT .UNINDENT .SS salt.states.pushover .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%pushover Salt Extension\fP\&. .UNINDENT .UNINDENT .SS Send a message to PushOver .sp This state is useful for sending messages to PushOver during state runs. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pushover\-message: pushover.post_message: \- user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \- token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \- title: Salt Returner \- device: phone \- priority: \-1 \- expire: 3600 \- retry: 5 \- message: \(aqThis state was executed successfully.\(aq .ft P .fi .UNINDENT .UNINDENT .sp The api key can be specified in the master or minion configuration like below: \&.. code\-block:: yaml .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B pushover: token: peWcBiMOS9HrZG15peWcBiMOS9HrZG15 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pushover.post_message(name, user=None, device=None, message=None, title=None, priority=None, expire=None, retry=None, sound=None, api_version=1, token=None) Send a message to a PushOver channel. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pushover\-message: pushover.post_message: \- user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \- token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \- title: Salt Returner \- device: phone \- priority: \-1 \- expire: 3600 \- retry: 5 .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B name The unique name for this event. .TP .B user The user or group of users to send the message to. Must be ID of user, not name or email address. .TP .B message The message that is to be sent to the PushOver channel. .UNINDENT .sp The following parameters are optional: .INDENT 7.0 .TP .B title The title to use for the message. .TP .B device The device for the user to send the message to. .TP .B priority The priority for the message. .TP .B expire The message should expire after specified amount of seconds. .TP .B retry The message should be resent this many times. .TP .B token The token for PushOver to use for authentication, if not specified in the configuration options of master or minion. .UNINDENT .UNINDENT .SS salt.states.pyenv .SS Managing python installations with pyenv .sp This module is used to install and manage python installations with pyenv. Different versions of python can be installed, and uninstalled. pyenv will be installed automatically the first time it is needed and can be updated later. This module will \fInot\fP automatically install packages which pyenv will need to compile the versions of python. .sp If pyenv is run as the root user then it will be installed to /usr/local/pyenv, otherwise it will be installed to the users ~/.pyenv directory. To make pyenv available in the shell you may need to add the pyenv/shims and pyenv/bin directories to the users PATH. If you are installing as root and want other users to be able to access pyenv then you will need to add pyenv_ROOT to their environment. .sp This is how a state configuration could look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pyenv\-deps: pkg.installed: \- pkgs: \- make \- build\-essential \- libssl\-dev \- zlib1g\-dev \- libbz2\-dev \- libreadline\-dev \- libsqlite3\-dev \- wget \- curl \- llvm python\-2.6: pyenv.absent: \- require: \- pkg: pyenv\-deps python\-2.7.6: pyenv.installed: \- default: True \- require: \- pkg: pyenv\-deps .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Git needs to be installed and available via PATH if pyenv is to be installed automatically by the module. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pyenv.absent(name, user=None) Verify that the specified python is not installed with pyenv. pyenv is installed if necessary. .INDENT 7.0 .TP .B name The version of python to uninstall .TP .B user: None The user to run pyenv as. .sp New in version 0.17.0. .UNINDENT .sp New in version 0.16.0. .UNINDENT .INDENT 0.0 .TP .B salt.states.pyenv.install_pyenv(name, user=None) Install pyenv if not installed. Allows you to require pyenv be installed prior to installing the plugins. Useful if you want to install pyenv plugins via the git or file modules and need them installed before installing any rubies. .sp Use the pyenv.root configuration option to set the path for pyenv if you want a system wide install that is not in a user home dir. .INDENT 7.0 .TP .B user: None The user to run pyenv as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pyenv.installed(name, default=False, user=None) Verify that the specified python is installed with pyenv. pyenv is installed if necessary. .INDENT 7.0 .TP .B name The version of python to install .TP .B default False Whether to make this python the default. .TP .B user: None The user to run pyenv as. .sp New in version 0.17.0. .UNINDENT .sp New in version 0.16.0. .UNINDENT .SS salt.states.pyrax_queues .SS Manage Rackspace Queues .sp New in version 2015.5.0. .sp Create and destroy Rackspace queues. Be aware that this interacts with Rackspace\(aqs services, and so may incur charges. .sp This module uses \fBpyrax\fP, which can be installed via package, or pip. This module is greatly inspired by boto_* modules from SaltStack code source. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myqueue: pyrax_queues.present: \- provider: my\-pyrax myqueue: pyrax_queues.absent: \- provider: my\-pyrax .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pyrax_queues.absent(name, provider) Ensure the named Rackspace queue is deleted. .INDENT 7.0 .TP .B name Name of the Rackspace queue. .TP .B provider Salt Cloud provider .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pyrax_queues.present(name, provider) Ensure the RackSpace queue exists. .INDENT 7.0 .TP .B name Name of the Rackspace queue. .TP .B provider Salt Cloud Provider .UNINDENT .UNINDENT .SS salt.states.quota .SS Management of POSIX Quotas .sp The quota can be managed for the system: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /: quota.mode: mode: off quotatype: user .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.quota.mode(name, mode, quotatype) Set the quota for the system .INDENT 7.0 .TP .B name The filesystem to set the quota mode on .TP .B mode Whether the quota system is on or off .TP .B quotatype Must be \fBuser\fP or \fBgroup\fP .UNINDENT .UNINDENT .SS salt.states.rabbitmq_cluster .SS Manage RabbitMQ Clusters .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rabbit@rabbit.example.com: rabbitmq_cluster.join: \- user: rabbit \- host: rabbit.example.com .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rabbitmq_cluster.join(name, host, user=\(aqrabbit\(aq, ram_node=None, runas=\(aqroot\(aq) This function is an alias of \fBjoined\fP\&. .INDENT 7.0 .INDENT 3.5 Ensure the current node joined to a cluster with node \fI\%user@host\fP .INDENT 0.0 .TP .B name Irrelevant, not used (recommended: \fI\%user@host\fP) .TP .B user The user of node to join to (default: rabbit) .TP .B host The host of node to join to .TP .B ram_node Join node as a RAM node .TP .B runas The user to run the rabbitmq command as .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rabbitmq_cluster.joined(name, host, user=\(aqrabbit\(aq, ram_node=None, runas=\(aqroot\(aq) Ensure the current node joined to a cluster with node \fI\%user@host\fP .INDENT 7.0 .TP .B name Irrelevant, not used (recommended: \fI\%user@host\fP) .TP .B user The user of node to join to (default: rabbit) .TP .B host The host of node to join to .TP .B ram_node Join node as a RAM node .TP .B runas The user to run the rabbitmq command as .UNINDENT .UNINDENT .SS salt.states.rabbitmq_plugin .SS Manage RabbitMQ Plugins .sp New in version 2014.1.0. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C some_plugin: rabbitmq_plugin.enabled: [] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rabbitmq_plugin.disabled(name, runas=None) Ensure the RabbitMQ plugin is disabled. .INDENT 7.0 .TP .B name The name of the plugin .TP .B runas The user to run the rabbitmq\-plugin command as .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rabbitmq_plugin.enabled(name, runas=None) Ensure the RabbitMQ plugin is enabled. .INDENT 7.0 .TP .B name The name of the plugin .TP .B runas The user to run the rabbitmq\-plugin command as .UNINDENT .UNINDENT .SS salt.states.rabbitmq_policy .SS Manage RabbitMQ Policies .INDENT 0.0 .TP .B maintainer Benn Eichhorn <\fI\%benn@getlocalmeasure.com\fP> .TP .B maturity new .TP .B platform all .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rabbit_policy: rabbitmq_policy.present: \- name: HA \- pattern: \(aq.*\(aq \- definition: \(aq{\(dqha\-mode\(dq: \(dqall\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rabbitmq_policy.absent(name, vhost=\(aq/\(aq, runas=None) Ensure the named policy is absent .sp Reference: \fI\%http://www.rabbitmq.com/ha.html\fP .INDENT 7.0 .TP .B name The name of the policy to remove .TP .B runas Name of the user to run the command as .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rabbitmq_policy.present(name, pattern, definition, priority=0, vhost=\(aq/\(aq, runas=None, apply_to=None) Ensure the RabbitMQ policy exists. .sp Reference: \fI\%https://rabbitmq.com/parameters.html#policies\fP .INDENT 7.0 .TP .B name Policy name .TP .B pattern A regex of queues to apply the policy to .TP .B definition A json dict describing the policy .TP .B priority Priority (defaults to 0) .TP .B vhost Virtual host to apply to (defaults to \(aq/\(aq) .TP .B runas Name of the user to run the command as .TP .B apply_to Apply policy to \(aqqueues\(aq, \(aqexchanges\(aq or \(aqall\(aq (default to \(aqall\(aq) .UNINDENT .UNINDENT .SS salt.states.rabbitmq_upstream .SS Manage RabbitMQ Upstreams .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rabbit_upstream: rabbitmq_upstream.present: \- name: upstream_1 \- uri: amqp://my_user:my_password@rabbitmq_host \- trust_user_id: True \- ack_mode: on\-confirm \- max_hops: 1 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3000. .INDENT 0.0 .TP .B salt.states.rabbitmq_upstream.absent(name, runas=None) Ensure the named upstream is absent. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the upstream to remove .IP \(bu 2 \fBrunas\fP (\fI\%str\fP) \-\- User to run the command .UNINDENT .UNINDENT .sp New in version 3000. .UNINDENT .INDENT 0.0 .TP .B salt.states.rabbitmq_upstream.present(name, uri, prefetch_count=None, reconnect_delay=None, ack_mode=None, trust_user_id=None, exchange=None, max_hops=None, expires=None, message_ttl=None, ha_policy=None, queue=None, runas=None) Ensure the RabbitMQ upstream exists. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the upstream connection .IP \(bu 2 \fBuri\fP (\fI\%str\fP) \-\- The URI to connect to. If upstream is a cluster and can have several URIs, you can enter them here separated by spaces. Examples: \- amqp://user:password@server_name \- amqp://user:password@server_name/vhost When connecting with SSL, several URI\-parameters need also be specified: \- cacertfile = /path/to/cacert.pem \- certfile = /path/to/cert.pem \- keyfile = /part/to/key.pem \- verity = verify_peer \- fail_if_no_peer_cert = true | false \- auth_mechanism = external Example: \- amqp://user:password@server_name?cacertfile=/path/to/cacert.pem& certfile=/path/to/cert.pem&keyfile=/path/to/key.pem&verify=verify_peer \- amqp://server\-name?cacertfile=/path/to/cacert.pem&certfile=/path/to/cert.pem& keyfile=/path/to/key.pem&verify=verify_peer&fail_if_no_peer_cert=true&auth_mechanism=external .IP \(bu 2 \fBprefetch_count\fP (\fI\%int\fP) \-\- Maximum number of unacknowledged messages that may be in flight over a federation link at one time. Default: 1000 .IP \(bu 2 \fBreconnect_delay\fP (\fI\%int\fP) \-\- Time in seconds to wait after a network link goes down before attempting reconnection. Default: 5 .IP \(bu 2 \fBack_mode\fP (\fI\%str\fP) \-\- The following values are allowed: on\-confirm: Messages are acknowledged to the upstream broker after they have been confirmed downstream. Handles network errors and broker failures without losing messages. The slowest option, and the default. on\-publish: Messages are acknowledged to the upstream broker after they have been published downstream. Handles network errors without losing messages, but may lose messages in the event of broker failures. no\-ack: Message acknowledgements are not used. The fastest option, but you may lose messages in the event of network or broker failures. .IP \(bu 2 \fBtrust_user_id\fP (\fI\%bool\fP) \-\- Set \fBTrue\fP to preserve the \(dquser\-id\(dq field across a federation link, even if the user\-id does not match that used to republish the message. Set to \fBFalse\fP to clear the \(dquser\-id\(dq field when messages are federated. Only set this to \fBTrue\fP if you trust the upstream broker not to forge user\-ids. .IP \(bu 2 \fBexchange\fP (\fI\%str\fP) \-\- The name of the upstream exchange. Default is to use the same name as the federated exchange. .IP \(bu 2 \fBmax_hops\fP (\fI\%int\fP) \-\- Maximum number of federation links that messages can traverse before being dropped. Defaults to 1 if not set. .IP \(bu 2 \fBexpires\fP (\fI\%int\fP) \-\- Time in milliseconds that the upstream should remember about this node for. After this time all upstream state will be removed. Set to \fBNone\fP (Default) to mean \(dqforever\(dq. .IP \(bu 2 \fBmessage_ttl\fP (\fI\%int\fP) \-\- Time in milliseconds that undelivered messages should be held upstream when there is a network outage or backlog. Set to \fBNone\fP (default) to mean \(dqforever\(dq. .IP \(bu 2 \fBha_policy\fP (\fI\%str\fP) \-\- Determines the \(dqx\-ha\-policy\(dq\-argument for the upstream queue for a federated exchange. Default is \(dqnone\(dq meaning the queue is not HA. .IP \(bu 2 \fBqueue\fP (\fI\%str\fP) \-\- The name of the upstream queue. Default is to use the same name as the federated queue. .UNINDENT .UNINDENT .sp New in version 3000. .UNINDENT .SS salt.states.rabbitmq_user .SS Manage RabbitMQ Users .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rabbit_user: rabbitmq_user.present: \- password: password \- force: True \- tags: \- monitoring \- user \- perms: \- \(aq/\(aq: \- \(aq.*\(aq \- \(aq.*\(aq \- \(aq.*\(aq \- runas: rabbitmq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rabbitmq_user.absent(name, runas=None) Ensure the named user is absent .INDENT 7.0 .TP .B name The name of the user to remove .TP .B runas User to run the command .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rabbitmq_user.present(name, password=None, force=False, tags=None, perms=(), runas=None) Ensure the RabbitMQ user exists. .INDENT 7.0 .TP .B name User name .TP .B password The user\(aqs password .TP .B force If force is \fBTrue\fP, the password will be automatically updated without extra password change check. .TP .B tags Optional list of tags for the user .TP .B perms A list of dicts with vhost keys and 3\-tuple values .TP .B runas Name of the user to run the command .UNINDENT .UNINDENT .SS salt.states.rabbitmq_vhost .SS Manage RabbitMQ Virtual Hosts .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virtual_host: rabbitmq_vhost.present: \- user: rabbit_user \- conf: .* \- write: .* \- read: .* .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rabbitmq_vhost.absent(name) Ensure the RabbitMQ Virtual Host is absent .INDENT 7.0 .TP .B name Name of the Virtual Host to remove .TP .B runas User to run the command .sp Deprecated since version 2015.8.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rabbitmq_vhost.present(name) Ensure the RabbitMQ VHost exists. .INDENT 7.0 .TP .B name VHost name .TP .B user Initial user permission to set on the VHost, if present .sp Deprecated since version 2015.8.0. .TP .B owner Initial owner permission to set on the VHost, if present .sp Deprecated since version 2015.8.0. .TP .B conf Initial conf string to apply to the VHost and user. Defaults to .* .sp Deprecated since version 2015.8.0. .TP .B write Initial write permissions to apply to the VHost and user. Defaults to .* .sp Deprecated since version 2015.8.0. .TP .B read Initial read permissions to apply to the VHost and user. Defaults to .* .sp Deprecated since version 2015.8.0. .TP .B runas Name of the user to run the command .sp Deprecated since version 2015.8.0. .UNINDENT .UNINDENT .SS salt.states.rbac_solaris .sp Management of Solaris RBAC .INDENT 0.0 .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B depends rbac_solaris,solaris_user .TP .B platform solaris,illumos .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sjorge: rbac.managed: \- roles: \- netcfg \- profiles: \- System Power \- authorizations: \- solaris.audit.* .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rbac_solaris.managed(name, roles=None, profiles=None, authorizations=None) Manage RBAC properties for user .INDENT 7.0 .TP .B name string username .TP .B roles list list of roles for user .TP .B profiles list list of profiles for user .TP .B authorizations list list of authorizations for user .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 All existing roles, profiles and authorizations will be replaced! An empty list will remove everything. .sp Set the property to \fINone\fP to not manage it. .UNINDENT .UNINDENT .UNINDENT .SS salt.states.rbenv .SS Managing Ruby installations with rbenv .sp This module is used to install and manage ruby installations with rbenv and the ruby\-build plugin. Different versions of ruby can be installed, and uninstalled. Rbenv will be installed automatically the first time it is needed and can be updated later. This module will \fInot\fP automatically install packages which rbenv will need to compile the versions of ruby. If your version of ruby fails to install, refer to the ruby\-build documentation to verify you are not missing any dependencies: \fI\%https://github.com/rbenv/ruby\-build/wiki\fP .sp If rbenv is run as the root user then it will be installed to /usr/local/rbenv, otherwise it will be installed to the users ~/.rbenv directory. To make rbenv available in the shell you may need to add the rbenv/shims and rbenv/bin directories to the users PATH. If you are installing as root and want other users to be able to access rbenv then you will need to add RBENV_ROOT to their environment. .sp The following state configuration demonstrates how to install Ruby 1.9.x and 2.x using rbenv on Ubuntu/Debian: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rbenv\-deps: pkg.installed: \- names: \- bash \- git \- openssl \- libssl\-dev \- make \- curl \- autoconf \- bison \- build\-essential \- libffi\-dev \- libyaml\-dev \- libreadline6\-dev \- zlib1g\-dev \- libncurses5\-dev ruby\-1.9.3\-p429: rbenv.absent: \- require: \- pkg: rbenv\-deps ruby\-2.0.0\-p598: rbenv.installed: \- default: True \- require: \- pkg: rbenv\-deps .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rbenv.absent(name, user=None) Verify that the specified ruby is not installed with rbenv. Rbenv is installed if necessary. .INDENT 7.0 .TP .B name The version of ruby to uninstall .TP .B user: None The user to run rbenv as. .sp New in version 0.17.0. .UNINDENT .sp New in version 0.16.0. .UNINDENT .INDENT 0.0 .TP .B salt.states.rbenv.install_rbenv(name, user=None) Install rbenv if not installed. Allows you to require rbenv be installed prior to installing the plugins. Useful if you want to install rbenv plugins via the git or file modules and need them installed before installing any rubies. .sp Use the rbenv.root configuration option to set the path for rbenv if you want a system wide install that is not in a user home dir. .INDENT 7.0 .TP .B user: None The user to run rbenv as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rbenv.installed(name, default=False, user=None) Verify that the specified ruby is installed with rbenv. Rbenv is installed if necessary. .INDENT 7.0 .TP .B name The version of ruby to install .TP .B default False Whether to make this ruby the default. .TP .B user: None The user to run rbenv as. .sp New in version 0.17.0. .UNINDENT .sp New in version 0.16.0. .UNINDENT .SS salt.states.rdp .sp Manage RDP Service on Windows servers .INDENT 0.0 .TP .B salt.states.rdp.disabled(name) Disable the RDP service .UNINDENT .INDENT 0.0 .TP .B salt.states.rdp.enabled(name) Enable the RDP service and make sure access to the RDP port is allowed in the firewall configuration .UNINDENT .SS salt.states.redismod .SS Management of Redis server .sp New in version 2014.7.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 redis Python module .UNINDENT .TP .B configuration See \fBsalt.modules.redis\fP for setup instructions. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C key_in_redis: redis.string: \- value: string data .ft P .fi .UNINDENT .UNINDENT .sp The redis server information specified in the minion config file can be overridden in states using the following arguments: \fBhost\fP, \fBpost\fP, \fBdb\fP, \fBpassword\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C key_in_redis: redis.string: \- value: string data \- host: localhost \- port: 6379 \- db: 0 \- password: somuchkittycat .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.redismod.absent(name, keys=None, **connection_args) Ensure key absent from redis .INDENT 7.0 .TP .B name Key to ensure absent from redis .TP .B keys list of keys to ensure absent, name will be ignored if this is used .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.redismod.slaveof(name, sentinel_host=None, sentinel_port=None, sentinel_password=None, **connection_args) Set this redis instance as a slave. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name Master to make this a slave of .TP .B sentinel_host Ip of the sentinel to check for the master .TP .B sentinel_port Port of the sentinel to check for the master .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.redismod.string(name, value, expire=None, expireat=None, **connection_args) Ensure that the key exists in redis with the value specified .INDENT 7.0 .TP .B name Redis key to manage .TP .B value Data to persist in key .TP .B expire Sets time to live for key in seconds .TP .B expireat Sets expiration time for key via UNIX timestamp, overrides \fIexpire\fP .UNINDENT .UNINDENT .SS salt.states.reg .SS Manage the Windows registry .sp Many python developers think of registry keys as if they were python keys in a dictionary which is not the case. The windows registry is broken down into the following components: .SS Hives .sp This is the top level of the registry. They all begin with HKEY. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 HKEY_CLASSES_ROOT (HKCR) .IP \(bu 2 HKEY_CURRENT_USER (HKCU) .IP \(bu 2 HKEY_LOCAL MACHINE (HKLM) .IP \(bu 2 HKEY_USER (HKU) .IP \(bu 2 HKEY_CURRENT_CONFIG .UNINDENT .UNINDENT .UNINDENT .SS Keys .sp Hives contain keys. These are basically the folders beneath the hives. They can contain any number of subkeys. .sp When passing the hivekey values they must be quoted correctly depending on the backslashes being used (\fB\e\fP vs \fB\e\e\fP). The way backslashes are handled in the state file is different from the way they are handled when working on the CLI. The following are valid methods of passing the hivekey: .INDENT 0.0 .TP .B Using single backslashes: HKLMSOFTWAREPython \(aqHKLMSOFTWAREPython\(aq .TP .B Using double backslashes: \(dqHKLM\eSOFTWARE\ePython\(dq .UNINDENT .SS Values or Entries .sp Values or Entries are the name/data pairs beneath the keys and subkeys. All keys have a default name/data pair. The name is \fB(Default)\fP with a displayed value of \fB(value not set)\fP\&. The actual value is Null. .sp Example .sp The following example is taken from the windows startup portion of the registry: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [HKEY_LOCAL_MACHINE\eSOFTWARE\eMicrosoft\eWindows\eCurrentVersion\eRun] \(dqRTHDVCPL\(dq=\(dq\e\(dqC:\e\eProgram Files\e\eRealtek\e\eAudio\e\eHDA\e\eRtkNGUI64.exe\e\(dq \-s\(dq \(dqNvBackend\(dq=\(dq\e\(dqC:\e\eProgram Files (x86)\e\eNVIDIA Corporation\e\eUpdate Core\e\eNvBackend.exe\e\(dq\(dq \(dqBTMTrayAgent\(dq=\(dqrundll32.exe \e\(dqC:\e\eProgram Files (x86)\e\eIntel\e\eBluetooth\e\ebtmshellex.dll\e\(dq,TrayApp\(dq .ft P .fi .UNINDENT .UNINDENT .sp In this example these are the values for each: .INDENT 0.0 .TP .B Hive: \fBHKEY_LOCAL_MACHINE\fP .TP .B Key and subkeys: \fBSOFTWARE\e\eMicrosoft\e\eWindows\e\eCurrentVersion\e\eRun\fP .UNINDENT .sp Value: .INDENT 0.0 .IP \(bu 2 There are 3 value names: \fBRTHDVCPL\fP, \fBNvBackend\fP, and \fBBTMTrayAgent\fP .IP \(bu 2 Each value name has a corresponding value .UNINDENT .INDENT 0.0 .TP .B salt.states.reg.absent(name, vname=None, use_32bit_registry=False) Ensure a registry value is removed. To remove a key use key_absent. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- .sp A string value representing the full path of the key to include the HIVE, Key, and all Subkeys. For example: .sp \fBHKEY_LOCAL_MACHINE\eSOFTWARE\eSalt\fP .sp Valid hive values include: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 HKEY_CURRENT_USER or HKCU .IP \(bu 2 HKEY_LOCAL_MACHINE or HKLM .IP \(bu 2 HKEY_USERS or HKU .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBvname\fP (\fI\%str\fP) \-\- The name of the value you\(aqd like to create beneath the Key. If this parameter is not passed it will assume you want to set the \fB(Default)\fP value .IP \(bu 2 \fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Use the 32bit portion of the registry. Applies only to 64bit windows. 32bit Windows will ignore this parameter. Default is False. .UNINDENT .TP .B Returns A dictionary showing the results of the registry operation. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aqHKEY_CURRENT_USER\eSOFTWARE\eSalt\(aq: reg.absent \- vname: version .ft P .fi .UNINDENT .UNINDENT .sp In the above example the value named \fBversion\fP will be removed from the SOFTWARE\eSalt key in the HKEY_CURRENT_USER hive. If \fBvname\fP was not passed, the \fB(Default)\fP value would be deleted. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.reg.key_absent(name, use_32bit_registry=False) New in version 2015.5.4. .sp Ensure a registry key is removed. This will remove the key, subkeys, and all value entries. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- .sp A string representing the full path to the key to be removed to include the hive and the keypath. The hive can be any of the following: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 HKEY_LOCAL_MACHINE or HKLM .IP \(bu 2 HKEY_CURRENT_USER or HKCU .IP \(bu 2 HKEY_USER or HKU .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Use the 32bit portion of the registry. Applies only to 64bit windows. 32bit Windows will ignore this parameter. Default is False. .UNINDENT .TP .B Returns A dictionary showing the results of the registry operation. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 The following example will delete the \fBSOFTWARE\eDeleteMe\fP key in the \fBHKEY_LOCAL_MACHINE\fP hive including all its subkeys and value pairs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C remove_key_demo: reg.key_absent: \- name: HKEY_CURRENT_USER\eSOFTWARE\eDeleteMe .ft P .fi .UNINDENT .UNINDENT .sp In the above example the path is interpreted as follows: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBHKEY_CURRENT_USER\fP is the hive .IP \(bu 2 \fBSOFTWARE\eDeleteMe\fP is the key .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.reg.present(name, vname=None, vdata=None, vtype=\(aqREG_SZ\(aq, use_32bit_registry=False, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=True, win_perms_reset=False) Ensure a registry key or value is present. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- .sp A string value representing the full path of the key to include the HIVE, Key, and all Subkeys. For example: .sp \fBHKEY_LOCAL_MACHINE\eSOFTWARE\eSalt\fP .sp Valid hive values include: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 HKEY_CURRENT_USER or HKCU .IP \(bu 2 HKEY_LOCAL_MACHINE or HKLM .IP \(bu 2 HKEY_USERS or HKU .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBvname\fP (\fI\%str\fP) \-\- The name of the value you\(aqd like to create beneath the Key. If this parameter is not passed it will assume you want to set the \fB(Default)\fP value .IP \(bu 2 \fBvdata\fP (\fI\%str\fP\fI, \fP\fI\%int\fP\fI, \fP\fI\%list\fP\fI, \fP\fI\%bytes\fP) \-\- .sp The value you\(aqd like to set. If a value name (\fBvname\fP) is passed, this will be the data for that value name. If not, this will be the \fB(Default)\fP value for the key. .sp The type of data this parameter expects is determined by the value type specified in \fBvtype\fP\&. The correspondence is as follows: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 REG_BINARY: Binary data (str in Py2, bytes in Py3) .IP \(bu 2 REG_DWORD: int .IP \(bu 2 REG_EXPAND_SZ: str .IP \(bu 2 REG_MULTI_SZ: list of str .IP \(bu 2 REG_QWORD: int .IP \(bu 2 REG_SZ: str .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When setting REG_BINARY, string data will be converted to binary automatically. To pass binary data, use the built\-in yaml tag \fB!!binary\fP to denote the actual binary characters. For example, the following lines will both set the same data in the registry: .INDENT 0.0 .IP \(bu 2 \fBvdata: Salty Test\fP .IP \(bu 2 \fBvdata: !!binary U2FsdHkgVGVzdA==\en\fP .UNINDENT .sp For more information about the \fB!!binary\fP tag see \fI\%here\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The type for the \fB(Default)\fP value is always REG_SZ and cannot be changed. This parameter is optional. If not passed, the Key will be created with no associated item/value pairs. .UNINDENT .UNINDENT .IP \(bu 2 \fBvtype\fP (\fI\%str\fP) \-\- .sp The value type for the data you wish to store in the registry. Valid values are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 REG_BINARY .IP \(bu 2 REG_DWORD .IP \(bu 2 REG_EXPAND_SZ .IP \(bu 2 REG_MULTI_SZ .IP \(bu 2 REG_QWORD .IP \(bu 2 REG_SZ (Default) .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Use the 32bit portion of the registry. Applies only to 64bit windows. 32bit Windows will ignore this parameter. Default is False. .IP \(bu 2 \fBwin_owner\fP (\fI\%str\fP) \-\- .sp The owner of the registry key. If this is not passed, the account under which Salt is running will be used. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 Owner is set for the key that contains the value/data pair. You cannot set ownership on value/data pairs themselves. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBwin_perms\fP (\fI\%dict\fP) \-\- .sp A dictionary containing permissions to grant and their propagation. If not passed the \(aqGrant\(ga permissions will not be modified. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 Permissions are set for the key that contains the value/data pair. You cannot set permissions on value/data pairs themselves. .UNINDENT .UNINDENT .sp For each user specify the account name, with a sub dict for the permissions to grant and the \(aqApplies to\(aq setting. For example: \fB{\(aqAdministrators\(aq: {\(aqperms\(aq: \(aqfull_control\(aq, \(aqapplies_to\(aq: \(aqthis_key_subkeys\(aq}}\fP\&. \fBperms\fP must be specified. .sp Registry permissions are specified using the \fBperms\fP key. You can specify a single basic permission or a list of advanced perms. The following are valid perms: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .TP .B Basic (passed as a string): .INDENT 7.0 .IP \(bu 2 full_control .IP \(bu 2 read .IP \(bu 2 write .UNINDENT .TP .B Advanced (passed as a list): .INDENT 7.0 .IP \(bu 2 delete .IP \(bu 2 query_value .IP \(bu 2 set_value .IP \(bu 2 create_subkey .IP \(bu 2 enum_subkeys .IP \(bu 2 notify .IP \(bu 2 create_link .IP \(bu 2 read_control .IP \(bu 2 write_dac .IP \(bu 2 write_owner .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp The \(aqApplies to\(aq setting is optional. It is specified using the \fBapplies_to\fP key. If not specified \fBthis_key_subkeys\fP is used. Valid options are: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .TP .B Applies to settings: .INDENT 7.0 .IP \(bu 2 this_key_only .IP \(bu 2 this_key_subkeys .IP \(bu 2 subkeys_only .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBwin_deny_perms\fP (\fI\%dict\fP) \-\- .sp A dictionary containing permissions to deny and their propagation. If not passed the \fIDeny\fP permissions will not be modified. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 Permissions are set for the key that contains the value/data pair. You cannot set permissions on value/data pairs themselves. .UNINDENT .UNINDENT .sp Valid options are the same as those specified in \fBwin_perms\fP .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .TP .B \(aqDeny\(aq permissions always take precedence over \(aqgrant\(aq permissions. .UNINDENT .UNINDENT .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBwin_inheritance\fP (\fI\%bool\fP) \-\- .sp \fBTrue\fP to inherit permissions from the parent key. \fBFalse\fP to disable inheritance. Default is \fBTrue\fP\&. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 Inheritance is set for the key that contains the value/data pair. You cannot set inheritance on value/data pairs themselves. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .IP \(bu 2 \fBwin_perms_reset\fP (\fI\%bool\fP) \-\- .sp If \fBTrue\fP the existing DACL will be cleared and replaced with the settings defined in this function. If \fBFalse\fP, new entries will be appended to the existing DACL. Default is \fBFalse\fP .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 Perms are reset for the key that contains the value/data pair. You cannot set permissions on value/data pairs themselves. .UNINDENT .UNINDENT .sp New in version 2019.2.0. .UNINDENT .TP .B Returns A dictionary showing the results of the registry operation. .TP .B Return type \fI\%dict\fP .UNINDENT .sp Example: .sp The following example will set the \fB(Default)\fP value for the \fBSOFTWARE\eSalt\fP key in the \fBHKEY_CURRENT_USER\fP hive to \fB2016.3.1\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HKEY_CURRENT_USER\eSOFTWARE\eSalt: reg.present: \- vdata: 2016.3.1 .ft P .fi .UNINDENT .UNINDENT .sp Example: .sp The following example will set the value for the \fBversion\fP entry under the \fBSOFTWARE\eSalt\fP key in the \fBHKEY_CURRENT_USER\fP hive to \fB2016.3.1\fP\&. The value will be reflected in \fBWow6432Node\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C HKEY_CURRENT_USER\eSOFTWARE\eSalt: reg.present: \- vname: version \- vdata: 2016.3.1 .ft P .fi .UNINDENT .UNINDENT .sp In the above example the path is interpreted as follows: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBHKEY_CURRENT_USER\fP is the hive .IP \(bu 2 \fBSOFTWARE\eSalt\fP is the key .IP \(bu 2 \fBvname\fP is the value name (\(aqversion\(aq) that will be created under the key .IP \(bu 2 \fBvdata\fP is the data that will be assigned to \(aqversion\(aq .UNINDENT .UNINDENT .UNINDENT .sp Example: .sp Binary data can be set in two ways. The following two examples will set a binary value of \fBSalty Test\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C no_conversion: reg.present: \- name: HKLM\eSOFTWARE\eSaltTesting \- vname: test_reg_binary_state \- vdata: Salty Test \- vtype: REG_BINARY conversion: reg.present: \- name: HKLM\eSOFTWARE\eSaltTesting \- vname: test_reg_binary_state_with_tag \- vdata: !!binary U2FsdHkgVGVzdA==\en \- vtype: REG_BINARY .ft P .fi .UNINDENT .UNINDENT .sp Example: .sp To set a \fBREG_MULTI_SZ\fP value: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C reg_multi_sz: reg.present: \- name: HKLM\eSOFTWARE\eSalt \- vname: reg_multi_sz \- vdata: \- list item 1 \- list item 2 .ft P .fi .UNINDENT .UNINDENT .sp Example: .sp To ensure a key is present and has permissions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C set_key_permissions: reg.present: \- name: HKLM\eSOFTWARE\eSalt \- vname: version \- vdata: 2016.3.1 \- win_owner: Administrators \- win_perms: jsnuffy: perms: full_control sjones: perms: \- read_control \- enum_subkeys \- query_value applies_to: \- this_key_only \- win_deny_perms: bsimpson: perms: full_control applies_to: this_key_subkeys \- win_inheritance: True \- win_perms_reset: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.restconf .sp RESTCONF State module for Proxy minions .INDENT 0.0 .TP .B codeauthor Jamie (Bear) Murphy <\fI\%jamiemurphyit@gmail.com\fP> .TP .B maturity new .TP .B platform any .UNINDENT .SS About .sp This state module was designed to manage RESTCONF states. This module relies on the RESTCONF proxy module to interface with the devices. .INDENT 0.0 .TP .B salt.states.restconf.config_manage(name, path, method, config, init_path=None, init_method=\(aqPATCH\(aq, init_config=None) Ensure a specific value exists at a given path .INDENT 7.0 .TP .B name: (str) The name for this rule .TP .B path: (str) The RESTCONF path to set / get config .TP .B method: (str) rest method to use eg GET, PUT, POST, PATCH, DELETE .TP .B config: (dict) The new value at the given path .TP .B init_path: (optional) (str) Alternative path incase the path doesnt exist on first pass .TP .B init_method: (optional) (str) Method to use on alternative path when setting config, default: PATCH .TP .B init_config: (optional) (dict) The new value at the given init path. This is only needed if you need to supply a different style of data to an init path. .UNINDENT .sp Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C do_configure_restconf_endpoint: restconf.config_manage: \- name: random_name_here \- path: restconf/data/Cisco\-IOS\-XE\-native:native/interface/GigabitEthernet=1%2F0%2F3 \- config: Cisco\-IOS\-XE\-native:GigabitEthernet: description: interfaceDescription name: \(dq1/0/3\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.rsync .sp State to synchronize files and directories with rsync. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /opt/user\-backups: rsync.synchronized: \- source: /home \- force: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rsync.synchronized(name, source, delete=False, force=False, update=False, passwordfile=None, exclude=None, excludefrom=None, prepare=False, dryrun=False, additional_opts=None) Guarantees that the source directory is always copied to the target. .INDENT 7.0 .TP .B name Name of the target directory. .TP .B source Source directory. .TP .B prepare Create destination directory if it does not exists. .TP .B delete Delete extraneous files from the destination dirs (True or False) .TP .B force Force deletion of dirs even if not empty .TP .B update Skip files that are newer on the receiver (True or False) .TP .B passwordfile Read daemon\-access password from the file (path) .TP .B exclude Exclude files, that matches pattern. .TP .B excludefrom Read exclude patterns from the file (path) .TP .B dryrun Perform a trial run with no changes made. Is the same as doing test=True .sp New in version 2016.3.1. .TP .B additional_opts Pass additional options to rsync, should be included as a list. .sp New in version 2018.3.0. .UNINDENT .UNINDENT .SS salt.states.rvm .SS Managing Ruby installations and gemsets with Ruby Version Manager (RVM) .sp This module is used to install and manage ruby installations and gemsets with RVM, the Ruby Version Manager. Different versions of ruby can be installed and gemsets created. RVM itself will be installed automatically if it\(aqs not present. This module will not automatically install packages that RVM depends on or ones that are needed to build ruby. If you want to run RVM as an unprivileged user (recommended) you will have to create this user yourself. This is how a state configuration could look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rvm: group.present: [] user.present: \- gid: rvm \- home: /home/rvm \- require: \- group: rvm rvm\-deps: pkg.installed: \- pkgs: \- bash \- coreutils \- gzip \- bzip2 \- gawk \- sed \- curl \- git\-core \- subversion mri\-deps: pkg.installed: \- pkgs: \- build\-essential \- openssl \- libreadline6 \- libreadline6\-dev \- curl \- git\-core \- zlib1g \- zlib1g\-dev \- libssl\-dev \- libyaml\-dev \- libsqlite3\-0 \- libsqlite3\-dev \- sqlite3 \- libxml2\-dev \- libxslt1\-dev \- autoconf \- libc6\-dev \- libncurses5\-dev \- automake \- libtool \- bison \- subversion \- ruby jruby\-deps: pkg.installed: \- pkgs: \- curl \- g++ \- openjdk\-6\-jre\-headless ruby\-1.9.2: rvm.installed: \- default: True \- user: rvm \- require: \- pkg: rvm\-deps \- pkg: mri\-deps \- user: rvm jruby: rvm.installed: \- user: rvm \- require: \- pkg: rvm\-deps \- pkg: jruby\-deps \- user: rvm jgemset: rvm.gemset_present: \- ruby: jruby \- user: rvm \- require: \- rvm: jruby mygemset: rvm.gemset_present: \- ruby: ruby\-1.9.2 \- user: rvm \- require: \- rvm: ruby\-1.9.2 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rvm.gemset_present(name, ruby=\(aqdefault\(aq, user=None) Verify that the gemset is present. .INDENT 7.0 .TP .B name The name of the gemset. .TP .B ruby: default The ruby version this gemset belongs to. .TP .B user: None The user to run rvm as. .sp New in version 0.17.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rvm.installed(name, default=False, user=None, opts=None, env=None) Verify that the specified ruby is installed with RVM. RVM is installed when necessary. .INDENT 7.0 .TP .B name The version of ruby to install .TP .B default False Whether to make this ruby the default. .TP .B user: None The user to run rvm as. .TP .B env: None A list of environment variables to set (ie, RUBY_CONFIGURE_OPTS) .TP .B opts: None A list of option flags to pass to RVM (ie \-C, \-\-patch) .sp New in version 0.17.0. .UNINDENT .UNINDENT .SS salt.states.salt_proxy .sp Salt proxy state .sp New in version 2015.8.2. .sp State to deploy and run salt\-proxy processes on a minion. .sp Set up pillar data for your proxies per the documentation. .sp Run the state as below .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy\-configure: salt_proxy.configure_proxy: \- proxyname: p8000 \- start: True .ft P .fi .UNINDENT .UNINDENT .sp This state will configure the salt proxy settings within /etc/salt/proxy (if /etc/salt/proxy doesn\(aqt exists) and start the salt\-proxy process (default true), if it isn\(aqt already running. .INDENT 0.0 .TP .B salt.states.salt_proxy.configure_proxy(name, proxyname=\(aqp8000\(aq, start=True) Create the salt proxy file and start the proxy process if required .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of this state .IP \(bu 2 \fBproxyname\fP \-\- Name to be used for this proxy (should match entries in pillar) .IP \(bu 2 \fBstart\fP \-\- Boolean indicating if the process should be started .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy\-configure: salt_proxy.configure_proxy: \- proxyname: p8000 \- start: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.saltmod .SS Control the Salt command interface .sp This state is intended for use from the Salt Master. It provides access to sending commands down to minions as well as access to executing master\-side modules. These state functions wrap Salt\(aqs \fI\%Python API\fP\&. .INDENT 0.0 .INDENT 3.5 New in version 2016.11.0. .sp Support for masterless minions was added to the \fBsalt.state\fP function, so they can run orchestration sls files. This is particularly useful when the rendering of a state is dependent on the execution of another state. Orchestration will render and execute each orchestration block independently, while honoring requisites to ensure the states are applied in the correct order. .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 More Orchestrate documentation .INDENT 0.0 .IP \(bu 2 \fI\%Full Orchestrate Tutorial\fP .IP \(bu 2 \fI\%The Orchestrate runner\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltmod.function(name, tgt, ssh=False, tgt_type=\(aqglob\(aq, ret=\(aq\(aq, ret_config=None, ret_kwargs=None, expect_minions=False, fail_minions=None, fail_function=None, arg=None, kwarg=None, timeout=None, batch=None, subset=None, failhard=None, **kwargs) Execute a single module function on a remote minion via salt or salt\-ssh .INDENT 7.0 .TP .B name The name of the function to run, aka cmd.run or pkg.install .TP .B tgt The target specification, aka \(aq*\(aq for all minions .TP .B tgt_type The target type, defaults to \fBglob\fP .TP .B arg The list of arguments to pass into the function .TP .B kwarg The dict (not a list) of keyword arguments to pass into the function .TP .B ret Optionally set a single or a list of returners to use .TP .B ret_config Use an alternative returner configuration .TP .B ret_kwargs Override individual returner configuration items .TP .B expect_minions An optional boolean for failing if some minions do not respond .TP .B fail_minions An optional list of targeted minions where failure is an option .TP .B fail_function An optional string that points to a salt module that returns True or False based on the returned data dict for individual minions .TP .B ssh Set to \fITrue\fP to use the ssh client instead of the standard salt client .TP .B roster In the event of using salt\-ssh, a roster system can be set .sp New in version 3005. .TP .B batch Execute the command \fI\%in batches\fP\&. E.g.: \fB10%\fP\&. .TP .B subset Number of minions from the targeted set to randomly use .sp New in version 2017.7.0. .TP .B failhard pass failhard down to the executing state .sp New in version 2019.2.2. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltmod.parallel_runners(name, runners, **kwargs) Executes multiple runner modules on the master in parallel. .sp New in version 2018.3.0. .sp A separate thread is spawned for each runner. This state is intended to be used with the orchestrate runner in place of the \fBsaltmod.runner\fP state when different tasks should be run in parallel. In general, Salt states are not safe when used concurrently, so ensure that they are used in a safe way (e.g. by only targeting separate minions in parallel tasks). .INDENT 7.0 .TP .B name: name identifying this state. The name is provided as part of the output, but not used for anything else. .TP .B runners: list of runners that should be run in parallel. Each element of the list has to be a dictionary. This dictionary\(aqs name entry stores the name of the runner function that shall be invoked. The optional kwarg entry stores a dictionary of named arguments that are passed to the runner function. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C parallel\-state: salt.parallel_runners: \- runners: my_runner_1: \- name: state.orchestrate \- kwarg: mods: orchestrate_state_1 my_runner_2: \- name: state.orchestrate \- kwarg: mods: orchestrate_state_2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltmod.runner(name, **kwargs) Execute a runner module on the master .sp New in version 2014.7.0. .INDENT 7.0 .TP .B name The name of the function to run .TP .B kwargs Any keyword arguments to pass to the runner function .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C run\-manage\-up: salt.runner: \- name: manage.up .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltmod.state(name, tgt, ssh=False, tgt_type=\(aqglob\(aq, ret=\(aq\(aq, ret_config=None, ret_kwargs=None, highstate=None, sls=None, top=None, saltenv=None, test=None, pillar=None, pillarenv=None, expect_minions=True, exclude=None, fail_minions=None, allow_fail=0, concurrent=False, timeout=None, batch=None, queue=False, subset=None, orchestration_jid=None, failhard=None, **kwargs) Invoke a state run on a given target .INDENT 7.0 .TP .B name An arbitrary name used to track the state execution .TP .B tgt The target specification for the state run. .sp New in version 2016.11.0. .sp Masterless support: When running on a masterless minion, the \fBtgt\fP is ignored and will always be the local minion. .TP .B tgt_type The target type to resolve, defaults to \fBglob\fP .TP .B ret Optionally set a single or a list of returners to use .TP .B ret_config Use an alternative returner configuration .TP .B ret_kwargs Override individual returner configuration items .TP .B highstate Defaults to None, if set to True the target systems will ignore any sls references specified in the sls option and call state.highstate on the targeted minions .TP .B top Should be the name of a top file. If set state.top is called with this top file instead of state.sls. .TP .B sls A group of sls files to execute. This can be defined as a single string containing a single sls file, or a list of sls files .TP .B test Pass \fBtest=true\fP or \fBtest=false\fP through to the state function. This can be used to override a test mode set in the minion\(aqs config file. If left as the default of None and the \(aqtest\(aq mode is supplied on the command line, that value is passed instead. .TP .B pillar Pass the \fBpillar\fP kwarg through to the state function .TP .B pillarenv The pillar environment to grab pillars from .sp New in version 2017.7.0. .TP .B saltenv The default salt environment to pull sls files from .TP .B ssh Set to \fITrue\fP to use the ssh client instead of the standard salt client .TP .B roster In the event of using salt\-ssh, a roster system can be set .TP .B expect_minions An optional boolean for failing if some minions do not respond .TP .B fail_minions An optional list of targeted minions where failure is an option .TP .B allow_fail Pass in the number of minions to allow for failure before setting the result of the execution to False .TP .B exclude Pass exclude kwarg to state .TP .B concurrent Allow multiple state runs to occur at once. .sp WARNING: This flag is potentially dangerous. It is designed for use when multiple state runs can safely be run at the same Do not use this flag for performance optimization. .TP .B queue Pass \fBqueue=true\fP through to the state function .TP .B batch Execute the command \fI\%in batches\fP\&. E.g.: \fB10%\fP\&. .sp New in version 2016.3.0. .TP .B subset Number of minions from the targeted set to randomly use .sp New in version 2017.7.0. .TP .B failhard pass failhard down to the executing state .sp New in version 2019.2.2. .UNINDENT .sp Examples: .sp Run a list of sls files via \fBstate.sls\fP on target minions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C webservers: salt.state: \- tgt: \(aqweb*\(aq \- sls: \- apache \- django \- core \- saltenv: prod .ft P .fi .UNINDENT .UNINDENT .sp Run sls file via \fBstate.sls\fP on target minions with exclude: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C docker: salt.state: \- tgt: \(aqdocker*\(aq \- sls: docker \- exclude: docker.swarm \- saltenv: prod .ft P .fi .UNINDENT .UNINDENT .sp Run a full \fBstate.highstate\fP on target mininons. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C databases: salt.state: \- tgt: role:database \- tgt_type: grain \- highstate: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltmod.wait_for_event(name, id_list, event_id=\(aqid\(aq, timeout=300, node=\(aqmaster\(aq) Watch Salt\(aqs event bus and block until a condition is met .sp New in version 2014.7.0. .INDENT 7.0 .TP .B name An event tag to watch for; supports Reactor\-style globbing. .TP .B id_list A list of event identifiers to watch for \-\- usually the minion ID. Each time an event tag is matched the event data is inspected for \fBevent_id\fP, if found it is removed from \fBid_list\fP\&. When \fBid_list\fP is empty this function returns success. .TP .B event_id id The name of a key in the event data. Default is \fBid\fP for the minion ID, another common value is \fBname\fP for use with orchestrating salt\-cloud events. .TP .B timeout 300 The maximum time in seconds to wait before failing. .UNINDENT .sp The following example blocks until all the listed minions complete a restart and reconnect to the Salt master: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C reboot_all_minions: salt.function: \- name: system.reboot \- tgt: \(aq*\(aq wait_for_reboots: salt.wait_for_event: \- name: salt/minion/*/start \- id_list: \- jerry \- stuart \- dave \- phil \- kevin \- mike \- require: \- salt: reboot_all_minions .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltmod.wheel(name, **kwargs) Execute a wheel module on the master .sp New in version 2014.7.0. .INDENT 7.0 .TP .B name The name of the function to run .TP .B kwargs Any keyword arguments to pass to the wheel function .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C accept_minion_key: salt.wheel: \- name: key.accept \- match: frank .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.saltutil .SS Saltutil State .sp This state wraps the saltutil execution modules to make them easier to run from a states. Rather than needing to to use \fBmodule.run\fP this state allows for improved change detection. .INDENT 0.0 .INDENT 3.5 New in version 3000. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_all(name, **kwargs) Performs the same task as saltutil.sync_all module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_all: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_beacons(name, **kwargs) Performs the same task as saltutil.sync_beacons module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_beacons: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_clouds(name, **kwargs) Performs the same task as saltutil.sync_clouds module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_clouds: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_engines(name, **kwargs) Performs the same task as saltutil.sync_engines module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_engines: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_executors(name, **kwargs) Performs the same task as saltutil.sync_executors module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_executors: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_grains(name, **kwargs) Performs the same task as saltutil.sync_grains module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_grains: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_log_handlers(name, **kwargs) Performs the same task as saltutil.sync_log_handlers module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_log_handlers: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_matchers(name, **kwargs) Performs the same task as saltutil.sync_matchers module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_matchers: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_modules(name, **kwargs) Performs the same task as saltutil.sync_modules module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_modules: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_output(name, **kwargs) Performs the same task as saltutil.sync_output module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_output: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_outputters(name, **kwargs) Performs the same task as saltutil.sync_outputters module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_outputters: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_pillar(name, **kwargs) Performs the same task as saltutil.sync_pillar module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_pillar: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_proxymodules(name, **kwargs) Performs the same task as saltutil.sync_proxymodules module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_proxymodules: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_renderers(name, **kwargs) Performs the same task as saltutil.sync_renderers module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_renderers: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_returners(name, **kwargs) Performs the same task as saltutil.sync_returners module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_returners: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_sdb(name, **kwargs) Performs the same task as saltutil.sync_sdb module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_sdb: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_serializers(name, **kwargs) Performs the same task as saltutil.sync_serializers module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_serializers: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_states(name, **kwargs) Performs the same task as saltutil.sync_states module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_states: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_thorium(name, **kwargs) Performs the same task as saltutil.sync_thorium module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_thorium: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_tops(name, **kwargs) Performs the same task as saltutil.sync_tops module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_tops: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_utils(name, **kwargs) Performs the same task as saltutil.sync_utils module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_utils: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.saltutil.sync_wrapper(name, **kwargs) New in version 3007.0. .sp Performs the same task as saltutil.sync_wrapper module See \fI\%saltutil module for full list of options\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sync_everything: saltutil.sync_wrapper: \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.schedule .SS Management of the Salt scheduler .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C job3: schedule.present: \- function: test.ping \- seconds: 3600 \- splay: 10 .ft P .fi .UNINDENT .UNINDENT .sp This will schedule the command: test.ping every 3600 seconds (every hour) splaying the time between 0 and 10 seconds .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C job2: schedule.present: \- function: test.ping \- seconds: 15 \- splay: start: 10 end: 20 .ft P .fi .UNINDENT .UNINDENT .sp This will schedule the command: test.ping every 15 seconds splaying the time between 10 and 20 seconds .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C job1: schedule.present: \- function: state.sls \- job_args: \- httpd \- job_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: state.sls httpd test=True at 5pm on Monday, Wednesday and Friday, and 3pm on Tuesday and Thursday. Requires that python\-dateutil is installed on the minion. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C job1: schedule.present: \- function: state.sls \- job_args: \- httpd \- job_kwargs: test: True \- cron: \(aq*/5 * * * *\(aq .ft P .fi .UNINDENT .UNINDENT .sp Scheduled jobs can also be specified using the format used by cron. This will schedule the command: state.sls httpd test=True to run every 5 minutes. Requires that python\-croniter is installed on the minion. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C job1: schedule.present: \- function: state.sls \- job_args: \- httpd \- job_kwargs: test: True \- when: \- Monday 5:00pm \- Tuesday 3:00pm \- Wednesday 5:00pm \- Thursday 3:00pm \- Friday 5:00pm \- returner: xmpp \- return_config: xmpp_state_run \- return_kwargs: recipient: user@domain.com .ft P .fi .UNINDENT .UNINDENT .sp This will schedule the command: state.sls httpd test=True at 5pm on Monday, Wednesday and Friday, and 3pm on Tuesday and Thursday. Using the xmpp returner to return the results of the scheduled job, with the alternative configuration options found in the xmpp_state_run section. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C job1: schedule.present: \- function: state.sls \- job_args: \- httpd \- job_kwargs: test: True \- hours: 1 \- skip_during_range: \- start: 2pm \- end: 3pm \- run_after_skip_range: True .ft P .fi .UNINDENT .UNINDENT .sp This will schedule the command: state.sls httpd test=True at 5pm on Monday, Wednesday and Friday, and 3pm on Tuesday and Thursday. Requires that python\-dateutil is installed on the minion. .INDENT 0.0 .TP .B salt.states.schedule.absent(name, **kwargs) Ensure a job is absent from the schedule .INDENT 7.0 .TP .B name The unique name that is given to the scheduled job. .TP .B persist Whether changes to the scheduled job should be saved, defaults to True. .sp When used with absent this will decide whether the scheduled job will be removed from the saved scheduled jobs and not be available when the Salt minion is restarted. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.schedule.disabled(name, **kwargs) Ensure a job is disabled in the schedule .INDENT 7.0 .TP .B name The unique name that is given to the scheduled job. .TP .B persist Whether changes to the scheduled job should be saved, defaults to True. .TP .B offline Delete the scheduled job to the Salt minion when the Salt minion is not running. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.schedule.enabled(name, **kwargs) Ensure a job is enabled in the schedule .INDENT 7.0 .TP .B name The unique name that is given to the scheduled job. .TP .B persist Whether changes to the scheduled job should be saved, defaults to True. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.schedule.present(name, **kwargs) Ensure a job is present in the schedule .INDENT 7.0 .TP .B name The unique name that is given to the scheduled job. .TP .B seconds The scheduled job will be executed after the specified number of seconds have passed. .TP .B minutes The scheduled job will be executed after the specified number of minutes have passed. .TP .B hours The scheduled job will be executed after the specified number of hours have passed. .TP .B days The scheduled job will be executed after the specified number of days have passed. .TP .B when This will schedule the job at the specified time(s). The when parameter must be a single value or a dictionary with the date string(s) using the dateutil format. Requires python\-dateutil. .TP .B cron This will schedule the job at the specified time(s) using the crontab format. Requires python\-croniter. .TP .B run_on_start Whether the scheduled job will run when Salt minion starts, or the job will be skipped \fBonce\fP and run at the next scheduled run. Value should be a boolean. .TP .B function The function that should be executed by the scheduled job. .TP .B job_args The arguments that will be used by the scheduled job. .TP .B job_kwargs The keyword arguments that will be used by the scheduled job. .TP .B maxrunning Ensure that there are no more than N copies of a particular job running. .TP .B jid_include Include the job into the job cache. .TP .B splay The amount of time in seconds to splay a scheduled job. Can be specified as a single value in seconds or as a dictionary range with \(aqstart\(aq and \(aqend\(aq values. .TP .B range This will schedule the command within the range specified. The range parameter must be a dictionary with the date strings using the dateutil format. Requires python\-dateutil. .TP .B once This will schedule a job to run once on the specified date. .TP .B once_fmt The default date format is ISO 8601 but can be overridden by also specifying the \fBonce_fmt\fP option. .TP .B enabled Whether the scheduled job should be enabled or disabled. Value should be a boolean. .TP .B return_job Whether to return information to the Salt master upon job completion. .TP .B metadata 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 return_job parameter. The metadata parameter must be specified as a dictionary, othewise it will be ignored. .TP .B returner The returner to use to return the results of the scheduled job. .TP .B return_config The alternative configuration to use for returner configuration options. .TP .B return_kwargs Any individual returner configuration items to override. Should be passed as a dictionary. .TP .B persist Whether changes to the scheduled job should be saved, defaults to True. .TP .B skip_during_range This will ensure that the scheduled command does not run within the range specified. The range parameter must be a dictionary with the date strings using the dateutil format. Requires python\-dateutil. .TP .B run_after_skip_range Whether the scheduled job should run immediately after the skip_during_range time period ends. .TP .B offline Add the scheduled job to the Salt minion when the Salt minion is not running. .sp New in version 3006.3. .UNINDENT .UNINDENT .SS salt.states.selinux .SS Management of SELinux rules .sp If SELinux is available for the running system, the mode can be managed and booleans can be set. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C enforcing: selinux.mode samba_create_home_dirs: selinux.boolean: \- value: True \- persist: True nginx: selinux.module: \- enabled: False .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Use of these states require that the \fI\%selinux\fP execution module is available. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.selinux.boolean(name, value, persist=False) Set up an SELinux boolean .INDENT 7.0 .TP .B name The name of the boolean to set .TP .B value The value to set on the boolean .TP .B persist Defaults to False, set persist to true to make the boolean apply on a reboot .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.selinux.fcontext_policy_absent(name, filetype=\(aqa\(aq, sel_type=None, sel_user=None, sel_level=None) New in version 2017.7.0. .sp Makes sure an SELinux file context policy for a given filespec (name), filetype and SELinux context type is absent. .INDENT 7.0 .TP .B name filespec of the file or directory. Regex syntax is allowed. .TP .B filetype The SELinux filetype specification. Use one of [a, f, d, c, b, s, l, p]. See also \fIman semanage\-fcontext\fP\&. Defaults to \(aqa\(aq (all files). .TP .B sel_type The SELinux context type. There are many. .TP .B sel_user The SELinux user. .TP .B sel_level The SELinux MLS range. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.selinux.fcontext_policy_applied(name, recursive=False) New in version 2017.7.0. .sp Checks and makes sure the SELinux policies for a given filespec are applied. .UNINDENT .INDENT 0.0 .TP .B salt.states.selinux.fcontext_policy_present(name, sel_type, filetype=\(aqa\(aq, sel_user=None, sel_level=None) New in version 2017.7.0. .sp Makes sure a SELinux policy for a given filespec (name), filetype and SELinux context type is present. .INDENT 7.0 .TP .B name filespec of the file or directory. Regex syntax is allowed. .TP .B sel_type SELinux context type. There are many. .TP .B filetype The SELinux filetype specification. Use one of [a, f, d, c, b, s, l, p]. See also \fIman semanage\-fcontext\fP\&. Defaults to \(aqa\(aq (all files). .TP .B sel_user The SELinux user. .TP .B sel_level The SELinux MLS range. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.selinux.mode(name) Verifies the mode SELinux is running in, can be set to enforcing, permissive, or disabled .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 A change to or from disabled mode requires a system reboot. You will need to perform this yourself. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The mode to run SELinux in, permissive, enforcing, or disabled. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.selinux.module(name, module_state=\(aqEnabled\(aq, version=\(aqany\(aq, **opts) Enable/Disable and optionally force a specific version for an SELinux module .INDENT 7.0 .TP .B name The name of the module to control .TP .B module_state Should the module be enabled or disabled? .TP .B version Defaults to no preference, set to a specified value if required. Currently can only alert if the version is incorrect. .TP .B install Setting to True installs module .TP .B source Points to module source file, used only when install is True .TP .B remove Setting to True removes module .UNINDENT .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.states.selinux.module_install(name) Installs custom SELinux module from given file .INDENT 7.0 .TP .B name Path to file with module to install .UNINDENT .sp New in version 2016.11.6. .UNINDENT .INDENT 0.0 .TP .B salt.states.selinux.module_remove(name) Removes SELinux module .INDENT 7.0 .TP .B name The name of the module to remove .UNINDENT .sp New in version 2016.11.6. .UNINDENT .INDENT 0.0 .TP .B salt.states.selinux.port_policy_absent(name, sel_type=None, protocol=None, port=None) New in version 2019.2.0. .sp Makes sure an SELinux port policy for a given port, protocol and SELinux context type is absent. .INDENT 7.0 .TP .B name The protocol and port spec. Can be formatted as \fB(tcp|udp)/(port|port\-range)\fP\&. .TP .B sel_type The SELinux Type. Optional; can be used in determining if policy is present, ignored by \fBsemanage port \-\-delete\fP\&. .TP .B protocol The protocol for the port, \fBtcp\fP or \fBudp\fP\&. Required if name is not formatted. .TP .B port The port or port range. Required if name is not formatted. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.selinux.port_policy_present(name, sel_type, protocol=None, port=None, sel_range=None) New in version 2019.2.0. .sp Makes sure an SELinux port policy for a given port, protocol and SELinux context type is present. .INDENT 7.0 .TP .B name The protocol and port spec. Can be formatted as \fB(tcp|udp)/(port|port\-range)\fP\&. .TP .B sel_type The SELinux Type. .TP .B protocol The protocol for the port, \fBtcp\fP or \fBudp\fP\&. Required if name is not formatted. .TP .B port The port or port range. Required if name is not formatted. .TP .B sel_range The SELinux MLS/MCS Security Range. .UNINDENT .UNINDENT .SS salt.states.serverdensity_device .SS Monitor Server with Server Density .sp New in version 2014.7.0. .sp \fI\%Server Density\fP Is a hosted monitoring service. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This state module is beta. It might be changed later to include more or less automation. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This state module requires a pillar for authentication with Server Density To install a v1 agent: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C serverdensity: api_token: \(dqb97da80a41c4f61bff05975ee51eb1aa\(dq account_url: \(dqhttps://your\-account.serverdensity.io\(dq .ft P .fi .UNINDENT .UNINDENT .sp To install a v2 agent: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C serverdensity: api_token: \(dqb97da80a41c4f61bff05975ee51eb1aa\(dq account_name: \(dqyour\-account\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Although Server Density allows duplicate device names in its database, this module will raise an exception if you try monitoring devices with the same name. .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aqserver_name\(aq: serverdensity_device.monitored .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.serverdensity_device.monitored(name, group=None, salt_name=True, salt_params=True, agent_version=1, **params) Device is monitored with Server Density. .INDENT 7.0 .TP .B name Device name in Server Density. .TP .B salt_name If \fBTrue\fP (default), takes the name from the \fBid\fP grain. If \fBFalse\fP, the provided name is used. .TP .B group Group name under with device will appear in Server Density dashboard. Default \- \fINone\fP\&. .TP .B agent_version The agent version you want to use. Valid values are 1 or 2. Default \- 1. .TP .B salt_params If \fBTrue\fP (default), needed config parameters will be sourced from grains and from \fI\%status.all_status\fP\&. .TP .B params Add parameters that you want to appear in the Server Density dashboard. Will overwrite the \fIsalt_params\fP parameters. For more info, see the \fI\%API docs\fP\&. .UNINDENT .sp Usage example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \(aqserver_name\(aq: serverdensity_device.monitored .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \(aqserver_name\(aq: serverdensity_device.monitored: \- group: web\-servers .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \(aqmy_special_server\(aq: serverdensity_device.monitored: \- salt_name: False \- group: web\-servers \- cpuCores: 2 \- os: \(aq{\(dqcode\(dq: \(dqlinux\(dq, \(dqname\(dq: \(dqLinux\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.service .SS Starting or restarting of services and daemons .sp Services are defined as system daemons and are typically launched using system init or rc scripts. This service state uses whichever service module is loaded on the minion with the virtualname of \fBservice\fP\&. Services can be defined as either running or dead. .sp If you need to know if your init system is supported, see the list of supported \fBservice modules\fP for your desired init system (systemd, sysvinit, launchctl, etc.). .sp Note that Salt\(aqs service execution module, and therefore this service state, uses OS grains to ascertain which service module should be loaded and used to execute service functions. As existing distributions change init systems or new distributions are created, OS detection can sometimes be incomplete. If your service states are running into trouble with init system detection, please see the \fI\%Overriding Virtual Module Providers\fP section of Salt\(aqs module documentation to work around possible errors. .sp For services managed by systemd, the systemd_service module includes a built\-in feature to reload the daemon when unit files are changed or extended. This feature is used automatically by the service state and the systemd_service module when running on a systemd minion, so there is no need to set up your own methods of reloading the daemon. If you need to manually reload the daemon for some reason, you can use the \fI\%systemd_service.systemctl_reload\fP function provided by Salt. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The current status of a service is determined by the return code of the init/rc script status command. A status return code of 0 it is considered running. Any other return code is considered dead. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: service.running: [] .ft P .fi .UNINDENT .UNINDENT .sp The service can also be set to start at runtime via the enable option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openvpn: service.running: \- enable: True .ft P .fi .UNINDENT .UNINDENT .sp By default if a service is triggered to refresh due to a watch statement the service is restarted. If the desired behavior is to reload the service, then set the reload value to True: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C redis: service.running: \- enable: True \- reload: True \- watch: \- pkg: redis .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 More details regarding \fBwatch\fP can be found in the \fI\%Requisites\fP documentation. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.service.dead(name, enable=None, sig=None, init_delay=None, **kwargs) Ensure that the named service is dead by stopping the service if it is running .INDENT 7.0 .TP .B name The name of the init or rc script used to manage the service .TP .B enable Set the service to be enabled at boot time, \fBTrue\fP sets the service to be enabled, \fBFalse\fP sets the named service to be disabled. The default is \fBNone\fP, which does not enable or disable anything. .TP .B sig The string to search for when looking for the service process with ps .TP .B init_delay Add a sleep command (in seconds) before the check to make sure service is killed. .sp New in version 2017.7.0. .TP .B no_block False \fBFor systemd minions only.\fP Stops the service using \fB\-\-no\-block\fP\&. .sp New in version 2017.7.0. .TP .B timeout \fBFor Windows minions only.\fP .sp The time in seconds to wait for the service to stop before returning. Default is the default for \fI\%win_service.stop\fP\&. .sp New in version 2017.7.9,2018.3.4. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.service.disabled(name, **kwargs) Ensure that the service is disabled on boot, only use this state if you don\(aqt want to manage the running process, remember that if you want to disable a service to use the enable: False option for the running or dead function. .INDENT 7.0 .TP .B name The name of the init or rc script used to manage the service .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.service.enabled(name, **kwargs) Ensure that the service is enabled on boot, only use this state if you don\(aqt want to manage the running process, remember that if you want to enable a running service to use the enable: True option for the running or dead function. .INDENT 7.0 .TP .B name The name of the init or rc script used to manage the service .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.service.masked(name, runtime=False) New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state is only available on minions which use \fI\%systemd\fP\&. .UNINDENT .UNINDENT .sp Ensures that the named service is masked (i.e. prevented from being started). .INDENT 7.0 .TP .B name Name of the service to mask .TP .B runtime False By default, this state will manage an indefinite mask for the named service. Set this argument to \fBTrue\fP to runtime mask the service. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 It is possible for a service to have both indefinite and runtime masks set for it. Therefore, this state will manage a runtime or indefinite mask independently of each other. This means that if the service is already indefinitely masked, running this state with \fBruntime\fP set to \fBTrue\fP will _not_ remove the indefinite mask before setting a runtime mask. In these cases, if it is desirable to ensure that the service is runtime masked and not indefinitely masked, pair this state with a \fI\%service.unmasked\fP state, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mask_runtime_foo: service.masked: \- name: foo \- runtime: True unmask_indefinite_foo: service.unmasked: \- name: foo \- runtime: False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.service.mod_beacon(name, **kwargs) Create a beacon to monitor a service based on a beacon state argument. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBbeacon\fP state argument for supported state functions. It should not be called directly. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.service.mod_watch(name, sfun=None, sig=None, reload=False, full_restart=False, init_delay=None, force=False, **kwargs) The service watcher, called to invoke the watch command. When called, it will restart or reload the named service. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBwatch\fP \fI\%requisite\fP\&. It should not be called directly. .sp Parameters for this function should be set by the watching service (e.g. \fBservice.running\fP). .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The name of the service to control. .TP .B sfun The original function which triggered the mod_watch call (\fIservice.running\fP, for example). .TP .B sig The string to search for when looking for the service process with ps. .TP .B reload When set, reload the service instead of restarting it (e.g. \fBservice nginx reload\fP). .TP .B full_restart Perform a full stop/start of a service by passing \fB\-\-full\-restart\fP\&. This option is ignored if \fBreload\fP is set and is supported by only a few \fI\%service modules\fP\&. .TP .B force Use service.force_reload instead of reload (needs reload to be set to True). .TP .B init_delay Add a sleep command (in seconds) before the service is restarted/reloaded. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.service.running(name, enable=None, sig=None, init_delay=None, **kwargs) Ensure that the service is running .INDENT 7.0 .TP .B name The name of the init or rc script used to manage the service .TP .B enable Set the service to be enabled at boot time, \fBTrue\fP sets the service to be enabled, \fBFalse\fP sets the named service to be disabled. The default is \fBNone\fP, which does not enable or disable anything. .TP .B sig The string to search for when looking for the service process with ps .TP .B init_delay Some services may not be truly available for a short period after their startup script indicates to the system that they are. Provide an \(aqinit_delay\(aq to specify that this state should wait an additional given number of seconds after a service has started before returning. Useful for requisite states wherein a dependent state might assume a service has started but is not yet fully initialized. .TP .B no_block False \fBFor systemd minions only.\fP Starts the service using \fB\-\-no\-block\fP\&. .sp New in version 2017.7.0. .TP .B timeout \fBFor Windows minions only.\fP .sp The time in seconds to wait for the service to start before returning. Default is the default for \fI\%win_service.start\fP\&. .sp New in version 2017.7.9,2018.3.4. .TP .B unmask False \fBFor systemd minions only.\fP Set to \fBTrue\fP to remove an indefinite mask before attempting to start the service. .sp New in version 2017.7.0: In previous releases, Salt would simply unmask a service before making any changes. This behavior is no longer the default. .TP .B unmask_runtime False \fBFor systemd minions only.\fP Set to \fBTrue\fP to remove a runtime mask before attempting to start the service. .sp New in version 2017.7.0: In previous releases, Salt would simply unmask a service before making any changes. This behavior is no longer the default. .TP .B wait 3 \fBFor systemd minions only.\fP Passed through when using \fI\%service.status\fP to determine whether the service is running or not. .sp New in version 2019.2.3. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBwatch\fP can be used with service.running to restart a service when another state changes ( example: a file.managed state that creates the service\(aqs config file ). More details regarding \fBwatch\fP can be found in the \fI\%Requisites\fP documentation. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.service.unmasked(name, runtime=False) New in version 2017.7.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state is only available on minions which use \fI\%systemd\fP\&. .UNINDENT .UNINDENT .sp Ensures that the named service is unmasked .INDENT 7.0 .TP .B name Name of the service to unmask .TP .B runtime False By default, this state will manage an indefinite mask for the named service. Set this argument to \fBTrue\fP to ensure that the service is runtime masked. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 It is possible for a service to have both indefinite and runtime masks set for it. Therefore, this state will manage a runtime or indefinite mask independently of each other. This means that if the service is indefinitely masked, running this state with \fBruntime\fP set to \fBTrue\fP will _not_ remove the indefinite mask. .UNINDENT .UNINDENT .UNINDENT .SS salt.states.slack .SS Send a message to Slack .sp This state is useful for sending messages to Slack during state runs. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C slack\-message: slack.post_message: \- channel: \(aq#general\(aq \- from_name: SuperAdmin \- message: \(aqThis state was executed successfully.\(aq \- api_key: peWcBiMOS9HrZG15peWcBiMOS9HrZG15 .ft P .fi .UNINDENT .UNINDENT .sp The api key can be specified in the master or minion configuration like below: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C slack: api_key: peWcBiMOS9HrZG15peWcBiMOS9HrZG15 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.slack.post_message(name, **kwargs) Send a message to a Slack channel. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C slack\-message: slack.post_message: \- channel: \(aq#general\(aq \- from_name: SuperAdmin \- message: \(aqThis state was executed successfully.\(aq \- api_key: peWcBiMOS9HrZG15peWcBiMOS9HrZG15 .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B api_key parameters: .INDENT 7.0 .TP .B name The unique name for this event. .TP .B channel The channel to send the message to. Can either be the ID or the name. .TP .B from_name The name of that is to be shown in the \(dqfrom\(dq field. .TP .B message The message that is to be sent to the Slack channel. .UNINDENT .sp The following parameters are optional: .INDENT 7.0 .TP .B api_key The api key for Slack to use for authentication, if not specified in the configuration options of master or minion. .TP .B icon URL to an image to use as the icon for this message .UNINDENT .TP .B webhook parameters: .INDENT 7.0 .TP .B name The unique name for this event. .TP .B message The message that is to be sent to the Slack channel. .TP .B color The color of border of left side .TP .B short An optional flag indicating whether the value is short enough to be displayed side\-by\-side with other values. .TP .B webhook The identifier of WebHook (URL or token). .TP .B channel The channel to use instead of the WebHook default. .TP .B username Username to use instead of WebHook default. .TP .B icon_emoji Icon to use instead of WebHook default. .UNINDENT .UNINDENT .UNINDENT .SS salt.states.smartos .sp Management of SmartOS Standalone Compute Nodes .INDENT 0.0 .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B depends vmadm, imgadm .TP .B platform smartos .UNINDENT .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vmtest.example.org: smartos.vm_present: \- config: reprovision: true \- vmconfig: image_uuid: c02a2044\-c1bd\-11e4\-bd8c\-dfc1db8b0182 brand: joyent alias: vmtest quota: 5 max_physical_memory: 512 tags: label: \(aqtest vm\(aq owner: \(aqsjorge\(aq nics: \(dq82:1b:8e:49:e9:12\(dq: nic_tag: trunk mtu: 1500 ips: \- 172.16.1.123/16 \- 192.168.2.123/24 vlan_id: 10 \(dq82:1b:8e:49:e9:13\(dq: nic_tag: trunk mtu: 1500 ips: \- dhcp vlan_id: 30 filesystems: \(dq/bigdata\(dq: source: \(dq/bulk/data\(dq type: lofs options: \- ro \- nodevices kvmtest.example.org: smartos.vm_present: \- vmconfig: brand: kvm alias: kvmtest cpu_type: host ram: 512 vnc_port: 9 tags: label: \(aqtest kvm\(aq owner: \(aqsjorge\(aq disks: disk0: size: 2048 model: virtio compression: lz4 boot: true nics: \(dq82:1b:8e:49:e9:15\(dq: nic_tag: trunk mtu: 1500 ips: \- dhcp vlan_id: 30 docker.example.org: smartos.vm_present: \- config: auto_import: true reprovision: true \- vmconfig: image_uuid: emby/embyserver:latest brand: lx alias: mydockervm quota: 5 max_physical_memory: 1024 tags: label: \(aqmy emby docker\(aq owner: \(aqsjorge\(aq resolvers: \- 172.16.1.1 nics: \(dq82:1b:8e:49:e9:18\(dq: nic_tag: trunk mtu: 1500 ips: \- 172.16.1.118/24 vlan_id: 10 filesystems: \(dq/config: source: \(dq/vmdata/emby_config\(dq type: lofs options: \- nodevices cleanup_images: smartos.image_vacuum .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Keep in mind that when removing properties from vmconfig they will not get removed from the vm\(aqs current configuration, except for nics, disk, tags, ... they get removed via add_*, set_*, update_*, and remove_*. Properties must be manually reset to their default value. The same behavior as when using \(aqvmadm update\(aq. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 For HVM (bhyve and KVM) brands the \fIimage_uuid\fP field should go on the boot disks, this disk should NOT have a size specified. (See man vmadm) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.smartos.config_absent(name) Ensure configuration property is absent in /usbkey/config .INDENT 7.0 .TP .B name string name of property .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.smartos.config_present(name, value) Ensure configuration property is set to value in /usbkey/config .INDENT 7.0 .TP .B name string name of property .TP .B value string value of property .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.smartos.image_absent(name) Ensure image is absent on the computenode .INDENT 7.0 .TP .B name string uuid of image .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 computenode.image_absent will only remove the image if it is not used by a vm. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.smartos.image_present(name) Ensure image is present on the computenode .INDENT 7.0 .TP .B name string uuid of image .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.smartos.image_vacuum(name) Delete images not in use or installed via image_present .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Only image_present states that are included via the top file will be detected. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.smartos.source_absent(name) Ensure an image source is absent on the computenode .INDENT 7.0 .TP .B name string source url .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.smartos.source_present(name, source_type=\(aqimgapi\(aq) Ensure an image source is present on the computenode .INDENT 7.0 .TP .B name string source url .TP .B source_type string source type (imgapi or docker) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.smartos.vm_absent(name, archive=False) Ensure vm is absent on the computenode .INDENT 7.0 .TP .B name string hostname of vm .TP .B archive boolean toggle archiving of vm on removal .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 State ID is used as hostname. Hostnames must be unique. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.smartos.vm_present(name, vmconfig, config=None) Ensure vm is present on the computenode .INDENT 7.0 .TP .B name string hostname of vm .TP .B vmconfig dict options to set for the vm .TP .B config dict fine grain control over vm_present .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B The following configuration properties can be toggled in the config parameter. .INDENT 7.0 .IP \(bu 2 kvm_reboot (true) \- reboots of kvm zones if needed for a config update .IP \(bu 2 auto_import (false) \- automatic importing of missing images .IP \(bu 2 auto_lx_vars (true) \- copy kernel_version and docker:* variables from image .IP \(bu 2 reprovision (false) \- reprovision on image_uuid changes .IP \(bu 2 enforce_tags (true) \- false = add tags only, true = add, update, and remove tags .IP \(bu 2 enforce_routes (true) \- false = add tags only, true = add, update, and remove routes .IP \(bu 2 enforce_internal_metadata (true) \- false = add metadata only, true = add, update, and remove metadata .IP \(bu 2 enforce_customer_metadata (true) \- false = add metadata only, true = add, update, and remove metadata .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 State ID is used as hostname. Hostnames must be unique. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If hostname is provided in vmconfig this will take president over the State ID. This allows multiple states to be applied to the same vm. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B The following instances should have a unique ID. .INDENT 7.0 .IP \(bu 2 nic : mac .IP \(bu 2 filesystem: target .IP \(bu 2 disk : path or diskN for zvols .UNINDENT .UNINDENT .sp e.g. disk0 will be the first disk added, disk1 the 2nd,... .UNINDENT .UNINDENT .sp Changed in version 2019.2.0: Added support for docker image uuids, added auto_lx_vars configuration, documented some missing configuration options. .UNINDENT .INDENT 0.0 .TP .B salt.states.smartos.vm_running(name) Ensure vm is in the running state on the computenode .INDENT 7.0 .TP .B name string hostname of vm .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 State ID is used as hostname. Hostnames must be unique. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.smartos.vm_stopped(name) Ensure vm is in the stopped state on the computenode .INDENT 7.0 .TP .B name string hostname of vm .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 State ID is used as hostname. Hostnames must be unique. .UNINDENT .UNINDENT .UNINDENT .SS salt.states.smtp .SS Sending Messages via SMTP .sp New in version 2014.7.0. .sp This state is useful for firing messages during state runs, using the SMTP protocol .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C server\-warning\-message: smtp.send_msg: \- name: \(aqThis is a server warning message\(aq \- profile: my\-smtp\-account \- recipient: admins@example.com .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.smtp.send_msg(name, recipient, subject, sender=None, profile=None, use_ssl=\(aqTrue\(aq, attachments=None) Send a message via SMTP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C server\-warning\-message: smtp.send_msg: \- name: \(aqThis is a server warning message\(aq \- profile: my\-smtp\-account \- subject: \(aqMessage from Salt\(aq \- recipient: admin@example.com \- sender: admin@example.com \- use_ssl: True \- attachments: \- /var/log/syslog \- /var/log/messages .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The message to send via SMTP .UNINDENT .UNINDENT .SS salt.states.snapper .SS Managing implicit state and baselines using snapshots .sp New in version 2016.11.0. .sp Salt can manage state against explicitly defined state, for example if your minion state is defined by: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/config_file: file.managed: \- source: salt://configs/myconfig .ft P .fi .UNINDENT .UNINDENT .sp If someone modifies this file, the next application of the highstate will allow the admin to correct this deviation and the file will be corrected. .sp Now, what happens if somebody creates a file \fB/etc/new_config_file\fP and deletes \fB/etc/important_config_file\fP? Unless you have a explicit rule, this change will go unnoticed. .sp The snapper state module allows you to manage state implicitly, in addition to explicit rules, in order to define a baseline and iterate with explicit rules as they show that they work in production. .sp The workflow is: once you have a working and audited system, you would create your baseline snapshot (eg. with \fBsalt tgt snapper.create_snapshot\fP) and define in your state this baseline using the identifier of the snapshot (in this case: 20): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_baseline: snapper.baseline_snapshot: \- number: 20 \- include_diff: False \- ignore: \- /var/log \- /var/cache .ft P .fi .UNINDENT .UNINDENT .sp Baseline snapshots can be also referenced by tag. Most recent baseline snapshot is used in case of multiple snapshots with the same tag: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B my_baseline_external_storage: .INDENT 7.0 .TP .B snapper.baseline_snapshot: .INDENT 7.0 .IP \(bu 2 tag: my_custom_baseline_tag .IP \(bu 2 config: external .IP \(bu 2 ignore: \- /mnt/tmp_files/ .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp If you have this state, and you haven\(aqt done changes to the system since the snapshot, and you add a user, the state will show you the changes (including full diffs) to \fB/etc/passwd\fP, \fB/etc/shadow\fP, etc if you call it with \fBtest=True\fP and will undo all changes if you call it without. .sp This allows you to add more explicit state knowing that you are starting from a very well defined state, and that you can audit any change that is not part of your explicit configuration. .sp So after you made this your state, you decided to introduce a change in your configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_baseline: snapper.baseline_snapshot: \- number: 20 \- ignore: \- /var/log \- /var/cache hosts_entry: file.blockreplace: \- name: /etc/hosts \- content: \(aqFirst line of content\(aq \- append_if_not_found: True .ft P .fi .UNINDENT .UNINDENT .sp The change in \fB/etc/hosts\fP will be done after any other change that deviates from the specified snapshot are reverted. This could be for example, modifications to the \fB/etc/passwd\fP file or changes in the \fB/etc/hosts\fP that could render your the \fBhosts_entry\fP rule void or dangerous. .sp Once you take a new snapshot and you update the baseline snapshot number to include the change in \fB/etc/hosts\fP the \fBhosts_entry\fP rule will basically do nothing. You are free to leave it there for documentation, to ensure that the change is made in case the snapshot is wrong, but if you remove anything that comes after the \fBsnapper.baseline_snapshot\fP as it will have no effect; by the moment the state is evaluated, the baseline state was already applied and include this change. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Make sure you specify the baseline state before other rules, otherwise the baseline state will revert all changes if they are not present in the snapshot. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Do not specify more than one baseline rule as only the last one will affect the result. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B codeauthor Duncan Mac\-Vicar P. <\fI\%dmacvicar@suse.de\fP> .TP .B codeauthor Pablo Suárez Hernández <\fI\%psuarezhernandez@suse.de\fP> .TP .B maturity new .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.states.snapper.baseline_snapshot(name, number=None, tag=None, include_diff=True, config=\(aqroot\(aq, ignore=None) Enforces that no file is modified comparing against a previously defined snapshot identified by number. .INDENT 7.0 .TP .B number Number of selected baseline snapshot. .TP .B tag Tag of the selected baseline snapshot. Most recent baseline baseline snapshot is used in case of multiple snapshots with the same tag. (\fItag\fP and \fInumber\fP cannot be used at the same time) .TP .B include_diff Include a diff in the response (Default: True) .TP .B config Snapper config name (Default: root) .TP .B ignore List of files to ignore. (Default: None) .UNINDENT .UNINDENT .SS salt.states.solrcloud .sp States for solrcloud alias and collection configuration .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.states.solrcloud.alias(name, collections, **kwargs) Create alias and enforce collection list. .sp Use the solrcloud module to get alias members and set them. .sp You can pass additional arguments that will be forwarded to http.query .INDENT 7.0 .TP .B name The collection name .TP .B collections list of collections to include in the alias .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.solrcloud.collection(name, options=None, **kwargs) Create collection and enforce options. .sp Use the solrcloud module to get collection parameters. .sp You can pass additional arguments that will be forwarded to http.query .INDENT 7.0 .TP .B name The collection name .TP .B options {} options to ensure .UNINDENT .UNINDENT .SS salt.states.splunk .sp Splunk User State Module .sp New in version 2016.3.0. .sp This state is used to ensure presence of users in splunk. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ensure example test user 1: splunk.present: \- name: \(aqExample TestUser1\(aq \- email: example@domain.com .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.splunk.absent(email, profile=\(aqsplunk\(aq, **kwargs) Ensure a splunk user is absent .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ensure example test user 1: splunk.absent: \- email: \(aqexample@domain.com\(aq \- name: \(aqexampleuser\(aq .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B email This is the email of the user in splunk .TP .B name This is the splunk username used to identify the user. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.splunk.present(email, profile=\(aqsplunk\(aq, **kwargs) Ensure a user is present .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ensure example test user 1: splunk.user_present: \- realname: \(aqExample TestUser1\(aq \- name: \(aqexampleuser\(aq \- email: \(aqexample@domain.com\(aq \- roles: [\(aquser\(aq] .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B email This is the email of the user in splunk .UNINDENT .UNINDENT .SS salt.states.splunk_search .sp Splunk Search State Module .sp New in version 2015.5.0. .sp This state is used to ensure presence of splunk searches. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C server\-warning\-message: splunk_search.present: \- name: This is the splunk search name \- search: index=main sourcetype= .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.splunk_search.absent(name, profile=\(aqsplunk\(aq) Ensure a search is absent .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C API Error Search: splunk_search.absent .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B name This is the name of the search in splunk .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.splunk_search.present(name, profile=\(aqsplunk\(aq, **kwargs) Ensure a search is present .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C API Error Search: splunk_search.present: search: index=main sourcetype=blah template: alert_5min .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B name This is the name of the search in splunk .UNINDENT .UNINDENT .SS salt.states.sqlite3 .SS Management of SQLite3 databases .sp New in version 2016.3.0. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 SQLite3 Python Module .UNINDENT .TP .B configuration See \fI\%salt.modules.sqlite3\fP for setup instructions .UNINDENT .sp The sqlite3 module is used to create and manage sqlite3 databases and execute queries .sp Here is an example of creating a table using sql statements: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: sqlite3.table_present: \- db: /var/www/data/app.sqlite \- schema: CREATE TABLE \(gausers\(ga (\(gausername\(ga TEXT COLLATE NOCASE UNIQUE NOT NULL, \(gapassword\(ga BLOB NOT NULL, \(gasalt\(ga BLOB NOT NULL, \(galast_login\(ga INT) .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of creating a table using yaml/jinja instead of sql: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: sqlite3.table_present: \- db: /var/www/app.sqlite \- schema: \- email TEXT COLLATE NOCASE UNIQUE NOT NULL \- firstname TEXT NOT NULL \- lastname TEXT NOT NULL \- company TEXT NOT NULL \- password BLOB NOT NULL \- salt BLOB NOT NULL .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of making sure a table is absent: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C badservers: sqlite3.table_absent: \- db: /var/www/data/users.sqlite .ft P .fi .UNINDENT .UNINDENT .sp Sometimes you would to have specific data in tables to be used by other services Here is an example of making sure rows with specific data exist: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C user_john_doe_xyz: sqlite3.row_present: \- db: /var/www/app.sqlite \- table: users \- where_sql: email=\(aqjohn.doe@companyxyz.com\(aq \- data: email: john.doe@companyxyz.com lastname: doe firstname: john company: companyxyz.com password: abcdef012934125 salt: abcdef012934125 \- require: \- sqlite3: users .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of removing a row from a table: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C user_john_doe_abc: sqlite3.row_absent: \- db: /var/www/app.sqlite \- table: users \- where_sql: email=\(dqjohn.doe@companyabc.com\(dq \- require: \- sqlite3: users .ft P .fi .UNINDENT .UNINDENT .sp Note that there is no explicit state to perform random queries, however, this can be approximated with sqlite3\(aqs module functions and module.run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zone\-delete: module.run: \- name: sqlite3.modify \- db: {{ db }} \- sql: \(dqDELETE FROM records WHERE id > {{ count[0] }} AND domain_id = {{ domain_id }}\(dq \- watch: \- sqlite3: zone\-insert\-12 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.sqlite3.row_absent(name, db, table, where_sql, where_args=None) Makes sure the specified row is absent in db. If multiple rows match where_sql, then the state will fail. .INDENT 7.0 .TP .B name Only used as the unique ID .TP .B db The database file name .TP .B table The table name to check .TP .B where_sql The sql to select the row to check .TP .B where_args The list parameters to substitute in where_sql .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.sqlite3.row_present(name, db, table, data, where_sql, where_args=None, update=False) Checks to make sure the given row exists. If row exists and update is True then row will be updated with data. Otherwise it will leave existing row unmodified and check it against data. If the existing data doesn\(aqt match data_check the state will fail. If the row doesn\(aqt exist then it will insert data into the table. If more than one row matches, then the state will fail. .INDENT 7.0 .TP .B name Only used as the unique ID .TP .B db The database file name .TP .B table The table name to check the data .TP .B data The dictionary of key/value pairs to check against if row exists, insert into the table if it doesn\(aqt .TP .B where_sql The sql to select the row to check .TP .B where_args The list parameters to substitute in where_sql .TP .B update True will replace the existing row with data When False and the row exists and data does not equal the row data then the state will fail .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.sqlite3.table_absent(name, db) Make sure the specified table does not exist .INDENT 7.0 .TP .B name The name of the table .TP .B db The name of the database file .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.sqlite3.table_present(name, db, schema, force=False) Make sure the specified table exists with the specified schema .INDENT 7.0 .TP .B name The name of the table .TP .B db The name of the database file .TP .B schema The dictionary containing the schema information .TP .B force If the name of the table exists and force is set to False, the state will fail. If force is set to True, the existing table will be replaced with the new table .UNINDENT .UNINDENT .SS salt.states.ssh_auth .SS Control of entries in SSH authorized_key files .sp The information stored in a user\(aqs SSH authorized key file can be easily controlled via the ssh_auth state. Defaults can be set by the enc, options, and comment keys. These defaults can be overridden by including them in the name. .sp Since the YAML specification limits the length of simple keys to 1024 characters, and since SSH keys are often longer than that, you may have to use a YAML \(aqexplicit key\(aq, as demonstrated in the second example below. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY==: ssh_auth.present: \- user: root \- enc: ssh\-dss ? AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY==... : ssh_auth.present: \- user: root \- enc: ssh\-dss thatch: ssh_auth.present: \- user: root \- source: salt://ssh_keys/thatch.id_rsa.pub \- config: \(aq%h/.ssh/authorized_keys\(aq sshkeys: ssh_auth.present: \- user: root \- enc: ssh\-rsa \- options: \- option1=\(dqvalue1\(dq \- option2=\(dqvalue2 flag2\(dq \- comment: myuser \- names: \- AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY== \- ssh\-dss AAAAB3NzaCL0sQ9fJ5bYTEyY== user@domain \- option3=\(dqvalue3\(dq ssh\-dss AAAAB3NzaC1kcQ9J5bYTEyY== other@testdomain \- AAAAB3NzaC1kcQ9fJFF435bYTEyY== newcomment sshkeys: ssh_auth.manage: \- user: root \- enc: ssh\-rsa \- options: \- option1=\(dqvalue1\(dq \- option2=\(dqvalue2 flag2\(dq \- comment: myuser \- ssh_keys: \- AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY== \- ssh\-dss AAAAB3NzaCL0sQ9fJ5bYTEyY== user@domain \- option3=\(dqvalue3\(dq ssh\-dss AAAAB3NzaC1kcQ9J5bYTEyY== other@testdomain \- AAAAB3NzaC1kcQ9fJFF435bYTEyY== newcomment .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ssh_auth.absent(name, user, enc=\(aqssh\-rsa\(aq, comment=\(aq\(aq, source=\(aq\(aq, options=None, config=\(aq.ssh/authorized_keys\(aq, fingerprint_hash_type=None) Verifies that the specified SSH key is absent .INDENT 7.0 .TP .B name The SSH key to manage .TP .B user The user who owns the SSH authorized keys file to modify .TP .B enc Defines what type of key is being used, can be ed25519, ecdsa, ssh\-rsa, ssh\-dss or any other type as of openssh server version 8.7. .TP .B comment The comment to be placed with the SSH public key .TP .B options The options passed to the key, pass a list object .TP .B source The source file for the key(s). Can contain any number of public keys, in standard \(dqauthorized_keys\(dq format. If this is set, comment, enc and options will be ignored. .sp New in version 2015.8.0. .TP .B config The location of the authorized keys file relative to the user\(aqs home directory, defaults to \(dq.ssh/authorized_keys\(dq. Token expansion %u and %h for username and home path supported. .TP .B fingerprint_hash_type The public key fingerprint hash type that the public key fingerprint was originally hashed with. This defaults to \fBsha256\fP if not specified. .sp New in version 2016.11.7. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ssh_auth.manage(name, ssh_keys, user, enc=\(aqssh\-rsa\(aq, comment=\(aq\(aq, source=\(aq\(aq, options=None, config=\(aq.ssh/authorized_keys\(aq, fingerprint_hash_type=None, **kwargs) New in version 3000. .sp Ensures that only the specified ssh_keys are present for the specified user .INDENT 7.0 .TP .B ssh_keys The SSH key to manage .TP .B user The user who owns the SSH authorized keys file to modify .TP .B enc Defines what type of key is being used, can be ed25519, ecdsa, ssh\-rsa, ssh\-dss or any other type as of openssh server version 8.7. .TP .B comment The comment to be placed with the SSH public key .TP .B source The source file for the key(s). Can contain any number of public keys, in standard \(dqauthorized_keys\(dq format. If this is set, comment and enc will be ignored. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The source file must contain keys in the format \fB<enc> <key> <comment>\fP\&. If you have generated a keypair using PuTTYgen, then you will need to do the following to retrieve an OpenSSH\-compatible public key. .INDENT 0.0 .IP 1. 3 In PuTTYgen, click \fBLoad\fP, and select the \fIprivate\fP key file (not the public key), and click \fBOpen\fP\&. .IP 2. 3 Copy the public key from the box labeled \fBPublic key for pasting into OpenSSH authorized_keys file\fP\&. .IP 3. 3 Paste it into a new file. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B options The options passed to the keys, pass a list object .TP .B config The location of the authorized keys file relative to the user\(aqs home directory, defaults to \(dq.ssh/authorized_keys\(dq. Token expansion %u and %h for username and home path supported. .TP .B fingerprint_hash_type The public key fingerprint hash type that the public key fingerprint was originally hashed with. This defaults to \fBsha256\fP if not specified. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ssh_auth.present(name, user, enc=\(aqssh\-rsa\(aq, comment=\(aq\(aq, source=\(aq\(aq, options=None, config=\(aq.ssh/authorized_keys\(aq, fingerprint_hash_type=None, **kwargs) Verifies that the specified SSH key is present for the specified user .INDENT 7.0 .TP .B name The SSH key to manage .TP .B user The user who owns the SSH authorized keys file to modify .TP .B enc Defines what type of key is being used, can be ed25519, ecdsa, ssh\-rsa, ssh\-dss or any other type as of openssh server version 8.7. .TP .B comment The comment to be placed with the SSH public key .TP .B source The source file for the key(s). Can contain any number of public keys, in standard \(dqauthorized_keys\(dq format. If this is set, comment and enc will be ignored. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The source file must contain keys in the format \fB<enc> <key> <comment>\fP\&. If you have generated a keypair using PuTTYgen, then you will need to do the following to retrieve an OpenSSH\-compatible public key. .INDENT 0.0 .IP 1. 3 In PuTTYgen, click \fBLoad\fP, and select the \fIprivate\fP key file (not the public key), and click \fBOpen\fP\&. .IP 2. 3 Copy the public key from the box labeled \fBPublic key for pasting into OpenSSH authorized_keys file\fP\&. .IP 3. 3 Paste it into a new file. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B options The options passed to the key, pass a list object .TP .B config The location of the authorized keys file relative to the user\(aqs home directory, defaults to \(dq.ssh/authorized_keys\(dq. Token expansion %u and %h for username and home path supported. .TP .B fingerprint_hash_type The public key fingerprint hash type that the public key fingerprint was originally hashed with. This defaults to \fBsha256\fP if not specified. .UNINDENT .UNINDENT .SS salt.states.ssh_known_hosts .SS Control of SSH known_hosts entries .sp Manage the information stored in the known_hosts files. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C github.com: ssh_known_hosts: \- present \- user: root \- fingerprint: 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48 \- fingerprint_hash_type: md5 example.com: ssh_known_hosts: \- absent \- user: root .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ssh_known_hosts.absent(name, user=None, config=None) Verifies that the specified host is not known by the given user .INDENT 7.0 .TP .B name The host name Note that only single host names are supported. If foo.example.com and bar.example.com are the same machine and you need to exclude both, you will need one Salt state for each. .TP .B user The user who owns the ssh authorized keys file to modify .TP .B config The location of the authorized keys file relative to the user\(aqs home directory, defaults to \(dq.ssh/known_hosts\(dq. If no user is specified, defaults to \(dq/etc/ssh/ssh_known_hosts\(dq. If present, must be an absolute path when a user is not specified. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ssh_known_hosts.present(name, user=None, fingerprint=None, key=None, port=None, enc=None, config=None, hash_known_hosts=True, timeout=5, fingerprint_hash_type=None) Verifies that the specified host is known by the specified user .sp On many systems, specifically those running with openssh 4 or older, the \fBenc\fP option must be set, only openssh 5 and above can detect the key type. .INDENT 7.0 .TP .B name The name of the remote host (e.g. \(dqgithub.com\(dq) Note that only a single hostname is supported, if foo.example.com and bar.example.com have the same host you will need two separate Salt States to represent them. .TP .B user The user who owns the ssh authorized keys file to modify .TP .B fingerprint The fingerprint of the key which must be present in the known_hosts file (optional if key specified) .TP .B key The public key which must be present in the known_hosts file (optional if fingerprint specified) .TP .B port optional parameter, port which will be used to when requesting the public key from the remote host, defaults to port 22. .TP .B enc Defines what type of key is being used, can be ed25519, ecdsa, ssh\-rsa, ssh\-dss or any other type as of openssh server version 8.7. .TP .B config The location of the authorized keys file relative to the user\(aqs home directory, defaults to \(dq.ssh/known_hosts\(dq. If no user is specified, defaults to \(dq/etc/ssh/ssh_known_hosts\(dq. If present, must be an absolute path when a user is not specified. .TP .B hash_known_hosts True Hash all hostnames and addresses in the known hosts file. .TP .B timeout int Set the timeout for connection attempts. If \fBtimeout\fP seconds have elapsed since a connection was initiated to a host or since the last time anything was read from that host, then the connection is closed and the host in question considered unavailable. Default is 5 seconds. .sp New in version 2016.3.0. .TP .B fingerprint_hash_type The public key fingerprint hash type that the public key fingerprint was originally hashed with. This defaults to \fBsha256\fP if not specified. .sp New in version 2016.11.4. .sp Changed in version 2017.7.0: default changed from \fBmd5\fP to \fBsha256\fP .UNINDENT .UNINDENT .SS salt.states.stateconf .SS Stateconf System .sp The stateconf system is intended for use only with the stateconf renderer. This State module presents the set function. This function does not execute any functionality, but is used to interact with the stateconf renderer. .INDENT 0.0 .TP .B salt.states.stateconf.context(name, **kwargs) No\-op state to support state config via the stateconf renderer. .UNINDENT .INDENT 0.0 .TP .B salt.states.stateconf.set(name, **kwargs) No\-op state to support state config via the stateconf renderer. .UNINDENT .SS salt.states.status .sp Minion status monitoring .sp Maps to the \fIstatus\fP execution module. .INDENT 0.0 .TP .B salt.states.status.loadavg(name, maximum=None, minimum=None) Return the current load average for the specified minion. Available values for name are \fI1\-min\fP, \fI5\-min\fP and \fI15\-min\fP\&. \fIminimum\fP and \fImaximum\fP values should be passed in as strings. .UNINDENT .INDENT 0.0 .TP .B salt.states.status.process(name) Return whether the specified signature is found in the process tree. This differs slightly from the services states, in that it may refer to a process that is not managed via the init system. .UNINDENT .SS salt.states.statuspage .SS StatusPage .sp Manage the \fI\%StatusPage\fP configuration. .sp In the minion configuration file, the following block is required: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C statuspage: api_key: <API_KEY> page_id: <PAGE_ID> .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.states.statuspage.create(name, endpoint=\(aqincidents\(aq, api_url=None, page_id=None, api_key=None, api_version=None, **kwargs) Insert a new entry under a specific endpoint. .INDENT 7.0 .TP .B endpoint: incidents Insert under this specific endpoint. .TP .B page_id Page ID. Can also be specified in the config file. .TP .B api_key API key. Can also be specified in the config file. .TP .B api_version: 1 API version. Can also be specified in the config file. .TP .B api_url Custom API URL in case the user has a StatusPage service running in a custom environment. .TP .B kwargs Other params. .UNINDENT .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C create\-my\-component: statuspage.create: \- endpoint: components \- name: my component \- group_id: 993vgplshj12 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.statuspage.delete(name, endpoint=\(aqincidents\(aq, id=None, api_url=None, page_id=None, api_key=None, api_version=None) Remove an entry from an endpoint. .INDENT 7.0 .TP .B endpoint: incidents Request a specific endpoint. .TP .B page_id Page ID. Can also be specified in the config file. .TP .B api_key API key. Can also be specified in the config file. .TP .B api_version: 1 API version. Can also be specified in the config file. .TP .B api_url Custom API URL in case the user has a StatusPage service running in a custom environment. .UNINDENT .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C delete\-my\-component: statuspage.delete: \- endpoint: components \- id: ftgks51sfs2d .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.statuspage.managed(name, config, api_url=None, page_id=None, api_key=None, api_version=None, pace=1, allow_empty=False) Manage the StatusPage configuration. .INDENT 7.0 .TP .B config Dictionary with the expected configuration of the StatusPage. The main level keys of this dictionary represent the endpoint name. If a certain endpoint does not exist in this structure, it will be ignored / not configured. .TP .B page_id Page ID. Can also be specified in the config file. .TP .B api_key API key. Can also be specified in the config file. .TP .B api_version: 1 API version. Can also be specified in the config file. .TP .B api_url Custom API URL in case the user has a StatusPage service running in a custom environment. .TP .B pace: 1 Max requests per second allowed by the API. .TP .B allow_empty: False Allow empty config. .UNINDENT .sp SLS example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C my\-statuspage\-config: statuspage.managed: \- config: components: \- name: component1 group_id: uy4g37rf \- name: component2 group_id: 3n4uyu4gf incidents: \- name: incident1 status: resolved impact: major backfilled: false \- name: incident2 status: investigating impact: minor .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.statuspage.update(name, endpoint=\(aqincidents\(aq, id=None, api_url=None, page_id=None, api_key=None, api_version=None, **kwargs) Update attribute(s) of a specific endpoint. .INDENT 7.0 .TP .B id The unique ID of the endpoint entry. .TP .B endpoint: incidents Endpoint name. .TP .B page_id Page ID. Can also be specified in the config file. .TP .B api_key API key. Can also be specified in the config file. .TP .B api_version: 1 API version. Can also be specified in the config file. .TP .B api_url Custom API URL in case the user has a StatusPage service running in a custom environment. .UNINDENT .sp SLS Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C update\-my\-incident: statuspage.update: \- id: dz959yz2nd4l \- status: resolved .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.supervisord .SS Interaction with the Supervisor daemon .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wsgi_server: supervisord.running: \- require: \- pkg: supervisor \- watch: \- file: /etc/nginx/sites\-enabled/wsgi_server.conf .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.supervisord.dead(name, user=None, conf_file=None, bin_env=None, **kwargs) Ensure the named service is dead (not running). .INDENT 7.0 .TP .B name Service name as defined in the supervisor configuration file .TP .B user Name of the user to run the supervisorctl command .sp New in version 0.17.0. .TP .B conf_file path to supervisorctl config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.supervisord.mod_watch(name, restart=True, update=False, user=None, conf_file=None, bin_env=None, **kwargs) The supervisord watcher, called to invoke the watch command. Always restart on watch .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBwatch\fP \fI\%requisite\fP\&. It should not be called directly. .sp Parameters for this function should be set by the state being triggered. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.supervisord.running(name, restart=False, update=False, user=None, conf_file=None, bin_env=None, **kwargs) Ensure the named service is running. .INDENT 7.0 .TP .B name Service name as defined in the supervisor configuration file .TP .B restart Whether to force a restart .TP .B update Whether to update the supervisor configuration. .TP .B user Name of the user to run the supervisorctl command .sp New in version 0.17.0. .TP .B conf_file path to supervisorctl config file .TP .B bin_env path to supervisorctl bin or path to virtualenv with supervisor installed .UNINDENT .UNINDENT .SS salt.states.svn .SS Manage SVN repositories .sp Manage repository checkouts via the svn vcs system. Note that subversion must be installed for these states to be available, so svn states should include a requisite to a pkg.installed state for the package which provides subversion (\fBsubversion\fP in most cases). Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C subversion: pkg.installed http://unladen\-swallow.googlecode.com/svn/trunk/: svn.latest: \- target: /tmp/swallow .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.svn.dirty(name, target, user=None, username=None, password=None, ignore_unversioned=False) Determine if the working directory has been changed. .UNINDENT .INDENT 0.0 .TP .B salt.states.svn.export(name, target=None, rev=None, user=None, username=None, password=None, force=False, overwrite=False, externals=True, trust=False, trust_failures=None) Export a file or directory from an SVN repository .INDENT 7.0 .TP .B name Address and path to the file or directory to be exported. .TP .B target Name of the target directory where the checkout will put the working directory .TP .B rev None The name revision number to checkout. Enable \(dqforce\(dq if the directory already exists. .TP .B user None Name of the user performing repository management operations .TP .B username None The user to access the name repository with. The svn default is the current user .TP .B password Connect to the Subversion server with this password .sp New in version 0.17.0. .TP .B force False Continue if conflicts are encountered .TP .B overwrite False Overwrite existing target .TP .B externals True Change to False to not checkout or update externals .TP .B trust False Automatically trust the remote server. SVN\(aqs \-\-trust\-server\-cert .TP .B trust_failures None Comma\-separated list of certificate trust failures, that shall be ignored. This can be used if trust=True is not sufficient. The specified string is passed to SVN\(aqs \-\-trust\-server\-cert\-failures option as\-is. .sp New in version 2019.2.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.svn.latest(name, target=None, rev=None, user=None, username=None, password=None, force=False, externals=True, trust=False, trust_failures=None) Checkout or update the working directory to the latest revision from the remote repository. .INDENT 7.0 .TP .B name Address of the name repository as passed to \(dqsvn checkout\(dq .TP .B target Name of the target directory where the checkout will put the working directory .TP .B rev None The name revision number to checkout. Enable \(dqforce\(dq if the directory already exists. .TP .B user None Name of the user performing repository management operations .TP .B username None The user to access the name repository with. The svn default is the current user .TP .B password Connect to the Subversion server with this password .sp New in version 0.17.0. .TP .B force False Continue if conflicts are encountered .TP .B externals True Change to False to not checkout or update externals .TP .B trust False Automatically trust the remote server. SVN\(aqs \-\-trust\-server\-cert .TP .B trust_failures None Comma\-separated list of certificate trust failures, that shall be ignored. This can be used if trust=True is not sufficient. The specified string is passed to SVN\(aqs \-\-trust\-server\-cert\-failures option as\-is. .sp New in version 2019.2.0. .UNINDENT .UNINDENT .SS salt.states.sysctl .SS Configuration of the kernel using sysctl .sp Control the kernel sysctl system. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vm.swappiness: sysctl.present: \- value: 20 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.sysctl.present(name, value, config=None) Ensure that the named sysctl value is set in memory and persisted to the named configuration file. The default sysctl configuration file is /etc/sysctl.conf .INDENT 7.0 .TP .B name The name of the sysctl value to edit .TP .B value The sysctl value to apply. Make sure to set the value to the correct expected output for systctl or reading the respective /proc/sys file. For example, instead of adding the value \fI1,2,3\fP you might need to write \fI1\-3\fP\&. If you do not set the correct value, Salt will continue to return with changes. .TP .B config The location of the sysctl configuration file. If not specified, the proper location will be detected based on platform. .UNINDENT .UNINDENT .SS salt.states.sysfs .SS Configuration of the kernel using sysfs .sp Control the kernel object attributes exported by sysfs .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C kernel/mm/transparent_hugepage/enabled sysfs.present: \- value: never .ft P .fi .UNINDENT .UNINDENT .sp New in version 3006.0. .INDENT 0.0 .TP .B salt.states.sysfs.present(name, value, config=None) Ensure that the named sysfs attribute is set with the defined value .INDENT 7.0 .TP .B name The name of the sysfs attribute to edit .TP .B value The sysfs value to apply .UNINDENT .UNINDENT .SS salt.states.syslog_ng .SS State module for syslog_ng .INDENT 0.0 .TP .B maintainer Tibor Benke <\fI\%btibi@sch.bme.hu\fP> .TP .B maturity new .TP .B depends cmd, ps, syslog_ng .TP .B platform all .UNINDENT .INDENT 0.0 .TP .B Users can generate syslog\-ng configuration files from YAML format or use plain ones and reload, start, or stop their syslog\-ng by using this module. .UNINDENT .SS Details .sp The service module is not available on all system, so this module includes \fI\%syslog_ng.reloaded\fP, \fI\%syslog_ng.stopped\fP, and \fI\%syslog_ng.started\fP functions. If the service module is available on the computers, users should use that. .sp Users can generate syslog\-ng configuration with \fI\%syslog_ng.config\fP function. For more information see \fI\%syslog\-ng state usage\fP\&. .SS Syslog\-ng configuration file format .sp The syntax of a configuration snippet in syslog\-ng.conf: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 object_type object_id {<options>}; .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp These constructions are also called statements. There are options inside of them: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 option(parameter1, parameter2); option2(parameter1, parameter2); .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp You can find more information about syslog\-ng\(aqs configuration syntax in the Syslog\-ng Admin guide: \fI\%http://www.balabit.com/sites/default/files/documents/syslog\-ng\-ose\-3.5\-guides/en/syslog\-ng\-ose\-v3.5\-guide\-admin/html\-single/index.html#syslog\-ng.conf.5\fP .INDENT 0.0 .TP .B salt.states.syslog_ng.config(name, config, write=True) Builds syslog\-ng configuration. .sp name : the id of the Salt document config : the parsed YAML code write : if True, it writes the config into the configuration file, otherwise just returns it .UNINDENT .INDENT 0.0 .TP .B salt.states.syslog_ng.reloaded(name) Reloads syslog\-ng. .UNINDENT .INDENT 0.0 .TP .B salt.states.syslog_ng.started(name=None, user=None, group=None, chroot=None, caps=None, no_caps=False, pidfile=None, enable_core=False, fd_limit=None, verbose=False, debug=False, trace=False, yydebug=False, persist_file=None, control=None, worker_threads=None, *args, **kwargs) Ensures, that syslog\-ng is started via the given parameters. .sp Users shouldn\(aqt use this function, if the service module is available on their system. .UNINDENT .INDENT 0.0 .TP .B salt.states.syslog_ng.stopped(name=None) Kills syslog\-ng. .UNINDENT .SS salt.states.sysrc .sp State to work with sysrc .INDENT 0.0 .TP .B salt.states.sysrc.absent(name, **kwargs) Ensure a sysrc variable is absent. .INDENT 7.0 .TP .B name The variable name to set .TP .B file (optional) The rc file to add the variable to. .TP .B jail (option) the name or JID of the jail to set the value in. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.sysrc.managed(name, value, **kwargs) Ensure a sysrc variable is set to a specific value. .INDENT 7.0 .TP .B name The variable name to set .TP .B value Value to set the variable to .TP .B file (optional) The rc file to add the variable to. .TP .B jail (option) the name or JID of the jail to set the value in. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C syslogd: sysrc.managed: \- name: syslogd_flags \- value: \-ss .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.telemetry_alert .SS Manage Telemetry alert configurations .sp New in version 2016.3.0. .sp Create, Update and destroy Mongo Telemetry alert configurations. .sp This module uses requests, which can be installed via package, or pip. .sp This module accepts explicit credential (telemetry api key) or can also read api key credentials from a pillar. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ensure telemetry alert X is defined on deployment Y: telemetry_alert.present: \- deployment_id: \(dqrs\-XXXXXX\(dq \- metric_name: \(dqtestMetric\(dq \- alert_config: max: 1 filter: SERVER_ROLE_MONGOD_PRIMARY escalate_to: \(dqexample@pagerduty.com\(dq \- name: \(dq**MANAGED BY ORCA DO NOT EDIT BY HAND** manages alarm on testMetric\(dq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.telemetry_alert.absent(name, deployment_id, metric_name, api_key=None, profile=\(aqtelemetry\(aq) Ensure the telemetry alert config is deleted .INDENT 7.0 .TP .B name An optional description of the alarms (not currently supported by telemetry API) .TP .B deployment_id Specifies the ID of the root deployment resource (replica set cluster or sharded cluster) to which this alert definition is attached .TP .B metric_name Specifies the unique ID of the metric to whose values these thresholds will be applied .TP .B api_key Telemetry api key for the user .TP .B profile A dict with telemetry config data. If present, will be used instead of api_key. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.telemetry_alert.present(name, deployment_id, metric_name, alert_config, api_key=None, profile=\(aqtelemetry\(aq) Ensure the telemetry alert exists. .INDENT 7.0 .TP .B name An optional description of the alarm (not currently supported by telemetry API) .TP .B deployment_id Specifies the ID of the root deployment resource (replica set cluster or sharded cluster) to which this alert definition is attached .TP .B metric_name Specifies the unique ID of the metric to whose values these thresholds will be applied .TP .B alert_config: Is a list of dictionaries where each dict contains the following fields: .INDENT 7.0 .TP .B filter By default the alert will apply to the deployment and all its constituent resources. If the alert only applies to a subset of those resources, a filter may be specified to narrow this scope. .TP .B min the smallest \(dqok\(dq value the metric may take on; if missing or null, no minimum is enforced. .TP .B max the largest \(dqok\(dq value the metric may take on; if missing or null, no maximum is enforced. .TP .B notify_all Used to indicate if you want to alert both onCallEngineer and apiNotifications .UNINDENT .TP .B api_key Telemetry api key for the user .TP .B profile A dict of telemetry config information. If present, will be used instead of api_key. .UNINDENT .UNINDENT .SS salt.states.test .SS Test States .sp Provide test case states that enable easy testing of things to do with state calls, e.g. running, calling, logging, output filtering etc. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C always\-passes\-with\-any\-kwarg: test.nop: \- name: foo \- something: else \- foo: bar always\-passes: test.succeed_without_changes: \- name: foo always\-fails: test.fail_without_changes: \- name: foo always\-changes\-and\-succeeds: test.succeed_with_changes: \- name: foo always\-changes\-and\-fails: test.fail_with_changes: \- name: foo my\-custom\-combo: test.configurable_test_state: \- name: foo \- changes: True \- result: False \- comment: bar.baz \- warnings: A warning is\-pillar\-foo\-present\-and\-bar\-is\-int: test.check_pillar: \- present: \- foo \- integer: \- bar .ft P .fi .UNINDENT .UNINDENT .sp You may also use these states for controlled failure in state definitions, for example if certain conditions in pillar or grains do not apply. The following state definition will fail with a message \(dqOS not supported!\(dq when \fIgrains[\(aqos\(aq]\fP is neither Ubuntu nor CentOS: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if grains[\(aqos\(aq] in [\(aqUbuntu\(aq, \(aqCentOS\(aq] %} # Your state definitions go here {% else %} failure: test.fail_without_changes: \- name: \(dqOS not supported!\(dq \- failhard: True {% endif %} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.test.check_pillar(name, present=None, boolean=None, integer=None, string=None, listing=None, dictionary=None, verbose=False) Checks the presence and, optionally, the type of given keys in Pillar .sp Supported kwargs for types are: \- boolean (bool) \- integer (int) \- string (str) \- listing (list) \- dictionary (dict) .sp Checking for None type pillars is not implemented yet. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C is\-pillar\-foo\-present\-and\-bar\-is\-int: test.check_pillar: \- present: \- foo \- integer: \- bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.test.configurable_test_state(name, changes=True, result=True, comment=\(aq\(aq, warnings=None, allow_test_mode_failure=False) New in version 2014.7.0. .sp A configurable test state which allows for more control over the return data .INDENT 7.0 .TP .B name A unique string to serve as the state\(aqs ID .TP .B changes True Controls whether or not the state reports that there were changes. There are three supported values for this argument: .INDENT 7.0 .IP \(bu 2 If \fBTrue\fP, the state will report changes .IP \(bu 2 If \fBFalse\fP, the state will report no changes .IP \(bu 2 If \fB\(dqRandom\(dq\fP, the state will randomly report either changes or no changes. .UNINDENT .TP .B result True Controls the result for for the state. Like \fBchanges\fP, there are three supported values for this argument: .INDENT 7.0 .IP \(bu 2 If \fBTrue\fP, the state will report a \fBTrue\fP result .IP \(bu 2 If \fBFalse\fP, the state will report a \fBFalse\fP result .IP \(bu 2 If \fB\(dqRandom\(dq\fP, the state will randomly report either \fBTrue\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The result will be reported as \fBNone\fP if \fIall\fP of the following are true: .sp 1. The state is being run in test mode (i.e. \fBtest=True\fP on the CLI) .INDENT 0.0 .IP 2. 3 \fBresult\fP is \fBTrue\fP (either explicitly, or via being set to \fB\(dqRandom\(dq\fP) .IP 3. 3 \fBchanges\fP is \fBTrue\fP (either explicitly, or via being set to \fB\(dqRandom\(dq\fP) .UNINDENT .UNINDENT .UNINDENT .TP .B comment \(dq\(dq Comment field field for the state. By default, this is an empty string. .TP .B warnings A string (or a list of strings) to fill the warnings field with. Default is None .sp New in version 3000. .TP .B allow_test_mode_failure When False, running this state in test mode can only return a True or None result. When set to True and result is set to False, the test mode result will be False. Default is False .sp New in version 3007.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.test.fail_with_changes(name, **kwargs) New in version 2014.7.0. .sp Returns \fBFalse\fP with an non\-empty \fBchanges\fP dictionary. Useful for testing requisites. .INDENT 7.0 .TP .B name A unique string to serve as the state\(aqs ID .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.test.fail_without_changes(name, **kwargs) New in version 2014.7.0. .sp Returns failure .INDENT 7.0 .TP .B name A unique string to serve as the state\(aqs ID .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.test.mod_watch(name, sfun=None, **kwargs) Call this function via a watch statement .sp New in version 2014.7.0. .sp Any parameters in the state return dictionary can be customized by adding the keywords \fBresult\fP, \fBcomment\fP, and \fBchanges\fP\&. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C this_state_will_return_changes: test.succeed_with_changes this_state_will_NOT_return_changes: test.succeed_without_changes this_state_is_watching_another_state: test.succeed_without_changes: \- comment: \(aqThis is a custom comment\(aq \- watch: \- test: this_state_will_return_changes \- test: this_state_will_NOT_return_changes this_state_is_also_watching_another_state: test.succeed_without_changes: \- watch: \- test: this_state_will_NOT_return_changes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.test.nop(name, **kwargs) New in version 2015.8.1. .sp A no\-op state that does nothing. Useful in conjunction with the \fBuse\fP requisite, or in templates which could otherwise be empty due to jinja rendering. .INDENT 7.0 .TP .B name A unique string to serve as the state\(aqs ID .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.test.show_notification(name, text=None, **kwargs) New in version 2015.8.0. .sp Simple notification using text argument. .INDENT 7.0 .TP .B name A unique string to serve as the state\(aqs ID .TP .B text Text to return in the comment field .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.test.succeed_with_changes(name, **kwargs) New in version 2014.7.0. .sp Returns \fBTrue\fP with an non\-empty \fBchanges\fP dictionary. Useful for testing requisites. .INDENT 7.0 .TP .B name A unique string to serve as the state\(aqs ID .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.test.succeed_without_changes(name, **kwargs) New in version 2014.7.0. .sp Returns successful .INDENT 7.0 .TP .B name A unique string to serve as the state\(aqs ID .UNINDENT .UNINDENT .SS salt.states.testinframod .INDENT 0.0 .TP .B salt.states.testinframod.camel_to_snake_case(camel_input) Converts camelCase (or CamelCase) to snake_case. From \fI\%https://codereview.stackexchange.com/questions/185966/functions\-to\-convert\-camelcase\-strings\-to\-snake\-case\fP .INDENT 7.0 .TP .B Parameters \fBcamel_input\fP (\fI\%str\fP) \-\- The camelcase or CamelCase string to convert to snake_case .UNINDENT .sp :return str .UNINDENT .SS salt.states.timezone .SS Management of timezones .sp The timezone can be managed for the system: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C America/Denver: timezone.system .ft P .fi .UNINDENT .UNINDENT .sp The system and the hardware clock are not necessarily set to the same time. By default, the hardware clock is set to localtime, meaning it is set to the same time as the system clock. If \fIutc\fP is set to True, then the hardware clock will be set to UTC, and the system clock will be an offset of that. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C America/Denver: timezone.system: \- utc: True .ft P .fi .UNINDENT .UNINDENT .sp The Ubuntu community documentation contains an explanation of this setting, as it applies to systems that dual\-boot with Windows. This is explained in greater detail \fI\%here\fP\&. .INDENT 0.0 .TP .B salt.states.timezone.system(name, utc=True) Set the timezone for the system. .INDENT 7.0 .TP .B name The name of the timezone to use (e.g.: America/Denver) .TP .B utc Whether or not to set the hardware clock to UTC (default is True) .UNINDENT .UNINDENT .SS salt.states.tls .SS Enforce state for SSL/TLS .INDENT 0.0 .TP .B salt.states.tls.valid_certificate(name, weeks=0, days=0, hours=0, minutes=0, seconds=0) Verify that a TLS certificate is valid now and (optionally) will be valid for the time specified through weeks, days, hours, minutes, and seconds. .UNINDENT .SS salt.states.tomcat .SS Manage Apache Tomcat web applications .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This state requires the Tomcat Manager webapp to be installed and running. .UNINDENT .UNINDENT .sp The following grains/pillars must be set for communication with Tomcat Manager to work: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tomcat\-manager: user: \(aqtomcat\-manager\(aq passwd: \(aqPassw0rd\(aq .ft P .fi .UNINDENT .UNINDENT .SS Configuring Tomcat Manager .sp To manage webapps via the Tomcat Manager, you\(aqll need to configure a valid user in the file \fBconf/tomcat\-users.xml\fP\&. .sp conf/tomcat\-users.xml .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C <?xml version=\(aq1.0\(aq encoding=\(aqutf\-8\(aq?> <tomcat\-users> <role rolename=\(dqmanager\-script\(dq/> <user username=\(dqtomcat\-manager\(dq password=\(dqPassw0rd\(dq roles=\(dqmanager\-script\(dq/> </tomcat\-users> .ft P .fi .UNINDENT .UNINDENT .sp Notes .INDENT 0.0 .IP \(bu 2 Using multiple versions (aka. parallel deployments) on the same context path is not supported. .IP \(bu 2 More information about the Tomcat Manager: \fI\%http://tomcat.apache.org/tomcat\-7.0\-doc/manager\-howto.html\fP .IP \(bu 2 If you use only this module for deployments you might want to restrict access to the manager so it\(aqs only accessible via localhost. For more info: \fI\%http://tomcat.apache.org/tomcat\-7.0\-doc/manager\-howto.html#Configuring_Manager_Application_Access\fP .IP \(bu 2 .INDENT 2.0 .TP .B Last tested on: .INDENT 7.0 .TP .B Tomcat Version: Apache Tomcat/7.0.54 .TP .B JVM Vendor: Oracle Corporation .TP .B JVM Version: 1.8.0_101\-b13 .TP .B OS Architecture: amd64 .TP .B OS Name: Linux .TP .B OS Version: 3.10.0\-327.22.2.el7.x86_64 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.tomcat.mod_watch(name, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) The tomcat watcher, called to invoke the watch command. When called, it will reload the webapp in question .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This state exists to support special handling of the \fBwatch\fP \fI\%requisite\fP\&. It should not be called directly. .sp Parameters for this function should be set by the state being triggered. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.tomcat.undeployed(name, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) Enforce that the WAR will be undeployed from the server .INDENT 7.0 .TP .B name The context path to undeploy. .TP .B url \fI\%http://localhost:8080/manager\fP The URL of the server with the Tomcat Manager webapp. .TP .B timeout 180 Timeout for HTTP request to the Tomcat Manager. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C jenkins: tomcat.undeployed: \- name: /ran \- require: \- service: application\-service .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.tomcat.wait(name, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180) Wait for the Tomcat Manager to load. .sp Notice that if tomcat is not running we won\(aqt wait for it start and the state will fail. This state can be required in the tomcat.war_deployed state to make sure tomcat is running and that the manager is running as well and ready for deployment. .INDENT 7.0 .TP .B url \fI\%http://localhost:8080/manager\fP The URL of the server with the Tomcat Manager webapp. .TP .B timeout 180 Timeout for HTTP request to the Tomcat Manager. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C tomcat\-service: service.running: \- name: tomcat \- enable: True wait\-for\-tomcatmanager: tomcat.wait: \- timeout: 300 \- require: \- service: tomcat\-service jenkins: tomcat.war_deployed: \- name: /ran \- war: salt://jenkins\-1.2.4.war \- require: \- tomcat: wait\-for\-tomcatmanager .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.tomcat.war_deployed(name, war, force=False, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180, temp_war_location=None, version=True) Enforce that the WAR will be deployed and started in the context path, while making use of WAR versions in the filename. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For more info about Tomcats file paths and context naming, please see \fI\%http://tomcat.apache.org/tomcat\-7.0\-doc/config/context.html#Naming\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name The context path to deploy (incl. forward slash) the WAR to. .TP .B war Absolute path to WAR file (should be accessible by the user running Tomcat) or a path supported by the \fBsalt.modules.cp.get_url\fP function. .TP .B force False Force deployment even if the version strings are the same. Disabled by default. .TP .B url \fI\%http://localhost:8080/manager\fP The URL of the Tomcat Web Application Manager. .TP .B timeout 180 Timeout for HTTP requests to the Tomcat Manager. .TP .B temp_war_location None Use another location to temporarily copy the WAR file to. By default the system\(aqs temp directory is used. .TP .B version \(aq\(aq Specify the WAR version. If this argument is provided, it overrides the version encoded in the WAR file name, if one is present. .sp New in version 2015.8.6. .sp Use \fBFalse\fP or blank value to prevent guessing the version and keeping it blank. .sp New in version 2016.11.0. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C jenkins: tomcat.war_deployed: \- name: /salt\-powered\-jenkins \- war: salt://jenkins\-1.2.4.war \- require: \- service: application\-service .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Be aware that in the above example the WAR \fBjenkins\-1.2.4.war\fP will be deployed to the context path \fBsalt\-powered\-jenkins##1.2.4\fP\&. To avoid this either specify a version yourself, or set version to \fBFalse\fP\&. .UNINDENT .UNINDENT .UNINDENT .SS salt.states.trafficserver .SS Control Apache Traffic Server .sp New in version 2015.8.0. .INDENT 0.0 .TP .B salt.states.trafficserver.bounce_cluster(name) Bounce all Traffic Server nodes in the cluster. Bouncing Traffic Server shuts down and immediately restarts Traffic Server, node\-by\-node. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C bounce_ats_cluster: trafficserver.bounce_cluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.trafficserver.bounce_local(name, drain=False) Bounce Traffic Server on the local node. Bouncing Traffic Server shuts down and immediately restarts the Traffic Server node. .sp This option modifies the behavior of traffic_line \-b and traffic_line \-L such that traffic_server is not shut down until the number of active client connections drops to the number given by the proxy.config.restart.active_client_threshold configuration variable. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C bounce_ats_local: trafficserver.bounce_local bounce_ats_local: trafficserver.bounce_local \- drain: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.trafficserver.clear_cluster(name) Clears accumulated statistics on all nodes in the cluster. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C clear_ats_cluster: trafficserver.clear_cluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.trafficserver.clear_node(name) Clears accumulated statistics on the local node. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C clear_ats_node: trafficserver.clear_node .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.trafficserver.config(name, value) Set Traffic Server configuration variable values. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C proxy.config.proxy_name: trafficserver.config: \- value: cdn.site.domain.tld OR traffic_server_setting: trafficserver.config: \- name: proxy.config.proxy_name \- value: cdn.site.domain.tld .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.trafficserver.offline(name, path) Mark a cache storage device as offline. The storage is identified by a path which must match exactly a path specified in storage.config. This removes the storage from the cache and redirects requests that would have used this storage to other storage. This has exactly the same effect as a disk failure for that storage. This does not persist across restarts of the traffic_server process. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C offline_ats_path: trafficserver.offline: \- path: /path/to/cache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.trafficserver.refresh(name) Initiate a Traffic Server configuration file reread. Use this command to update the running configuration after any configuration file modification. .sp The timestamp of the last reconfiguration event (in seconds since epoch) is published in the proxy.node.config.reconfigure_time metric. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C refresh_ats: trafficserver.refresh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.trafficserver.restart_cluster(name) Restart the traffic_manager process and the traffic_server process on all the nodes in a cluster. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C restart_ats_cluster: trafficserver.restart_cluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.trafficserver.restart_local(name, drain=False) Restart the traffic_manager and traffic_server processes on the local node. .sp This option modifies the behavior of traffic_line \-b and traffic_line \-L such that traffic_server is not shut down until the number of active client connections drops to the number given by the proxy.config.restart.active_client_threshold configuration variable. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C restart_ats_local: trafficserver.restart_local restart_ats_local_drain: trafficserver.restart_local \- drain: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.trafficserver.shutdown(name) Shut down Traffic Server on the local node. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C shutdown_ats: trafficserver.shutdown .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.trafficserver.startup(name) Start Traffic Server on the local node. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C startup_ats: trafficserver.startup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.trafficserver.zero_cluster(name) Reset performance statistics to zero across the cluster. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C zero_ats_cluster: trafficserver.zero_cluster .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.trafficserver.zero_node(name) Reset performance statistics to zero on the local node. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C zero_ats_node: trafficserver.zero_node .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.tuned .sp Interface to Red Hat tuned\-adm module .INDENT 0.0 .TP .B maintainer Syed Ali <\fI\%alicsyed@gmail.com\fP> .TP .B maturity new .TP .B depends cmd.run .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.states.tuned.off(name=None) Turns \(aqtuned\(aq off. Example tuned.sls file for turning tuned off: .INDENT 7.0 .TP .B tuned: tuned.off: [] .TP .B To see a valid list of states call execution module: \fI\%tuned.list\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.tuned.profile(name) This state module allows you to modify system tuned parameters .sp Example tuned.sls file to set profile to virtual\-guest .INDENT 7.0 .TP .B tuned: .INDENT 7.0 .TP .B tuned.profile .INDENT 7.0 .IP \(bu 2 name: virtual\-guest .UNINDENT .UNINDENT .TP .B name tuned profile name to set the system to .TP .B To see a valid list of states call execution module: \fI\%tuned.list\fP .UNINDENT .UNINDENT .SS salt.states.uptime .SS Monitor Web Server with Uptime .sp \fI\%Uptime\fP is an open source remote monitoring application using Node.js, MongoDB, and Twitter Bootstrap. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This state module is beta. It might be changed later to include more or less automation. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This state module requires a pillar to specify the location of your uptime install .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C uptime: application_url: \(dqhttp://uptime\-url.example.org\(dq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C url: uptime.monitored url/sitemap.xml: uptime.monitored: \- polling: 600 # every hour .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.uptime.monitored(name, **params) Makes sure an URL is monitored by uptime. Checks if URL is already monitored, and if not, adds it. .UNINDENT .SS salt.states.user .SS Management of user accounts. .sp The user module is used to create and manage user settings, users can be set as either absent or present .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fred: user.present: \- fullname: Fred Jones \- shell: /bin/zsh \- home: /home/fred \- uid: 4000 \- gid: 4000 \- groups: \- wheel \- storage \- games testuser: user.absent .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.user.absent(name, purge=False, force=False, local=False) Ensure that the named user is absent .INDENT 7.0 .TP .B name The name of the user to remove .TP .B purge Set purge to True to delete all of the user\(aqs files as well as the user, Default is \fBFalse\fP\&. .TP .B force If the user is logged in, the absent state will fail. Set the force option to True to remove the user even if they are logged in. Not supported in FreeBSD and Solaris, Default is \fBFalse\fP\&. .TP .B local (Only on systems with luserdel available): Ensure the user account is removed locally ignoring global account management (default is False). .sp New in version 3007.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.user.present(name, uid=None, gid=None, usergroup=None, groups=None, optional_groups=None, remove_groups=True, home=None, createhome=True, password=None, hash_password=False, enforce_password=True, empty_password=False, shell=None, unique=True, system=False, fullname=None, roomnumber=None, workphone=None, homephone=None, other=None, loginclass=None, date=None, mindays=None, maxdays=None, inactdays=None, warndays=None, expire=None, win_homedrive=None, win_profile=None, win_logonscript=None, win_description=None, nologinit=False, allow_uid_change=False, allow_gid_change=False, password_lock=None, local=False) Ensure that the named user is present with the specified properties .INDENT 7.0 .TP .B name The name of the user to manage .TP .B uid The user id to assign. If not specified, and the user does not exist, then the next available uid will be assigned. .TP .B gid The id of the default group to assign to the user. Either a group name or gid can be used. If not specified, and the user does not exist, then the next available gid will be assigned. .TP .B allow_uid_change False Set to \fBTrue\fP to allow the state to update the uid. .sp New in version 2018.3.1. .TP .B allow_gid_change False Set to \fBTrue\fP to allow the state to update the gid. .sp New in version 2018.3.1. .TP .B usergroup If True, a group with the same name as the user will be created. If False, a group with the same name as the user will not be created. The default is distribution\-specific. See the USERGROUPS_ENAB section of the login.defs(5) man page. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Only supported on GNU/Linux distributions .UNINDENT .UNINDENT .sp New in version 3001. .TP .B groups A list of groups to assign the user to, pass a list object. If a group specified here does not exist on the minion, the state will fail. If set to the empty list, the user will be removed from all groups except the default group. If unset, salt will assume current groups are still wanted, and will make no changes to them. .TP .B optional_groups A list of groups to assign the user to, pass a list object. If a group specified here does not exist on the minion, the state will silently ignore it. .UNINDENT .sp NOTE: If the same group is specified in both \(dqgroups\(dq and \(dqoptional_groups\(dq, then it will be assumed to be required and not optional. .INDENT 7.0 .TP .B remove_groups Remove groups that the user is a member of that weren\(aqt specified in the state, Default is \fBTrue\fP\&. .TP .B home The custom login directory of user. Uses default value of underlying system if not set. Notice that this directory does not have to exist. This also the location of the home directory to create if createhome is set to True. .TP .B createhome True If set to \fBFalse\fP, the home directory will not be created if it doesn\(aqt already exist. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Not supported on Windows or Mac OS. .sp Additionally, parent directories will \fInot\fP be created. The parent directory for \fBhome\fP must already exist. .UNINDENT .UNINDENT .TP .B nologinit False If set to \fBTrue\fP, it will not add the user to lastlog and faillog databases. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Not supported on Windows. .UNINDENT .UNINDENT .TP .B password A password hash to set for the user. This field is only supported on Linux, FreeBSD, NetBSD, OpenBSD, and Solaris. If the \fBempty_password\fP argument is set to \fBTrue\fP then \fBpassword\fP is ignored. For Windows this is the plain text password. For Linux, the hash can be generated with \fBmkpasswd \-m sha\-256\fP\&. .UNINDENT .sp Changed in version 0.16.0: BSD support added. .INDENT 7.0 .TP .B hash_password Set to True to hash the clear text password. Default is \fBFalse\fP\&. .TP .B enforce_password Set to False to keep the password from being changed if it has already been set and the password hash differs from what is specified in the \(dqpassword\(dq field. This option will be ignored if \(dqpassword\(dq is not specified, Default is \fBTrue\fP\&. .TP .B empty_password Set to True to enable password\-less login for user, Default is \fBFalse\fP\&. .TP .B password_lock Set to \fBFalse\fP to unlock a user\(aqs password (or Windows account). On non\-Windows systems ONLY, this parameter can be set to \fBTrue\fP to lock a user\(aqs password. Default is \fBNone\fP, which does not take action on the password (or Windows account). .sp New in version 3006.0. .TP .B shell The login shell, defaults to the system default shell .TP .B unique Require a unique UID, Default is \fBTrue\fP\&. .TP .B system Choose UID in the range of FIRST_SYSTEM_UID and LAST_SYSTEM_UID, Default is \fBFalse\fP\&. .TP .B loginclass The login class, defaults to empty (BSD only) .UNINDENT .sp User comment field (GECOS) support (currently Linux, BSD, and MacOS only): .sp The below values should be specified as strings to avoid ambiguities when the values are loaded. (Especially the phone and room number fields which are likely to contain numeric data) .INDENT 7.0 .TP .B fullname The user\(aqs full name .TP .B roomnumber The user\(aqs room number (not supported in MacOS) .TP .B workphone The user\(aqs work phone number (not supported in MacOS) .TP .B homephone The user\(aqs home phone number (not supported in MacOS) .TP .B other The user\(aqs other attribute (not supported in MacOS) If GECOS field contains more than 4 commas, this field will have the rest of \(aqem .UNINDENT .sp Changed in version 2014.7.0: Shadow attribute support added. .sp Shadow attributes support (currently Linux only): .sp The below values should be specified as integers. .INDENT 7.0 .TP .B date Date of last change of password, represented in days since epoch (January 1, 1970). .TP .B mindays The minimum number of days between password changes. .TP .B maxdays The maximum number of days between password changes. .TP .B inactdays The number of days after a password expires before an account is locked. .TP .B warndays Number of days prior to maxdays to warn users. .TP .B expire Date that account expires, represented in days since epoch (January 1, 1970). .TP .B local (Only on systems with luseradd available): Create the user account locally ignoring global account management (default is False). .sp New in version 3007.0. .UNINDENT .sp The below parameters apply to windows only: .INDENT 7.0 .TP .B win_homedrive (Windows Only) The drive letter to use for the home directory. If not specified the home directory will be a unc path. Otherwise the home directory will be mapped to the specified drive. Must be a letter followed by a colon. Because of the colon, the value must be surrounded by single quotes. ie: \fB\- win_homedrive: \(aqU:\(aq\fP .sp Changed in version 2015.8.0. .TP .B win_profile (Windows Only) The custom profile directory of the user. Uses default value of underlying system if not set. .sp Changed in version 2015.8.0. .TP .B win_logonscript (Windows Only) The full path to the logon script to run when the user logs in. .sp Changed in version 2015.8.0. .TP .B win_description (Windows Only) A brief description of the purpose of the users account. .sp Changed in version 2015.8.0. .UNINDENT .UNINDENT .SS salt.states.vagrant .SS Manage Vagrant VMs .sp Manange execution of Vagrant virtual machines on Salt minions. .sp \fI\%Vagrant\fP is a tool for building and managing virtual machine environments. It can use various providers, such as \fI\%VirtualBox\fP, \fI\%Docker\fP, or \fI\%VMware\fP, to run its VMs. Vagrant provides some of the functionality of a light\-weight hypervisor. The combination of Salt modules, Vagrant running on the host, and a virtual machine provider, gives hypervisor\-like functionality for developers who use Vagrant to quickly define their virtual environments. .INDENT 0.0 .INDENT 3.5 New in version 2018.3.0. .UNINDENT .UNINDENT .sp The configuration of each virtual machine is defined in a file named \fBVagrantfile\fP which must exist on the VM host machine. The essential parameters which must be defined to start a Vagrant VM are the directory where the \fBVagrantfile\fP is located (argument \fBcwd:\fP), and the username which will own the \fBVagrant box\fP created for the VM ( argument \fBvagrant_runas:\fP). .sp A single \fBVagrantfile\fP may define one or more virtual machines. Use the \fBmachine\fP argument to chose among them. The default (blank) value will select the \fBprimary\fP (or only) machine in the Vagrantfile. .sp [NOTE:] Each virtual machine host must have the following: .INDENT 0.0 .IP \(bu 2 a working salt\-minion .IP \(bu 2 a Salt sdb database configured for \fBvagrant_sdb_data\fP\&. .IP \(bu 2 Vagrant installed and the \fBvagrant\fP command working .IP \(bu 2 a suitable VM provider .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # EXAMPLE: # file /etc/salt/minion.d/vagrant_sdb.conf on the host computer # \-\- 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 .INDENT 0.0 .TP .B salt.states.vagrant.destroyed(name) Stops a VM (or VMs) and removes all references to it (them). (Runs \fBvagrant destroy\fP\&.) .sp Subsequent re\-use of the same machine will requere another operation of \fBvagrant.running\fP or a call to the \fBvagrant.init\fP execution module. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- May be a Salt_id node or a POSIX\-style wildcard string. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C node_name: vagrant.destroyed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.vagrant.initialized(name, **kwargs) Defines a new VM with specified arguments, but does not start it. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- the Salt_id node name you wish your VM to have. .UNINDENT .sp Each machine must be initialized individually using this function or the \(dqvagrant.running\(dq function, or the vagrant.init execution module call. .sp This command will not change the state of a running or paused machine. .sp Possible keyword arguments: .INDENT 7.0 .IP \(bu 2 cwd: The directory (path) containing the Vagrantfile .IP \(bu 2 machine: (\(aq\(aq) the name of the machine (in the Vagrantfile) if not default .IP \(bu 2 vagrant_runas: (\(aqroot\(aq) the username who owns the vagrantbox file .IP \(bu 2 vagrant_provider: the provider to run the VM (usually \(aqvirtualbox\(aq) .IP \(bu 2 vm: ({}) a dictionary containing these or other keyword arguments .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C node_name1: vagrant.initialized \- cwd: /projects/my_project \- vagrant_runas: my_username \- machine: machine1 node_name2: vagrant.initialized \- cwd: /projects/my_project \- vagrant_runas: my_username \- machine: machine2 start_nodes: vagrant.start: \- name: node_name? .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.vagrant.paused(name) Stores the state of a VM (or VMs) for fast restart. (Runs \fBvagrant suspend\fP\&.) .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- May be a Salt_id node or a POSIX\-style wildcard string. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C node_name: vagrant.paused .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.vagrant.powered_off(name) Stops a VM (or VMs) by power off. (Runs \fBvagrant halt\fP\&.) .sp This method is provided for compatibility with other VM\-control state modules. For Vagrant, the action is identical with \fBstopped\fP\&. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- May be a Salt_id node or a POSIX\-style wildcard string. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C node_name: vagrant.unpowered .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.vagrant.rebooted(name) Reboots a running, paused, or stopped VM (or VMs). (Runs \fBvagrant reload\fP\&.) .sp The will re\-run the provisioning .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- May be a Salt_id node or a POSIX\-style wildcard string. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C node_name: vagrant.reloaded .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.vagrant.running(name, **kwargs) Defines and starts a new VM with specified arguments, or restart a VM (or group of VMs). (Runs \fBvagrant up\fP\&.) .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- the Salt_id node name you wish your VM to have. .UNINDENT .sp If \fBname\fP contains a \(dq?\(dq or \(dq*\(dq then it will re\-start a group of VMs which have been paused or stopped. .sp Each machine must be initially started individually using this function or the vagrant.init execution module call. .sp [NOTE:] Keyword arguments are silently ignored when re\-starting an existing VM. .sp Possible keyword arguments: .INDENT 7.0 .IP \(bu 2 cwd: The directory (path) containing the Vagrantfile .IP \(bu 2 machine: (\(aq\(aq) the name of the machine (in the Vagrantfile) if not default .IP \(bu 2 vagrant_runas: (\(aqroot\(aq) the username who owns the vagrantbox file .IP \(bu 2 vagrant_provider: the provider to run the VM (usually \(aqvirtualbox\(aq) .IP \(bu 2 vm: ({}) a dictionary containing these or other keyword arguments .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C node_name: vagrant.running .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C node_name: vagrant.running: \- cwd: /projects/my_project \- vagrant_runas: my_username \- machine: machine1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.vagrant.stopped(name) Stops a VM (or VMs) by shutting it (them) down nicely. (Runs \fBvagrant halt\fP) .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- May be a Salt_id node, or a POSIX\-style wildcard string. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C node_name: vagrant.stopped .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.vault .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module will be removed from Salt in version 3009 in favor of the \fI\%vault Salt Extension\fP\&. .UNINDENT .UNINDENT .sp States for managing Hashicorp Vault. Currently handles policies. Configuration instructions are documented in the \fI\%execution module docs\fP\&. .INDENT 0.0 .TP .B maintainer SaltStack .TP .B maturity new .TP .B platform all .UNINDENT .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.states.vault.policy_absent(name) Ensure a Vault policy with the given name and rules is absent. .INDENT 7.0 .TP .B name The name of the policy .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.vault.policy_present(name, rules) Ensure a Vault policy with the given name and rules is present. .INDENT 7.0 .TP .B name The name of the policy .TP .B rules Rules formatted as in\-line HCL .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C demo\-policy: vault.policy_present: \- name: foo/bar \- rules: | path \(dqsecret/top\-secret/*\(dq { policy = \(dqdeny\(dq } path \(dqsecret/not\-very\-secret/*\(dq { policy = \(dqwrite\(dq } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.states.vbox_guest .sp VirtualBox Guest Additions installer state .INDENT 0.0 .TP .B salt.states.vbox_guest.additions_installed(name, reboot=False, upgrade_os=False) Ensure that the VirtualBox Guest Additions are installed. Uses the CD, connected by VirtualBox. .INDENT 7.0 .TP .B name The name has no functional value and is only used as a tracking reference. .TP .B reboot False Restart OS to complete installation. .TP .B upgrade_os False Upgrade OS (to ensure the latests version of kernel and developer tools installed). .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.vbox_guest.additions_removed(name, force=False) Ensure that the VirtualBox Guest Additions are removed. Uses the CD, connected by VirtualBox. .sp To connect VirtualBox Guest Additions via VirtualBox graphical interface press \(aqHost+D\(aq (\(aqHost\(aq is usually \(aqRight Ctrl\(aq). .INDENT 7.0 .TP .B name The name has no functional value and is only used as a tracking reference. .TP .B force Force VirtualBox Guest Additions removing. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.vbox_guest.grant_access_to_shared_folders_to(name, users=None) Grant access to auto\-mounted shared folders to the users. .sp User is specified by its name. To grant access for several users use argument \fIusers\fP\&. .INDENT 7.0 .TP .B name Name of the user to grant access to auto\-mounted shared folders to. .TP .B users List of names of users to grant access to auto\-mounted shared folders to. If specified, \fIname\fP will not be taken into account. .UNINDENT .UNINDENT .SS salt.states.victorops .SS Create an Event in VictorOps .sp New in version 2015.8.0. .sp This state is useful for creating events on the VictorOps service during state runs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C webserver\-warning\-message: victorops.create_event: \- message_type: \(aqCRITICAL\(aq \- entity_id: \(aqwebserver/diskspace\(aq \- state_message: \(aqWebserver diskspace is low.\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.victorops.create_event(name, message_type, routing_key=\(aqeveryone\(aq, **kwargs) Create an event on the VictorOps service .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C webserver\-warning\-message: victorops.create_event: \- message_type: \(aqCRITICAL\(aq \- entity_id: \(aqwebserver/diskspace\(aq \- state_message: \(aqWebserver diskspace is low.\(aq database\-server\-warning\-message: victorops.create_event: \- message_type: \(aqWARNING\(aq \- entity_id: \(aqdb_server/load\(aq \- state_message: \(aqDatabase Server load is high.\(aq \- entity_is_host: True \- entity_display_name: \(aqdbdserver.example.com\(aq .ft P .fi .UNINDENT .UNINDENT .sp The following parameters are required: .INDENT 7.0 .TP .B name This is a short description of the event. .TP .B message_type One of the following values: INFO, WARNING, ACKNOWLEDGEMENT, CRITICAL, RECOVERY. .UNINDENT .sp The following parameters are optional: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B routing_key The key for where messages should be routed. By default, sent to \(aqeveryone\(aq route. .TP .B entity_id The name of alerting entity. If not provided, a random name will be assigned. .TP .B timestamp Timestamp of the alert in seconds since epoch. Defaults to the time the alert is received at VictorOps. .TP .B timestamp_fmt The date format for the timestamp parameter. Defaults to \(aq\(aq%Y\-%m\-%dT%H:%M:%S\(aq. .TP .B state_start_time The time this entity entered its current state (seconds since epoch). Defaults to the time alert is received. .TP .B state_start_time_fmt The date format for the timestamp parameter. Defaults to \(aq%Y\-%m\-%dT%H:%M:%S\(aq. .TP .B state_message Any additional status information from the alert item. .TP .B entity_is_host Used within VictorOps to select the appropriate display format for the incident. .TP .B entity_display_name Used within VictorOps to display a human\-readable name for the entity. .TP .B ack_message A user entered comment for the acknowledgment. .TP .B ack_author The user that acknowledged the incident. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS salt.states.virt .SS Manage virt .sp For the key certificate this state uses the external pillar in the master to call for the generation and signing of certificates for systems running libvirt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C libvirt_keys: virt.keys .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.virt.defined(name, cpu=None, mem=None, vm_type=None, disk_profile=None, disks=None, nic_profile=None, interfaces=None, graphics=None, seed=True, install=True, pub_key=None, priv_key=None, connection=None, username=None, password=None, os_type=None, arch=None, boot=None, numatune=None, boot_dev=None, hypervisor_features=None, clock=None, serials=None, consoles=None, stop_on_reboot=False, live=True, host_devices=None, autostart=False) Starts an existing guest, or defines and starts a new VM with specified arguments. .sp New in version 3001. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- name of the virtual machine to run .IP \(bu 2 \fBcpu\fP \-\- .sp Number of virtual CPUs to assign to the virtual machine or a dictionary with detailed information to configure cpu model and topology, numa node tuning, cpu tuning and iothreads allocation. The structure of the dictionary is documented in \fI\%cpu parameters definition\fP\&. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C cpu: placement: static cpuset: 0\-11 current: 5 maximum: 12 vcpus: 0: enabled: \(aqyes\(aq hotpluggable: \(aqno\(aq order: 1 1: enabled: \(aqno\(aq hotpluggable: \(aqyes\(aq match: minimum mode: custom check: full vendor: Intel model: name: core2duo fallback: allow vendor_id: GenuineIntel topology: sockets: 1 cores: 12 threads: 1 cache: level: 3 mode: emulate feature: policy: optional name: lahf_lm numa: 0: cpus: 0\-3 memory: 1g discard: \(aqyes\(aq distances: 0: 10 # sibling id : value 1: 21 2: 31 3: 41 1: cpus: 4\-6 memory: 1g memAccess: shared distances: 0: 21 1: 10 2: 21 3: 31 tuning: vcpupin: 0: 1\-4,^2 # vcpuid : cpuset 1: 0,1 2: 2,3 3: 0,4 emulatorpin: 1\-3 iothreadpin: 1: 5,6 # iothread id: cpuset 2: 7,8 shares: 2048 period: 1000000 quota: \-1 global_period: 1000000 global_quota: \-1 emulator_period: 1000000 emulator_quota: \-1 iothread_period: 1000000 iothread_quota: \-1 vcpusched: \- scheduler: fifo priority: 1 \- scheduler: fifo priority: 2 vcpus: 1\-3 \- scheduler: rr priority: 3 vcpus: 4 iothreadsched: \- scheduler: batch iothreads: 2 emulatorsched: scheduler: idle cachetune: 0\-3: # vcpus set 0: # cache id level: 3 type: both size: 4 1: level: 3 type: both size: 6 monitor: 1: 3 0\-3: 3 4\-5: monitor: 4: 3 # vcpus: level 5: 3 memorytune: 0\-3: # vcpus set 0: 60 # node id: bandwidth 4\-5: 0: 60 iothreads: 4 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBmem\fP \-\- .sp Amount of memory to allocate to the virtual machine in MiB. Since 3002, a dictionary can be used to contain detailed configuration which support memory allocation or tuning. Supported parameters are \fBboot\fP, \fBcurrent\fP, \fBmax\fP, \fBslots\fP, \fBhard_limit\fP, \fBsoft_limit\fP, \fBswap_hard_limit\fP, \fBmin_guarantee\fP, \fBhugepages\fP , \fBnosharepages\fP, \fBlocked\fP, \fBsource\fP, \fBaccess\fP, \fBallocation\fP and \fBdiscard\fP\&. The structure of the dictionary is documented in \fI\%Memory parameter definition\fP\&. Both decimal and binary base are supported. Detail unit specification is documented in \fI\%Units specification\fP\&. Please note that the value for \fBslots\fP must be an integer. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C boot: 1g current: 1g max: 1g slots: 10 hard_limit: 1024 soft_limit: 512m swap_hard_limit: 1g min_guarantee: 512mib hugepages: \- size: 2m \- nodeset: 0\-2 size: 1g \- nodeset: 3 size: 2g nosharepages: True locked: True source: file access: shared allocation: immediate discard: True .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3002. .IP \(bu 2 \fBvm_type\fP \-\- force virtual machine type for the new VM. The default value is taken from the host capabilities. This could be useful for example to use \fB\(aqqemu\(aq\fP type instead of the \fB\(aqkvm\(aq\fP one. .IP \(bu 2 \fBdisk_profile\fP \-\- Name of the disk profile to use for the new virtual machine .IP \(bu 2 \fBdisks\fP \-\- List of disk to create for the new virtual machine. See \fI\%Disks Definitions\fP for more details on the items on this list. .IP \(bu 2 \fBnic_profile\fP \-\- Name of the network interfaces profile to use for the new virtual machine .IP \(bu 2 \fBinterfaces\fP \-\- List of network interfaces to create for the new virtual machine. See \fI\%Network Interfaces Definitions\fP for more details on the items on this list. .IP \(bu 2 \fBgraphics\fP \-\- Graphics device to create for the new virtual machine. See \fI\%Graphics Definition\fP for more details on this dictionary .IP \(bu 2 \fBsaltenv\fP \-\- Fileserver environment (Default: \fB\(aqbase\(aq\fP). See \fI\%cp module for more details\fP .IP \(bu 2 \fBseed\fP \-\- \fBTrue\fP to seed the disk image. Only used when the \fBimage\fP parameter is provided. (Default: \fBTrue\fP) .IP \(bu 2 \fBinstall\fP \-\- install salt minion if absent (Default: \fBTrue\fP) .IP \(bu 2 \fBpub_key\fP \-\- public key to seed with (Default: \fBNone\fP) .IP \(bu 2 \fBpriv_key\fP \-\- public key to seed with (Default: \fBNone\fP) .IP \(bu 2 \fBseed_cmd\fP \-\- Salt command to execute to seed the image. (Default: \fB\(aqseed.apply\(aq\fP) .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .IP \(bu 2 \fBos_type\fP \-\- type of virtualization as found in the \fB//os/type\fP element of the libvirt definition. The default value is taken from the host capabilities, with a preference for \fBhvm\fP\&. Only used when creating a new virtual machine. .IP \(bu 2 \fBarch\fP \-\- architecture of the virtual machine. The default value is taken from the host capabilities, but \fBx86_64\fP is prefed over \fBi686\fP\&. Only used when creating a new virtual machine. .IP \(bu 2 \fBboot\fP \-\- .sp Specifies kernel, initial ramdisk and kernel command line parameters for the virtual machine. This is an optional parameter, all of the keys are optional within the dictionary. .sp Refer to \fI\%Boot parameters definition\fP for the complete boot parameters description. .sp To update any boot parameters, specify the new path for each. To remove any boot parameters, pass a None object, for instance: \(aqkernel\(aq: \fBNone\fP\&. .sp New in version 3000. .IP \(bu 2 \fBboot_dev\fP \-\- .sp Space separated list of devices to boot from sorted by decreasing priority. Values can be \fBhd\fP, \fBfd\fP, \fBcdrom\fP or \fBnetwork\fP\&. .sp By default, the value will \fB\(dqhd\(dq\fP\&. .sp New in version 3002. .IP \(bu 2 \fBnumatune\fP \-\- .sp The optional numatune element provides details of how to tune the performance of a NUMA host via controlling NUMA policy for domain process. The optional \fBmemory\fP element specifies how to allocate memory for the domain process on a NUMA host. \fBmemnode\fP elements can specify memory allocation policies per each guest NUMA node. The definition used in the dictionary can be found at \fI\%cpu parameters definition\fP\&. .sp New in version 3003. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C { \(aqmemory\(aq: {\(aqmode\(aq: \(aqstrict\(aq, \(aqnodeset\(aq: \(aq0\-11\(aq}, \(aqmemnodes\(aq: {0: {\(aqmode\(aq: \(aqstrict\(aq, \(aqnodeset\(aq: 1}, 1: {\(aqmode\(aq: \(aqpreferred\(aq, \(aqnodeset\(aq: 2}} } .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBhypervisor_features\fP \-\- .sp Enable or disable hypervisor\-specific features on the virtual machine. .sp New in version 3003. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C hypervisor_features: kvm\-hint\-dedicated: True .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBclock\fP \-\- .sp Configure the guest clock. The value is a dictionary with the following keys: .INDENT 2.0 .TP .B adjustment time adjustment in seconds or \fBreset\fP .TP .B utc set to \fBFalse\fP to use the host local time as the guest clock. Defaults to \fBTrue\fP\&. .TP .B timezone synchronize the guest to the correspding timezone .TP .B timers a dictionary associating the timer name with its configuration. This configuration is a dictionary with the properties \fBtrack\fP, \fBtickpolicy\fP, \fBcatchup\fP, \fBfrequency\fP, \fBmode\fP, \fBpresent\fP, \fBslew\fP, \fBthreshold\fP and \fBlimit\fP\&. See \fI\%libvirt time keeping documentation\fP for the possible values. .UNINDENT .sp New in version 3003. .sp Set the clock to local time using an offset in seconds \&.. code\-block:: yaml .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .TP .B clock: adjustment: 3600 utc: False .UNINDENT .UNINDENT .UNINDENT .sp Set the clock to a specific time zone: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C clock: timezone: CEST .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBserials\fP \-\- .sp Dictionary providing details on the serials connection to create. (Default: \fBNone\fP) See \fI\%Serials and Consoles Definitions\fP for more details on the possible values. .sp New in version 3003. .IP \(bu 2 \fBconsoles\fP \-\- .sp Dictionary providing details on the consoles device to create. (Default: \fBNone\fP) See \fI\%Serials and Consoles Definitions\fP for more details on the possible values. .sp New in version 3003. .IP \(bu 2 \fBstop_on_reboot\fP \-\- .sp If set to \fBTrue\fP the guest will stop instead of rebooting. This is specially useful when creating a virtual machine with an installation cdrom or an autoinstallation needing a special first boot configuration. Defaults to \fBFalse\fP .sp New in version 3003. .IP \(bu 2 \fBlive\fP \-\- .sp If set to \fBFalse\fP the changes will not be applied live to the running instance, but will only apply at the next start. Note that reboot will not take those changes. .sp New in version 3003. .IP \(bu 2 \fBhost_devices\fP \-\- .sp List of host devices to passthrough to the guest. The value is a list of device names as provided by the \fI\%node_devices()\fP function. (Default: \fBNone\fP) .sp New in version 3003. .IP \(bu 2 \fBautostart\fP \-\- If set to \fBTrue\fP the host will start the guest after boot. (Default: \fBFalse\fP) .UNINDENT .UNINDENT .sp Example States .sp Make sure a virtual machine called \fBdomain_name\fP is defined: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C domain_name: virt.defined: \- cpu: 2 \- mem: 2048 \- boot_dev: network hd \- disk_profile: prod \- disks: \- name: system size: 8192 overlay_image: True pool: default image: /path/to/image.qcow2 \- name: data size: 16834 \- nic_profile: prod \- interfaces: \- name: eth0 mac: 01:23:45:67:89:AB \- name: eth1 type: network source: admin \- graphics: type: spice listen: type: address address: 192.168.0.125 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.virt.keys(name, basepath=\(aq/etc/pki\(aq, **kwargs) Manage libvirt keys. .INDENT 7.0 .TP .B name The name variable used to track the execution .TP .B basepath Defaults to \fB/etc/pki\fP, this is the root location used for libvirt keys on the hypervisor .UNINDENT .sp The following parameters are optional: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B country The country that the certificate should use. Defaults to US. .UNINDENT .sp New in version 2018.3.0. .INDENT 0.0 .TP .B state The state that the certificate should use. Defaults to Utah. .UNINDENT .sp New in version 2018.3.0. .INDENT 0.0 .TP .B locality The locality that the certificate should use. Defaults to Salt Lake City. .UNINDENT .sp New in version 2018.3.0. .INDENT 0.0 .TP .B organization The organization that the certificate should use. Defaults to Salted. .UNINDENT .sp New in version 2018.3.0. .INDENT 0.0 .TP .B expiration_days The number of days that the certificate should be valid for. Defaults to 365 days (1 year) .UNINDENT .sp New in version 2018.3.0. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.virt.network_defined(name, bridge, forward, vport=None, tag=None, ipv4_config=None, ipv6_config=None, autostart=True, connection=None, username=None, password=None, mtu=None, domain=None, nat=None, interfaces=None, addresses=None, physical_function=None, dns=None) Defines a new network with specified arguments. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Network name .IP \(bu 2 \fBbridge\fP \-\- Bridge name .IP \(bu 2 \fBforward\fP \-\- .sp Forward mode(bridge, router, nat) .sp Changed in version 3003: a \fBNone\fP value creates an isolated network with no forwarding at all .IP \(bu 2 \fBvport\fP \-\- .sp Virtualport type (Default: \fB\(aqNone\(aq\fP) The value can also be a dictionary with \fBtype\fP and \fBparameters\fP keys. The \fBparameters\fP value is a dictionary of virtual port parameters. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- vport: type: openvswitch parameters: interfaceid: 09b11c53\-8b5c\-4eeb\-8f00\-d84eaa0aaa4f .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3003: possible dictionary value .IP \(bu 2 \fBtag\fP \-\- .sp Vlan tag (Default: \fB\(aqNone\(aq\fP) The value can also be a dictionary with the \fBtags\fP and optional \fBtrunk\fP keys. \fBtrunk\fP is a boolean value indicating whether to use VLAN trunking. \fBtags\fP is a list of dictionaries with keys \fBid\fP and \fBnativeMode\fP\&. The \fBnativeMode\fP value can be one of \fBtagged\fP or \fBuntagged\fP\&. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- tag: trunk: True tags: \- id: 42 nativeMode: untagged \- id: 47 .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3003: possible dictionary value .IP \(bu 2 \fBipv4_config\fP \-\- IPv4 network configuration. See the \fI\%virt.network_define\fP function corresponding parameter documentation for more details on this dictionary. (Default: None). .IP \(bu 2 \fBipv6_config\fP \-\- IPv6 network configuration. See the \fI\%virt.network_define\fP function corresponding parameter documentation for more details on this dictionary. (Default: None). .IP \(bu 2 \fBautostart\fP \-\- Network autostart (default \fB\(aqTrue\(aq\fP) .IP \(bu 2 \fBconnection\fP \-\- libvirt connection URI, overriding defaults .IP \(bu 2 \fBusername\fP \-\- username to connect with, overriding defaults .IP \(bu 2 \fBpassword\fP \-\- password to connect with, overriding defaults .IP \(bu 2 \fBmtu\fP \-\- .sp size of the Maximum Transmission Unit (MTU) of the network. (default \fBNone\fP) .sp New in version 3003. .IP \(bu 2 \fBdomain\fP \-\- .sp DNS domain name of the DHCP server. The value is a dictionary with a mandatory \fBname\fP property and an optional \fBlocalOnly\fP boolean one. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- domain: name: lab.acme.org localOnly: True .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBnat\fP \-\- .sp addresses and ports to route in NAT forward mode. The value is a dictionary with optional keys \fBaddress\fP and \fBport\fP\&. Both values are a dictionary with \fBstart\fP and \fBend\fP values. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: nat \- nat: address: start: 1.2.3.4 end: 1.2.3.10 port: start: 500 end: 1000 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBinterfaces\fP \-\- .sp whitespace separated list of network interfaces devices that can be used for this network. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: passthrough \- interfaces: \(dqeth10 eth11 eth12\(dq .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBaddresses\fP \-\- .sp whitespace separated list of addresses of PCI devices that can be used for this network in \fIhostdev\fP forward mode. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: hostdev \- interfaces: \(dq0000:04:00.1 0000:e3:01.2\(dq .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBphysical_function\fP \-\- .sp device name of the physical interface to use in \fBhostdev\fP forward mode. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: hostdev \- physical_function: \(dqeth0\(dq .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBdns\fP \-\- .sp virtual network DNS configuration The value is a dictionary described in \fI\%DNS configuration definition\fP\&. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- dns: forwarders: \- domain: example.com addr: 192.168.1.1 \- addr: 8.8.8.8 \- domain: www.example.com txt: example.com: \(dqv=spf1 a \-all\(dq _http.tcp.example.com: \(dqname=value,paper=A4\(dq hosts: 192.168.1.2: \- mirror.acme.lab \- test.acme.lab srvs: \- name: ldap protocol: tcp domain: ldapserver.example.com target: . port: 389 priority: 1 weight: 10 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .UNINDENT .UNINDENT .sp New in version 3001. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C network_name: virt.network_defined .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C network_name: virt.network_defined: \- bridge: main \- forward: bridge \- vport: openvswitch \- tag: 180 \- autostart: True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C network_name: virt.network_defined: \- bridge: natted \- forward: nat \- ipv4_config: cidr: 192.168.42.0/24 dhcp_ranges: \- start: 192.168.42.10 end: 192.168.42.25 \- start: 192.168.42.100 end: 192.168.42.150 \- autostart: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.virt.network_running(name, bridge, forward, vport=None, tag=None, ipv4_config=None, ipv6_config=None, autostart=True, connection=None, username=None, password=None, mtu=None, domain=None, nat=None, interfaces=None, addresses=None, physical_function=None, dns=None) Defines and starts a new network with specified arguments. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Network name .IP \(bu 2 \fBbridge\fP \-\- Bridge name .IP \(bu 2 \fBforward\fP \-\- .sp Forward mode(bridge, router, nat) .sp Changed in version 3003: a \fBNone\fP value creates an isolated network with no forwarding at all .IP \(bu 2 \fBvport\fP \-\- .sp Virtualport type (Default: \fB\(aqNone\(aq\fP) The value can also be a dictionary with \fBtype\fP and \fBparameters\fP keys. The \fBparameters\fP value is a dictionary of virtual port parameters. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- vport: type: openvswitch parameters: interfaceid: 09b11c53\-8b5c\-4eeb\-8f00\-d84eaa0aaa4f .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3003: possible dictionary value .IP \(bu 2 \fBtag\fP \-\- .sp Vlan tag (Default: \fB\(aqNone\(aq\fP) The value can also be a dictionary with the \fBtags\fP and optional \fBtrunk\fP keys. \fBtrunk\fP is a boolean value indicating whether to use VLAN trunking. \fBtags\fP is a list of dictionaries with keys \fBid\fP and \fBnativeMode\fP\&. The \fBnativeMode\fP value can be one of \fBtagged\fP or \fBuntagged\fP\&. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- tag: trunk: True tags: \- id: 42 nativeMode: untagged \- id: 47 .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3003: possible dictionary value .IP \(bu 2 \fBipv4_config\fP \-\- .sp IPv4 network configuration. See the :py:func\(gavirt.network_define <salt.modules.virt.network_define>\(ga function corresponding parameter documentation for more details on this dictionary. (Default: None). .sp New in version 3000. .IP \(bu 2 \fBipv6_config\fP \-\- .sp IPv6 network configuration. See the :py:func\(gavirt.network_define <salt.modules.virt.network_define>\(ga function corresponding parameter documentation for more details on this dictionary. (Default: None). .sp New in version 3000. .IP \(bu 2 \fBautostart\fP \-\- Network autostart (default \fB\(aqTrue\(aq\fP) .IP \(bu 2 \fBconnection\fP \-\- .sp libvirt connection URI, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBusername\fP \-\- .sp username to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBpassword\fP \-\- .sp password to connect with, overriding defaults .sp New in version 2019.2.0. .IP \(bu 2 \fBmtu\fP \-\- .sp size of the Maximum Transmission Unit (MTU) of the network. (default \fBNone\fP) .sp New in version 3003. .IP \(bu 2 \fBdomain\fP \-\- .sp DNS domain name of the DHCP server. The value is a dictionary with a mandatory \fBname\fP property and an optional \fBlocalOnly\fP boolean one. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- domain: name: lab.acme.org localOnly: True .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBnat\fP \-\- .sp addresses and ports to route in NAT forward mode. The value is a dictionary with optional keys \fBaddress\fP and \fBport\fP\&. Both values are a dictionary with \fBstart\fP and \fBend\fP values. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: nat \- nat: address: start: 1.2.3.4 end: 1.2.3.10 port: start: 500 end: 1000 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBinterfaces\fP \-\- .sp whitespace separated list of network interfaces devices that can be used for this network. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: passthrough \- interfaces: \(dqeth10 eth11 eth12\(dq .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBaddresses\fP \-\- .sp whitespace separated list of addresses of PCI devices that can be used for this network in \fIhostdev\fP forward mode. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: hostdev \- interfaces: \(dq0000:04:00.1 0000:e3:01.2\(dq .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBphysical_function\fP \-\- .sp device name of the physical interface to use in \fBhostdev\fP forward mode. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- forward: hostdev \- physical_function: \(dqeth0\(dq .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .IP \(bu 2 \fBdns\fP \-\- .sp virtual network DNS configuration The value is a dictionary described in \fI\%DNS configuration definition\fP\&. (default \fBNone\fP) .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C \- dns: forwarders: \- domain: example.com addr: 192.168.1.1 \- addr: 8.8.8.8 \- domain: www.example.com txt: host.widgets.com.: \(dqprinter=lpr5\(dq example.com.: \(dqThis domain name is reserved for use in documentation\(dq hosts: 192.168.1.2: \- mirror.acme.lab \- test.acme.lab srvs: \- name: ldap protocol: tcp domain: ldapserver.example.com target: . port: 389 priority: 1 weight: 10 .ft P .fi .UNINDENT .UNINDENT .sp New in version 3003. .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C network_name: virt.network_running .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C network_name: virt.network_running: \- bridge: main \- forward: bridge \- vport: openvswitch \- tag: 180 \- autostart: True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C network_name: virt.network_running: \- bridge: natted \- forward: nat \- ipv4_config: cidr: 192.168.42.0/24 dhcp_ranges: \- start: 192.168.42.10 end: 192.168.42.25 \- start: 192.168.42.100 end: 192.168.42.150 \- autostart: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.virt.pool_defined(name, ptype=None, target=None, permissions=None, source=None, transient=False, autostart=True, connection=None, username=None, password=None) Defines a new pool with specified arguments. .sp New in version 3001. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBptype\fP \-\- libvirt pool type .IP \(bu 2 \fBtarget\fP \-\- full path to the target device or folder. (Default: \fBNone\fP) .IP \(bu 2 \fBpermissions\fP \-\- target permissions. See \fI\%Permissions definition\fP for more details on this structure. .IP \(bu 2 \fBsource\fP \-\- dictionary containing keys matching the \fBsource_*\fP parameters in function \fI\%salt.modules.virt.pool_define()\fP\&
